Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.41.0

0.41.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))