dymokomi/luce-kernel
Source of release 0.1.0
0.1.0 / src / lower / assist_index.lucb
# Editor help's view of what a snippet can name: the lib's functions and types, luce-std's
# `math` and `math32`, and the host's stub structs, read from their source text with their
# `##` docs, so every doc lives once, next to its declaration.
## What a completion item or hovered word is.
pub enum ItemKind:
function
method
field
type_
keyword
local
## The kind's name, as an editor shows it.
pub func kind_name(kind: ItemKind) -> str:
return match kind:
.function => "function"
.method => "method"
.field => "field"
.type_ => "type"
.keyword => "keyword"
_ => "local"
## One declaration. `owner` is "" for a free function or a type, else the struct or module
## (`math32`) it belongs to; `detail` the signature (`snoise(p: f32[4]) -> f32`) or a
## field's `name: type`; `result` a function's result or a field's type as written ("" for
## none); `on_type` whether it is called on the type (a static function).
struct Decl:
let owner: str
let name: str
let kind: ItemKind
let detail: str
let result: str
let doc: str
let on_type: bool
## Every declaration of the sources, and the docs joined from their `##` lines.
struct Index:
var decls: collections.List[Decl]
var texts: collections.TextPool
func destroy():
self.decls.destroy()
self.texts.destroy()
## The lib, luce-std's math modules and the host's stub texts (each a module of
## structs, as luce-geocore's `code`).
static func of(host_texts: const str[]) -> Index!:
var index = Index()
errdefer index.destroy()
for (at, path) in source_paths.indexed():
if strings.starts_with(path, "luce_kernel/lib/"):
try index.read(source_texts[at], "", true, false)
elif path == "luce_std/math.lucb":
try index.read(source_texts[at], "math", false, false)
elif path == "luce_std/math32.lucb":
try index.read(source_texts[at], "math32", false, false)
for text in host_texts:
try index.read(text, "", false, false)
return index
## The declaration `name` of `owner`, if there is one.
func find(owner: str, name: str) -> Decl?:
for decl in self.decls.view():
if decl.owner == owner and decl.name == name: return decl
return none
## Whether `name` is a type the index knows.
func is_type(name: str) -> bool:
if let decl = self.find("", name):
return decl.kind == .type_
return false
## Read the public declarations of one source. Top-level ones belong to `module`;
## `lib` keeps only the names a snippet gets without an import. A member without a
## `##` doc shares the doc of the member before it (`ptnum`, `numpt`), until a blank
## line or another line at its level. `private_too` reads a header's own helpers,
## which need no `pub`.
func read(text: str, module: str, lib: bool, private_too: bool) -> !:
var doc = collections.List[u8]()
defer doc.destroy()
var shared: str = ""
var owner: str? = none
var lines = Lines(text = text)
while let line = lines.next():
let trimmed = strings.trim(line)
let indent = indentation(line)
if trimmed.length == 0:
doc.clear()
shared = ""
continue
if strings.starts_with(trimmed, "##"):
if doc.length() > 0: try doc.append(' ')
let words = strings.trim((str)trimmed.bytes[2..])
for byte in words.bytes: try doc.append(byte)
continue
if trimmed.bytes[0] == '#': continue
if indent == 0:
owner = none
shared = ""
elif indent > 4:
continue
var doc_text = shared
if doc.length() > 0: doc_text = try self.texts.keep_text(doc.view())
doc.clear()
if indent == 0:
if let name = declaration(trimmed, "struct ", private_too):
let struct_name = leading_name(name)
if not lib or is_lib_name(struct_name):
try self.decls.append(Decl(owner = "", name = struct_name, kind = .type_, detail = (str)trimmed.bytes[(4 if strings.starts_with(trimmed, "pub ") else 0)..<trimmed.length - 1], result = struct_name, doc = doc_text, on_type = false))
owner = struct_name
continue
if let signature = declaration(trimmed, "func ", private_too):
let name = leading_name(signature)
if lib and not is_lib_name(name): continue
try self.add_function(module, signature, doc_text, .function, false)
continue
if let field = declaration(trimmed, "let ", private_too):
try self.add_field(module, field, doc_text)
continue
# A member of a public struct.
let struct_name = owner else continue
shared = ""
if let signature = declaration(trimmed, "static func ", private_too):
try self.add_function(struct_name, signature, doc_text, .method, true)
elif let signature = declaration(trimmed, "func ", private_too):
try self.add_function(struct_name, signature, doc_text, .method, false)
elif let field = declaration(trimmed, "var ", private_too):
try self.add_field(struct_name, field, doc_text)
elif let field = declaration(trimmed, "let ", private_too):
try self.add_field(struct_name, field, doc_text)
else:
continue
shared = doc_text
## `signature` is the text after `func `, ending in `:`.
func add_function(owner: str, signature: str, doc: str, kind: ItemKind, on_type: bool) -> !:
let detail = (str)signature.bytes[..<signature.length - 1] if strings.ends_with(signature, ":") else signature
var result: str = ""
if let arrow = strings.find_last(detail, ") -> "):
result = (str)detail.bytes[arrow + 5..]
try self.decls.append(Decl(owner = owner, name = leading_name(detail), kind = kind, detail = detail, result = result, doc = doc, on_type = on_type))
## `field` is the text after `let ` or `var `: `name: type`, perhaps `= value`.
func add_field(owner: str, field: str, doc: str) -> !:
var detail = field
if let equals = strings.find(field, " = "):
detail = (str)field.bytes[..<equals]
var result: str = ""
if let colon = strings.find(detail, ": "):
result = (str)detail.bytes[colon + 2..]
try self.decls.append(Decl(owner = owner, name = leading_name(detail), kind = .field, detail = detail, result = result, doc = doc, on_type = false))
## The lines of a text, without their newlines.
struct Lines:
let text: str
var at: usize = 0
func next() -> str?:
if self.at > self.text.length: return none
let start = self.at
var end = start
while end < self.text.length and self.text.bytes[end] != '\n': end += 1
self.at = end + 1
return (str)self.text.bytes[start..<end]
## The text after `pub word` (or plain `word` when `private_too`) starting `text`.
func declaration(text: str, word: str, private_too: bool) -> str?:
if strings.starts_with(text, "pub "):
return after_word((str)text.bytes[4..], word)
if private_too: return after_word(text, word)
return none
## The text after `word` when `text` starts with it.
func after_word(text: str, word: str) -> str?:
if not strings.starts_with(text, word): return none
return (str)text.bytes[word.length..]
## The name at the start of `text` (letters, digits, `_`).
func leading_name(text: str) -> str:
var end: usize = 0
while end < text.length and word_byte(text.bytes[end]): end += 1
return (str)text.bytes[..<end]
## How many spaces a line starts with.
func indentation(line: str) -> usize:
var count: usize = 0
while count < line.length and line.bytes[count] == ' ': count += 1
return count
func is_lib_name(name: str) -> bool:
for known in lib_names:
if known == name: return true
return false
## A type as written, reduced to the struct or scalar it names: `const Geometry*` is
## `Geometry`, `Hit?` is `Hit`.
func base_type(written: str) -> str:
var text = strings.trim(written)
if strings.starts_with(text, "const "): text = (str)text.bytes[6..]
var end = text.length
while end > 0 and (text.bytes[end - 1] == '*' or text.bytes[end - 1] == '?' or text.bytes[end - 1] == '!' or text.bytes[end - 1] == ' '): end -= 1
return (str)text.bytes[..<end]
## The element type of an array or span type (`f32[4]` is `f32`), or the type itself.
func item_type(written: str) -> str:
let text = base_type(written)
if not strings.ends_with(text, "]"): return text
let open = strings.last(text, '[') else return text
return (str)text.bytes[..<open]