Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.41.0

0.41.0 / src / support / manifest.lucb

#==============================================================================================
#
#   manifest - The package manifest, `package.prisma`
#
#   DESCRIPTION:
#       A package has a `package.prisma` at its root (base.md §16.4). This reads the little of it
#       the compiler needs: `[package] name`, the identity of the package's error codes
#       (§11.3); `symbol_prefix`, what every exported symbol starts with (§17.6); and the
#       `[native]` inputs the build hands the C compiler and the linker (§17.4); and, for the
#       module resolver, the source root, the dependencies, the exports, and the compiled
#       modules' package identities (§16.4). The file is found upward from the entry file's
#       directory; a program without one is the package `app` with no inputs. `settings`
#       is the one line reader: every `key = value` line under its `[section]`, with either
#       TOML quoting, a trailing comment dropped, and any other line refused.
#
#==============================================================================================

import luce_std.paths
import c
import os
import platform
import support.cache as cache
import support.in_arena
import memory
import strings

# mark: Settings ==============================================================================

## A manifest line or value is malformed.
pub let malformed: ErrorCode = ErrorCode.package(17)

## One `key = value` line of a manifest, under its section, the value unquoted.
pub struct Setting:
    ## The `[section]` header the setting falls under.
    pub var section: str
    ## The setting's key, trimmed.
    pub var key: str
    ## The setting's value, unquoted and trimmed.
    pub var value: str

## Every setting of a `package.prisma` `text`, as section/key/value records in order, so the
## rest of the compiler reads one shape:
##
##   def package "n" {                              [package] name = n   (n as an identifier)
##                                                  [package] written name = n   (as spelled)
##     str k = "v"                                  [package] k = v
##     def dependency "n" { str path = "p" }        [dependencies] n = p, or .luc/deps/n without a path
##     str[] public = ["m", "n.o"]                  [package] public = ["m", "n.o"]
##     def native "x" { str[] k = ["a", "b"] }      [native] k = ["a", "b"]
##
## A package name may be spelled `luce-ui`; the compiler's identifier for it is `luce_ui`.
## Other elements (tasks, the desktop bundle) and properties are luc's and are skipped, but
## a key set twice in one element is refused, luc's or not (§16.4). A malformed line is
## refused at `path:line:column`, `path` naming the file `text` was read from.
pub func settings(text: str, path: str) -> Setting[]!:
    var out = try new Setting[count_lines(text) + 2] ---
    var count: usize = 0
    var keys = try Keys.create(count_lines(text) + 1)
    var kind: str = ""
    var element: str = ""
    var saw_path = false
    var line_number: usize = 0
    var rest = text
    while rest.length > 0:
        let cut = strings.find(rest, "\n") else rest.length
        let raw_line = (str)rest.bytes[..<cut]
        let line = trim(raw_line)
        let at = Place(path = path, line = line_number + 1, indent = raw_line.length - trim_start(raw_line).length)
        line_number += 1
        rest = (str)rest.bytes[cut + 1..] if cut < rest.length else ""
        if line.length == 0 or line.bytes[0] == '#':
            continue
        if line == "}":
            if keys.depth == 2 and kind == "dependency" and not saw_path:
                out[count] = Setting(section = "[dependencies]", key = element, value = try deps_path(element))
                count += 1
            if keys.depth == 0:
                try at.refuse(0, "package.prisma closes an element it never opened")
            keys.close_element()
            continue
        if line.length > 4 and (str)line.bytes[..<4] == "def ":
            let after = trim((str)line.bytes[4..])
            let space = strings.find(after, " ") else after.length
            let word = (str)after.bytes[..<space]
            let named = trim((str)after.bytes[space..])
            if named.length < 3 or named.bytes[named.length - 1] != '{':
                try at.refuse(0, "an element is `def kind \"name\" {`")
            let name = unquote(trim((str)named.bytes[..<named.length - 1]))
            try keys.open_element()
            if keys.depth == 1:
                if word != "package":
                    try at.refuse(0, "package.prisma starts with `def package`")
                out[count] = Setting(section = "[package]", key = "name", value = try identifier_of(name))
                out[count + 1] = Setting(section = "[package]", key = "written name", value = name)
                count += 2
            elif keys.depth == 2:
                kind = word
                element = try identifier_of(name) if word == "dependency" else name
                saw_path = false
            continue
        let eq = strings.find(line, "=") else line.length
        if eq >= line.length:
            try at.refuse(0, "a property is `type key = value`")
        let left = trim((str)line.bytes[..<eq])
        let type_end = strings.find(left, " ") else left.length
        if type_end >= left.length:
            try at.refuse(0, "a property is `type key = value`")
        let key = trim((str)left.bytes[type_end..])
        let column = left.length - trim_start((str)left.bytes[type_end..]).length
        if let first = try keys.set(key, at.line):
            var room = try new u8[key.length + 64] ---
            try at.refuse(column, try strings.format(room, f"`{key}` is set twice in one element; it was set on line {first}"))
        let raw = trim((str)line.bytes[eq + 1..])
        if keys.depth == 1:
            out[count] = Setting(section = "[package]", key = key, value = unquote(raw))
            count += 1
        elif keys.depth == 2:
            if kind == "dependency" and key == "path":
                out[count] = Setting(section = "[dependencies]", key = element, value = unquote(raw))
                count += 1
                saw_path = true
            elif kind == "export":
                try at.refuse(0, "a package names its public modules in `str[] public = [...]`, under `src/` (§16.4); `def export` is gone")
            elif kind == "native":
                # The element's name says where it applies; parse keeps the ones for the target.
                var room = try new u8[element.length + key.length + 1] ---
                let scoped = try strings.format(room, f"{element}/{key}")
                out[count] = Setting(section = "[native]", key = scoped, value = raw)
                count += 1
    return out[..<count]

## Where in a manifest a line starts: its file, its line, and the blanks before its text.
struct Place:
    var path: str
    var line: usize
    var indent: usize

    ## Refuse the line as malformed, `what` naming why, at `column` past its indent.
    func refuse(column: usize, what: str) -> never!:
        var room = try new u8[self.path.length + what.length + 48] ---
        error(malformed, try strings.format(room, f"{self.path}:{self.line}:{self.indent + column + 1}: {what}"))

## The keys set in each open element, so one set twice in an element is found; elements
## are numbered as they open, and each key remembers the element and the line it is in.
struct Keys:
    var names: str[]
    var elements: usize[]
    var lines: usize[]
    var count: usize
    ## The open elements' numbers, outermost first, and how many are open.
    var open: usize[16]
    var depth: usize
    var opened: usize

    static func create(capacity: usize) -> Keys!:
        return Keys(names = try new str[capacity] ---, elements = try new usize[capacity] ---, lines = try new usize[capacity] ---)

    func open_element() -> !:
        if self.depth >= self.open.length:
            error(malformed, "package.prisma nests elements too deeply")
        self.open[self.depth] = self.opened
        self.opened += 1
        self.depth += 1

    func close_element():
        self.depth -= 1

    ## Note `key` set on `line` in the innermost open element; the line of the setting
    ## already there, if the element has one.
    func set(key: str, line: usize) -> usize?!:
        let current = self.open[self.depth - 1] if self.depth > 0 else self.opened
        for i in 0..<self.count:
            if self.elements[i] == current and self.names[i] == key:
                return self.lines[i]
        self.names[self.count] = key
        self.elements[self.count] = current
        self.lines[self.count] = line
        self.count += 1
        return none

## `luce-ui` as the identifier `luce_ui`.
pub func identifier_of(name: str) -> str!:
    var copy = try new u8[name.length] ---
    var i: usize = 0
    for b in name.bytes:
        copy[i] = '_' if b == '-' else b
        i += 1
    return (str)copy

## Where luc unpacks a registry dependency that declares no checkout path.
func deps_path(name: str) -> str!:
    let prefix = ".luc/deps/"
    var copy = try new u8[prefix.length + name.length] ---
    var i: usize = 0
    for b in prefix.bytes:
        copy[i] = b
        i += 1
    for b in name.bytes:
        copy[i] = b
        i += 1
    return (str)copy

func count_lines(text: str) -> usize:
    var n: usize = 0
    for b in text.bytes:
        if b == '\n':
            n += 1
    return n

# mark: Manifests =============================================================================

## What the manifest says; the lists hold NUL-terminated text, ready for a tool's arguments.
pub struct Manifest:
    ## The package's name, as an identifier.
    pub var name: str
    ## The package's name as `def package` spells it (`luce-ui`), empty without a
    ## manifest; the program a build makes carries it (`platform.program`).
    pub var written_name: str
    ## The manifest's `version`, empty when it gives none (`platform.program_version`).
    pub var version: str
    ## The directory holding `package.prisma`, with its trailing slash; empty when none was found.
    pub var root: str
    ## The prefix put before exported C symbols, or empty.
    pub var symbol_prefix: str
    ## The C source files to compile alongside the program, NUL-terminated.
    pub var sources: c.str[]
    ## The libraries to link, NUL-terminated.
    pub var libraries: c.str[]
    ## The directories to search for libraries, NUL-terminated.
    pub var link_search: c.str[]
    ## The macOS frameworks to link, NUL-terminated.
    pub var frameworks: c.str[]
    ## The pkg-config packages whose flags to add, NUL-terminated.
    pub var pkg_config: c.str[]

## The manifest of the package holding `entry_path`, or the default one.
pub func load(entry_path: str) -> Manifest!:
    var dir = directory_of(entry_path)
    while true:
        var buffer = try new u8[dir.length + 16] ---
        let candidate = try strings.format(buffer, f"{dir}package.prisma")
        if let text = read_if_present((c.str)candidate):
            return try parse((str)text, dir)
        if dir.length == 0:
            return try parse("", "")
        dir = parent_of(dir)

## The bytes of the file at `path`, or `none` when there is no such file.
func read_if_present(path: c.str) -> u8[]?:
    let data = in_arena.read(path) catch:
        cache.note_absent((str)path)
        return none
    cache.note_input((str)path, data)
    return data

## The manifest `text` describes, for the package rooted at `root`.
pub func parse(text: str, root: str) -> Manifest!:
    var m = Manifest(name = "app", written_name = "", version = "", root = root, symbol_prefix = "", sources = try no_items(), libraries = try no_items(),
                     link_search = try no_items(), frameworks = try no_items(), pkg_config = try no_items())
    var room = try new u8[root.length + 16] ---
    for setting in try settings(text, try strings.format(room, f"{root}package.prisma")):
        let section = setting.section
        let key = setting.key
        let value = setting.value
        if section == "[package]":
            if key == "name":
                m.name = value
            elif key == "written name":
                m.written_name = value
            elif key == "version":
                m.version = value
            elif key == "symbol_prefix":
                m.symbol_prefix = value
        elif section == "[native]":
            let slash = strings.find(key, "/") else key.length
            if slash >= key.length or not applies((str)key.bytes[..<slash]):
                continue
            let field = (str)key.bytes[slash + 1..]
            let items = try items_of(value)
            if field == "sources":
                m.sources = try joined(m.sources, items)
            elif field == "libraries":
                m.libraries = try joined(m.libraries, items)
            elif field == "link_search":
                m.link_search = try joined(m.link_search, try searched(items))
            elif field == "frameworks":
                m.frameworks = try joined(m.frameworks, items)
            elif field == "pkg_config":
                m.pkg_config = try joined(m.pkg_config, items)
    return m

# mark: Targets ===============================================================================

## The target native elements are chosen for: the host's unless the build names another.
var target_name: str = ""

## Choose the target `def native` elements are selected for (`arm64-macos`, …).
pub func set_target(name: str):
    target_name = name

## Whether a `def native "NAME"` element applies to the target: `inputs` (or `all`)
## everywhere, an operating system (`macos`, `linux`, `windows`) on each of its
## architectures, or one exact target (`x86_64-windows`).
pub func applies(name: str) -> bool:
    if name == "inputs" or name == "all":
        return true
    let target = target_name if target_name.length > 0 else platform.name
    if name == target:
        return true
    return target.length > name.length + 1 and target.bytes[target.length - name.length - 1] == '-' and (str)target.bytes[target.length - name.length..] == name

## Search directories with a leading `$NAME` taken from the environment: `$VULKAN_SDK/Lib`
## is the SDK's library directory where the variable is set, and nothing where it is not.
func searched(items: c.str[]) -> c.str[]!:
    var out = try new c.str[items.length] ---
    var count: usize = 0
    for item in items:
        let text = (str)item
        if text.length == 0 or text.bytes[0] != '$':
            out[count] = item
            count += 1
            continue
        let slash = strings.find(text, "/") else text.length
        let name = try new u8[slash] ---
        memory.copy(name, text.bytes[1..<slash], slash - 1)
        name[slash - 1] = 0
        let value = os.env((c.str)name.data) else continue
        let rest = (str)text.bytes[slash..] if slash < text.length else ""
        let room = try new u8[value.length + rest.length + 1] ---
        let joined_text = try strings.format(room, f"{value}{rest}")
        room[joined_text.length] = 0
        out[count] = (c.str)room.data
        count += 1
    return out[..<count]

## Two item lists as one, in order.
func joined(first: c.str[], second: c.str[]) -> c.str[]!:
    if first.length == 0:
        return second
    if second.length == 0:
        return first
    var out = try new c.str[first.length + second.length] ---
    for index in 0..<first.length:
        out[index] = first[index]
    for index in 0..<second.length:
        out[first.length + index] = second[index]
    return out

## `["a", "b"]` as its strings, each copied with a NUL after it; a bare string is one item.
func items_of(value: str) -> c.str[]!:
    var body = value
    if body.length >= 2 and body.bytes[0] == '[' and body.bytes[body.length - 1] == ']':
        body = (str)body.bytes[1..<body.length - 1]
    var out = try new c.str[body.length + 1] ---
    var count: usize = 0
    var at: usize = 0
    while at < body.length:
        while at < body.length and (body.bytes[at] == ' ' or body.bytes[at] == '\t'):
            at += 1
        if at == body.length or body.bytes[at] == '#':
            break
        let quote = body.bytes[at]
        if quote != '"' and quote != '\'':
            error(malformed, "a list holds quoted strings")
        at += 1
        let text = try new u8[body.length + 1] ---
        var used: usize = 0
        var ended = false
        while at < body.length:
            var byte = body.bytes[at]
            at += 1
            if byte == quote:
                ended = true
                break
            if byte == '\\' and quote == '"':
                if at == body.length:
                    error(malformed, "a list string ends inside an escape")
                byte = body.bytes[at]
                at += 1
                if byte == 'n':
                    byte = '\n'
                elif byte == 'r':
                    byte = '\r'
                elif byte == 't':
                    byte = '\t'
                elif byte != '"' and byte != '\\':
                    error(malformed, "a list string has an escape other than \\n, \\r, \\t, \\\" and \\\\")
            if byte == 0:
                error(malformed, "a list string cannot hold NUL")
            text[used] = byte
            used += 1
        if not ended or used == 0:
            error(malformed, "a list string is nonempty and closed")
        text[used] = 0
        out[count] = (c.str)text.data
        count += 1
        while at < body.length and (body.bytes[at] == ' ' or body.bytes[at] == '\t'):
            at += 1
        if at < body.length:
            if body.bytes[at] != ',':
                error(malformed, "list strings are separated by commas")
            at += 1
    return out[..<count]

## The strings of a manifest list, `["ui", "widgets.button"]`, in order.
pub func strings_of(value: str) -> str[]!:
    let items = try items_of(value)
    var out = try new str[items.length] ---
    for k in 0..<items.length:
        out[k] = try strings.copy((str)items[k])
    return out

# mark: Text and paths ========================================================================

## A TOML string's text: `"basic"` or `'literal'`, with a trailing `# comment` dropped; a
## bare value stays as written.
pub func unquote(value: str) -> str:
    let b = value.bytes
    if b.length >= 2 and (b[0] == '"' or b[0] == '\''):
        var end: usize = 1
        while end < b.length and b[end] != b[0]:
            end += 1
        if end < b.length:
            return (str)b[1..<end]
    return value

## `text` without the blanks at its start.
func trim_start(text: str) -> str:
    var start: usize = 0
    while start < text.length and (text.bytes[start] == ' ' or text.bytes[start] == '\t'):
        start += 1
    return (str)text.bytes[start..]

## `text` without the blanks at either end.
func trim(text: str) -> str:
    let b = text.bytes
    var start: usize = 0
    var end = b.length
    while start < end and (b[start] == ' ' or b[start] == '\t' or b[start] == '\r'):
        start += 1
    while end > start and (b[end - 1] == ' ' or b[end - 1] == '\t' or b[end - 1] == '\r'):
        end -= 1
    return (str)b[start..<end]

func no_items() -> c.str[]!:
    var none_at_all = try new c.str[1] ---
    return none_at_all[..<0]

## The directory part of a path, with its trailing slash; empty for a bare name.
pub func directory_of(path: str) -> str:
    let b = path.bytes
    var end: usize = 0
    var i: usize = 0
    while i < b.length:
        if paths.separator(b[i]):
            end = i + 1
        i += 1
    return (str)b[..<end]

## The directory above `dir`, with its trailing slash; empty at the top.
pub func parent_of(dir: str) -> str:
    if paths.root(dir).length == dir.length:
        return ""
    let b = dir.bytes
    if b.length == 0:
        return ""
    var end: usize = 0
    var i: usize = 0
    while i + 1 < b.length:
        if paths.separator(b[i]):
            end = i + 1
        i += 1
    return (str)b[..<end]

test "a manifest names the package, the prefix, and the native inputs":
    var backing: u8[8192]
    var arena = memory.FixedBuffer.over(backing)
    with arena:
        let m = try parse("#prisma 4.0\ndef package \"wid-gets\" {\n    str version = \"1.2.3\"\n    str symbol_prefix = \"wg_\"\n    def native \"inputs\" {\n        str[] sources = [\"vendor/a.c\", \"shims.c\"]\n        str[] libraries = [\"m\"]\n        str[] frameworks = [\"Metal\"]\n    }\n}\n", "pkg/")
        assert(m.name == "wid_gets")
        assert(m.written_name == "wid-gets" and m.version == "1.2.3")
        assert(m.symbol_prefix == "wg_")
        assert(m.root == "pkg/")
        assert(m.sources.length == 2)
        assert((str)m.sources[1] == "shims.c")
        assert(m.libraries.length == 1)
        assert(m.frameworks.length == 1)
        assert(m.pkg_config.length == 0)
        let none_at_all = try parse("", "")
        assert(none_at_all.name == "app")
        assert(none_at_all.written_name == "" and none_at_all.version == "")
        assert(none_at_all.sources.length == 0)

test "every element becomes settings under its section; luc's own elements are skipped":
    var backing: u8[8192]
    var arena = memory.FixedBuffer.over(backing)
    with arena:
        let found = try settings("#prisma 4.0\ndef package \"w\" {\n    str kind = \"package\"\n    str source = 'lib'\n    str[] public = [\"ui\", \"widgets.button\"]\n    def dependency \"luce-ui\" {\n        str owner = \"dymokomi\"\n        str path = \"../luce-ui\"\n    }\n    def dependency \"luce-json\" {\n        str version = \"^0.2.0\"\n    }\n    def task \"ci\" {\n        str cmd = \"luc test\"\n    }\n}\n", "w/package.prisma")
        assert(found.length == 7)
        assert(found[0].section == "[package]" and found[0].key == "name" and found[0].value == "w")
        assert(found[1].key == "written name" and found[1].value == "w")
        assert(found[2].key == "kind" and found[2].value == "package")
        assert(found[3].key == "source" and found[3].value == "lib")
        assert(found[4].key == "public")
        let public = try strings_of(found[4].value)
        assert(public.length == 2 and public[0] == "ui" and public[1] == "widgets.button")
        assert(found[5].section == "[dependencies]" and found[5].key == "luce_ui" and found[5].value == "../luce-ui")
        assert(found[6].section == "[dependencies]" and found[6].key == "luce_json" and found[6].value == ".luc/deps/luce_json")
        let exported = settings("def package \"w\" {\n    def export \"ui\" {\n        str module = \"ui\"\n    }\n}\n", "w/package.prisma") catch failure:
            recover found[..<0]
        assert(exported.length == 0)
        let bad = settings("def widget \"x\" {\n}\n", "w/package.prisma") catch failure:
            assert(failure.message == "w/package.prisma:1:1: package.prisma starts with `def package`")
            recover found[..<0]
        assert(bad.length == 0)

test "a key set twice in one element is refused where it is set again":
    var backing: u8[8192]
    var arena = memory.FixedBuffer.over(backing)
    with arena:
        let empty = try new Setting[1] ---
        var refused = false
        _ = settings("#prisma 4.0\ndef package \"w\" {\n    str[] public = [\"a\"]\n    str[] public = [\"a\"]\n}\n", "w/package.prisma") catch failure:
            assert(failure.code == malformed)
            assert(failure.message == "w/package.prisma:4:11: `public` is set twice in one element; it was set on line 3")
            refused = true
            recover empty[..<0]
        assert(refused)
        refused = false
        _ = settings("def package \"w\" {\n    def task \"ci\" {\n        str cmd = \"a\"\n        str cmd = \"b\"\n    }\n}\n", "p") catch failure:
            assert(failure.message == "p:4:13: `cmd` is set twice in one element; it was set on line 3")
            refused = true
            recover empty[..<0]
        assert(refused)
        # the same key in different elements, and in the package around them, is no repeat
        let fine = try settings("def package \"w\" {\n    str version = \"1\"\n    def dependency \"a\" {\n        str version = \"^1.0.0\"\n    }\n    def dependency \"b\" {\n        str version = \"^1.0.0\"\n    }\n    str owner = \"o\"\n}\n", "p")
        assert(fine.length == 6)

test "native elements apply by operating system or exact target":
    set_target("arm64-macos")
    assert(applies("inputs") and applies("all") and applies("macos") and applies("arm64-macos"))
    assert(not applies("windows") and not applies("linux") and not applies("x86_64-linux"))
    set_target("x86_64-windows")
    assert(applies("windows") and not applies("macos"))
    let m = try parse("def package \"p\" {\n    def native \"inputs\" {\n        list libraries = [\"m\"]\n    }\n    def native \"windows\" {\n        list libraries = [\"user32\"]\n    }\n    def native \"macos\" {\n        list frameworks = [\"AppKit\"]\n    }\n}\n", "")
    assert(m.libraries.length == 2 and (str)m.libraries[0] == "m" and (str)m.libraries[1] == "user32" and m.frameworks.length == 0)
    set_target("")

test "a search directory may start from an environment variable, and goes where it is unset":
    let m = try parse("def package \"p\" {\n    def native \"inputs\" {\n        list link_search = [\"$HOME/lib\", \"$LUCE_UNSET_FOR_TEST/Lib\", \"vendor\"]\n    }\n}\n", "")
    let home = os.env("HOME") else return
    assert(m.link_search.length == 2 and (str)m.link_search[1] == "vendor")
    var expected: u8[1024]
    assert((str)m.link_search[0] == try strings.format(expected, f"{home}/lib"))