dymokomi/luce-base
Source of release 0.45.0
0.45.0 / src / embed / checked.lucb
#==============================================================================================
#
# embed - The checker as a library
#
# FRAGMENTS:
# checked.lucb - the result, `check_root`, and what the checker said as diagnostics
# library.lucb - `Library`: the standard modules checked once, then check after check
# packages.lucb - the other packages' modules a library keeps checked (`check_file`)
#
# DESCRIPTION:
# A program that checks Base without running the luce-base command calls `check_root`
# with a directory it supplies and a module there: the module's imports resolve under
# that directory alone, the standard library is the copy the checker carries
# (`standard_sources`), and nothing else is read. The answer is a `Checked`: the typed
# tree, every module and the type table, and what the checker said as diagnostics with
# their file, line and column. It owns all of that in one arena, which `close` frees.
#
# A host that checks again and again keeps a `Library`. Its `check_file` checks a file
# of a package with imports resolved as a build resolves them, and keeps the modules
# of the other packages it imports checked for the next check.
#
# `luce-base check` comes through here too (`check_file`), with the standard library
# from its directory and imports resolved as every build resolves them.
#
# docs/EMBEDDING.md is the guide: the call, the result, and the walk over the tree.
#
#==============================================================================================
import c
import memory
import back.target as targets
import front.ast
import sema.check
import sema.standard as standard
import sema.standard_sources as standard_sources
from support.arena import Arena
import support.cache as cache
import support.list
import support.modules as module_paths
import luce_std.files
import luce_std.paths
import support.in_arena
import support.stamps
import support.changes
import strings
# mark: Diagnostics ===========================================================================
## How much a diagnostic matters.
pub enum Severity as u8:
## The check failed here.
error = 1
## A second place the error before it names, or how many more errors there were.
note = 2
## Something the checker noticed and pruned, an unused local, function or import (§19.6).
warning = 3
## One thing the checker said, at a place in a source.
pub struct Diagnostic:
## How much it matters.
pub var severity: Severity
## The file as positions name it: relative to the root for `check_root` (`snippet.lucb`,
## `luce_kernel/lib.lucb`), `std/...` for a standard module; empty when the message
## names no place.
pub var file: str
## The one-based line; 0 when the message names no place.
pub var line: u32
## The one-based column, counted in bytes; 0 when the message names no place.
pub var column: u32
## What was said, without the position or a `warning:` or `note:` word.
pub var message: str
# mark: The result ============================================================================
## A finished check: the modules, the type table, the entry's tree and the diagnostics, all
## in one arena that `close` frees. Nothing in it may be used after `close`, and it must be
## closed exactly once, whether the check passed or not. The standard modules' trees are the
## library's (`Library.check`), which must outlive it; the other packages' modules a
## library keeps (`Library.check_file`) live as long as a result that uses them.
pub struct Checked:
## The arena that holds everything below, in its own parent.
var arena: Arena*
## The library the result alone uses (`check_root`), closed with it.
var own_library: Library? = none
## The other packages' modules this check was made on top of (`Library.check_file`),
## which it holds until `close`.
var kept: Kept*? = none
## The checker, which holds the type table (`checker.table`) and every module
## (`checker.modules`, the standard ones first, the entry last).
pub var checker: check.Checker
## The entry module's tree: fully typed when `ok()`, partly when it is not; `none` when
## the module could not be read or parsed.
pub var tree: ast.Node*?
## Errors, the notes that go with them, and warnings, in the order they were said.
pub var diagnostics: Diagnostic[]
## The failure as the checker said it, one diagnostic a line with its position, as the
## luce-base command prints it; empty when the check passed.
pub var failure: str
## Whether the check passed: no error was said.
pub func ok() -> bool:
return self.failure.length == 0
## Free the arena and with it everything the check made: the trees, the type table,
## the diagnostics.
pub func close():
destroy_arena(self.arena)
if let library = self.own_library:
var owned = library
owned.close()
self.own_library = none
if let kept = self.kept:
release_kept(kept)
self.kept = none
self.tree = none
self.diagnostics = Diagnostic[]((Diagnostic*)(usize)8, 0)
self.failure = ""
# mark: Checking ==============================================================================
## The room a checker formats its diagnostics in, the same as the command's.
let scratch_size: usize = 65536
## Check module `entry` (a dotted name, `snippet` or `kernels.blur`) of the directory `root`.
## Its imports resolve under `root` alone: the host puts there the modules a snippet may
## import, its own stubs and any library sources such as luce-std's `math.lucb`, and the
## standard modules (`standard_modules`) are the copy the checker carries. Nothing else is
## read, no manifest and no toolchain. Every error of the check is a diagnostic; the call
## itself fails only when memory runs out before there is a result to hold them.
##
## The standard modules are parsed and checked for this call alone; a host that checks
## again and again keeps a `Library` and calls its `check`, which is the same check.
pub func check_root(root: str, entry: str) -> Checked!:
var library = try Library.create()
errdefer library.close()
var result = try library.check(root, entry)
result.own_library = library
return result
## The standard modules the checker carries, in binding order: `memory`, `thread`, `c`,
## `io` and the rest. A module of one of these names is always the standard one, and an
## import of one needs nothing in the root. A tool that accepts a subset of Base refuses
## imports by these names.
pub func standard_modules() -> const str[]:
return standard_sources.modules[0..]
## Check the program whose entry is the file `path` for `target`, as the luce-base command
## does: the standard library from its directory (`standard`), imports resolved as every
## build resolves them (§16.3), positions as the path is spelled. With `whole_package`, every
## other module of the file's package too, imported or not (`check --package`).
pub func check_file(path: c.str, target: targets.Target, whole_package: bool = false) -> Checked!:
let arena = try new_arena(memory.heap)
errdefer destroy_arena(arena)
with arena:
var checker = try check.Checker.create(try new u8[scratch_size] ---)
checker.build_target = target
checker.whole_package = whole_package
let message = load_and_check(&checker, path) catch failure:
recover try strings.copy(failure.message)
return try finish(arena, &checker, file_tree(&checker, (str)path), message)
## `entry` and its imports from `root`, checked on top of the standard modules.
func load_and_check_root(checker: check.Checker*, root: str, entry: str) -> str!:
try checker.load_sealed(root, entry)
try checker.check_program()
return ""
## The standard library from its directory, then the file at `path` and its imports.
func load_and_check(checker: check.Checker*, path: c.str) -> str!:
try checker.add_prelude()
try checker.load(path)
try checker.check_program()
return ""
## The result of a check that said `failure` (empty when it passed), with the entry's
## `tree`, and the diagnostics, in the current allocator, which is `arena`. The checker,
## some 1.8 KB, is copied once, into the result.
func finish(arena: Arena*, checker: const check.Checker*, tree: ast.Node*?, failure: str) -> Checked!:
var said = try list.List[Diagnostic].create(8)
try add_lines(&said, failure, Severity.error)
for warning in checker.warnings.span():
try add_lines(&said, warning, Severity.warning)
return Checked(arena = arena, checker = *checker, tree = tree, diagnostics = said.span(), failure = failure)
## The tree of the program module `entry`, a dotted name, when it was loaded.
func entry_tree(checker: const check.Checker*, entry: str) -> ast.Node*?:
let index = checker.find_module(entry) else return none
let m = checker.modules.get(index)
if m.is_prelude:
return none
return m.tree
## The tree of the module read from the file `path`, when it was loaded.
func file_tree(checker: const check.Checker*, path: str) -> ast.Node*?:
let found = checker.module_at(path) catch:
return none
let index = found else return none
return checker.modules.get(index).tree
# mark: Reading what the checker said =========================================================
## Each line of `text` as a diagnostic: `file:line:column: message`, a ` note: ...` line
## after an error, or a line with no position (` ... and 3 more`).
func add_lines(said: list.List[Diagnostic]*, text: str, severity: Severity) -> !:
var start: usize = 0
for i in 0..<text.length + 1:
if i < text.length and text.bytes[i] != '\n':
continue
if i > start:
try said.push(diagnostic((str)text.bytes[start..<i], severity))
start = i + 1
## One line of what the checker said as a diagnostic of `severity`, unless the line says
## it is a note or a warning.
func diagnostic(line: str, severity: Severity) -> Diagnostic:
var text = strings.trim(line)
var kind = severity
if strings.starts_with(text, "note: "):
kind = Severity.note
text = (str)text.bytes[6..]
elif strings.starts_with(text, "..."):
kind = Severity.note
var said = Diagnostic(severity = kind, file = "", line = 0, column = 0, message = text)
if let at = placed(text):
let (file, number, column, rest) = at
said.file = file
said.line = number
said.column = column
said.message = rest
if strings.starts_with(said.message, "warning: "):
said.severity = Severity.warning
said.message = (str)said.message.bytes[9..]
return said
## `text` taken apart as `file:line:column: rest`, the first colon followed by a line and a
## column being the one after the file; `none` when it names no place.
func placed(text: str) -> (str, u32, u32, str)?:
for i in 0..<text.length:
if text.bytes[i] != ':':
continue
let line_end = digits(text, i + 1) else continue
let (line, after_line) = line_end
if after_line >= text.length or text.bytes[after_line] != ':':
continue
let column_end = digits(text, after_line + 1) else continue
let (column, after_column) = column_end
if after_column + 1 < text.length and text.bytes[after_column] == ':' and text.bytes[after_column + 1] == ' ':
return ((str)text.bytes[..<i], line, column, (str)text.bytes[after_column + 2..])
return none
## The decimal number at `at` in `text` and where it ends; `none` when no digit is there or
## it does not fit.
func digits(text: str, at: usize) -> (u32, usize)?:
var value: u32 = 0
var end = at
while end < text.length and text.bytes[end] >= '0' and text.bytes[end] <= '9':
let tens = value *? 10 else return none
value = tens +? (u32)(text.bytes[end] - '0') else return none
end += 1
if end == at:
return none
return (value, end)