std/compiler

The compiler as a library, for tools such as editors, linters, and documentation generators. Import it with as, since the compiler declares many names; a program that imports it carries the whole compiler, so it takes longer to build.

import "std/compiler" as compiler

compiler.Analysis a = compiler.analyze("main.cz")
for d in a.diagnostics do
    print(compiler.diagnostic_text(d))
end
match compiler.symbol_at(a, "main.cz", 12, 7) do
    when SOME(symbol) then
        print(symbol.detail)
        print(symbol.doc)
    when NONE then
end

analyze(path) checks a program, with everything it imports, and keeps what the questions need: Analysis has the program's diagnostics (see Diagnostics) and its tree. A program with errors is analyzed as far as it was read, so the questions work on code being written. Places are lines and columns from 1, columns in UTF-8 bytes; a Place is a range of a file, file, line, col, end_line, and end_col.

Function	Gives
`symbol_at(a, file, line, col)`	the `Symbol` a name at a place means: its `name`, `kind`, `detail` (its signature or type, as code), `place` (its name in its declaration), `whole` declaration, `container` type, `doc` (the comment lines before its declaration), and `type`
`definition(a, file, line, col)`	where that is declared; Cuarzo declares and defines in one place
`type_definition(a, file, line, col)`	where the type of what is there is declared
`references(a, file, line, col, declaration)`	every place it is used, in every file, with its declaration if asked
`rename(a, file, line, col, new_name)`	the edits that rename it, and the conflicts that should stop it: a name already visible where it is used, a keyword, a built-in, the standard library
`type_at(a, file, line, col)`	the type of the innermost expression there
`members_of(a, type)`	the fields and methods of a struct, or the members and functions of an enum
`hover(a, file, line, col)`	what to show over a name: its detail and documentation
`completions(a, file, line, col)`	what may be written there: after a `.`, the members of what is before it (or a module's names); elsewhere the variables, functions, types, constants, built-ins, and keywords visible there
`signature_help(a, file, line, col)`	the call a place is in the arguments of: its signature, parameters, and which one the place is at
`document_symbols(a, file)`	the declarations of a file, with the fields, methods, and members inside them
`workspace_symbols(a, query)`	the program's declarations whose names hold `query`
`incoming_calls(a, symbol)` and `outgoing_calls(a, symbol)`	the call hierarchy: the functions that call one, or that it calls, each with the places of the calls
`inlay_hints(a, file)`	the types of loop variables and of function values' parameters written without them, and parameter names before literal arguments
`folding_ranges(a, file)`	the lines of each block, run of comments, and the imports
`selection_ranges(a, file, line, col)`	the places around a place, from its token outward
`semantic_tokens(a, file)`	each token's class for highlighting, as the Language Server Protocol names them, with `declaration`, `readonly`, and `defaultLibrary`

An editor checks the program again at each change with a workspace, which keeps the files parsed and checks only the code a change can matter to:

compiler.Workspace w = compiler.open_workspace("main.cz")
match compiler.change_file(w, "main.cz", new_text) do
    when SOME(a) then
        print(len(a.diagnostics))
    when NONE then
        // A newer change stopped this check; the next takes both in.
end

open_workspace(main) checks the program whole; change_file(w, path, text) stands text for the file, saved or not, and checks again; release_file(w, path) reads the file from the disk again, and files_changed(w, paths) checks again after files changed on the disk. Each gives the Analysis, which w.analysis keeps, or NONE when STOP_CHECKING, a function the tool sets, said to stop, as when a newer change came in. A change to a function's code in a program of 50,000 lines is checked again in under 100 ms; calling collect_garbage() while idle keeps a collection from falling in the middle of one.

lint_program(a) gives the warnings of cuarzo lint, as diagnostics with severity WARNING (see Diagnostics).

check_program(path) gives only the tree and the diagnostics, and diagnostic_text and diagnostics_json show diagnostics as the command line does. line_starts, offset_at, position_at, utf16_column, and byte_column convert between lines and columns, offsets, and the UTF-16 columns of the Language Server Protocol.