Editor integration
Connect an LSP-capable editor to the Ocean compiler.
Start the language server#
Configure your editor’s language client with command ocean and two separate arguments, check and --lsp. It communicates using Language Server Protocol framing over stdin and stdout. Ensure ocean is available to the editor process. Clang is not required for language-server validation.
The language server is part of the compiler executable, so there is no separate server binary to install. Your editor needs an LSP client configured to associate .oc files with Ocean and start the command below. Use an absolute path to ocean if the editor does not inherit the same PATH as your terminal.
The server uses standard input and output as a protocol stream, not as an interactive terminal. A client starts the process, sends initialization, and exchanges LSP messages. Launching it manually is useful for confirming that the command exists, but it will then wait for protocol input.
ocean check --lsp
A generic client configuration has executable ocean and an argument list containing check and --lsp as separate arguments. The exact configuration file and language identifier depend on the editor. Also make sure the server process can locate the standard library. When using a compiler binary directly from a checkout, set the language server environment variable OCEAN_SRC to the matching standard-library source tree; the default installed-layout path may not exist. Unresolved standard-library imports prevent completion of their exports; recoverable errors still allow completion of unrelated local symbols.
Language features#
The server reports scanner, parser, and semantic diagnostics on open, change, and save. Validation includes same-package and external _test.oc files in the selected package, including unsaved editor buffers, without running tests. Hover shows resolved types. Definition, declaration, type-definition, and references follow bindings across source files and imports.
Hover is useful for inferred variables because it shows the resolved type at the symbol rather than requiring a separate annotation. Navigation requests distinguish the declaration of a symbol from the declaration of its type, which helps when following fields and package exports. References follow actual symbol bindings across files and imports.
Diagnostics resolve packages and imports and validate source correctness through semantic analysis, stopping before backend lowering. Editor validation does not generate code, verify LLVM, or check native compilation or linking. Use standalone ocean check to verify backend support and native linking.
The client decides how to present this information, such as an inline underline, a diagnostics panel, or a hover popup. If a feature appears missing, check that the editor is connected to this server and supports the corresponding LSP request.
Completion and rename#
Completion suggests visible local variables, parameters, package functions and types, import qualifiers, struct fields, interface and receiver methods, enum variants (including generic specializations), array operations, and exported package members. It filters names by the typed prefix and respects lexical scope. Rename respects shadowing and rejects invalid names, collisions, and a change from an exported uppercase name to a private lowercase name when that declaration is used through an import.
Completion uses the receiver’s resolved type when you type a dot, including fields, methods, dynamic-array operations, and exported package names. It also considers lexical scope so local variables and parameters are suggested where they are actually available. Incomplete member expressions can still receive suggestions. The server keeps valid statements and declarations available around recoverable scanner, syntax, package-resolution, and type errors, including errors in sibling files. Recovery is best effort: malformed declarations or unterminated strings and comments can hide symbols in the damaged region. Function arity diagnostics point at calls and report expected and actual argument counts.
Completing an unimported package name with a nonempty prefix offers an import through LSP additionalTextEdits. Accepting the completion lets the client insert the import after the package declaration. Candidates include installed standard packages, packages in the current module, local replacements, and cached declared dependencies; discovery does not download packages. Existing imports and visible bindings suppress conflicting suggestions.
Rename operates on resolved bindings rather than replacing every matching string. This is important when a local variable shadows another declaration with the same spelling. The server can also reject a rename that collides with an existing declaration or makes an imported public export private.
Review workspace edits in the editor before accepting a larger rename. The server supplies edits across the relevant source files; the editor controls their preview and application.
Unsaved files#
Open buffers, including new unsaved files and incomplete member expressions, are checked with their package and imports without changing source files. Edit ranges and diagnostic positions exchanged with the editor count UTF-16 code units, rather than UTF-8 bytes. Editor-specific setup depends on your editor’s language-client configuration.
The server checks open buffers together with the rest of their package graph. A new or edited file can therefore receive diagnostics without first writing those changes to disk. Other files in the package and imported packages are still considered, so errors may depend on more than the visible buffer.
Positions exchanged with the client use UTF-16 units, as required by the supported protocol behavior. This matters when a line contains characters whose encoding spans more than one unit; a custom client should not treat byte offsets as equivalent positions.
If command-line checks and editor feedback disagree, compare the executable path, working directory, environment variables, and unsaved buffer contents. These are common reasons for the two processes to resolve different sources or toolchains.