dymokomi/luce-pkg
Source of release 0.6.1
## Authored package definition in package.prisma; see docs/PACKAGE_PRISMA.md.
## Decoding uses Prism's own reader. Unknown elements and properties are errors.
import memory
from luce_prism import prism
import strings
from semver import parse, invalid
pub let max_size: usize = 65536
pub let max_dependencies: usize = 128
pub let max_public: usize = 64
pub let max_tasks: usize = 64
pub let max_task_depends: usize = 16
pub let max_development: usize = 16
## Development paths every package has: `luc install` leaves these out unless `--dev`.
pub let default_development: str[2] = ["tests", "dev"]
## `name` is the dependency's package name and the compiler's dependency key.
pub struct Requirement:
pub var name: str
pub var owner: str
## A caret requirement (`^1.2.0`) or an exact version; empty for the newest release.
pub var version: str
## Empty, or a local checkout used instead of the registry release.
pub var path: str
## How an application is bundled for the desktop: Name.app on macOS, an AppDir with a
## .desktop entry on Linux. `name` is the display name.
pub struct Application:
pub var name: str
## Reverse-DNS identifier such as com.luciaos.luced.
pub var identifier: str
## Empty, or a relative path to the icon (.icns on macOS, .png on Linux).
pub var icon: str
## Native inputs the compiler builds and links with the package, as in its `[native]`.
pub struct Native:
pub var sources: str[32]
pub var source_count: usize
pub var link_search: str[16]
pub var link_search_count: usize
pub var libraries: str[32]
pub var library_count: usize
pub var frameworks: str[32]
pub var framework_count: usize
pub var pkg_config: str[16]
pub var pkg_config_count: usize
pub struct Task:
pub var name: str
pub var command: str
pub var description: str
pub var depends: str[16]
pub var depend_count: usize
## Decoded definition. Strings borrow `storage`; callers close it once.
pub struct Definition:
var storage: u8[]
var dependencies: Requirement[]
var tasks: Task[]
pub var name: str
pub var owner: str
pub var version: str
## `package` (a library), `application` (a desktop program) or `tool` (a terminal program).
pub var kind: str
pub var language: str
pub var source: str
pub var description: str
## Empty, or the package's license as an SPDX expression: `MIT OR Apache-2.0`.
pub var license: str
pub var readme: str
## Empty for a library; the program entry path for an application.
pub var entry: str
## Empty, or the post-compile install script of an application.
pub var install: str
pub var native: Native
## `application.name` is empty when the package declares no desktop bundle.
pub var application: Application
pub var dependency_count: usize
pub var task_count: usize
## The modules other packages may import (`str[] public`), by their paths under the
## source root: `ui`, `widgets.button` (base.md ยง16.4).
pub var public: str[64]
pub var public_count: usize
## Development-only paths the package declares (`str[] development`), relative to its
## root, besides `tests` and `dev`. `luc install` leaves all of them out unless `--dev`.
pub var development: str[16]
pub var development_count: usize
## True for anything that builds a program: an application or a tool.
pub func is_application() -> bool:
return self.entry.length > 0
pub func is_tool() -> bool:
return self.kind == "tool"
pub func is_package() -> bool:
return self.kind == "package"
pub func is_bundled() -> bool:
return self.application.name.length > 0
## Borrowed dependency in lexical name order.
pub func dependency_at(index: usize) -> Requirement!:
if index >= self.dependency_count: error(invalid, "package dependency index out of bounds")
return self.dependencies[index]
## Whether `path` (relative to the package root, `/`-separated) is development
## material: `tests`, `dev`, a declared development path, or anything inside one.
pub func is_development(path: str) -> bool:
for prefix in default_development:
if under(path, prefix): return true
for i in 0..<self.development_count:
if under(path, self.development[i]): return true
return false
pub func task_at(index: usize) -> Task!:
if index >= self.task_count: error(invalid, "package task index out of bounds")
return self.tasks[index]
pub func close():
if self.dependencies.length > 0: free(self.dependencies) in memory.heap
if self.tasks.length > 0: free(self.tasks) in memory.heap
if self.storage.length > 0: free(self.storage) in memory.heap
self = Definition()
func name_valid(value: str) -> bool:
if value.length == 0 or value.length > 64: return false
for i in 0..<value.length:
let byte = value.bytes[i]
let alnum = (byte >= 'a' and byte <= 'z') or (byte >= '0' and byte <= '9')
if not alnum and (i == 0 or (byte != '_' and byte != '-')): return false
return true
## Display names become directory names, so they stay plain: letters, digits, spaces, `-`, `_`, `.`.
func display_valid(value: str) -> bool:
if value.length == 0 or value.length > 64 or value.bytes[0] == ' ' or value.bytes[0] == '.' or value.bytes[value.length - 1] == ' ': return false
for byte in value.bytes:
let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
if not alnum and byte != ' ' and byte != '-' and byte != '_' and byte != '.': return false
return true
## Reverse-DNS: at least two dot-separated labels of letters, digits and hyphens.
func identifier_valid(value: str) -> bool:
if value.length == 0 or value.length > 128: return false
var labels: usize
var start: usize
for end in 0..<value.length + 1:
if end != value.length and value.bytes[end] != '.': continue
if end == start: return false
for byte in value.bytes[start..<end]:
let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
if not alnum and byte != '-': return false
labels += 1
start = end + 1
return labels >= 2
## A library, framework or pkg-config name: never a path or an option.
func token_valid(value: str) -> bool:
if value.length == 0 or value.length > 128 or value.bytes[0] == '-': return false
for byte in value.bytes:
let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
if not alnum and byte != '_' and byte != '-' and byte != '.' and byte != '+': return false
return true
## Dotted module name such as `luce_ui.ui`.
func module_valid(value: str) -> bool:
if value.length == 0 or value.length > 256: return false
var start: usize
for end in 0..<value.length + 1:
if end != value.length and value.bytes[end] != '.': continue
if end == start: return false
for byte in value.bytes[start..<end]:
let alnum = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9')
if not alnum and byte != '_': return false
start = end + 1
return true
## Relative, `/`-separated, no empty, `.` or `..` segment, backslash, colon or control byte.
## `inputs` or `all` for every target, an operating system (`macos`, `linux`, `windows`,
## `wasi`) on each of its architectures, or one exact target such as `x86_64-windows`.
func native_element_valid(name: str) -> bool:
let systems = ["macos", "linux", "windows", "wasi"]
if name == "inputs" or name == "all": return true
for system in systems:
if name == system: return true
let (machine, system) = strings.split_once(name, "-") else return false
if machine != "arm64" and machine != "x86_64" and machine != "wasm32": return false
for known in systems:
if system == known: return true
return false
func path_valid(value: str) -> bool:
if value.length == 0 or value.length > 1024: return false
var start: usize
for end in 0..<value.length + 1:
if end != value.length:
let byte = value.bytes[end]
if byte < 0x20 or byte == 0x7f or byte == '\\' or byte == ':': return false
if byte != '/': continue
let part = (str)value.bytes[start..<end]
if part.length == 0 or part == "." or part == "..": return false
start = end + 1
return true
## Whether public `module` (`widgets.button`) would sit in a development path of
## `definition`: its file `<source>/widgets/button.lucb` or its directory.
func public_development(definition: const Definition*, module: str) -> bool:
var buffer: u8[1200]
if definition.source.length + 1 + module.length + 5 > buffer.length: return false
var used: usize = 0
for byte in definition.source.bytes:
buffer[used] = byte
used += 1
buffer[used] = '/'
used += 1
for byte in module.bytes:
buffer[used] = '/' if byte == '.' else byte
used += 1
if definition.is_development((str)buffer[..<used]): return true
for suffix in [".lucb", ".luc"]:
for i in 0..<suffix.length: buffer[used + i] = suffix.bytes[i]
if definition.is_development((str)buffer[..<used + suffix.length]): return true
return false
## Whether `path` is `prefix` or lies inside it.
func under(path: str, prefix: str) -> bool:
if not strings.starts_with(path, prefix): return false
return path.length == prefix.length or path.bytes[prefix.length] == '/'
## A dependency checkout may sit outside the package, so `..` is allowed here.
func local_path_valid(value: str) -> bool:
if value.length == 0 or value.length > 1024: return false
for byte in value.bytes:
if byte < 0x20 or byte == 0x7f or byte == '\\': return false
return true
func requirement_valid(value: str) -> bool:
let exact = (str)value.bytes[1..] if value.length > 1 and value.bytes[0] == '^' else value
_ = parse(exact) catch: return false
return true
## An SPDX license expression: identifiers (`MIT`, `Apache-2.0`, `GPL-2.0+`,
## `LicenseRef-x`, `DocumentRef-a:LicenseRef-b`) joined by `AND`, `OR` and `WITH`, with
## parentheses, on one line. Which identifiers SPDX lists is not checked.
func license_valid(value: str) -> bool:
if value.length == 0 or not line_valid(value): return false
var open: usize
# whether the next word is an identifier (true) or an operator (false)
var operand = true
var i: usize
while i < value.length:
let byte = value.bytes[i]
if byte == ' ':
i += 1
elif byte == '(':
if not operand: return false
open += 1
i += 1
elif byte == ')':
if operand or open == 0: return false
open -= 1
i += 1
else:
var end = i
while end < value.length and value.bytes[end] != ' ' and value.bytes[end] != '(' and value.bytes[end] != ')':
end += 1
let word = (str)value.bytes[i..<end]
if word == "AND" or word == "OR" or word == "WITH":
if operand: return false
elif not operand or not license_identifier(word):
return false
operand = not operand
i = end
return not operand and open == 0
func license_identifier(word: str) -> bool:
for i in 0..<word.length:
let byte = word.bytes[i]
let plain = (byte >= 'a' and byte <= 'z') or (byte >= 'A' and byte <= 'Z') or (byte >= '0' and byte <= '9') or byte == '.' or byte == '-' or byte == ':'
# `+` means "or later" and ends an identifier
if not plain and not (byte == '+' and i == word.length - 1 and i > 0): return false
return true
func line_valid(value: str) -> bool:
if value.length > 256: return false
for byte in value.bytes:
if byte < 0x20 or byte == 0x7f: return false
return true
## Copies decoded text into the arena owned by the Definition.
struct Arena:
var bytes: u8[]
var used: usize
func copy(text: str) -> str!:
if self.used + text.length > self.bytes.length: error(invalid, "package definition exceeds its bound")
let start = self.used
for i in 0..<text.length: self.bytes[start + i] = text.bytes[i]
self.used += text.length
return (str)self.bytes[start..<self.used]
func text(doc: prism.Document*, path: str, name: str) -> str!:
let value = try doc.get(path, name)
defer value.release()
if value.value().dtype() != prism.DType.string or value.value().rank() != 0:
error(invalid, "package property must be a single str")
return try self.copy(try value.value().text_at())
func list(doc: prism.Document*, path: str, name: str, output: str[], count: usize*) -> !:
let value = try doc.get(path, name)
defer value.release()
if value.value().dtype() != prism.DType.string or value.value().rank() != 1:
error(invalid, "package property must be a str array")
if *count + value.value().count() > output.length: error(invalid, "package str array is too long")
for i in 0..<value.value().count():
output[*count + i] = try self.copy(try value.value().text_at(i))
*count += value.value().count()
func sort(values: Requirement[], count: usize):
for i in 1..<count:
let current = values[i]
var at = i
while at > 0 and values[at - 1].name > current.name:
values[at] = values[at - 1]
at -= 1
values[at] = current
## Where the last refused package.prisma of this thread went wrong, and why.
local var diagnosis: u8[320]
## Prism's refusal of package.prisma, as `package.prisma:line:column: why`. The text
## lives in this thread's `diagnosis` until the next refusal.
func located(result: prism.DecodeResult*) -> str!:
let why = result.error_message()
let shown = (str)why.bytes[..<why.length if why.length < 240 else 240]
return try strings.format(diagnosis, f"package.prisma:{result.line()}:{result.column()}: {shown}")
pub func decode(text: const u8[]) -> Definition!:
if text.length == 0 or text.length > max_size: error(invalid, "package definition size outside bounds")
let diagnosed = try prism.decode_diagnosed(text, prism.Codec.prisma)
defer diagnosed.release()
if not diagnosed.value().ok(): error(invalid, try located(diagnosed.value()))
let reference = try diagnosed.value().document()
defer reference.release()
let doc = reference.value()
if doc.connection_count() != 0: error(invalid, "package.prisma may not contain connections")
var result: Definition
errdefer result.close()
result.storage = try new u8[text.length] --- in memory.heap
var arena = Arena(bytes = result.storage)
var found: Requirement[128]
var declared = try new Task[max_tasks] --- in memory.heap
defer free(declared) in memory.heap
var root = ""
var seen_application = false
for index in 0..<doc.element_count():
let path = try doc.path_at(index)
let kind = try doc.type_at(path)
var depth: usize
var last: usize
for i in 0..<path.length:
if path.bytes[i] == '/':
depth += 1
last = i
let name = (str)path.bytes[last + 1..]
if depth == 1:
if kind != "package" or root.length > 0: error(invalid, "package.prisma needs exactly one root package element")
if not name_valid(name): error(invalid, "invalid package name")
root = path
for i in 0..<try doc.property_count(path):
let key = try doc.property_name(path, i)
if key == "development":
try arena.list(doc, path, key, result.development[0..], &result.development_count)
continue
if key == "public":
try arena.list(doc, path, key, result.public[0..], &result.public_count)
continue
let value = try arena.text(doc, path, key)
if key == "owner": result.owner = value
elif key == "version": result.version = value
elif key == "kind": result.kind = value
elif key == "language": result.language = value
elif key == "source": result.source = value
elif key == "description": result.description = value
elif key == "license": result.license = value
elif key == "readme": result.readme = value
elif key == "entry": result.entry = value
elif key == "install": result.install = value
else: error(invalid, "unknown package property")
result.name = try arena.copy(name)
elif depth == 2 and kind == "dependency":
if result.dependency_count >= max_dependencies: error(invalid, "too many package dependencies")
if not name_valid(name): error(invalid, "invalid dependency name")
var entry = Requirement(name = try arena.copy(name))
for i in 0..<try doc.property_count(path):
let key = try doc.property_name(path, i)
let value = try arena.text(doc, path, key)
if key == "owner": entry.owner = value
elif key == "version": entry.version = value
elif key == "path": entry.path = value
else: error(invalid, "unknown dependency property")
if not name_valid(entry.owner): error(invalid, "dependency owner is missing or invalid")
# no version asks for the newest release; luc.lock records the one chosen
if entry.version.length > 0 and not requirement_valid(entry.version): error(invalid, "dependency version is invalid")
if entry.path.length > 0 and not local_path_valid(entry.path): error(invalid, "invalid dependency path")
for i in 0..<result.dependency_count:
if found[i].name == entry.name: error(invalid, "duplicate package dependency")
found[result.dependency_count] = entry
result.dependency_count += 1
elif depth == 2 and kind == "application":
if seen_application: error(invalid, "a package declares at most one application")
seen_application = true
for i in 0..<try doc.property_count(path):
let key = try doc.property_name(path, i)
if key == "name": result.application.name = try arena.text(doc, path, key)
elif key == "identifier": result.application.identifier = try arena.text(doc, path, key)
elif key == "icon": result.application.icon = try arena.text(doc, path, key)
else: error(invalid, "unknown application property")
if not display_valid(result.application.name): error(invalid, "application name is missing or not a plain display name")
if not identifier_valid(result.application.identifier): error(invalid, "application identifier must be reverse-DNS, such as com.example.app")
if result.application.icon.length > 0 and not path_valid(result.application.icon): error(invalid, "invalid application icon path")
elif depth == 2 and kind == "native":
# one element per target it applies to, their inputs taken together here
if not native_element_valid(name): error(invalid, "a native element is named inputs, all, an operating system or a target")
for i in 0..<try doc.property_count(path):
let key = try doc.property_name(path, i)
if key == "sources": try arena.list(doc, path, key, result.native.sources[0..], &result.native.source_count)
elif key == "link_search": try arena.list(doc, path, key, result.native.link_search[0..], &result.native.link_search_count)
elif key == "libraries": try arena.list(doc, path, key, result.native.libraries[0..], &result.native.library_count)
elif key == "frameworks": try arena.list(doc, path, key, result.native.frameworks[0..], &result.native.framework_count)
elif key == "pkg_config": try arena.list(doc, path, key, result.native.pkg_config[0..], &result.native.pkg_config_count)
else: error(invalid, "unknown native property")
for i in 0..<result.native.source_count:
if not path_valid(result.native.sources[i]): error(invalid, "invalid native source path")
for i in 0..<result.native.link_search_count:
if not path_valid(result.native.link_search[i]): error(invalid, "invalid native link search path")
for i in 0..<result.native.library_count:
if not token_valid(result.native.libraries[i]): error(invalid, "invalid native library name")
for i in 0..<result.native.framework_count:
if not token_valid(result.native.frameworks[i]): error(invalid, "invalid native framework name")
for i in 0..<result.native.pkg_config_count:
if not token_valid(result.native.pkg_config[i]): error(invalid, "invalid pkg-config name")
elif depth == 2 and kind == "export":
error(invalid, "a package names its public modules in `str[] public = [...]`; `def export` is gone")
elif depth == 2 and kind == "task":
if result.task_count >= max_tasks: error(invalid, "too many package tasks")
if not name_valid(name): error(invalid, "invalid task name")
var entry = Task(name = try arena.copy(name))
for i in 0..<try doc.property_count(path):
let key = try doc.property_name(path, i)
if key == "cmd": entry.command = try arena.text(doc, path, key)
elif key == "description": entry.description = try arena.text(doc, path, key)
elif key == "depends": try arena.list(doc, path, key, entry.depends[0..], &entry.depend_count)
else: error(invalid, "unknown task property")
if entry.command.length == 0 and entry.depend_count == 0: error(invalid, "task needs a cmd or depends")
if not line_valid(entry.description): error(invalid, "task description must be one line")
declared[result.task_count] = entry
result.task_count += 1
else:
error(invalid, "unknown element in package.prisma")
if root.length == 0: error(invalid, "package.prisma needs exactly one root package element")
if not name_valid(result.owner): error(invalid, "package owner is missing or invalid")
_ = parse(result.version) catch: error(invalid, "package version is missing or invalid")
if result.language != "luce" and result.language != "luce-base": error(invalid, "package language must be luce or luce-base")
if result.source.length == 0: result.source = "src"
if not path_valid(result.source): error(invalid, "invalid package source path")
if not line_valid(result.description): error(invalid, "package description must be one line of at most 256 bytes")
if result.license.length > 0 and not license_valid(result.license): error(invalid, "package license must be an SPDX expression, such as MIT OR Apache-2.0")
if result.readme.length > 0 and not path_valid(result.readme): error(invalid, "invalid package readme path")
if result.entry.length > 0 and not path_valid(result.entry): error(invalid, "invalid package entry path")
# The kind decides what else the definition must and must not say.
if result.kind == "package":
if result.entry.length > 0 or result.application.name.length > 0 or result.install.length > 0:
error(invalid, "a package is a library: it has no entry, application or install script")
elif result.kind == "tool":
if result.entry.length == 0: error(invalid, "a tool needs an entry")
if result.application.name.length > 0: error(invalid, "a tool runs in a terminal; declare kind application for a desktop program")
elif result.kind == "application":
if result.entry.length == 0 or result.application.name.length == 0:
error(invalid, "an application needs an entry and an application element with its name and identifier")
else:
error(invalid, "kind must be package, application or tool")
if result.install.length > 0:
if result.entry.length == 0: error(invalid, "only an application may declare an install script")
if not path_valid(result.install): error(invalid, "invalid package install path")
# What an install builds must not be development material, or it would be left out.
for i in 0..<result.development_count:
if not path_valid(result.development[i]): error(invalid, "invalid development path")
if result.entry.length > 0 and result.is_development(result.entry):
error(invalid, "the entry lies in a development path, which luc install leaves out")
if result.install.length > 0 and result.is_development(result.install):
error(invalid, "the install script lies in a development path, which luc install leaves out")
if result.is_development(result.source):
error(invalid, "the source root lies in a development path, which luc install leaves out")
for i in 0..<result.public_count:
if not module_valid(result.public[i]): error(invalid, "a public module is a dotted path under the source root")
if public_development(&result, result.public[i]):
error(invalid, "a public module lies in a development path, which luc install leaves out")
sort(found, result.dependency_count)
if result.dependency_count > 0:
result.dependencies = try new Requirement[result.dependency_count] --- in memory.heap
for i in 0..<result.dependency_count: result.dependencies[i] = found[i]
if result.task_count > 0:
result.tasks = try new Task[result.task_count] --- in memory.heap
for i in 0..<result.task_count: result.tasks[i] = declared[i]
return result