dymokomi/luce-base
Source of release 0.42.0
0.42.0 / src / sema / describe.lucb
#==============================================================================================
#
# describe - The public module description
#
# DESCRIPTION:
# Describes checked Base APIs; a consumer decides which signatures it can import. Native
# representation and public visibility are separate facts, so private fields are never
# reconstructed from a list of public fields.
#
#==============================================================================================
import front.ast
import io
import sema.check
import sema.interop
import sema.types
import support.list
# mark: The public description ================================================================
## Write the public description of module `tree`, named `name`, to `out`.
pub func write(out: io.Writer, checker: check.Checker*, tree: ast.Node*, name: str) -> !:
var writer = DescriptionWriter(out = out, checker = checker, tree = tree,
used = try new bool[checker.modules.count] ---,
foreign_types = try list.List[u32].create(8))
var i: usize = 0
while i < writer.used.length:
writer.used[i] = false
i += 1
try writer.module(name)
# mark: The writer ============================================================================
struct DescriptionWriter:
var out: io.Writer
var checker: check.Checker*
var tree: ast.Node*
var used: bool[]
var foreign_types: list.List[u32]
func module(name: str) -> !:
try self.out.write(f"description 9\nmodule {name}\n")
var cursor = self.tree.body
while let d = cursor:
if d.has(ast.flag_pub) and not generic(d):
try self.mark(d.type_id)
try self.mark_conformance(d)
var members = d.body
while let member = members:
if visible_member(d, member) and not generic(member):
try self.mark(member.type_id)
members = member.next
cursor = d.next
var i: usize = 0
while i < self.used.length:
if self.used[i]:
let module = self.checker.modules.get(i)
let kind = "standard" if module.is_prelude else "import"
try self.out.write(f"{kind} {module.name} as ")
try self.alias(i)
try self.out.write("\n")
i += 1
for id in self.foreign_types.span():
let t = self.checker.table.get(id)
let module = try self.foreign_module(id) else continue
let decl = t.decl else continue
var kind = "opaque"
if decl.has(ast.flag_pub):
if decl.kind == ast.Kind.extern_type and decl.right != none:
kind = "handle"
elif t.kind == types.Kind.struct_:
kind = "struct"
if let declaration = try interop.owned(self.checker, id):
kind = "view" if declaration.view else "object"
elif t.kind == types.Kind.enum_ and decl.ty != none:
kind = "enum"
elif t.kind == types.Kind.interface_:
kind = "interface"
try self.out.write("foreign ")
try self.alias(module)
try self.out.write(f".{t.name} {kind}\n")
cursor = self.tree.body
while let d = cursor:
if d.has(ast.flag_pub):
try self.declaration(d)
cursor = d.next
func declaration(d: ast.Node*) -> !:
if generic(d):
try self.out.write(f"unavailable {d.text} generic\n")
return
match d.kind:
.func_:
try self.signature(d, "func ")
.constant:
# a re-exported function is the function under this name (§9.4)
if let target = self.checker.function_alias(d):
try self.signature_as(target, "func ", d.text)
return
if interop.standard(self.checker, d.type_id, "Type") or interop.standard(self.checker, d.type_id, "ViewType"):
_ = try interop.owned(self.checker, self.checker.table.get(d.type_id).args[0])
return
try self.out.write(f"let {d.text}: ")
try self.type_name(d.type_id)
try self.out.write("\n")
.struct_, .extern_struct:
let owned = try interop.owned(self.checker, d.type_id)
if let native = owned:
if native.view:
try self.out.write(f"view {d.text} descriptor {native.descriptor.text} mutable {native.mutable}\n")
else:
let dispose = native.dispose else error(check.type_error, "an owned declaration has no disposal")
let close = dispose.text if native.closeable else "-"
try self.out.write(f"object {d.text} descriptor {native.descriptor.text} close {close}\n")
else:
try self.out.write(f"struct {d.text}\n")
var complete = true
var init: ast.Node*? = none
var cursor = d.body
while let member = cursor:
if member.kind == ast.Kind.field and not member.has(ast.flag_pub):
complete = false
if member.kind == ast.Kind.func_ and member.text == "init":
init = member
cursor = member.next
try self.out.write(" representation complete\n" if complete else " representation private\n")
var view = false
if let native = owned:
view = native.view
if view:
try self.out.write(" constructor private\n")
elif let initializer = init:
if initializer.has(ast.flag_pub):
try self.signature(initializer, " constructor ")
else:
try self.out.write(" constructor private\n")
else:
try self.out.write(" constructor memberwise\n")
if owned == none:
try self.out.write(" storage value\n" if self.value_storage(d.type_id, true) else " storage unavailable\n")
try self.members(d)
try self.conformance(d)
.interface_:
try self.out.write(f"interface {d.text}\n")
try self.members(d)
.enum_:
if let backing = d.ty:
try self.out.write(f"enum {d.text} as ")
try self.type_name(backing.type_id)
try self.out.write("\n")
var cursor = d.body
while let member = cursor:
if member.kind == ast.Kind.enum_case:
try self.out.write(f" case {member.text} = {types.case_value(d, member)}\n")
cursor = member.next
try self.members(d)
try self.conformance(d)
else:
try self.out.write(f"unavailable {d.text} payload-enum\n")
.extern_type:
if let destroy = d.right:
try self.out.write(f"handle {d.text} destroy {destroy.text}\n")
else:
try self.out.write(f"unavailable {d.text} extern-type\n")
.type_alias:
try self.out.write(f"type {d.text} = ")
let owned = try interop.owned(self.checker, d.type_id)
if let native = owned:
try self.out.write("borrowed[" if native.view else "owned[")
try self.type_name(d.type_id, true)
if owned != none:
try self.out.write("]")
try self.out.write("\n")
.union_, .extern_union:
try self.out.write(f"unavailable {d.text} union\n")
_:
_ = 0
## A native value may hide scalar storage, but not an untracked borrow. Public
## text/data fields can be rebased onto the consumer's owned copies. Every
## private nested member must therefore be independent of borrowed storage.
func value_storage(id: u32, public_path: bool) -> bool:
let t = self.checker.table.get(id)
match t.kind:
.unit_, .bool_, .i8_, .i16_, .i32_, .i64_, .isize_, .u8_, .u16_, .u32_, .u64_, .usize_, .f16_, .f32_, .f64_, .char_, .error_code:
return true
.str_:
return public_path
.span:
return public_path and t.is_const and t.elem == types.u8_id
.optional, .array:
return self.value_storage(t.elem, public_path)
.tuple:
for member in t.args:
if not self.value_storage(member, public_path):
return false
return true
.enum_:
let declaration = t.decl else return false
return declaration.ty != none
.struct_:
let declaration = t.decl else return false
if declaration.kind == ast.Kind.extern_type:
return false
var cursor = declaration.body
while let member = cursor:
if member.kind == ast.Kind.field and not self.value_storage(member.type_id, public_path and member.has(ast.flag_pub)):
return false
cursor = member.next
return true
_:
return false
func members(d: ast.Node*) -> !:
let ownership = try interop.owned(self.checker, d.type_id)
var cursor = d.body
while let member = cursor:
if let native = ownership:
if member == native.dispose and not native.closeable:
cursor = member.next
continue
if member.text == ("is_valid" if native.view else "is_closed"):
error(check.type_error, "this name is the shared native ownership state query; choose another package member name")
if visible_member(d, member):
if generic(member):
try self.out.write(f" unavailable {member.text} generic\n")
elif member.kind == ast.Kind.field:
let mode = "let" if member.has(ast.flag_const) else "var"
try self.out.write(f" field {mode} {member.text}: ")
try self.type_name(member.type_id)
if member.left != none or self.checker.table.zeroable(member.type_id):
try self.out.write(" = default")
try self.out.write("\n")
elif member.kind == ast.Kind.func_ and member.text != "init":
if member.has(ast.flag_static):
try self.signature(member, " static method ")
elif member.has(ast.flag_mutating):
try self.signature(member, " mutating method ")
else:
try self.signature(member, " method ")
cursor = member.next
func signature(d: ast.Node*, prefix: str) -> !:
try self.signature_as(d, prefix, d.text)
## `d`'s signature under `name`, the name a re-export gives it.
func signature_as(d: ast.Node*, prefix: str, name: str) -> !:
try self.out.write(f"{prefix}{name}(")
var first = true
var cursor = d.right
while let param = cursor:
if not first:
try self.out.write(", ")
first = false
try self.out.write(f"{param.text}: ")
try self.type_name(param.type_id)
if let value = param.left:
try self.default(value)
cursor = param.next
try self.out.write(")")
let result = self.checker.table.get(d.type_id).elem
if result != types.unit_id:
try self.out.write(" -> ")
try self.type_name(result)
try self.out.write("\n")
## Caller facts are expanded by the consumer at its source call. Other
## defaults stay native so private constants and language semantics survive.
func default(value: ast.Node*) -> !:
if value.kind == ast.Kind.member:
if let owner = value.left:
if owner.kind == ast.Kind.name and owner.text == "luce" and (value.text == "file" or value.text == "line" or value.text == "function" or value.text == "location"):
try self.out.write(f" = caller.{value.text}")
return
try self.out.write(" = default")
## Each public interface `d` conforms to, and before it the methods implementing its
## requirements that are not `pub`: a conformance needs no `pub` (§14.2), and they are
## the public surface through the interface though not callable by name.
func conformance(d: ast.Node*) -> !:
var cursor = d.right if d.kind == ast.Kind.enum_ else d.ty
while let interface_type = cursor:
let decl = self.checker.table.get(interface_type.type_id).decl
if let target = decl:
if target.has(ast.flag_pub):
var requirement = target.body
while let r = requirement:
if let witness = private_witness(d, r):
try self.signature(witness, " witness mutating method " if witness.has(ast.flag_mutating) else " witness method ")
requirement = r.next
try self.out.write(" conforms ")
try self.type_name(interface_type.type_id, true)
try self.out.write("\n")
cursor = interface_type.next
func mark_conformance(d: ast.Node*) -> !:
if d.kind != ast.Kind.struct_ and d.kind != ast.Kind.enum_:
return
var cursor = d.right if d.kind == ast.Kind.enum_ else d.ty
while let interface_type = cursor:
if let target = self.checker.table.get(interface_type.type_id).decl:
if target.has(ast.flag_pub):
try self.mark(interface_type.type_id)
var requirement = target.body
while let r = requirement:
if let witness = private_witness(d, r):
try self.mark(witness.type_id)
requirement = r.next
cursor = interface_type.next
func foreign_module(id: u32) -> usize?!:
let decl = self.checker.table.get(id).decl else return none
let module = try self.checker.owner_of(decl) else return none
if self.checker.modules.get(module).tree == self.tree:
return none
return module
## The name a description gives module `index` it names a type of: `__base_` and the
## module's name, each dot two underscores (`support.list` is `__base_support__list`), so
## a module reads the same in any closure, whatever order its modules were loaded in.
func alias(index: usize) -> !:
try self.out.write("__base_")
let name = self.checker.modules.get(index).name
var start: usize = 0
for i in 0..<name.length:
if name.bytes[i] == '.':
try self.out.write((str)name.bytes[start..<i])
try self.out.write("__")
start = i + 1
try self.out.write((str)name.bytes[start..])
func mark(id: u32) -> !:
if let module = try self.foreign_module(id):
self.used[module] = true
var found = false
for known in self.foreign_types.span():
found = found or known == id
if not found:
try self.foreign_types.push(id)
let t = self.checker.table.get(id)
if t.elem != 0:
try self.mark(t.elem)
for arg in t.args:
try self.mark(arg)
func type_name(id: u32, nominal: bool = false) -> !:
let carrier = self.checker.table.get(id)
if carrier.args.length == 3 and interop.standard(self.checker, id, "WorkerEntry"):
try self.out.write("worker[")
try self.type_name(carrier.args[0])
try self.out.write(", ")
try self.type_name(carrier.args[1])
try self.out.write(", ")
try self.type_name(carrier.args[2])
try self.out.write("]")
return
if carrier.args.length == 2 and interop.standard(self.checker, id, "Callback"):
try self.out.write("callback[")
try self.type_name(carrier.args[0])
try self.out.write(", ")
try self.type_name(carrier.args[1])
try self.out.write("]")
return
if carrier.args.length == 1:
let iface = interop.standard(self.checker, id, "Interface")
let owned = interop.standard(self.checker, id, "Owned")
let outcome = interop.standard(self.checker, id, "Outcome")
if iface or owned or outcome:
if iface and self.checker.table.kind(carrier.args[0]) != types.Kind.interface_:
error(check.type_error, "interop.Interface must name an actual interface")
try self.out.write("interface[" if iface else ("owned_value[" if owned else "outcome["))
try self.type_name(carrier.args[0], iface)
try self.out.write("]")
return
if carrier.kind == types.Kind.interface_ and not nominal:
try self.out.write("unowned_interface[")
try self.type_name(id, true)
try self.out.write("]")
return
if let native = interop.reference(self.checker, id):
if let declaration = try interop.owned(self.checker, native):
let view = interop.standard(self.checker, id, "View")
if view == declaration.view:
try self.out.write("borrowed[" if view else "owned[")
try self.type_name(native)
try self.out.write("]")
return
let t = self.checker.table.get(id)
if let module = try self.foreign_module(id):
if t.args.length == 0:
try self.alias(module)
try self.out.write(f".{t.name}")
return
match t.kind:
.pointer, .span:
if t.is_const:
try self.out.write("const ")
if t.is_volatile:
try self.out.write("volatile ")
try self.type_name(t.elem)
try self.out.write("*" if t.kind == types.Kind.pointer else "[]")
.array:
try self.type_name(t.elem)
try self.out.write(f"[{t.length}]")
.optional, .fallible:
if t.elem != types.unit_id or t.kind == types.Kind.optional:
try self.type_name(t.elem)
try self.out.write("?" if t.kind == types.Kind.optional else "!")
.atomic:
try self.out.write("@")
try self.type_name(t.elem)
.tuple, .func_:
try self.out.write("func(" if t.kind == types.Kind.func_ else "(")
var i: usize = 0
while i < t.args.length:
if i > 0:
try self.out.write(", ")
try self.type_name(t.args[i])
i += 1
try self.out.write(")")
if t.kind == types.Kind.func_:
try self.out.write(" -> ")
try self.type_name(t.elem)
_:
try self.checker.table.describe(self.out, id)
func generic(d: ast.Node*) -> bool:
return d.left != none and (d.kind == ast.Kind.func_ or d.kind == ast.Kind.struct_ or d.kind == ast.Kind.enum_ or d.kind == ast.Kind.interface_)
## The method of `d` that implements requirement `r` when it is not `pub`, which the
## description names as a witness; none when it is `pub`, and so described already.
func private_witness(d: ast.Node*, r: ast.Node*) -> ast.Node*?:
if r.kind != ast.Kind.func_:
return none
var cursor = d.body
while let member = cursor:
if member.kind == ast.Kind.func_ and member.text == r.text and not member.has(ast.flag_pub) and not generic(member):
return member
cursor = member.next
return none
func visible_member(owner: ast.Node*, member: ast.Node*) -> bool:
return (member.kind == ast.Kind.field or member.kind == ast.Kind.func_) and (owner.kind == ast.Kind.interface_ or member.has(ast.flag_pub))