pub func await[T](self: Future[T]): T =
- while not self.ready:
- block
+ while not self.ready do
+ # block
self.value! # apply callbacks?
This implementation differs from standard async/await implementations quite a bit.
-In particular, this means there is no concept of an "async function" - any block of computation that resolves to a value can be made asynchronous. This allows for "anonymous" async functions, among other things.
+In particular, this means there is no concept of an "async function" - any block of computation that resolves to a value can be made asynchronous. This allows for "anonymous" async functions, among other things.
This (packaging up blocks of code to suspend and resume arbitrarily) is hard, and requires particular portable intermediate structures out of the compiler. Luckily, Zig is doing all of the R&D here. Some design decisions to consider revolve around APIs. The Linux kernel interface (among other things) provides both synchronous and asynchronous versions of its API, and fast code will use one or the other, depending if it is in an async context. Zig works around this by way of a known global constant that low-level functions read at compile time to determine whether to operate on synchronous APIs or asynchronous APIs. This is... not great. But what's better?
@@ -245,22 +245,6 @@ In particular, this means there is no concept of an "async function" -
-
-
diff --git a/docs/book/ERRORS.html b/docs/book/ERRORS.html
index 1e4d27a..9ec3f6f 100644
--- a/docs/book/ERRORS.html
+++ b/docs/book/ERRORS.html
@@ -7,7 +7,7 @@
-
+
@@ -174,66 +174,84 @@
Puck's error handling is shamelessly stolen from Swift. It uses a combination of Option/Result types and try/catch statements, and leans somewhat on Puck's metaprogramming capabilities.
-
There are several ways to handle errors in Puck. If the error is encoded in the type, one can:
+
Puck's error handling is heavily inspired syntactically by Swift and semantically by the underlying effects system. It uses a combination of monadic error handling and effectful error propagation, with much in the way of syntactic sugar for conversion between the two, and leans somewhat heavily on Puck's metaprogramming capabilities. In comparison to Rust, it is considerably more dynamic by default.
+
There are several ways to handle errors in Puck. If the error is encoded in the type (as an Option or Result type), one can:
match on the error
compactly match on the error with if ... of
propagate the error with ?
throw the error with !
-
If an error is thrown, one must explicitly handle (or disregard) it with a try/catch block or risk runtime failure. This method of error handling may feel more familiar to Java programmers.
Puck provides Option[T] and a Result[T, E] types, imported by default. These are union types and so must be pattern matched upon to be useful: but the standard library provides a bevy of helper functions.
+
If the error is thrown (encoded as an effect), one can:
+
+
ignore the error, propagating it up the call stack
+
recover from the error in a try block
+
convert the error to a Result[T] (monadic form)
+
+
If an error is thrown, one must explicitly handle it at some level of the stack, or risk runtime failure. This method of error handling may feel more familiar to Java programmers. The compiler will warn on - but not enforce catching - such unhandled errors.
Puck provides Option[T] and a Result[T, E] types, imported by default. These are union types under the hood and so must be pattern matched upon to be useful: but the standard library provides a bevy of helper functions.
Two in particular are of note. The ? operator unwraps a Result or propagates its error up a function call (and may only be used in type-appropriate contexts). The ! operator unwraps an Option or Result directly or throws an exception in the case of None or Error.
pub macro ?[T, E](self: Result[T, E]) =
+ quote
match `self`
- of Okay(x): x
- of Error(e): return Error(e)
+ of Okay(x) then x
+ of Error(e) then return Error(e)
-
pub func `!`[T](self: Option[T]): T =
+
pub func ![T](self: Option[T]): T =
match self
- of Some(x): x
- of None: raise EmptyValue
+ of Some(x) then x
+ of None then raise "empty value"
-pub func `!`[T, E](self: Result[T, E]): T =
- of Okay(x): x
- of Error(e): raise e
-
-
The utility of the provided helpers in std.options and std.results should not be understated. While encoding errors into the type system may appear restrictive at first glance, some syntactic sugar goes a long way in writing compact and idiomatic code. Java programmers in particular are urged to give type-first errors a try, before falling back on unwraps and try/catch.
-
A notable helpful type is the aliasing of Result[T] to Result[T, ref Err], for when the particular error does not matter. This breaks try/catch exhaustion (as ref Err denotes a reference to any Error), but is particularly useful when used in conjunction with the propagation operator.
Errors raised by raise/throw (or subsequently the ! operator) must be explicitly caught and handled via a try/catch/finally statement.
-If an exception is not handled within a function body, the function must be explicitly marked as a throwing function via the yeet prefix (name to be determined). The compiler will statically determine which exceptions in particular are thrown from any given function, and enforce them to be explicitly handled or explicitly ignored.
-
Despite functioning here as exceptions: errors remain types. An error thrown from an unwrapped Result[T, E] is of type E. catch statements, then, may pattern match upon possible errors, behaving similarly to of branches.
-
try:
- ...
-catch "Error":
- ...
-finally:
- ...
+pub func ![T, E](self: Result[T, E]): T =
+ match self
+ of Okay(x) then x
+ of Error(e) then raise e
-
This creates a distinction between two types of error handling, working in sync: functional error handling with Option and Result types, and object-oriented error handling with catchable exceptions. These styles may be swapped between with minimal syntactic overhead. Libraries, however, should universally use Option/Result, as this provides the best support for both styles.
Some functions do not return a value but can still fail: for example, setters.
-This can make it difficult to do monadic error handling elegantly: one could return a Result[void, E], but...
-
pub func set[T](self: list[T], i: uint, val: T) =
- if i > self.length:
+
The utility of the provided helpers in std.options and std.results should not be understated. While encoding errors into the type system may appear restrictive at first glance, some syntactic sugar goes a long way in writing compact and idiomatic code. Java programmers in particular are urged to give type-first errors a try, before falling back on unwraps and try/with.
+
A notable helpful type is the aliasing of Result[T] to Result[T, ref Err], for when the particular error does not matter. This breaks match exhaustion (as ref Err denotes a reference to any Error), but is particularly useful when used in conjunction with the propagation operator.
Some functions do not return a value but can still fail: for example, setters. This can make it difficult to do monadic error handling elegantly. One could return a type Success[E] = Result[void, E], but such an approach is somewhat inelegant. Instead: we treat an assert within a function as having an effect: a possible failure, that can be handled and recovered from at any point in the call stack. If a possible exception is not handled within a function body, the function is implicitly marked by the compiler as throwing that exception.
+
pub type list[T] = struct
+ data: ptr T
+ capacity: uint
+ length: uint
+
+@[safe]
+pub func set[T](self: list[T], i: uint, val: T) =
+ if i > self.length then
raise IndexOutOfBounds
- self.data.raw_set(offset = i, val)
+ self.data.set(offset = i, val)
+
+var foo = ["Hello", "world"]
+foo.set(0, "Goodbye") # set can panic
+# this propagates an IndexOutOfBounds effect up the call stack.
Despite functioning here as exceptions: errors remain types. An error thrown from an unwrapped Result[T, E] is of type E. with statements, then, may pattern match upon possible errors, behaving semantically and syntactically similarly to of branches: though notably not requiring exhaustion.
+
try
+ foo.set(0, "Goodbye")
+with IndexOutOfBounds(index) then
+ dbg "Index out of bounds at {}".fmt(index)
+ panic
+finally
+ ...
+
+
This creates a distinction between two types of error handling, working in sync: functional error handling with Option and Result types, and object-oriented error handling with algebraic effects. These styles may be swapped between with minimal syntactic overhead. It is up to libraries to determine which classes of errors are exceptional and best given the effect treatment and which should be explicitly handled monadically. Libraries should tend towards using Option/Result as this provides the best support for both styles (thanks to the ! operator).
There are three issues that complicate language interop:
-
Conflicting memory management systems, i.e. Boehm GC vs. reference counting
-
Conflicting type systems, i.e. Python vs. Rust
The language of communication, i.e. the C ABI.
+
Conflicting type systems, i.e. Python vs. Rust
+
Conflicting memory management systems, i.e. tracing / reference counting vs. ownership
-
For the first, Puck uses what amounts to a combination of ownership and reference counting: and thus it is exchangeable in this regard with Nim (same system), Rust (ownership), Swift (reference counting), and many others. (It should be noted that ownership systems are broadly compatible with reference counting systems).
-
For the second, Puck has a type system of similar capability to that of Rust, Nim, and Swift: and thus interop with those languages should be straightforward for the user. Its type system is strictly more powerful than that of Python or C, and so interop requires additional help. Its type system is equally as powerful as but somewhat orthogonal to Java's, and so interop is a little more difficult.
-
For the third, Puck is being written at the same time as the crABI ABI spec is in development. crABI promises a C-ABI-compatible, cross-language ABI spec, which would dramatically simplify the task of linking to object files produced by other languages. It is being led by the Rust language team, and both the Nim and Swift teams have expressed interest in it, which bodes quite well for its future.
-
Languages often focus on interop from purely technical details. This is very important: but typically no thought is given to usability (and often none can be, for necessity of compiler support), and so using foreign function interfaces very much feel like using foreign interfaces. Puck attempts to change that.
+
For the first, Puck is being written at the same time as the crABI ABI spec is in development. crABI promises a C-ABI-compatible, cross-language ABI spec: which would dramatically simplify the task of linking to object files produced by other languages (so long as languages actually conform to the ABI). It is being led by the Rust language team, and both Nim and Swift developers have expressed interest in it, which bodes quite well for its future.
+
For the second, Puck has a type system of similar capability to that of Rust, Nim, and Swift: and thus interop with those languages should be a straightforward exchange of types. Its type system is strictly more powerful than that of Python or C, and so interop requires additional help. Its type system is equally as powerful as but somewhat orthogonal to Java's, and so interop will be a little more difficult.
+
For the third: Puck uses what amounts to a combination of ownership and reference counting: and thus it is exchangeable in this regard with Rust. Nim and Swift, by contrast, use reference counting: which is not directly compatible with ownership, as attempting to use an owned type as a GC'd reference will immediately lead to a use-after-free. Puck may have to explore some form of gradual typing at linking-time to accommodate making its functions available for use. Using functions from GC'd languages, however, is perfectly doable with the refc type: though this may necessitate copying object graphs over the call boundary.
+
There is additional significant work being put into the use of Wasm as a language runtime. Wasm allows for - among other things - the sharing of garbage collectors, which means that any garbage-collected language compiling to it can simply use the primitive refc type to denote a garbage-collected reference. This does not, however, immediately work off the bat with ownership: as ownership necessitates certain invariants that garbage collection does not preserve. There is active research into fixing this: notably RichWasm, which retrofits a structural type system with ownership atop Wasm. Such extensions necessitate the runtime environment to implement them, however, and so Puck may have to explore some form of gradual typing for the broader Wasm ecosystem.
use std.io
+use rust.os.linux
+use nim.os.sleep
+...
+
+
Languages often focus on interop from purely technical details. This is very important: but typically little thought is given to usability (and often none can be, for necessity of compiler support), and so using foreign function interfaces very much feel like using foreign function interfaces. Puck attempts to change that.
A trivial concern is that identifiers are not always the same across languages: for example, in Racket this-function is a valid identifier, while in Puck the - character is disallowed outright. Matters of convention are issues, too: in Puck, snake_case is preferred for functions and PamelCase for types, but this is certainly not always the case. Puck addresses this at an individual level by attributes allowing for rewriting: and at a language level by consistent rewrite rules.
Puck has rich metaprogramming support, heavily inspired by Nim. Many features that would have to be at the compiler level in most languages (error propagation ?, std.fmt.print, async/await) are instead implemented as macros within the standard library.
-
Macros take in fragments of the AST within their scope, transform them with arbitrary compile-time code, and spit back out transformed AST fragments to be injected and checked for validity. This is similar to what Nim and the Lisp family of languages do.
-By keeping an intentionally minimal AST, some things not possible to express in literal code may be expressible in the AST: in particular, bindings can be injected in many places they could not be injected in ordinarily. (A minimal AST also has the benefit of being quite predictable.)
-
Macros may not change Puck's syntax: the syntax is flexible enough. Code is syntactically checked (parsed), but not semantically checked (typechecked) before being passed to macros. This may change in the future. Macros have the same scope as other routines, that is:
+
Puck has rich metaprogramming support, heavily inspired by Nim. Many features that would have to be at the compiler level in most languages (error propagation ?, std.fmt.print, ?, !, -> type sugar, => closure sugar, async/await) are instead implemented as macros within the standard library.
+
Macros take in fragments of the AST within their scope, transform them with arbitrary compile-time code, and spit back out transformed AST fragments to be injected and checked for validity. This is similar to what the Lisp family of languages do. It has a number of benefits: there is no separate metaprogramming language, it is syntactically and semantically hygienic, and the underlying framework can be reused for all kinds of compile-time code execution.
+
By keeping an intentionally minimal AST, some things not possible to express in literal code may be expressible in the AST: in particular, bindings can be injected in many places they could not be injected in ordinarily. (A minimal AST also has the benefit of being quite predictable.)
+
Macros may not change Puck's syntax: the syntax is flexible enough. They have the same scope as other routines, that is:
function scope: takes the arguments within or following a function call
macro print(params: varargs) =
- for param in params:
- result.add(quote(stdout.write(`params`.str)))
+ var res = Call("write", [stdout])
+ for param in params do
+ res.params.add(param)
print(1, 2, 3, 4)
-print "hello", " ", "world", "!"
+print "hello", " ", "world", "!"
block scope: takes the expression following a colon as a single argument
macro my_macro(body)
-my_macro:
+my_macro
1
2
3
4
-
operator scope: takes one or two parameters either as a postfix (one parameter) or an infix (two parameters) operator
-
macro +=(a, b) =
- quote:
- `a` = `a` + `b`
+
operator scope: takes one or two parameters either as an infix (two parameters) or a postfix (one parameter) operator
+
# operators are restricted to punctuation
+macro +=(a, b) =
+ Call("=", [a, Call("+", [a, b])])
a += b
Macros typically take a list of parameters without types, but they optionally may be given a type to constrain the usage of a macro. Regardless: as macros operate at compile time, their parameters are not instances of a type, but rather an Expr expression representing a portion of the abstract syntax tree.
Similarly, macros always return an Expr to be injected into the abstract syntax tree despite the usual absence of an explicit return type, but the return type may be specified to additionally typecheck the returned Expr.
-
As macros operate at compile time, they may not inspect the values that their parameters evaluate to. However, parameters may be marked with static[T]: in which case they will be treated like parameters in functions: as values. (note static parameters may be written as static[T] or static T.) There are many restrictions on what might be static parameters. Currently, it is constrained to literals i.e. 1, "hello", etc, though this will hopefully be expanded to any function that may be evaluated statically in the future.
+
As macros operate at compile time, they may not inspect the values that their parameters evaluate to. However, parameters may be marked const: in which case they will be treated like parameters in functions: as values. (note constant parameters may be written as const[T] or const T.)
macro ?[T, E](self: Result[T, E]) =
- quote:
- match self
- of Okay(x): x
- of Error(e): return Error(e)
+ quote
+ match `self`
+ of Okay(x) then x
+ of Error(e) then return Error(e)
func meow: Result[bool, ref Err] =
let a = stdin.get()?
-
The quote macro is special. It takes in literal code and returns that code as the AST. Within quoted data, backticks may be used to break out in order to evaluate and inject arbitrary code: though the code must evaluate to an expression of type Expr.
+
The quote macro is special. It takes in literal code and returns that code as the AST. Within quoted data, backticks may be used to break out in order to evaluate and inject arbitrary code: though the code must evaluate to an expression of type Expr. Thus, quoting is structured: one cannot simply quote any arbitrary section. Quoting is very powerful: most macros are implemented using it.
The Expr type is available from std.ast, as are many helpers, and combined they provide the construction of arbitrary syntax trees (indeed, quote relies on and emits types of it). It is a union type with its variants directly corresponding to the variants of the internal AST of Puck.
-
Construction of macros can be difficult: and so several helpers are provided to ease debugging. The Debug and Display interfaces are implemented for abstract syntax trees: dbg will print a representation of the passed syntax tree as an object, and print will print a best-effort representation as literal code. Together with quote and optionally with static, these can be used to quickly get the representation of arbitrary code.
+
Construction of macros can be difficult: and so several helpers are provided to ease debugging. The Debug and Display interfaces are implemented for abstract syntax trees: dbg will print a representation of the passed syntax tree as an object, and print will print a best-effort representation as literal code. Together with quote and optionally with const, these can be used to quickly get the representation of arbitrary code.
Modules package up code for use by others. Identifiers known at compile time may be part of a module signature: these being constants, functions, macros, types, and other modules themselves. They may be made accessible to external users by prefixing them with the pub keyword. Files are modules, named with their filename. The mod keyword followed by an identifier and an indented block of code explicitly defines a module, inside of the current module. Modules are first class: they may be bound to constants (having the type : mod) and publicly exported, or bound to local variables and passed into functions for who knows what purpose.
-
The use keyword lets you use other modules. The use keyword imports public symbols from the specified module into the current scope unqualified. This runs contrary to expectations coming from most other languages: from Python to Standard ML, the standard notion of an "import" usually puts the imported symbols behind another symbol to avoid "polluting the namespace". As Puck is strongly typed and allows overloading, however, the author sees no reason for namespace pollution to be of concern. These unqualified imports have the added benefit of making uniform function call syntax more widely accessible. It is inevitable that identifier conflicts will exist on occasion, of course: when this happens, the compiler will force qualification (this then does restrict uniform function call syntax).
pub mod stack =
+ pub type Stack[T] = class
+ init(static type Self): Stack[T]
+ push(mut Self, val: T)
+ pop(mut Self): T?
+ peek(lent Self): lent T?
+
+ pub mod list =
+ type ListStack[T] = list[T]
+
+ pub func init[T](self: static type ListStack[T]): Stack[T] = []
+ pub func push[T](self: mut ListStack[T], val: T) = self.push(T)
+ pub func pop[T](self: mut ListStack[T]): T? = self.pop
+ pub func peek[T](self: lent ListStack[T]): lent T? =
+ if self.len == 0 then None else Some(self.last)
+
+use stack.list
+
+let a = ListStack[int].init
+print a.len # error: unable to access method on private type outside its module
+
+a.push(5)
+print a.pop # Some(5)
+
+
Modules package up code for use by others. Identifiers known at compile time may be part of a module: these being constants, functions, macros, types, and other modules themselves. Such identifiers may be made accessible outside of the module by prefixing them with the pub keyword.
+
Importantly, files are implicitly modules, public and named with their filename. The mod keyword followed by an identifier and an indented block of code explicitly defines a module, inside of the current module. Modules are first class: they may be bound to constants (having the type : mod) and publicly exported, or bound to local variables and passed into functions for who knows what purpose.
The use keyword imports public symbols from the specified module into the current scope unqualified. This runs contrary to expectations coming from most other languages: from Python to Standard ML, the standard notion of an "import" puts the imported symbols behind another symbol to avoid "polluting the namespace". As Puck is strongly typed and allows overloading, however, we see no reason for namespace pollution to be of concern. These unqualified imports have the added benefit of making uniform function call syntax more widely accessible. It is inevitable that identifier conflicts will exist on occasion, of course: when this happens, the compiler will force qualification (this then does restrict uniform function call syntax). We discuss this more later.
Nonetheless, if qualification of imports is so desired, an alternative approach is available - binding a module to a constant. Both the standard library and external libraries are available behind identifiers without use of use: std and lib, respectively. (FFI and local modules will likely use more identifiers, but this is not hammered out yet.) A submodule - for example, std.net - may be bound in a constant as const net = std.net, providing all of the modules' public identifiers for use, as fields of the constant net. We will see this construction to be extraordinarily helpful in crafting high-level public APIs for libraries later on.
-
Multiple modules can be imported at once, i.e. use std.[logs, tests], use lib.crypto, lib.http. The standard namespaces (std, lib) deserve more than a passing mention. There are several of these: std for the standard library, lib for all external libraries, crate for the top-level namespace of a project (subject to change), this for the current containing module (subject to change)... In addition: there are a suite of language namespaces, for FFI - rust, nim, and swift preliminarily - that give access to libraries from other languages. Recall that imports are unqualified - so use std will allow use of the standard library without the std qualifier (not recommended: several modules have common names), and use lib will dump every library it can find into the global namespace (even less recommended).
+
use std.[logs, test]
+use lib.crypto, lib.http
+
+
Multiple modules can be imported at once. The standard namespaces deserve more than a passing mention. There are several of these: std for the standard library, lib for all external libraries, pkg for the top-level namespace of a project, this for the current containing module... In addition: there are a suite of language namespaces, for FFI - rust, nim, and swift preliminarily - that give access to libraries from other languages. Recall that imports are unqualified - so use std will allow use of the standard library without the std qualifier (not recommended: several modules have common names), and use lib will dump the name of every library it can find into the global namespace (even less recommended).
A major goal of Puck's module system is to allow the same level of expressiveness as the ML family, while cutting down on the extraneous syntax and boilerplate needed to do so. As such, access modifiers are written directly inline with their declaration, and the file system structure is reused to form an implicit module system for internal use. This - particularly the former - limits the structure a module can expose at first glance, but we will see later that interfaces recoup much of this lost specificity.
-
We mentioned that the filesystem forms an implicit module structure. This begets a couple of design choices. Module names must be lowercase, for compatibility with case-insensitive filesystems. Both a file and a folder with the same name can exist. Files within the aforementioned folder are treated as submodules of the aforementioned file. This again restricts the sorts of module structures we can build, but we will again see later that this restriction can be bypassed.
-
The this and crate modules are useful for this implicit structure...
A major goal of Puck's module system is to allow the same level of expressiveness as the ML family, while cutting down on the extraneous syntax and boilerplate needed to do so. As such, access modifiers are written directly inline with their declaration, and the file system structure is reused to form an implicit module system for internal use. This - particularly the former - limits the structure a module can expose at first glance, but we will see later that classes recoup much of this lost specificity.
+
We mentioned that the filesystem forms an implicit module structure. This begets a couple of design choices. Module names must be lowercase, for compatibility with case-insensitive filesystems. Both a file and a folder with the same name can exist. Files within the aforementioned folder are treated as submodules of the aforementioned file. This again restricts the sorts of module structures we can build, but we will see later that this restriction can be bypassed.
+
The this and pkg modules are useful for this implicit structure...
Puck is an experimental, high-level, memory-safe, statically-typed, whitespace-sensitive, interface-oriented, imperative programming language with functional underpinnings.
-
It attempts to explore designs in making functional programming paradigms comfortable to those familiar with imperative and object-oriented languages, as well as deal with some more technical problems along the way, such as integrated refinement types and typesafe interop.
+
Puck is an experimental, high-level, memory-safe, statically-typed, whitespace-sensitive, interface-oriented, imperative programming language with functional underpinnings.
+
It attempts to explore designs in making functional programming paradigms comfortable to those familiar with imperative and object-oriented languages, as well as deal with some more technical problems along the way, such as integrated refinement types and typesafe interop.
This is the language I keep in my head. It reflects the way I think and reason about code.
let ident: int = 413
# type annotations are optional
-var phrase = "Hello, world!"
-const compile_time = when linux: "linux" else: "windows"
+var phrase = "Hello, world!"
+const compile_time = when linux then "linux" else "windows"
Variables may be mutable (var), immutable (let), or compile-time evaluated and immutable (const).
Type annotations on variables and other bindings follow the name of the binding (with : Type), and are typically optional.
@@ -190,8 +191,7 @@ The type system is comprehensive, and complex enough to warrant delaying full co
int, uint: signed and unsigned integers
-
i8/i16/i32/i64/i128: their fixed-size counterparts
-
u8/u16/u32/u64/u128: their fixed-size counterparts
+
i[\d+], u[\d+]: arbitrary fixed-size counterparts
float, decimal: floating-point numbers
@@ -201,30 +201,33 @@ The type system is comprehensive, and complex enough to warrant delaying full co
byte: an alias to u8, representing one byte
-
chr: an alias to u32, representing one Unicode character
+
char: an alias to u32, representing one Unicode character
bool: defined as union[false, true]
-
array[T, S]: primitive fixed-size (S) arrays
+
array[T, size]: primitive fixed-size arrays
list[T]: dynamic lists
-
str: mutable strings. internally a list[byte], externally a list[chr]
-
slice[T]: borrowed "views" into the three types above
+
str: mutable strings. internally a list[byte], externally a list[char]
+
slice[T]: borrowed "views" into the three types above
Comments are declared with # and run until the end of the line.
Documentation comments are declared with ## and may be parsed by language servers and other tooling.
Multi-line comments are declared with #[ ]# and may be nested.
Taking cues from the Lisp family of languages, any expression may be commented out with a preceding #;.
Functions are declared with the func keyword. They take an (optional) list of generic parameters (in brackets), an (optional) list of parameters (in parentheses), and must be annotated with a return type if they return a type. Every function parameter must be annotated with a type. Their type may optionally be prefixed with either mut or static: denoting a mutable type (types are copied into functions and thus immutable by default), or a static type (known to the compiler at compile time, and usable in const exprs). Generic parameters may each be optionally annotated with a type functioning as a constraint.
+
Functions are declared with the func keyword. They take an (optional) list of generic parameters (in brackets), an (optional) list of parameters (in parentheses), and must be annotated with a return type if they return a type. Every function parameter must be annotated with a type. Their type may optionally be prefixed with either lent, mut or const: denoting an immutable or mutable borrow (more on these later), or a constant type (known to the compiler at compile time, and usable in const exprs). Generic parameters may each be optionally annotated with a type functioning as a constraint.
-
Whitespace is significant but flexible: functions may be declared entirely on one line if so desired. A new level of indentation after certain tokens (:, =) denotes a new level of scope. There are some places where arbitrary indentation and line breaks are allowed - as a general rule of thumb, after operators, commas, and opening parentheses. The particular rules governing indentation may be found in the syntax guide.
+
Whitespace is significant but flexible: functions may be declared entirely on one line if so desired. A new level of indentation after certain tokens (=, do, then) denotes a new level of scope. There are some places where arbitrary indentation and line breaks are allowed - as a general rule of thumb, after operators, commas, and opening parentheses. The particular rules governing indentation may be found in the syntax guide.
Puck supports uniform function call syntax: and so any function may be called using the typical syntax for method calls, that is, the first parameter of any function may be appended with a . and moved to precede it, in the style of a typical method. (There are no methods in Puck. All functions are statically dispatched. This may change in the future.)
This allows for a number of syntactic cleanups. Arbitrary functions with compatible types may be chained with no need for a special pipe operator. Object field access, module member access, and function calls are unified, reducing the need for getters and setters. Given a first type, IDEs using dot-autocomplete can fill in all the functions defined for that type. Programmers from object-oriented languages may find the lack of classes more bearable. UFCS is implemented in shockingly few languages, and so Puck joins the tiny club that previously consisted of just D and Nim.
Boolean logic and integer operations are standard and as one would expect out of a typed language: and, or, xor, not, shl, shr, +, -, *, /, <, >, <=, >=, div, mod, rem. Notably:
@@ -232,88 +235,142 @@ print [1].len # 1
integer division is expressed with the keyword div while floating point division uses /
% is absent and replaced with distinct modulus and remainder operators
boolean operators are bitwise and also apply to integers and floats
-
more operators are available via the standard library
+
more operators are available via the standard library (exp and log)
The above operations are performed with operators, special functions that take a prefixed first argument and (often) a suffixed second argument. Custom operators may be implemented, but they must consist of only a combination of the symbols =+-*/<>@$~&%|!?^\ for the purpose of keeping the grammar context-free. They are are declared identically to functions.
-
Term (in)equality is expressed with the == and != operators. Type equality is expressed with is. Subtyping relations may be queried with of, which has the additional property of introducing new bindings in the current scope (more on this in the types document).
-
let phrase: str = "I am a string! Wheeee! ✨"
-for c in phrase:
+
Term (in)equality is expressed with the == and != operators. Type equality is expressed with is. Subtyping relations may be queried with of, which has the additional property of introducing new bindings to the current scope in certain contexts (more on this in the types document).
+
let phrase: str = "I am a string! Wheeee! ✨"
+for c in phrase do
stdout.write(c) # I am a string! Wheeee! ✨
-for b in phrase.bytes():
- stdout.write(b.chr) # Error: cannot convert between u8 and chr
+for b in phrase.bytes() do
+ stdout.write(b.char) # Error: cannot convert from byte to char
print phrase.last() # ✨
String concatenation uses a distinct & operator rather than overloading the + operator (as the complement - has no natural meaning for strings). Strings are unified, mutable, internally a byte array, externally a char array, and are stored as a pointer to heap data after their length and capacity (fat pointer). Chars are four bytes and represent a Unicode character in UTF-8 encoding. Slices of strings are stored as a length followed by a pointer to string data, and have non-trivial interactions with the memory management system. More details can be found in the type system overview.
Basic conditional control flow uses standard if/elif/else statements. The when statement provides a compile-time if. It also takes elif and else branches and is syntactic sugar for an if statement within a static block (more on those later).
-
All values in Puck must be handled, or explicitly discarded. This allows for conditional statements and many other control flow constructs to function as expressions, and evaluate to a value, when an unbound value is left at the end of each of their branches' scopes. This is particularly relevant for functions, where it is often idiomatic to omit an explicit return statement. There is no attempt made to differentiate without context, and so expressions and statements often look identical in syntax.
+
Basic conditional control flow uses standard if/elif/else statements. The when statement provides a compile-time if. It also takes elif and else branches and is syntactic sugar for an if statement within a const expression (more on those later).
+
All values in Puck must be handled, or explicitly discarded. This allows for conditional statements and many other control flow constructs to function as expressions: and evaluate to a value when an unbound value is left at the end of each of their branches' scopes. This is particularly relevant for functions, where it is often idiomatic to omit an explicit return statement. There is no attempt made to differentiate without context, and so expressions and statements often look identical in syntax.
Exhaustive structural pattern matching is available with the match/of statement, and is particularly useful for the struct and union types. of branches of a match statement take a pattern, of which the unbound identifiers within will be injected into the branch's scope. Multiple patterns may be used for one branch provided they all bind the same identifiers of the same type. Branches may be guarded with the where keyword, which takes a conditional, and will necessarily remove the branch from exhaustivity checks.
-
The of statement also stands on its own as an operator for querying subtype equality. Used as a conditional in if statements or while loops, it retains the variable injection properties of its match counterpart. This allows it to be used as a compact alternative to if let statements in other languages.
-
func may_fail: Result[T, ref Err]
+
The of statement also stands on its own as an operator for querying subtype equality. Used as a conditional in if statements or while loops, it retains the variable injection properties of its match counterpart. This allows it to be used as a compact and coherent alternative to if let statements in other languages.
Error handling is done via a fusion of imperative try/catch statements and functional Option/Result types, with much syntactic sugar. Functions may raise errors, but should return Option[T] or Result[T, E] types instead by convention. The compiler will note functions that raise errors, and force explicit qualification of them via try/catch statements.
-
A bevy of helper functions and macros are available for Option/Result types, and are documented and available in the std.options and std.results modules (included in the prelude by default). Two in particular are of note: the ? macro accesses the inner value of a Result[T, E] or propagates (returns in context) the Error(e), and the ! accesses the inner value of an Option[T] / Result[T, E] or raises an error on None / the specific Error(e). Both operators take one parameter and so are postfix. (There is additionally another ? postfix macro, taking in a type, as a shorthand for Option[T])
-
The utility of the ? macro is readily apparent to anyone who has written code in Rust or Swift. The utility of the ! function is perhaps less so obvious. These errors raised by !, however, are known to the compiler: and they may be comprehensively caught by a single or sequence of catch statements. This allows for users used to a try/catch error handling style to do so with ease, with only the need to add one additional character to a function call.
+
Error handling is done via a fusion of functional monadic types and imperative exceptions, with much syntactic sugar. Functions may raise exceptions, but by convention should return Option[T] or Result[T, E] types instead: these may be handled in match or if/of statements. The compiler will track functions that raise errors, and warn on those that are not handled explicitly via try/with statements.
+
A bevy of helper functions and macros are available for Option/Result types, and are documented and available in the std.options and std.results modules (included in the prelude by default). Two in particular are of note: the ? macro accesses the inner value of a Result[T, E] or propagates (returns in context) the Error(e), and the ! accesses the inner value of an Option[T] / Result[T, E] or raises an error on None / the specific Error(e). Both operators take one parameter and so are postfix. The ? and ! macros are overloaded and additionally function on types as shorthand for Option[T] and Result[T] respectively.
+
The utility of the ? macro is readily apparent to anyone who has written code in Rust or Swift. The utility of the ! function is perhaps less so obvious. These errors raised by !, however, are known to the compiler: and they may be comprehensively caught by a single or sequence of catch statements. This allows for users used to a try/with error handling style to do so with ease, with only the need to add one additional character to a function call.
loop
+ print "This will never normally exit."
break
-for i in 0 .. 3: # exclusive
- for j in 0 ..= 3: # inclusive
- print "{} {}".fmt(i, j)
+for i in 0 .. 3 do # exclusive
+ for j in 0 ..= 3 do # inclusive
+ print "{} {}".fmt(i, j)
Three types of loops are available: for loops, while loops, and infinite loops (loop loops). For loops take a binding (which may be structural, see pattern matching) and an iterable object and will loop until the iterable object is spent. While loops take a condition that is executed upon the beginning of each iteration to determine whether to keep looping. Infinite loops are infinite are infinite are infinite are infinite are infinite are infinite and must be manually broken out of.
-
There is no special concept of iterators: iterable objects are any object that implements the Iter[T] interface (more on those in the type system document), that is, provides a self.next() function returning an Option[T]. As such, iterators are first-class constructs. For loops can be thought of as while loops that unwrap the result of the next() function and end iteration upon a None value. While loops, in turn, can be thought of as infinite loops with an explicit conditional break.
+
There is no special concept of iterators: iterable objects are any object that implements the Iter[T] class (more on those in the type system document), that is, provides a self.next() function returning an Option[T]. As such, iterators are first-class constructs. For loops can be thought of as while loops that unwrap the result of the next() function and end iteration upon a None value. While loops, in turn, can be thought of as infinite loops with an explicit conditional break.
The break keyword immediately breaks out of the current loop, and the continue keyword immediately jumps to the next iteration of the current loop. Loops may be used in conjunction with blocks for more fine-grained control flow manipulation.
-
block:
+
block
statement
let x = block:
let y = read_input()
transform_input(y)
-block foo:
- for i in 0 ..= 100:
- block bar:
- if i == 10: break foo
+block foo
+ for i in 0 ..= 100 do
+ block bar
+ if i == 10 then break foo
print i
Blocks provide arbitrary scope manipulation. They may be labelled or unlabelled. The break keyword additionally functions inside of blocks and without any parameters will jump out of the current enclosing block (or loop). It may also take a block label as a parameter for fine-grained scope control.
Code is segmented into modules. Modules may be made explicit with the mod keyword followed by a name, but there is also an implicit module structure in every codebase that follows the structure and naming of the local filesystem. For compatibility with filesystems, and for consistency, module names are exclusively lowercase (following the same rules as Windows).
A module can be imported into another module by use of the use keyword, taking a path to a module or modules. Contrary to the majority of languages ex. Python, unqualified imports are encouraged - in fact, are idiomatic (and the default) - type-based disambiguation and official LSP support are intended to remove any ambiguity.
-
Within a module, functions, types, constants, and other modules may be exported for use by other modules with the pub keyword. All such identifiers are private by default and only accessible module-locally without. Modules are first-class and may be bound, inspected, modified, and returned. As such, imported modules may be re-exported for use by other modules by binding them to a public constant, i.e. use my_module; pub const my_module = my_module.
+
Within a module, functions, types, constants, and other modules may be exported for use by other modules with the pub keyword. All such identifiers are private by default and only accessible module-locally without. Modules are first-class and may be bound, inspected, modified, and returned. As such, imported modules may be re-exported for use by other modules by binding them to a public constant.
Compile-time programming may be done via the previously-mentioned const keyword and when statements: or via constblocks. All code within a const block is evaluated at compile-time and all assignments and allocations made are propagated to the compiled binary as static data.
-
Further compile-time programming may be done via metaprogramming: compile-time manipulation of the abstract syntax tree. The macro system is complex, and a description may be found in the metaprogramming document.
+
Compile-time programming may be done via the previously-mentioned const keyword and when statements: or via constblocks. All code within a const block is evaluated at compile-time and all assignments and allocations made are propagated to the compiled binary as static data. Further compile-time programming may be done via macros: compile-time manipulation of the abstract syntax tree. The macro system is complex, and a description may be found in the metaprogramming document.
The async system is colourblind: the special async macro will turn any function call returning a T into an asynchronous call returning a Future[T]. The special await function will wait for any Future[T] and return a T (or an error). Async support is included in the standard library in std.async in order to allow for competing implementations. More details may be found in the async document.
Threading support is complex and also regulated to external libraries. OS-provided primitives will likely provide a spawn function, and there will be substantial restrictions for memory safety. I really haven't given much thought to this.
-
-
Details on memory safety, references and pointers, and deep optimizations may be found in the memory management overview.
-The memory model intertwines deeply with the type system.
-
-
Finally, a few notes on the type system are in order.
-
Types are declared with the type keyword and are transparent aliases.
-That is, type Foo = Bar means that any function defined for Bar is defined for Foo - that is, objects of type Foo can be used any time an object of type Bar is called for.
-If such behavior is not desired, the distinct keyword forces explicit qualification and conversion of types. type Foo = distinct Baz will force a type Foo to be wrapped in a call to the constructor Baz() before being passed to such functions.
-
Types, like functions, can be generic: declared with "holes" that may be filled in with other types upon usage. A type must have all its holes filled before it can be constructed. The syntax for generics in types much resembles the syntax for generics in functions, and constraints and the like also apply.
# Differences in Puck and Rust types in declarations and at call sights.
+func foo(a:
+ lent T → &'a T
+ mut T → &'a mut T
+ T → T
+):
+ lent T → &'a T
+ mut T → &'a mut T
+ T → T
+
+let t: T = ...
+foo( # this is usually elided
+ lent t → &t
+ mut t → &mut t
+ t → t
+)
+
+
Puck copies Rust-style ownership near verbatim. &T corresponds to lent T, &mut T to mut T, and T to T: with T implicitly convertible to lent T and mut T at call sites. A major goal of Puck is for all lifetimes to be inferred: there is no overt support for lifetime annotations, and it is likely code with strange lifetimes will be rejected before it can be inferred. (Total inference, however, is a goal.)
+
Another major difference is the consolidation of Box, Rc, Arc, Cell, RefCell into just two (magic) types: ref and refc. ref takes the role of Box, and refc both the role of Rc and Arc: while Cell and RefCell are disregarded. The underlying motivation for compiler-izing these types is to make deeper compiler optimizations accessible: particularly with refc, where the existing ownership framework is used to eliminate counts. Details on memory safety, references and pointers, and deep optimizations may be found in the memory management overview.
# The type Foo is defined here as an alias to a list of bytes.
+type Foo = list[byte]
+
+# implicit conversion to Foo in declarations
+let foo: Foo = [1, 2, 3]
+
+func fancy_dbg(self: Foo) =
+ print "Foo:"
+ # iteration is defined for list[byte]
+ # so self is implicitly converted from Foo to list[byte]
+ for elem in self do
+ dbg(elem)
+
+# NO implicit conversion to Foo on calls
+[4, 5, 6].foo_dbg # this fails!
+
+Foo([4, 5, 6]).foo_dbg # prints: Foo:\n 4\n\ 5\n 6\n
+
+
Finally, a few notes on the type system are in order. Types are declared with the type keyword and are aliases: all functions defined on a type carry over to its alias, though the opposite is not true. Functions defined on the alias must take an object known to be a type of that alias: exceptions are made for type declarations, but at call sites this means that conversion must be explicit.
+
# We do not want functions defined on list[byte] to carry over,
+# as strings function differently (operating on chars).
+# So we declare `str` as a struct, rather than a type alias.
+pub type str = struct
+ data: list[byte]
+
+# However, the underlying `empty` function is still useful.
+# So we expose it in a one-liner alias.
+# In the future, a `with` macro may be available to ease carryover.
+pub func empty(self: str): bool = self.data.empty
+
+# Alternatively, if we want total transparent type aliasing, we can use constants.
+pub const MyAlias: type = VeryLongExampleType
+
+
If one wishes to define a new type without previous methods accessible, the newtype paradigm is preferred: declaring a single-field struct, and manually implementing functions that carry over. It can also be useful to have transparent type aliases, that is, simply a shorter name to refer to an existing type. These do not require type conversion, implicit or explicit, and can be used freely and interchangeably with their alias. This is done with constants.
+
Types, like functions, can be generic: declared with "holes" that may be filled in with other types upon usage. A type must have all its holes filled before it can be constructed. The syntax for generics in types much resembles the syntax for generics in functions, and generic constraints and the like also apply.
Struct and tuple types are declared with struct[<fields>] and tuple[<fields>], respectively. Their declarations make them look similar at a glance, but they differ fairly fundamentally. Structs are unordered, and every field must be named. They may be constructed with {} brackets. Tuples are ordered and so field names are optional - names are just syntactic sugar for positional access. Tuples may be constructed with () parenthesis.
-
I am undecided whether to allow structural subtyping: that is, {a: Type, b: Type, c: Type} being valid in a context expecting {a: Type, b: Type}. This has benefits (multiple inheritance with no boilerplate) but also downsides (obvious).
-
It is worth noting that there is no concept of pub at a field level on structs - a type is either fully transparent, or fully opaque. This is because such partial transparency breaks with structural initialization (how could one provide for hidden fields?). An idiomatic workaround is to model the desired field structure with a public-facing interface.
+
Struct and tuple types are declared with struct[<fields>] and tuple[<fields>], respectively. Their declarations make them look similar at a glance, but they differ fairly fundamentally. Structs are unordered, and every field must be named. They may be constructed with {} brackets. Tuples are ordered and so field names are optional - names are just syntactic sugar for positional access (foo.0, bar.1, ...). Tuples are constructed with () parentheses: and also may be declared with such, as syntactic sugar for tuple[...].
+
It is worth noting that there is no concept of pub at a field level on structs - a type is either fully transparent, or fully opaque. This is because such partial transparency breaks with structural initialization (how could one provide for hidden fields?). However, the @[opaque] attribute allows for expressing that the internal fields of a struct are not to be accessed or initialized: this, however, is only a compiler warning and can be totally suppressed with @[allow(opaque)].
type Expr = union
Literal(int)
Variable(str)
@@ -323,18 +380,21 @@ print a.b # world
Union types are composed of a list of variants. Each variant has a tag and an inner type the union wraps over. Before the inner type can be accessed, the tag must be pattern matched upon, in order to handle all possible values. These are also known as sum types or tagged unions in other languages.
Union types are the bread and butter of structural pattern matching. Composed with structs and tuples, unions provide for a very general programming construct commonly referred to as an algebraic data type.
This is often useful as an idiomatic and safer replacement for inheritance.
-
pub type Iter[T] = interface
+
+
Enum types are similarly composed of a list of variants. These variants, however, are static values: assigned at compile-time, and represented under the hood by a single integer. They function similarly to unions, and can be passed through to functions and pattern matched upon, however their underlying simplicity and default values mean they are much more useful for collecting constants and acting as flags than anything else.
pub type Iter[T] = class
next(mut Self): T?
-pub type Peek[T] = interface
+pub type Peek[T] = class
next(mut Self): T?
peek(mut Self): T?
peek_nth(mut Self, int): T?
-
Interface types function much as type classes in Haskell or traits in Rust do. They are not concrete types, and cannot be constructed - instead, their utility is via indirection, as parameters or as ref types, providing constraints that some concrete type must meet. They consist of a list of function signatures, implementations of which must exist for the given type in order to compile.
-
Their major difference, however, is that Puck's interfaces are implicit: there is no impl block that implementations of their associated functions have to go under. If functions for a concrete type exist satisfying some interface, the type implements that interface. This does run the risk of accidentally implementing an interface one does not desire to, but the author believes such situations are few and far between, well worth the decreased syntactic and semantic complexity, and mitigatable with tactical usage of the distinct keyword.
-
As the compiler makes no such distinction between fields and single-argument functions on a type when determining identifier conflicts, interfaces similarly make no such distinction. They do distinguish mutable and immutable parameters, those being part of the type signature.
-
Interfaces are widely used throughout the standard library to provide general implementations of such conveniences like iteration, debug and display printing, generic error handling, and much more.
+
Class types function much as type classes in Haskell or traits in Rust do. They are not concrete types, and cannot be constructed - instead, their utility is via indirection, as parameters in functions or as ref types in structures, providing constraints that some concrete type must meet. They consist of a list of function signatures, implementations of which must exist for the given type passed in in order to compile.
+
Their major difference, however, is that Puck's classes are implicit: there is no impl block that implementations of their associated functions have to go under. If functions for a concrete type exist satisfying some class, the type implements that class. This does run the risk of accidentally implementing a class one does not desire to, but the author believes such situations are few and far between and well worth the decreased syntactic and semantic complexity. As a result, however, classes are entirely unable to guarantee any invariants hold (like PartialOrd or Ord in Rust do).
+
As the compiler makes no such distinction between fields and single-argument functions on a type when determining identifier conflicts, classes similarly make no such distinction. They do distinguish borrowed/mutable/owned parameters, those being part of the type signature.
+
Classes are widely used throughout the standard library to provide general implementations of such conveniences like iteration, debug and display printing, generic error handling, and much more.
There is little difference between a function, macro, and operator call. There are only a few forms such calls can take, too, though notably more than most other languages (due to, among other things, uniform function call syntax): hence this section.
+
# The standard, unambiguous call.
+routine(1, 2, 3, 4)
+# The method call syntax equivalent.
+1.routine(2, 3, 4)
+# A block-based call. This is only really useful for macros taking in a body.
+routine
+ 1
+ 2
+ 3
+ 4
+# A parentheses-less call. This is only really useful for `print` and `dbg`.
+# Only valid at the start of a line.
+routine 1, 2, 3, 4
+
+
Binary operators have some special rules.
+
# Valid call syntaxes for binary operators. What can constitute a binary
+# operator is constrained for parsing's sake. Whitespace is optional.
+1 + 2
+1+2
++ 1, 2 # Only valid at the start of a line. Also, don't do this.
++(1, 2)
+
+
As do unary operators.
+
# The standard call for unary operators. Postfix.
+1?
+?(1)
+
+
Method call syntax has a number of advantages: notably that it can be chained: acting as a natural pipe operator. Redundant parenthesis can also be omitted.
+
# The following statements are equivalent:
+foo.bar.baz
+foo().bar().baz()
+baz(bar(foo))
+baz
+ bar
+ foo
+baz bar(foo)
+baz foo.bar
+
The tokens =, then, do, of, else, block, const, block X, and X (where X is an identifier) are scope tokens. They denote a new scope for their associated expressions (functions/macros/declarations, control flow, loops). The tokens ,, . (notably not ...), and all default binary operators (notably not not) are continuation tokens. An expression beginning or ending in one of them would always be a syntactic error.
+
Line breaks are treated as the end of a statement, with several exceptions.
+
pub func foo() =
+ print "Hello, world!"
+ print "This is from a function."
+
+pub func inline_decl() = print "Hello, world!"
+
+
Indented lines following a line ending in a scope token are treated as belonging to a new scope. That is, indented lines following a line ending in a scope token form the body of the expression associated with the scope token.
+
Indentation is not obligatory after a scope token. However, this necessarily constrains the body of the associated expression to one line: no lines following will be treated as an extension of the body, only the expression associated with the original scope token. (This may change in the future.)
+
pub func foo(really_long_parameter: ReallyLongType,
+another_really_long_parameter: AnotherReallyLongType) = # no indentation! this is ok
+ print really_long_parameter # this line is indented relative to the first line
+ print really_long_type
+
+
Lines following a line ending in a continuation token (and, additionally not and () are treated as a continuation of that line and can have any level of indentation (even negative). If they end in a scope token, however, the following lines must be indented relative to the indentation of the previous line.
+
let really_long_parameter: ReallyLongType = ...
+let another_really_long_parameter: AnotherReallyLongType = ...
+
+really_long_parameter
+ .foo(another_really_long_parameter) # some indentation! this is ok
+
+
Lines beginning in a continuation token (and, additionally )), too, are treated as a continuation of the previous line and can have any level of indentation. If they end in a scope token, the following lines must be indented relative to the indentation of the previous line.
+
pub func foo() =
+ print "Hello, world!"
+pub func bar() = # this line is no longer in the above scope.
+ print "Another function declaration."
+
+
Dedented lines not beginning or ending with a continuation token are treated as no longer in the previous scope, returning to the scope of the according indentation level.
+
if cond then this
+else that
+
+match cond
+of this then ...
+of that then ...
+
+
A line beginning with a scope token is treated as attached to the previous expression.
+
# Technically allowed. Please don't do this.
+let foo
+= ...
+
+if cond then if cond then this
+else that
+
+for i
+in iterable
+do ...
+
+match foo of this then ...
+of that then ...
+
+match foo of this
+then ...
+of that then ...
+
+
This can lead to some ugly possibilities for formatting that are best avoided.
+
# Much preferred.
+
+let foo =
+ ...
+let foo = ...
+
+if cond then
+ if cond then
+ this
+else that
+if cond then
+ if cond then this
+else that
+
+for i in iterable do
+ ...
+for i in iterable do ...
+
+match foo
+of this then ...
+of that then ...
+
+
The indentation rules are complex, but the effect is such that long statements can be broken almost anywhere.
First, a word on the distinction between expressions and statements. Expressions return a value. Statements do not. That is all.
+
There are some syntactic constructs unambiguously recognizable as statements: all declarations, modules, and use statements. There are no syntactic constructs unambiguously recognizable as expressions. As calls returning void are treated as statements, and expressions that return a type could possibly return void, there is no explicit distinction between expressions and statements made in the parser: or anywhere before type-checking.
+
Expressions can go almost anywhere. Our indentation rules above allow for it.
+
# Some different formulations of valid expressions.
+
+if cond then
+ this
+else
+ that
+
+if cond then this
+else that
+
+if cond
+then this
+else that
+
+if cond then this else that
+
+let foo =
+ if cond then
+ this
+ else
+ that
+
+
# Some different formulations of *invalid* expressions.
+# These primarily break the rule that everything following a scope token
+# (ex. `=`, `do`, `then`) not at the end of the line must be self-contained.
+
+let foo = if cond then
+ this
+ else
+ that
+
+let foo = if cond then this
+ else that
+
+let foo = if cond then this
+else that
+
+# todo: how to handle this?
+if cond then if cond then that
+else that
+
+# shrimple
+if cond then
+ if cond then that
+else that
+
+# this should be ok
+if cond then this
+else that
+
+match foo of
+this then ...
+of that then ...
+
We now shall take a look at a more formal description of Puck's syntax.
+
We now shall take a look at a more formal description of Puck's syntax.
Syntax rules are described in extended Backus–Naur form (EBNF): however, most rules surrounding whitespace, and scope, and line breaks, are modified to how they would appear after a lexing step.
All arguments to functions must have a type. This is resolved at the semantic level, however. (Arguments to macros may lack types. This signifies a generic node.)
char: a distinct alias to u32. For working with Unicode.
-
str: a string type. mutable. internally a byte-array: externally a char-array.
-
void: an internal type designating the absence of a value. often elided.
-
never: a type that denotes functions that do not return. distinct from returning nothing.
+
char: an alias to u32. For working with Unicode.
+
str: a string type. mutable. packed: internally a byte-array, externally a char-array.
+
void: an internal type designating the absence of a value. often elided.
+
never: a type that denotes functions that do not return. distinct from returning nothing.
bool and int/uint/float and siblings (and subsequently byte and char) are all considered primitive types and are always copied (unless passed as mutable). More on when parameters are passed by value vs. passed by reference can be found in the memory management document.
-
Primitive types combine with str, void, and never to form basic types. void and never will rarely be referenced by name: instead, the absence of a type typically implicitly denotes one or the other. Still, having a name is helpful in some situations.
+
Primitive types, alongside str, void, and never, form basic types. void and never will rarely be referenced by name: instead, the absence of a type typically implicitly denotes one or the other. Still, having a name is helpful in some situations.
They are also quite complicated. Puck has full support for Unicode and wishes to be intuitive, performant, and safe, as all languages wish to be. Strings present a problem that much effort has been expended on in (primarily) Swift and Rust to solve.
Abstract types, broadly speaking, are types described by their behavior rather than their implementation. They are more commonly know as abstract data types: which is confusingly similar to "algebraic data types", another term for the advanced types they are built out of under the hood. We refer to them here as "abstract types" to mitigate some confusion.
+
Abstract types, broadly speaking, are types described by their behavior rather than their implementation. They are more commonly know as abstract data types: which is confusingly similar to "algebraic data types", another term for the advanced types they are built out of under the hood. We refer to them here as "abstract types" to mitigate some confusion.
array[S, T]: Fixed-size arrays. Can only contain one type T. Of a fixed size S and cannot grow/shrink, but can mutate. Initialized in-place with [a, b, c].
-
list[T]: Dynamic arrays. Can only contain one type T. May grow/shrink dynamically. Initialized in-place with [a, b, c]. (this is the same as arrays!)
-
slice[T]: Slices. Used to represent a "view" into some sequence of elements of type T. Cannot be directly constructed: they are unsized. Cannot grow/shrink, but their elements may be accessed and mutated. As they are underlyingly a reference to an array or list, they must not outlive the data they reference: this is non-trivial, and so slices interact in complex ways with the memory management system.
-
str: Strings. Described above. They are alternatively treated as either list[byte] or list[char], depending on who's asking. Initialized in-place with "abc".
+
array[T, size]: Fixed-size arrays. Can only contain one type T. Of a fixed size size and cannot grow/shrink, but can mutate. Initialized in-place with [a, b, c].
+
list[T]: Dynamic arrays. Can only contain one type T. May grow/shrink dynamically. Initialized in-place with [a, b, c]. (this is the same as arrays!)
+
slice[T]: Slices. Used to represent a "view" into some sequence of elements of type T. Cannot be directly constructed: they are unsized. Cannot grow/shrink, but their elements may be accessed and mutated. As they are underlyingly a reference to an array or list, they must not outlive the data they reference: this is non-trivial, and so slices interact in complex ways with the memory management system.
+
str: Strings. Described above. They are alternatively treated as either list[byte] or list[char], depending on who's asking. Initialized in-place with "abc".
These iterable types are commonly used, and bits and pieces of compiler magic are used here and there (mostly around initialization, and ownership) to ease use. All of these types are some sort of sequence: and implement the Iter interface, and so can be iterated (hence the name).
@@ -255,12 +254,12 @@ These are monomorphized into more specific functions at compile-time if needed.<
Parameter types can be one-of:
mutable: func foo(a: mut str): Marks a parameter as mutable (parameters are immutable by default). Passed as a ref if not one already.
-
static: func foo(a: static str): Denotes a parameter whose value must be known at compile-time. Useful in macros, and with when for writing generic code.
+
constant: func foo(a: const str): Denotes a parameter whose value must be known at compile-time. Useful in macros, and with when for writing generic code.
generic: func foo[T](a: list[T], b: T): The standard implementation of generics, where a parameter's exact type is not listed, and instead statically dispatched based on usage.
constrained: func foo(a: str | int | float): A basic implementation of generics, where a parameter can be one-of several listed types. The only allowed operations on such parameters are those shared by each type. Makes for particularly straightforward monomorphization.
functions: func foo(a: (int, int) -> int): First-class functions. All functions are first class - function declarations implicitly have this type, and may be bound in variable declarations. However, the function type is only terribly useful as a parameter type.
slices: func foo(a: slice[...]): Slices of existing lists, strings, and arrays. Generic over length. These are references under the hood, may be either immutable or mutable (with mut), and interact non-trivially with Puck's ownership system.
-
interfaces: func foo(a: Stack[int]): Implicit typeclasses. More in the interfaces section.
+
classes: func foo(a: Stack[int]): Implicit typeclasses. More in the classes section.
ex. for above: type Stack[T] = interface[push(mut Self, T); pop(mut Self): T]
@@ -270,33 +269,34 @@ These are monomorphized into more specific functions at compile-time if needed.<
Several of these parameter types - specifically, slices, functions, and interfaces - share a common trait: they are not sized. The exact size of the type is not generally known until compilation - and in some cases, not even during compilation! As the size is not always rigorously known, problems arise when attempting to construct these parameter types or compose them with other types: and so this is disallowed. They may still be used with indirection, however - detailed in the section on reference types.
# fully generic. monomorphizes based on usage.
+func add[T](a: list[T], b: T) = a.push(b)
-func length[T](a: T) =
- return a.len # monomorphizes based on usage.
- # lots of things use .len, but only a few called by this do.
- # throws a warning if exported for lack of specitivity.
+# constrained generics. restricts possible operations to the intersection
+# of defined methods on each type.
+func length[T](a: str | list[T]) =
+ a.len # both strings and lists have a `len` method
-func length(a: str | list) =
- return a.len
+# alternative formulation: place the constraint on a generic parameter.
+# this ensures both a and b are of the *same* type.
+func add[T: int | float](a: T, b: T) = a + b
-
The syntax for generics is func, ident, followed by the names of the generic parameters in brackets [T, U, V], followed by the function's parameters (which may then refer to the generic types).
-Generics are replaced with concrete types at compile time (monomorphization) based on their usage in function calls within the main function body.
+
The syntax for generics is func, ident, followed by the names of the generic parameters in brackets [T, U, V], followed by the function's parameters (which may then refer to the generic types). Generics are replaced with concrete types at compile time (monomorphization) based on their usage in function calls within the main function body.
Constrained generics have two syntaxes: the constraint can be defined directly on a parameter, leaving off the [T] box, or it may be defined within the box as [T: int | float] for easy reuse in the parameters.
-
Other constructions like modules and type declarations themselves may also be generic.
+
Other constructions like type declarations themselves may also be generic over types. In the future, modules also may be generic: whether that is to be over types or over other modules is to be determined.
Types are typically constructed by value on the stack. That is, without any level of indirection: and so type declarations that recursively refer to one another, or involve unsized types (notably including parameter types), would not be allowed. However, Puck provides two avenues for indirection.
+
Types are typically constructed by value on the stack. That is, without any level of indirection: and so type declarations that recursively refer to one another, or involve unsized types (notably including parameter types), would not be allowed. However, Puck provides several avenues for indirection.
Reference types can be one-of:
-
ref T: An automatically-managed reference to type T. This is a pointer of size uint (native).
-
ptr T: A manually-managed pointer to type T. (very) unsafe. The compiler will yell at you.
+
ref T: An owned reference to a type T. This is a pointer of size uint (native).
+
refc T: A reference-counted reference to a type T. This allows escaping the borrow checker.
+
ptr T: A manually-managed pointer to a type T. (very) unsafe. The compiler will yell at you.
type BinaryTree = ref struct
left: BinaryTree
right: BinaryTree
-type AbstractTree[T] = interface
+type AbstractTree[T] = class
func left(self: Self): Option[AbstractTree[T]]
func right(self: Self): Option[AbstractTree[T]]
func data(self: Self): T
@@ -311,57 +311,61 @@ type UnsafeTree = struct
right: ptr UnsafeTree
The ref prefix may be placed at the top level of type declarations, or inside on a field of a structural type. ref types may often be more efficient when dealing with large data structures. They also provide for the usage of unsized types (functions, interfaces, slices) within type declarations.
-
The compiler abstracts over ref types to provide optimization for reference counts: and so a distinction between Rc/Arc/Box is not needed. Furthermore, access implicitly dereferences (with address access available via .addr), and so a * dereference operator is also not needed. Much care has been given to make references efficient and safe, and so ptr should be avoided if at all possible. The compiler will yell at you if you use it (or any other unsafe features).
The compiler abstracts over ref types to provide optimization for reference counts: and so a distinction between Rc/Arc/Box is not needed. Furthermore, access implicitly dereferences (with address access available via .addr), and so a * dereference operator is also not needed.
+
Much care has been given to make references efficient and safe, and so ptr should be avoided if at all possible. They are only usable inside functions explicitly marked with #[safe].
+
The implementations of reference types are delved into in further detail in the memory management document.
The type keyword is used to declare aliases to custom data types. These types are algebraic: they function by composition. Algebraic data types can be one-of:
+
The type keyword is used to declare aliases to custom data types. These types are algebraic: they function by composition. Such algebraic data types can be one-of:
struct: An unordered, named collection of types. May have default values.
tuple: An ordered collection of types. Optionally named.
enum: Ordinal labels, that may hold values. Their default values are their ordinality.
union: Powerful matchable tagged unions a la Rust. Sum types.
class: Implicit type classes. User-defined duck typing.
-
There also exist distinct types: while type declarations define an alias to an existing or new type, distinct types define a type that must be explicitly converted to/from. This is useful for having some level of separation from the implicit interfaces that abound.
+
All functions defined on the original type carry over. If this is not desired, the newtype paradigm is preferred: declaring a single-field struct and copying function declarations over.
+
Types may be explicitly to and from via the Coerce and Convert classes and provided from and to functions.
Structs are an unordered collection of named types.
-
They are declared with struct[identifier: Type, ...] and initialized with brackets: {field: "value", another: 500}.
-
type LinkedNode[T] = struct
- previous, next: Option[ref LinkedNode[T]]
+
They are declared with struct[identifier: Type, ...] and initialized with brackets: { field = "value", another = 500}. Structs are structural: while the type system is fundamentally nominal, and different type declarations are treated as distinct, a struct object initialized with {} is usable in any context that expects a struct with the same fields.
+
type LinkedNode[T] = ref struct
+ previous: Option[LinkedNode[T]]
+ next: Option[LinkedNode[T]]
data: T
-let node = {
- previous: None, next: None
- data: 413
+let node = { # inferred type: LinkedNode[int], from prints_data call
+ previous = None, next = None
+ data = 413
}
func pretty_print(node: LinkedNode[int]) =
print node.data
- if node.next of Some(node):
+ if node.next of Some(node) then
node.pretty_print()
# structural typing!
prints_data(node)
-
Structs are structural and so structs composed entirely of fields with the same signature (identical in name and type) are considered equivalent.
-This is part of a broader structural trend in the type system, and is discussed in detail in the section on subtyping.
Tuples are an ordered collection of either named and/or unnamed types.
-
They are declared with tuple[Type, identifier: Type, ...] and initialized with parentheses: (413, "hello", value: 40000). Syntax sugar allows for them to be declared with () as well.
-
They are exclusively ordered - named types within tuples are just syntax sugar for positional access. Passing a fully unnamed tuple into a context that expects a tuple with a named parameter is allowed so long as the types line up in order.
+
They are declared with tuple[Type, identifier: Type, ...] and initialized with parentheses: (413, "hello", value: 40000). Syntactic sugar allows for them to be declared with () as well.
+
They are exclusively ordered - named types within tuples are just syntactic sugar for positional access. Passing a fully unnamed tuple into a context that expects a tuple with a named parameter is allowed (so long as the types line up).
Tuples are particularly useful for "on-the-fly" types. Creating type aliases to tuples is discouraged - structs are generally a better choice for custom type declarations.
+
Tuples are particularly useful for "on-the-fly" types. Creating type declarations to tuples is discouraged - structs are generally a better choice, as they are fully named, support default values, and may have their layout optimized by the compiler.
Enums are ordinal labels that may have associated values.
-
They are declared with enum[Label, AnotherLabel = 4, ...] and are never initialized (their values are known statically).
-Enums may be accessed directly by their label, and are ordinal and iterable regardless of their associated value. They are useful in collecting large numbers of "magic values", that would otherwise be constants.
+
They are declared with enum[Label, AnotherLabel = 4, ...] and are never initialized (their values are known statically). Enums may be accessed directly by their label, and are ordinal and iterable regardless of their associated value. They are useful in collecting large numbers of "magic values" that would otherwise be constants.
type Keys = enum
Left, Right, Up, Down
- A = "a"
- B = "b"
+ A = "a"
+ B = "b"
In the case of an identifier conflict (with other enum labels, or types, or...) they must be prefixed with the name of their associated type (separated by a dot). This is standard for identifier conflicts: and is discussed in more detail in the modules document.
@@ -387,83 +391,90 @@ type Expr = ref union
func eval(context: mut HashTable[Ident, Value], expr: Expr): Result[Value]
match expr
- of Literal(value): Okay(value)
- of Variable(ident):
- context.get(ident).err("Variable not in context")
- of Application(body, arg):
+ of Literal(value) then Okay(value)
+ of Variable(ident) then
+ context.get(ident).err("Variable not in context")
+ of Application(body, arg) then
if body of Abstraction(param, body as inner_body):
context.set(param, context.eval(arg)?) # from std.tables
context.eval(inner_body)
- else:
- Error("Expected Abstraction, found {}".fmt(body))
+ else
+ Error("Expected Abstraction, found {}".fmt(body))
of Conditional(condition, then_case, else_case):
- if context.eval(condition)? == "true":
+ if context.eval(condition)? == "true" then
context.eval(then_case)
else:
context.eval(else_case)
- of expr:
- Error("Invalid expression {}".fmt(expr))
+ of expr then
+ Error("Invalid expression {}".fmt(expr))
The match statement takes exclusively a list of of sub-expressions, and checks for exhaustivity. The expr of Type(binding) syntax can be reused as a conditional, in if statements and elsewhere.
The ofoperator is similar to the is operator in that it queries type equality, returning a boolean. However, unbound identifiers within of expressions are bound to appropriate values (if matched) and injected into the scope. This allows for succinct handling of union types in situations where match is overkill.
-
Each branch of a match expression can also have a guard: an arbitrary conditional that must be met in order for it to match. Guards are written as where cond and immediately follow the last pattern in an of branch, preceding the colon.
Interfaces can be thought of as analogous to Rust's traits, without explicit impl blocks and without need for the derive macro. Types that have functions fulfilling the interface requirements implicitly implement the associated interface.
-
The interface type is composed of a list of function signatures that refer to the special type Self that must exist for a type to be valid. The special type Self is replaced with the concrete type at compile time in order to typecheck. They are declared with interface[signature, ...].
-
type Stack[T] = interface
+
Each branch of a match expression can also have a guard: an arbitrary conditional that must be met in order for it to match. Guards are written as where cond and immediately follow the last pattern in an of branch, preceding then.
Classes can be thought of as analogous to Rust's traits: without explicit impl blocks and without need for the derive macro. Types that have functions defined on them fulfilling the class requirements implicitly implement the associated class.
+
The class type is composed of a list of function signatures that refer to the special type Self that must exist for a type to be valid. The special type Self is replaced with the concrete type at compile time in order to typecheck. They are declared with class[signature, ...].
+
type Stack[T] = class
push(self: mut Self, val: T)
pop(self: mut Self): T
- peek(self: Self): T
+ peek(self: lent Self): lent T
func takes_any_stack(stack: Stack[int]) =
- # only stack.push, stack.pop, and stack.peek are available methods
+ # only stack.push, stack.pop, and stack.peek are available, regardless of the concrete type passed
-
Differing from Rust, Haskell, and many others, there is no explicit impl block. If there exist functions for a type that satisfy all of an interface's signatures, it is considered to match and the interface typechecks. This may seem strange and ambiguous - but again, static typing and uniform function call syntax help make this a more reasonable design. The purpose of explicit impl blocks in ex. Rust is three-fold: to provide a limited form of uniform function call syntax; to explicitly group together associated code; and to disambiguate. UFCS provides for the first, the module system provides for the second, and the third is proposed to not matter.
-
Interfaces cannot be constructed because they are unsized. They serve purely as a list of valid operations on a type within a context: no information about their memory layout is relevant. The concrete type fulfilling an interface is known at compile time, however, and so there are no issues surrounding interfaces as parameters, just when attempted to be used as (part of) a concrete type. They can be used as part of a concrete type with indirection, however: type Foo = struct[a: int, b: ref interface[...]] is perfectly valid.
-
Interfaces also cannot extend or rely upon other interfaces in any way. There is no concept of an interface extending an interface. There is no concept of a parameter satisfying two interfaces. In the author's experience, while such constructions are powerful, they are also an immense source of complexity, leading to less-than-useful interface hierarchies seen in languages like Java, and yes, Rust.
-
Instead, if one wishes to form an interface that also satisfies another interface, they must include all of the other interface's associated functions within the new interface. Given that interfaces overwhelmingly only have a handful of associated functions, and if you're using more than one interface you really should be using a concrete type, the hope is that this will provide explicitness.
-
-
Interfaces compose with modules to offer fine grained access control.
Any type can be declared as an alias to a type simply by assigning it to such. All functions defined on the original type carry over, and functions expecting one type may receive the other with no issues.
-
type Float = float
+
Differing from Rust, Haskell, and many others, there is no explicit impl block. If there exist functions for a type that satisfy all of a class's signatures, it is considered to match and the class typechecks. This may seem strange and ambiguous - but again, static typing and uniform function call syntax help make this a more reasonable design. The purpose of explicit impl blocks in ex. Rust is three-fold: to provide a limited form of uniform function call syntax; to explicitly group together associated code; and to disambiguate. UFCS provides for the first, the module system provides for the second, and type-based disambiguation provides for the third, with such information exposed to the user via the language server protocol.
+
type Set[T] = class
+ in(lent Self, T): bool
+ add(mut Self, T)
+ remove(mut Self, T): Option[T]
+
+type Foo = struct
+ a: int
+ b: ref Set[int] # indirection: now perfectly valid
-
It is no more than an alias. When explicit conversion between types is desired and functions carrying over is undesired, distinct types may be used.
Classes cannot be constructed, as they are unsized. They serve purely as a list of valid operations on a type: no information about their memory layout is relevant. The concrete type fulfilling a class is known at compile time, however, and so there are no issues surrounding the use of classes as parameters, just when attempted to be used as (part of) a concrete type in ex. a struct. They can be used with indirection, however: as references are sized (consisting of a memory address).
+
## The Display class. Any type implementing `str` is printable.
+## Any type that is Display must necessarily also implement Debug.
+pub type Display = class
+ str(Self): str
+ dbg(Self): str
+
+## The Debug class. Broadly implemented for every type with compiler magic.
+## Types can (and should) override the generic implementations.
+pub type Debug = class
+ dbg(Self): str
-
Types then must be explicitly converted via constructors.
+
Classes also cannot extend or rely upon other classes in any way, nor is there any concept of a parameter satisfying two classes. In the author's experience, while such constructions are powerful, they are also an immense source of complexity, leading to less-than-useful hierarchies seen in languages like Java, and yes, Rust. Instead, if one wishes to form an class that also satisfies another class, they must name a new class that explicitly includes all of the other class's associated functions. Given that classes in Puck overwhelmingly only have a small handful of associated functions, and if you're using more than one class you really should be using a concrete type: the hope is that this will provide for explicitness and reduce complexity.
+
Classes compose well with modules to offer fine grained access control.
Puck does not have any concept of null: all values must be initialized.
-But always explicitly initializing types is syntactically verbose, and so most types have an associated "default value".
+But always explicitly initializing types is syntactically verbose, and so most types have an associated "default value".
Default values:
bool: false
int, uint, etc: 0
float, etc: 0.0
char: '\0'
-
str: ""
+
str: ""
void, never: unconstructable
array[T], list[T]: []
set[T], table[T, U]: {}
tuple[T, U, ...]: (default values of its fields)
struct[T, U, ...]: {default values of its fields}
-
enum[One, Two, ...]: <first label>
+
enum[One, Two, ...]: disallowed
union[T, U, ...]: disallowed
slice[T], func: disallowed
-
ref, ptr: disallowed
+
ref, refc, ptr: disallowed
-
For unions, slices, references, and pointers, this is a bit trickier. They all have no reasonable "default" for these types aside from null.
+
For unions, slices, references, and pointers, this is a bit trickier. They all have no reasonable "default" for these types aside from null.
Instead of giving in, the compiler instead disallows any non-initializations or other cases in which a default value would be inserted.
Puck supports overloading - that is, there may exist multiple functions, or multiple types, or multiple modules, so long as they have the same signature.
-The signature of a function / type / module is important. Interfaces, among other constructs, depend on the user having some understanding of what the compiler considers to be a signature.
-So, it is stated here explicitly:
+
Puck supports overloading - that is, there may exist multiple functions, or multiple types, or multiple modules, with the same name - so long as they have a different signature.
+The signature of a function/type/module is important. Classes, among other constructs, depend on the user having some understanding of what the compiler considers to be a signature. So we state it here explicitly:
-
The signature of a function is its name and the types of each of its parameters, in order. Optional parameters are ignored. Generic parameters are ???
+
The signature of a function is its name and the types of each of its parameters, in order, ignoring optional parameters. Generic parameters are ???
ex. ...
@@ -475,62 +486,8 @@ So, it is stated here explicitly:
The signature of a module is just its name. This may change in the future.
Mention of subtyping has been on occasion in contexts surrounding structural type systems, particularly the section on distinct types, but no explicit description of what the subtyping rules are have been given.
-
Subtyping is the implicit conversion of compatible types, usually in a one-way direction. The following types are implicitly convertible:
Puck is not an object-oriented language. Idiomatic design patterns in object-oriented languages are harder to accomplish and not idiomatic here.
-
But, Puck has a number of features that somewhat support the object-oriented paradigm, including:
-
-
uniform function call syntax
-
structural typing / subtyping
-
interfaces
-
-
type Building = struct
- size: struct[length, width: uint]
- color: enum[Red, Blue, Green]
- location: tuple[longitude, latitude: float]
-
-type House = struct
- size: struct[length, width: uint]
- color: enum[Red, Blue, Green]
- location: tuple[longitude, latitude: float]
- occupant: str
-
-func init(_: type[House]): House =
- { size: {length, width: 500}, color: Red
- location: (0.0, 0.0), occupant: "Barry" }
-
-func address(building: Building): str =
- let number = int(building.location.0 / building.location.1).abs
- let street = "Logan Lane"
- return number.str & " " & street
-
-# subtyping! methods!
-print House.init().address()
-
-func address(house: House): str =
- let number = int(house.location.0 - house.location.1).abs
- let street = "Logan Lane"
- return number.str & " " & street
-
-# overriding! (will warn)
-print address(House.init())
-
-# abstract types! inheritance!
-type Addressable = interface for Building
- func address(self: Self)
-
-
These features may compose into code that closely resembles its object-oriented counterpart. But make no mistake! Puck is static first and functional somewhere in there: dynamic dispatch and the like are not accessible (currently).
@@ -561,22 +518,6 @@ type Addressable = interface for Building
-
-
diff --git a/docs/book/highlight.js b/docs/book/highlight.js
index 3256c00..2661c0e 100644
--- a/docs/book/highlight.js
+++ b/docs/book/highlight.js
@@ -1,53 +1,4913 @@
-/*
- Highlight.js 10.1.1 (93fd0d73)
+/*!
+ Highlight.js v11.9.0 (git: 215b7639e5)
+ (c) 2006-2023 undefined and other contributors
License: BSD-3-Clause
- Copyright (c) 2006-2020, Ivan Sagalaev
-*/
-var hljs=function(){"use strict";function e(n){Object.freeze(n);var t="function"==typeof n;return Object.getOwnPropertyNames(n).forEach((function(r){!Object.hasOwnProperty.call(n,r)||null===n[r]||"object"!=typeof n[r]&&"function"!=typeof n[r]||t&&("caller"===r||"callee"===r||"arguments"===r)||Object.isFrozen(n[r])||e(n[r])})),n}class n{constructor(e){void 0===e.data&&(e.data={}),this.data=e.data}ignoreMatch(){this.ignore=!0}}function t(e){return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'")}function r(e,...n){var t={};for(const n in e)t[n]=e[n];return n.forEach((function(e){for(const n in e)t[n]=e[n]})),t}function a(e){return e.nodeName.toLowerCase()}var i=Object.freeze({__proto__:null,escapeHTML:t,inherit:r,nodeStream:function(e){var n=[];return function e(t,r){for(var i=t.firstChild;i;i=i.nextSibling)3===i.nodeType?r+=i.nodeValue.length:1===i.nodeType&&(n.push({event:"start",offset:r,node:i}),r=e(i,r),a(i).match(/br|hr|img|input/)||n.push({event:"stop",offset:r,node:i}));return r}(e,0),n},mergeStreams:function(e,n,r){var i=0,s="",o=[];function l(){return e.length&&n.length?e[0].offset!==n[0].offset?e[0].offset"}function u(e){s+=""+a(e)+">"}function d(e){("start"===e.event?c:u)(e.node)}for(;e.length||n.length;){var g=l();if(s+=t(r.substring(i,g[0].offset)),i=g[0].offset,g===e){o.reverse().forEach(u);do{d(g.splice(0,1)[0]),g=l()}while(g===e&&g.length&&g[0].offset===i);o.reverse().forEach(c)}else"start"===g[0].event?o.push(g[0].node):o.pop(),d(g.splice(0,1)[0])}return s+t(r.substr(i))}});const s="",o=e=>!!e.kind;class l{constructor(e,n){this.buffer="",this.classPrefix=n.classPrefix,e.walk(this)}addText(e){this.buffer+=t(e)}openNode(e){if(!o(e))return;let n=e.kind;e.sublanguage||(n=`${this.classPrefix}${n}`),this.span(n)}closeNode(e){o(e)&&(this.buffer+=s)}value(){return this.buffer}span(e){this.buffer+=``}}class c{constructor(){this.rootNode={children:[]},this.stack=[this.rootNode]}get top(){return this.stack[this.stack.length-1]}get root(){return this.rootNode}add(e){this.top.children.push(e)}openNode(e){const n={kind:e,children:[]};this.add(n),this.stack.push(n)}closeNode(){if(this.stack.length>1)return this.stack.pop()}closeAllNodes(){for(;this.closeNode(););}toJSON(){return JSON.stringify(this.rootNode,null,4)}walk(e){return this.constructor._walk(e,this.rootNode)}static _walk(e,n){return"string"==typeof n?e.addText(n):n.children&&(e.openNode(n),n.children.forEach(n=>this._walk(e,n)),e.closeNode(n)),e}static _collapse(e){"string"!=typeof e&&e.children&&(e.children.every(e=>"string"==typeof e)?e.children=[e.children.join("")]:e.children.forEach(e=>{c._collapse(e)}))}}class u extends c{constructor(e){super(),this.options=e}addKeyword(e,n){""!==e&&(this.openNode(n),this.addText(e),this.closeNode())}addText(e){""!==e&&this.add(e)}addSublanguage(e,n){const t=e.root;t.kind=n,t.sublanguage=!0,this.add(t)}toHTML(){return new l(this,this.options).value()}finalize(){return!0}}function d(e){return e?"string"==typeof e?e:e.source:null}const g="(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",h={begin:"\\\\[\\s\\S]",relevance:0},f={className:"string",begin:"'",end:"'",illegal:"\\n",contains:[h]},p={className:"string",begin:'"',end:'"',illegal:"\\n",contains:[h]},b={begin:/\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/},m=function(e,n,t={}){var a=r({className:"comment",begin:e,end:n,contains:[]},t);return a.contains.push(b),a.contains.push({className:"doctag",begin:"(?:TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):",relevance:0}),a},v=m("//","$"),x=m("/\\*","\\*/"),E=m("#","$");var _=Object.freeze({__proto__:null,IDENT_RE:"[a-zA-Z]\\w*",UNDERSCORE_IDENT_RE:"[a-zA-Z_]\\w*",NUMBER_RE:"\\b\\d+(\\.\\d+)?",C_NUMBER_RE:g,BINARY_NUMBER_RE:"\\b(0b[01]+)",RE_STARTERS_RE:"!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~",SHEBANG:(e={})=>{const n=/^#![ ]*\//;return e.binary&&(e.begin=function(...e){return e.map(e=>d(e)).join("")}(n,/.*\b/,e.binary,/\b.*/)),r({className:"meta",begin:n,end:/$/,relevance:0,"on:begin":(e,n)=>{0!==e.index&&n.ignoreMatch()}},e)},BACKSLASH_ESCAPE:h,APOS_STRING_MODE:f,QUOTE_STRING_MODE:p,PHRASAL_WORDS_MODE:b,COMMENT:m,C_LINE_COMMENT_MODE:v,C_BLOCK_COMMENT_MODE:x,HASH_COMMENT_MODE:E,NUMBER_MODE:{className:"number",begin:"\\b\\d+(\\.\\d+)?",relevance:0},C_NUMBER_MODE:{className:"number",begin:g,relevance:0},BINARY_NUMBER_MODE:{className:"number",begin:"\\b(0b[01]+)",relevance:0},CSS_NUMBER_MODE:{className:"number",begin:"\\b\\d+(\\.\\d+)?(%|em|ex|ch|rem|vw|vh|vmin|vmax|cm|mm|in|pt|pc|px|deg|grad|rad|turn|s|ms|Hz|kHz|dpi|dpcm|dppx)?",relevance:0},REGEXP_MODE:{begin:/(?=\/[^/\n]*\/)/,contains:[{className:"regexp",begin:/\//,end:/\/[gimuy]*/,illegal:/\n/,contains:[h,{begin:/\[/,end:/\]/,relevance:0,contains:[h]}]}]},TITLE_MODE:{className:"title",begin:"[a-zA-Z]\\w*",relevance:0},UNDERSCORE_TITLE_MODE:{className:"title",begin:"[a-zA-Z_]\\w*",relevance:0},METHOD_GUARD:{begin:"\\.\\s*[a-zA-Z_]\\w*",relevance:0},END_SAME_AS_BEGIN:function(e){return Object.assign(e,{"on:begin":(e,n)=>{n.data._beginMatch=e[1]},"on:end":(e,n)=>{n.data._beginMatch!==e[1]&&n.ignoreMatch()}})}}),N="of and for in not or if then".split(" ");function w(e,n){return n?+n:function(e){return N.includes(e.toLowerCase())}(e)?0:1}const R=t,y=r,{nodeStream:k,mergeStreams:O}=i,M=Symbol("nomatch");return function(t){var a=[],i={},s={},o=[],l=!0,c=/(^(<[^>]+>|\t|)+|\n)/gm,g="Could not find the language '{}', did you forget to load/include a language module?";const h={disableAutodetect:!0,name:"Plain text",contains:[]};var f={noHighlightRe:/^(no-?highlight)$/i,languageDetectRe:/\blang(?:uage)?-([\w-]+)\b/i,classPrefix:"hljs-",tabReplace:null,useBR:!1,languages:null,__emitter:u};function p(e){return f.noHighlightRe.test(e)}function b(e,n,t,r){var a={code:n,language:e};S("before:highlight",a);var i=a.result?a.result:m(a.language,a.code,t,r);return i.code=a.code,S("after:highlight",i),i}function m(e,t,a,s){var o=t;function c(e,n){var t=E.case_insensitive?n[0].toLowerCase():n[0];return Object.prototype.hasOwnProperty.call(e.keywords,t)&&e.keywords[t]}function u(){null!=y.subLanguage?function(){if(""!==A){var e=null;if("string"==typeof y.subLanguage){if(!i[y.subLanguage])return void O.addText(A);e=m(y.subLanguage,A,!0,k[y.subLanguage]),k[y.subLanguage]=e.top}else e=v(A,y.subLanguage.length?y.subLanguage:null);y.relevance>0&&(I+=e.relevance),O.addSublanguage(e.emitter,e.language)}}():function(){if(!y.keywords)return void O.addText(A);let e=0;y.keywordPatternRe.lastIndex=0;let n=y.keywordPatternRe.exec(A),t="";for(;n;){t+=A.substring(e,n.index);const r=c(y,n);if(r){const[e,a]=r;O.addText(t),t="",I+=a,O.addKeyword(n[0],e)}else t+=n[0];e=y.keywordPatternRe.lastIndex,n=y.keywordPatternRe.exec(A)}t+=A.substr(e),O.addText(t)}(),A=""}function h(e){return e.className&&O.openNode(e.className),y=Object.create(e,{parent:{value:y}})}function p(e){return 0===y.matcher.regexIndex?(A+=e[0],1):(L=!0,0)}var b={};function x(t,r){var i=r&&r[0];if(A+=t,null==i)return u(),0;if("begin"===b.type&&"end"===r.type&&b.index===r.index&&""===i){if(A+=o.slice(r.index,r.index+1),!l){const n=Error("0 width match regex");throw n.languageName=e,n.badRule=b.rule,n}return 1}if(b=r,"begin"===r.type)return function(e){var t=e[0],r=e.rule;const a=new n(r),i=[r.__beforeBegin,r["on:begin"]];for(const n of i)if(n&&(n(e,a),a.ignore))return p(t);return r&&r.endSameAsBegin&&(r.endRe=RegExp(t.replace(/[-/\\^$*+?.()|[\]{}]/g,"\\$&"),"m")),r.skip?A+=t:(r.excludeBegin&&(A+=t),u(),r.returnBegin||r.excludeBegin||(A=t)),h(r),r.returnBegin?0:t.length}(r);if("illegal"===r.type&&!a){const e=Error('Illegal lexeme "'+i+'" for mode "'+(y.className||"")+'"');throw e.mode=y,e}if("end"===r.type){var s=function(e){var t=e[0],r=o.substr(e.index),a=function e(t,r,a){let i=function(e,n){var t=e&&e.exec(n);return t&&0===t.index}(t.endRe,a);if(i){if(t["on:end"]){const e=new n(t);t["on:end"](r,e),e.ignore&&(i=!1)}if(i){for(;t.endsParent&&t.parent;)t=t.parent;return t}}if(t.endsWithParent)return e(t.parent,r,a)}(y,e,r);if(!a)return M;var i=y;i.skip?A+=t:(i.returnEnd||i.excludeEnd||(A+=t),u(),i.excludeEnd&&(A=t));do{y.className&&O.closeNode(),y.skip||y.subLanguage||(I+=y.relevance),y=y.parent}while(y!==a.parent);return a.starts&&(a.endSameAsBegin&&(a.starts.endRe=a.endRe),h(a.starts)),i.returnEnd?0:t.length}(r);if(s!==M)return s}if("illegal"===r.type&&""===i)return 1;if(B>1e5&&B>3*r.index)throw Error("potential infinite loop, way more iterations than matches");return A+=i,i.length}var E=T(e);if(!E)throw console.error(g.replace("{}",e)),Error('Unknown language: "'+e+'"');var _=function(e){function n(n,t){return RegExp(d(n),"m"+(e.case_insensitive?"i":"")+(t?"g":""))}class t{constructor(){this.matchIndexes={},this.regexes=[],this.matchAt=1,this.position=0}addRule(e,n){n.position=this.position++,this.matchIndexes[this.matchAt]=n,this.regexes.push([n,e]),this.matchAt+=function(e){return RegExp(e.toString()+"|").exec("").length-1}(e)+1}compile(){0===this.regexes.length&&(this.exec=()=>null);const e=this.regexes.map(e=>e[1]);this.matcherRe=n(function(e,n="|"){for(var t=/\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./,r=0,a="",i=0;i0&&(a+=n),a+="(";o.length>0;){var l=t.exec(o);if(null==l){a+=o;break}a+=o.substring(0,l.index),o=o.substring(l.index+l[0].length),"\\"===l[0][0]&&l[1]?a+="\\"+(+l[1]+s):(a+=l[0],"("===l[0]&&r++)}a+=")"}return a}(e),!0),this.lastIndex=0}exec(e){this.matcherRe.lastIndex=this.lastIndex;const n=this.matcherRe.exec(e);if(!n)return null;const t=n.findIndex((e,n)=>n>0&&void 0!==e),r=this.matchIndexes[t];return n.splice(0,t),Object.assign(n,r)}}class a{constructor(){this.rules=[],this.multiRegexes=[],this.count=0,this.lastIndex=0,this.regexIndex=0}getMatcher(e){if(this.multiRegexes[e])return this.multiRegexes[e];const n=new t;return this.rules.slice(e).forEach(([e,t])=>n.addRule(e,t)),n.compile(),this.multiRegexes[e]=n,n}considerAll(){this.regexIndex=0}addRule(e,n){this.rules.push([e,n]),"begin"===n.type&&this.count++}exec(e){const n=this.getMatcher(this.regexIndex);n.lastIndex=this.lastIndex;const t=n.exec(e);return t&&(this.regexIndex+=t.position+1,this.regexIndex===this.count&&(this.regexIndex=0)),t}}function i(e,n){const t=e.input[e.index-1],r=e.input[e.index+e[0].length];"."!==t&&"."!==r||n.ignoreMatch()}if(e.contains&&e.contains.includes("self"))throw Error("ERR: contains `self` is not supported at the top-level of a language. See documentation.");return function t(s,o){const l=s;if(s.compiled)return l;s.compiled=!0,s.__beforeBegin=null,s.keywords=s.keywords||s.beginKeywords;let c=null;if("object"==typeof s.keywords&&(c=s.keywords.$pattern,delete s.keywords.$pattern),s.keywords&&(s.keywords=function(e,n){var t={};return"string"==typeof e?r("keyword",e):Object.keys(e).forEach((function(n){r(n,e[n])})),t;function r(e,r){n&&(r=r.toLowerCase()),r.split(" ").forEach((function(n){var r=n.split("|");t[r[0]]=[e,w(r[0],r[1])]}))}}(s.keywords,e.case_insensitive)),s.lexemes&&c)throw Error("ERR: Prefer `keywords.$pattern` to `mode.lexemes`, BOTH are not allowed. (see mode reference) ");return l.keywordPatternRe=n(s.lexemes||c||/\w+/,!0),o&&(s.beginKeywords&&(s.begin="\\b("+s.beginKeywords.split(" ").join("|")+")(?=\\b|\\s)",s.__beforeBegin=i),s.begin||(s.begin=/\B|\b/),l.beginRe=n(s.begin),s.endSameAsBegin&&(s.end=s.begin),s.end||s.endsWithParent||(s.end=/\B|\b/),s.end&&(l.endRe=n(s.end)),l.terminator_end=d(s.end)||"",s.endsWithParent&&o.terminator_end&&(l.terminator_end+=(s.end?"|":"")+o.terminator_end)),s.illegal&&(l.illegalRe=n(s.illegal)),void 0===s.relevance&&(s.relevance=1),s.contains||(s.contains=[]),s.contains=[].concat(...s.contains.map((function(e){return function(e){return e.variants&&!e.cached_variants&&(e.cached_variants=e.variants.map((function(n){return r(e,{variants:null},n)}))),e.cached_variants?e.cached_variants:function e(n){return!!n&&(n.endsWithParent||e(n.starts))}(e)?r(e,{starts:e.starts?r(e.starts):null}):Object.isFrozen(e)?r(e):e}("self"===e?s:e)}))),s.contains.forEach((function(e){t(e,l)})),s.starts&&t(s.starts,o),l.matcher=function(e){const n=new a;return e.contains.forEach(e=>n.addRule(e.begin,{rule:e,type:"begin"})),e.terminator_end&&n.addRule(e.terminator_end,{type:"end"}),e.illegal&&n.addRule(e.illegal,{type:"illegal"}),n}(l),l}(e)}(E),N="",y=s||_,k={},O=new f.__emitter(f);!function(){for(var e=[],n=y;n!==E;n=n.parent)n.className&&e.unshift(n.className);e.forEach(e=>O.openNode(e))}();var A="",I=0,S=0,B=0,L=!1;try{for(y.matcher.considerAll();;){B++,L?L=!1:(y.matcher.lastIndex=S,y.matcher.considerAll());const e=y.matcher.exec(o);if(!e)break;const n=x(o.substring(S,e.index),e);S=e.index+n}return x(o.substr(S)),O.closeAllNodes(),O.finalize(),N=O.toHTML(),{relevance:I,value:N,language:e,illegal:!1,emitter:O,top:y}}catch(n){if(n.message&&n.message.includes("Illegal"))return{illegal:!0,illegalBy:{msg:n.message,context:o.slice(S-100,S+100),mode:n.mode},sofar:N,relevance:0,value:R(o),emitter:O};if(l)return{illegal:!1,relevance:0,value:R(o),emitter:O,language:e,top:y,errorRaised:n};throw n}}function v(e,n){n=n||f.languages||Object.keys(i);var t=function(e){const n={relevance:0,emitter:new f.__emitter(f),value:R(e),illegal:!1,top:h};return n.emitter.addText(e),n}(e),r=t;return n.filter(T).filter(I).forEach((function(n){var a=m(n,e,!1);a.language=n,a.relevance>r.relevance&&(r=a),a.relevance>t.relevance&&(r=t,t=a)})),r.language&&(t.second_best=r),t}function x(e){return f.tabReplace||f.useBR?e.replace(c,e=>"\n"===e?f.useBR?" ":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/ /g,"\n"):n=e;const r=n.textContent,a=t?b(t,r,!0):v(r),i=k(n);if(i.length){const e=document.createElement("div");e.innerHTML=a.value,a.value=O(i,k(e),r)}a.value=x(a.value),S("after:highlightBlock",{block:e,result:a}),e.innerHTML=a.value,e.className=function(e,n,t){var r=n?s[n]:t,a=[e.trim()];return e.match(/\bhljs\b/)||a.push("hljs"),e.includes(r)||a.push(r),a.join(" ").trim()}(e.className,t,a.language),e.result={language:a.language,re:a.relevance,relavance:a.relevance},a.second_best&&(e.second_best={language:a.second_best.language,re:a.second_best.relevance,relavance:a.second_best.relevance})}const N=()=>{if(!N.called){N.called=!0;var e=document.querySelectorAll("pre code");a.forEach.call(e,E)}};function T(e){return e=(e||"").toLowerCase(),i[e]||i[s[e]]}function A(e,{languageName:n}){"string"==typeof e&&(e=[e]),e.forEach(e=>{s[e]=n})}function I(e){var n=T(e);return n&&!n.disableAutodetect}function S(e,n){var t=e;o.forEach((function(e){e[t]&&e[t](n)}))}Object.assign(t,{highlight:b,highlightAuto:v,fixMarkup:x,highlightBlock:E,configure:function(e){f=y(f,e)},initHighlighting:N,initHighlightingOnLoad:function(){window.addEventListener("DOMContentLoaded",N,!1)},registerLanguage:function(e,n){var r=null;try{r=n(t)}catch(n){if(console.error("Language definition for '{}' could not be registered.".replace("{}",e)),!l)throw n;console.error(n),r=h}r.name||(r.name=e),i[e]=r,r.rawDefinition=n.bind(null,t),r.aliases&&A(r.aliases,{languageName:e})},listLanguages:function(){return Object.keys(i)},getLanguage:T,registerAliases:A,requireLanguage:function(e){var n=T(e);if(n)return n;throw Error("The '{}' language is required, but not loaded.".replace("{}",e))},autoDetection:I,inherit:y,addPlugin:function(e){o.push(e)}}),t.debugMode=function(){l=!1},t.safeMode=function(){l=!0},t.versionString="10.1.1";for(const n in _)"object"==typeof _[n]&&e(_[n]);return Object.assign(t,_),t}({})}();"object"==typeof exports&&"undefined"!=typeof module&&(module.exports=hljs);
-hljs.registerLanguage("apache",function(){"use strict";return function(e){var n={className:"number",begin:"\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}(:\\d{1,5})?"};return{name:"Apache config",aliases:["apacheconf"],case_insensitive:!0,contains:[e.HASH_COMMENT_MODE,{className:"section",begin:"?",end:">",contains:[n,{className:"number",begin:":\\d{1,5}"},e.inherit(e.QUOTE_STRING_MODE,{relevance:0})]},{className:"attribute",begin:/\w+/,relevance:0,keywords:{nomarkup:"order deny allow setenv rewriterule rewriteengine rewritecond documentroot sethandler errordocument loadmodule options header listen serverroot servername"},starts:{end:/$/,relevance:0,keywords:{literal:"on off all deny allow"},contains:[{className:"meta",begin:"\\s\\[",end:"\\]$"},{className:"variable",begin:"[\\$%]\\{",end:"\\}",contains:["self",{className:"number",begin:"[\\$%]\\d+"}]},n,{className:"number",begin:"\\d+"},e.QUOTE_STRING_MODE]}}],illegal:/\S/}}}());
-hljs.registerLanguage("bash",function(){"use strict";return function(e){const s={};Object.assign(s,{className:"variable",variants:[{begin:/\$[\w\d#@][\w\d_]*/},{begin:/\$\{/,end:/\}/,contains:[{begin:/:-/,contains:[s]}]}]});const t={className:"subst",begin:/\$\(/,end:/\)/,contains:[e.BACKSLASH_ESCAPE]},n={className:"string",begin:/"/,end:/"/,contains:[e.BACKSLASH_ESCAPE,s,t]};t.contains.push(n);const a={begin:/\$\(\(/,end:/\)\)/,contains:[{begin:/\d+#[0-9a-f]+/,className:"number"},e.NUMBER_MODE,s]},i=e.SHEBANG({binary:"(fish|bash|zsh|sh|csh|ksh|tcsh|dash|scsh)",relevance:10}),c={className:"function",begin:/\w[\w\d_]*\s*\(\s*\)\s*\{/,returnBegin:!0,contains:[e.inherit(e.TITLE_MODE,{begin:/\w[\w\d_]*/})],relevance:0};return{name:"Bash",aliases:["sh","zsh"],keywords:{$pattern:/\b-?[a-z\._]+\b/,keyword:"if then else elif fi for while in do done case esac function",literal:"true false",built_in:"break cd continue eval exec exit export getopts hash pwd readonly return shift test times trap umask unset alias bind builtin caller command declare echo enable help let local logout mapfile printf read readarray source type typeset ulimit unalias set shopt autoload bg bindkey bye cap chdir clone comparguments compcall compctl compdescribe compfiles compgroups compquote comptags comptry compvalues dirs disable disown echotc echoti emulate fc fg float functions getcap getln history integer jobs kill limit log noglob popd print pushd pushln rehash sched setcap setopt stat suspend ttyctl unfunction unhash unlimit unsetopt vared wait whence where which zcompile zformat zftp zle zmodload zparseopts zprof zpty zregexparse zsocket zstyle ztcp",_:"-ne -eq -lt -gt -f -d -e -s -l -a"},contains:[i,e.SHEBANG(),c,a,e.HASH_COMMENT_MODE,n,{className:"",begin:/\\"/},{className:"string",begin:/'/,end:/'/},s]}}}());
-hljs.registerLanguage("c-like",function(){"use strict";return function(e){function t(e){return"(?:"+e+")?"}var n="(decltype\\(auto\\)|"+t("[a-zA-Z_]\\w*::")+"[a-zA-Z_]\\w*"+t("<.*?>")+")",r={className:"keyword",begin:"\\b[a-z\\d_]*_t\\b"},a={className:"string",variants:[{begin:'(u8?|U|L)?"',end:'"',illegal:"\\n",contains:[e.BACKSLASH_ESCAPE]},{begin:"(u8?|U|L)?'(\\\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4,8}|[0-7]{3}|\\S)|.)",end:"'",illegal:"."},e.END_SAME_AS_BEGIN({begin:/(?:u8?|U|L)?R"([^()\\ ]{0,16})\(/,end:/\)([^()\\ ]{0,16})"/})]},i={className:"number",variants:[{begin:"\\b(0b[01']+)"},{begin:"(-?)\\b([\\d']+(\\.[\\d']*)?|\\.[\\d']+)(u|U|l|L|ul|UL|f|F|b|B)"},{begin:"(-?)(\\b0[xX][a-fA-F0-9']+|(\\b[\\d']+(\\.[\\d']*)?|\\.[\\d']+)([eE][-+]?[\\d']+)?)"}],relevance:0},s={className:"meta",begin:/#\s*[a-z]+\b/,end:/$/,keywords:{"meta-keyword":"if else elif endif define undef warning error line pragma _Pragma ifdef ifndef include"},contains:[{begin:/\\\n/,relevance:0},e.inherit(a,{className:"meta-string"}),{className:"meta-string",begin:/<.*?>/,end:/$/,illegal:"\\n"},e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},o={className:"title",begin:t("[a-zA-Z_]\\w*::")+e.IDENT_RE,relevance:0},c=t("[a-zA-Z_]\\w*::")+e.IDENT_RE+"\\s*\\(",l={keyword:"int float while private char char8_t char16_t char32_t catch import module export virtual operator sizeof dynamic_cast|10 typedef const_cast|10 const for static_cast|10 union namespace unsigned long volatile static protected bool template mutable if public friend do goto auto void enum else break extern using asm case typeid wchar_t short reinterpret_cast|10 default double register explicit signed typename try this switch continue inline delete alignas alignof constexpr consteval constinit decltype concept co_await co_return co_yield requires noexcept static_assert thread_local restrict final override atomic_bool atomic_char atomic_schar atomic_uchar atomic_short atomic_ushort atomic_int atomic_uint atomic_long atomic_ulong atomic_llong atomic_ullong new throw return and and_eq bitand bitor compl not not_eq or or_eq xor xor_eq",built_in:"std string wstring cin cout cerr clog stdin stdout stderr stringstream istringstream ostringstream auto_ptr deque list queue stack vector map set pair bitset multiset multimap unordered_set unordered_map unordered_multiset unordered_multimap priority_queue make_pair array shared_ptr abort terminate abs acos asin atan2 atan calloc ceil cosh cos exit exp fabs floor fmod fprintf fputs free frexp fscanf future isalnum isalpha iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit tolower toupper labs ldexp log10 log malloc realloc memchr memcmp memcpy memset modf pow printf putchar puts scanf sinh sin snprintf sprintf sqrt sscanf strcat strchr strcmp strcpy strcspn strlen strncat strncmp strncpy strpbrk strrchr strspn strstr tanh tan vfprintf vprintf vsprintf endl initializer_list unique_ptr _Bool complex _Complex imaginary _Imaginary",literal:"true false nullptr NULL"},d=[r,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,i,a],_={variants:[{begin:/=/,end:/;/},{begin:/\(/,end:/\)/},{beginKeywords:"new throw return else",end:/;/}],keywords:l,contains:d.concat([{begin:/\(/,end:/\)/,keywords:l,contains:d.concat(["self"]),relevance:0}]),relevance:0},u={className:"function",begin:"("+n+"[\\*&\\s]+)+"+c,returnBegin:!0,end:/[{;=]/,excludeEnd:!0,keywords:l,illegal:/[^\w\s\*&:<>]/,contains:[{begin:"decltype\\(auto\\)",keywords:l,relevance:0},{begin:c,returnBegin:!0,contains:[o],relevance:0},{className:"params",begin:/\(/,end:/\)/,keywords:l,relevance:0,contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,i,r,{begin:/\(/,end:/\)/,keywords:l,relevance:0,contains:["self",e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,i,r]}]},r,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,s]};return{aliases:["c","cc","h","c++","h++","hpp","hh","hxx","cxx"],keywords:l,disableAutodetect:!0,illegal:"",contains:[].concat(_,u,d,[s,{begin:"\\b(deque|list|queue|priority_queue|pair|stack|vector|map|set|bitset|multiset|multimap|unordered_map|unordered_set|unordered_multiset|unordered_multimap|array)\\s*<",end:">",keywords:l,contains:["self",r]},{begin:e.IDENT_RE+"::",keywords:l},{className:"class",beginKeywords:"class struct",end:/[{;:]/,contains:[{begin:/,end:/>/,contains:["self"]},e.TITLE_MODE]}]),exports:{preprocessor:s,strings:a,keywords:l}}}}());
-hljs.registerLanguage("c",function(){"use strict";return function(e){var n=e.getLanguage("c-like").rawDefinition();return n.name="C",n.aliases=["c","h"],n}}());
-hljs.registerLanguage("coffeescript",function(){"use strict";const e=["as","in","of","if","for","while","finally","var","new","function","do","return","void","else","break","catch","instanceof","with","throw","case","default","try","switch","continue","typeof","delete","let","yield","const","class","debugger","async","await","static","import","from","export","extends"],n=["true","false","null","undefined","NaN","Infinity"],a=[].concat(["setInterval","setTimeout","clearInterval","clearTimeout","require","exports","eval","isFinite","isNaN","parseFloat","parseInt","decodeURI","decodeURIComponent","encodeURI","encodeURIComponent","escape","unescape"],["arguments","this","super","console","window","document","localStorage","module","global"],["Intl","DataView","Number","Math","Date","String","RegExp","Object","Function","Boolean","Error","Symbol","Set","Map","WeakSet","WeakMap","Proxy","Reflect","JSON","Promise","Float64Array","Int16Array","Int32Array","Int8Array","Uint16Array","Uint32Array","Float32Array","Array","Uint8Array","Uint8ClampedArray","ArrayBuffer"],["EvalError","InternalError","RangeError","ReferenceError","SyntaxError","TypeError","URIError"]);return function(r){var t={keyword:e.concat(["then","unless","until","loop","by","when","and","or","is","isnt","not"]).filter((e=>n=>!e.includes(n))(["var","const","let","function","static"])).join(" "),literal:n.concat(["yes","no","on","off"]).join(" "),built_in:a.concat(["npm","print"]).join(" ")},i="[A-Za-z$_][0-9A-Za-z$_]*",s={className:"subst",begin:/#\{/,end:/}/,keywords:t},o=[r.BINARY_NUMBER_MODE,r.inherit(r.C_NUMBER_MODE,{starts:{end:"(\\s*/)?",relevance:0}}),{className:"string",variants:[{begin:/'''/,end:/'''/,contains:[r.BACKSLASH_ESCAPE]},{begin:/'/,end:/'/,contains:[r.BACKSLASH_ESCAPE]},{begin:/"""/,end:/"""/,contains:[r.BACKSLASH_ESCAPE,s]},{begin:/"/,end:/"/,contains:[r.BACKSLASH_ESCAPE,s]}]},{className:"regexp",variants:[{begin:"///",end:"///",contains:[s,r.HASH_COMMENT_MODE]},{begin:"//[gim]{0,3}(?=\\W)",relevance:0},{begin:/\/(?![ *]).*?(?![\\]).\/[gim]{0,3}(?=\W)/}]},{begin:"@"+i},{subLanguage:"javascript",excludeBegin:!0,excludeEnd:!0,variants:[{begin:"```",end:"```"},{begin:"`",end:"`"}]}];s.contains=o;var c=r.inherit(r.TITLE_MODE,{begin:i}),l={className:"params",begin:"\\([^\\(]",returnBegin:!0,contains:[{begin:/\(/,end:/\)/,keywords:t,contains:["self"].concat(o)}]};return{name:"CoffeeScript",aliases:["coffee","cson","iced"],keywords:t,illegal:/\/\*/,contains:o.concat([r.COMMENT("###","###"),r.HASH_COMMENT_MODE,{className:"function",begin:"^\\s*"+i+"\\s*=\\s*(\\(.*\\))?\\s*\\B[-=]>",end:"[-=]>",returnBegin:!0,contains:[c,l]},{begin:/[:\(,=]\s*/,relevance:0,contains:[{className:"function",begin:"(\\(.*\\))?\\s*\\B[-=]>",end:"[-=]>",returnBegin:!0,contains:[l]}]},{className:"class",beginKeywords:"class",end:"$",illegal:/[:="\[\]]/,contains:[{beginKeywords:"extends",endsWithParent:!0,illegal:/[:="\[\]]/,contains:[c]},c]},{begin:i+":",end:":",returnBegin:!0,returnEnd:!0,relevance:0}])}}}());
-hljs.registerLanguage("cpp",function(){"use strict";return function(e){var t=e.getLanguage("c-like").rawDefinition();return t.disableAutodetect=!1,t.name="C++",t.aliases=["cc","c++","h++","hpp","hh","hxx","cxx"],t}}());
-hljs.registerLanguage("csharp",function(){"use strict";return function(e){var n={keyword:"abstract as base bool break byte case catch char checked const continue decimal default delegate do double enum event explicit extern finally fixed float for foreach goto if implicit in int interface internal is lock long object operator out override params private protected public readonly ref sbyte sealed short sizeof stackalloc static string struct switch this try typeof uint ulong unchecked unsafe ushort using virtual void volatile while add alias ascending async await by descending dynamic equals from get global group into join let nameof on orderby partial remove select set value var when where yield",literal:"null false true"},i=e.inherit(e.TITLE_MODE,{begin:"[a-zA-Z](\\.?\\w)*"}),a={className:"number",variants:[{begin:"\\b(0b[01']+)"},{begin:"(-?)\\b([\\d']+(\\.[\\d']*)?|\\.[\\d']+)(u|U|l|L|ul|UL|f|F|b|B)"},{begin:"(-?)(\\b0[xX][a-fA-F0-9']+|(\\b[\\d']+(\\.[\\d']*)?|\\.[\\d']+)([eE][-+]?[\\d']+)?)"}],relevance:0},s={className:"string",begin:'@"',end:'"',contains:[{begin:'""'}]},t=e.inherit(s,{illegal:/\n/}),l={className:"subst",begin:"{",end:"}",keywords:n},r=e.inherit(l,{illegal:/\n/}),c={className:"string",begin:/\$"/,end:'"',illegal:/\n/,contains:[{begin:"{{"},{begin:"}}"},e.BACKSLASH_ESCAPE,r]},o={className:"string",begin:/\$@"/,end:'"',contains:[{begin:"{{"},{begin:"}}"},{begin:'""'},l]},g=e.inherit(o,{illegal:/\n/,contains:[{begin:"{{"},{begin:"}}"},{begin:'""'},r]});l.contains=[o,c,s,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,a,e.C_BLOCK_COMMENT_MODE],r.contains=[g,c,t,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,a,e.inherit(e.C_BLOCK_COMMENT_MODE,{illegal:/\n/})];var d={variants:[o,c,s,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE]},E={begin:"<",end:">",contains:[{beginKeywords:"in out"},i]},_=e.IDENT_RE+"(<"+e.IDENT_RE+"(\\s*,\\s*"+e.IDENT_RE+")*>)?(\\[\\])?",b={begin:"@"+e.IDENT_RE,relevance:0};return{name:"C#",aliases:["cs","c#"],keywords:n,illegal:/::/,contains:[e.COMMENT("///","$",{returnBegin:!0,contains:[{className:"doctag",variants:[{begin:"///",relevance:0},{begin:"\x3c!--|--\x3e"},{begin:"?",end:">"}]}]}),e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,{className:"meta",begin:"#",end:"$",keywords:{"meta-keyword":"if else elif endif define undef warning error line region endregion pragma checksum"}},d,a,{beginKeywords:"class interface",end:/[{;=]/,illegal:/[^\s:,]/,contains:[{beginKeywords:"where class"},i,E,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{beginKeywords:"namespace",end:/[{;=]/,illegal:/[^\s:]/,contains:[i,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{className:"meta",begin:"^\\s*\\[",excludeBegin:!0,end:"\\]",excludeEnd:!0,contains:[{className:"meta-string",begin:/"/,end:/"/}]},{beginKeywords:"new return throw await else",relevance:0},{className:"function",begin:"("+_+"\\s+)+"+e.IDENT_RE+"\\s*(\\<.+\\>)?\\s*\\(",returnBegin:!0,end:/\s*[{;=]/,excludeEnd:!0,keywords:n,contains:[{begin:e.IDENT_RE+"\\s*(\\<.+\\>)?\\s*\\(",returnBegin:!0,contains:[e.TITLE_MODE,E],relevance:0},{className:"params",begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,keywords:n,relevance:0,contains:[d,a,e.C_BLOCK_COMMENT_MODE]},e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},b]}}}());
-hljs.registerLanguage("css",function(){"use strict";return function(e){var n={begin:/(?:[A-Z\_\.\-]+|--[a-zA-Z0-9_-]+)\s*:/,returnBegin:!0,end:";",endsWithParent:!0,contains:[{className:"attribute",begin:/\S/,end:":",excludeEnd:!0,starts:{endsWithParent:!0,excludeEnd:!0,contains:[{begin:/[\w-]+\(/,returnBegin:!0,contains:[{className:"built_in",begin:/[\w-]+/},{begin:/\(/,end:/\)/,contains:[e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,e.CSS_NUMBER_MODE]}]},e.CSS_NUMBER_MODE,e.QUOTE_STRING_MODE,e.APOS_STRING_MODE,e.C_BLOCK_COMMENT_MODE,{className:"number",begin:"#[0-9A-Fa-f]+"},{className:"meta",begin:"!important"}]}}]};return{name:"CSS",case_insensitive:!0,illegal:/[=\/|'\$]/,contains:[e.C_BLOCK_COMMENT_MODE,{className:"selector-id",begin:/#[A-Za-z0-9_-]+/},{className:"selector-class",begin:/\.[A-Za-z0-9_-]+/},{className:"selector-attr",begin:/\[/,end:/\]/,illegal:"$",contains:[e.APOS_STRING_MODE,e.QUOTE_STRING_MODE]},{className:"selector-pseudo",begin:/:(:)?[a-zA-Z0-9\_\-\+\(\)"'.]+/},{begin:"@(page|font-face)",lexemes:"@[a-z-]+",keywords:"@page @font-face"},{begin:"@",end:"[{;]",illegal:/:/,returnBegin:!0,contains:[{className:"keyword",begin:/@\-?\w[\w]*(\-\w+)*/},{begin:/\s/,endsWithParent:!0,excludeEnd:!0,relevance:0,keywords:"and or not only",contains:[{begin:/[a-z-]+:/,className:"attribute"},e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,e.CSS_NUMBER_MODE]}]},{className:"selector-tag",begin:"[a-zA-Z-][a-zA-Z0-9_-]*",relevance:0},{begin:"{",end:"}",illegal:/\S/,contains:[e.C_BLOCK_COMMENT_MODE,n]}]}}}());
-hljs.registerLanguage("diff",function(){"use strict";return function(e){return{name:"Diff",aliases:["patch"],contains:[{className:"meta",relevance:10,variants:[{begin:/^@@ +\-\d+,\d+ +\+\d+,\d+ +@@$/},{begin:/^\*\*\* +\d+,\d+ +\*\*\*\*$/},{begin:/^\-\-\- +\d+,\d+ +\-\-\-\-$/}]},{className:"comment",variants:[{begin:/Index: /,end:/$/},{begin:/={3,}/,end:/$/},{begin:/^\-{3}/,end:/$/},{begin:/^\*{3} /,end:/$/},{begin:/^\+{3}/,end:/$/},{begin:/^\*{15}$/}]},{className:"addition",begin:"^\\+",end:"$"},{className:"deletion",begin:"^\\-",end:"$"},{className:"addition",begin:"^\\!",end:"$"}]}}}());
-hljs.registerLanguage("go",function(){"use strict";return function(e){var n={keyword:"break default func interface select case map struct chan else goto package switch const fallthrough if range type continue for import return var go defer bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 uint16 uint32 uint64 int uint uintptr rune",literal:"true false iota nil",built_in:"append cap close complex copy imag len make new panic print println real recover delete"};return{name:"Go",aliases:["golang"],keywords:n,illegal:"",contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,{className:"string",variants:[e.QUOTE_STRING_MODE,e.APOS_STRING_MODE,{begin:"`",end:"`"}]},{className:"number",variants:[{begin:e.C_NUMBER_RE+"[i]",relevance:1},e.C_NUMBER_MODE]},{begin:/:=/},{className:"function",beginKeywords:"func",end:"\\s*(\\{|$)",excludeEnd:!0,contains:[e.TITLE_MODE,{className:"params",begin:/\(/,end:/\)/,keywords:n,illegal:/["']/}]}]}}}());
-hljs.registerLanguage("http",function(){"use strict";return function(e){var n="HTTP/[0-9\\.]+";return{name:"HTTP",aliases:["https"],illegal:"\\S",contains:[{begin:"^"+n,end:"$",contains:[{className:"number",begin:"\\b\\d{3}\\b"}]},{begin:"^[A-Z]+ (.*?) "+n+"$",returnBegin:!0,end:"$",contains:[{className:"string",begin:" ",end:" ",excludeBegin:!0,excludeEnd:!0},{begin:n},{className:"keyword",begin:"[A-Z]+"}]},{className:"attribute",begin:"^\\w",end:": ",excludeEnd:!0,illegal:"\\n|\\s|=",starts:{end:"$",relevance:0}},{begin:"\\n\\n",starts:{subLanguage:[],endsWithParent:!0}}]}}}());
-hljs.registerLanguage("ini",function(){"use strict";function e(e){return e?"string"==typeof e?e:e.source:null}function n(...n){return n.map(n=>e(n)).join("")}return function(a){var s={className:"number",relevance:0,variants:[{begin:/([\+\-]+)?[\d]+_[\d_]+/},{begin:a.NUMBER_RE}]},i=a.COMMENT();i.variants=[{begin:/;/,end:/$/},{begin:/#/,end:/$/}];var t={className:"variable",variants:[{begin:/\$[\w\d"][\w\d_]*/},{begin:/\$\{(.*?)}/}]},r={className:"literal",begin:/\bon|off|true|false|yes|no\b/},l={className:"string",contains:[a.BACKSLASH_ESCAPE],variants:[{begin:"'''",end:"'''",relevance:10},{begin:'"""',end:'"""',relevance:10},{begin:'"',end:'"'},{begin:"'",end:"'"}]},c={begin:/\[/,end:/\]/,contains:[i,r,t,l,s,"self"],relevance:0},g="("+[/[A-Za-z0-9_-]+/,/"(\\"|[^"])*"/,/'[^']*'/].map(n=>e(n)).join("|")+")";return{name:"TOML, also INI",aliases:["toml"],case_insensitive:!0,illegal:/\S/,contains:[i,{className:"section",begin:/\[+/,end:/\]+/},{begin:n(g,"(\\s*\\.\\s*",g,")*",n("(?=",/\s*=\s*[^#\s]/,")")),className:"attr",starts:{end:/$/,contains:[i,c,r,t,l,s]}}]}}}());
-hljs.registerLanguage("java",function(){"use strict";function e(e){return e?"string"==typeof e?e:e.source:null}function n(e){return a("(",e,")?")}function a(...n){return n.map(n=>e(n)).join("")}function s(...n){return"("+n.map(n=>e(n)).join("|")+")"}return function(e){var t="false synchronized int abstract float private char boolean var static null if const for true while long strictfp finally protected import native final void enum else break transient catch instanceof byte super volatile case assert short package default double public try this switch continue throws protected public private module requires exports do",i={className:"meta",begin:"@[À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*",contains:[{begin:/\(/,end:/\)/,contains:["self"]}]},r=e=>a("[",e,"]+([",e,"_]*[",e,"]+)?"),c={className:"number",variants:[{begin:`\\b(0[bB]${r("01")})[lL]?`},{begin:`\\b(0${r("0-7")})[dDfFlL]?`},{begin:a(/\b0[xX]/,s(a(r("a-fA-F0-9"),/\./,r("a-fA-F0-9")),a(r("a-fA-F0-9"),/\.?/),a(/\./,r("a-fA-F0-9"))),/([pP][+-]?(\d+))?/,/[fFdDlL]?/)},{begin:a(/\b/,s(a(/\d*\./,r("\\d")),r("\\d")),/[eE][+-]?[\d]+[dDfF]?/)},{begin:a(/\b/,r(/\d/),n(/\.?/),n(r(/\d/)),/[dDfFlL]?/)}],relevance:0};return{name:"Java",aliases:["jsp"],keywords:t,illegal:/<\/|#/,contains:[e.COMMENT("/\\*\\*","\\*/",{relevance:0,contains:[{begin:/\w+@/,relevance:0},{className:"doctag",begin:"@[A-Za-z]+"}]}),e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,{className:"class",beginKeywords:"class interface",end:/[{;=]/,excludeEnd:!0,keywords:"class interface",illegal:/[:"\[\]]/,contains:[{beginKeywords:"extends implements"},e.UNDERSCORE_TITLE_MODE]},{beginKeywords:"new throw return else",relevance:0},{className:"function",begin:"([À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*(<[À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*(\\s*,\\s*[À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*)*>)?\\s+)+"+e.UNDERSCORE_IDENT_RE+"\\s*\\(",returnBegin:!0,end:/[{;=]/,excludeEnd:!0,keywords:t,contains:[{begin:e.UNDERSCORE_IDENT_RE+"\\s*\\(",returnBegin:!0,relevance:0,contains:[e.UNDERSCORE_TITLE_MODE]},{className:"params",begin:/\(/,end:/\)/,keywords:t,relevance:0,contains:[i,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,e.C_NUMBER_MODE,e.C_BLOCK_COMMENT_MODE]},e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},c,i]}}}());
-hljs.registerLanguage("javascript",function(){"use strict";const e=["as","in","of","if","for","while","finally","var","new","function","do","return","void","else","break","catch","instanceof","with","throw","case","default","try","switch","continue","typeof","delete","let","yield","const","class","debugger","async","await","static","import","from","export","extends"],n=["true","false","null","undefined","NaN","Infinity"],a=[].concat(["setInterval","setTimeout","clearInterval","clearTimeout","require","exports","eval","isFinite","isNaN","parseFloat","parseInt","decodeURI","decodeURIComponent","encodeURI","encodeURIComponent","escape","unescape"],["arguments","this","super","console","window","document","localStorage","module","global"],["Intl","DataView","Number","Math","Date","String","RegExp","Object","Function","Boolean","Error","Symbol","Set","Map","WeakSet","WeakMap","Proxy","Reflect","JSON","Promise","Float64Array","Int16Array","Int32Array","Int8Array","Uint16Array","Uint32Array","Float32Array","Array","Uint8Array","Uint8ClampedArray","ArrayBuffer"],["EvalError","InternalError","RangeError","ReferenceError","SyntaxError","TypeError","URIError"]);function s(e){return r("(?=",e,")")}function r(...e){return e.map(e=>(function(e){return e?"string"==typeof e?e:e.source:null})(e)).join("")}return function(t){var i="[A-Za-z$_][0-9A-Za-z$_]*",c={begin:/<[A-Za-z0-9\\._:-]+/,end:/\/[A-Za-z0-9\\._:-]+>|\/>/},o={$pattern:"[A-Za-z$_][0-9A-Za-z$_]*",keyword:e.join(" "),literal:n.join(" "),built_in:a.join(" ")},l={className:"number",variants:[{begin:"\\b(0[bB][01]+)n?"},{begin:"\\b(0[oO][0-7]+)n?"},{begin:t.C_NUMBER_RE+"n?"}],relevance:0},E={className:"subst",begin:"\\$\\{",end:"\\}",keywords:o,contains:[]},d={begin:"html`",end:"",starts:{end:"`",returnEnd:!1,contains:[t.BACKSLASH_ESCAPE,E],subLanguage:"xml"}},g={begin:"css`",end:"",starts:{end:"`",returnEnd:!1,contains:[t.BACKSLASH_ESCAPE,E],subLanguage:"css"}},u={className:"string",begin:"`",end:"`",contains:[t.BACKSLASH_ESCAPE,E]};E.contains=[t.APOS_STRING_MODE,t.QUOTE_STRING_MODE,d,g,u,l,t.REGEXP_MODE];var b=E.contains.concat([{begin:/\(/,end:/\)/,contains:["self"].concat(E.contains,[t.C_BLOCK_COMMENT_MODE,t.C_LINE_COMMENT_MODE])},t.C_BLOCK_COMMENT_MODE,t.C_LINE_COMMENT_MODE]),_={className:"params",begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,contains:b};return{name:"JavaScript",aliases:["js","jsx","mjs","cjs"],keywords:o,contains:[t.SHEBANG({binary:"node",relevance:5}),{className:"meta",relevance:10,begin:/^\s*['"]use (strict|asm)['"]/},t.APOS_STRING_MODE,t.QUOTE_STRING_MODE,d,g,u,t.C_LINE_COMMENT_MODE,t.COMMENT("/\\*\\*","\\*/",{relevance:0,contains:[{className:"doctag",begin:"@[A-Za-z]+",contains:[{className:"type",begin:"\\{",end:"\\}",relevance:0},{className:"variable",begin:i+"(?=\\s*(-)|$)",endsParent:!0,relevance:0},{begin:/(?=[^\n])\s/,relevance:0}]}]}),t.C_BLOCK_COMMENT_MODE,l,{begin:r(/[{,\n]\s*/,s(r(/(((\/\/.*)|(\/\*(.|\n)*\*\/))\s*)*/,i+"\\s*:"))),relevance:0,contains:[{className:"attr",begin:i+s("\\s*:"),relevance:0}]},{begin:"("+t.RE_STARTERS_RE+"|\\b(case|return|throw)\\b)\\s*",keywords:"return throw case",contains:[t.C_LINE_COMMENT_MODE,t.C_BLOCK_COMMENT_MODE,t.REGEXP_MODE,{className:"function",begin:"(\\([^(]*(\\([^(]*(\\([^(]*\\))?\\))?\\)|"+t.UNDERSCORE_IDENT_RE+")\\s*=>",returnBegin:!0,end:"\\s*=>",contains:[{className:"params",variants:[{begin:t.UNDERSCORE_IDENT_RE},{className:null,begin:/\(\s*\)/,skip:!0},{begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,keywords:o,contains:b}]}]},{begin:/,/,relevance:0},{className:"",begin:/\s/,end:/\s*/,skip:!0},{variants:[{begin:"<>",end:">"},{begin:c.begin,end:c.end}],subLanguage:"xml",contains:[{begin:c.begin,end:c.end,skip:!0,contains:["self"]}]}],relevance:0},{className:"function",beginKeywords:"function",end:/\{/,excludeEnd:!0,contains:[t.inherit(t.TITLE_MODE,{begin:i}),_],illegal:/\[|%/},{begin:/\$[(.]/},t.METHOD_GUARD,{className:"class",beginKeywords:"class",end:/[{;=]/,excludeEnd:!0,illegal:/[:"\[\]]/,contains:[{beginKeywords:"extends"},t.UNDERSCORE_TITLE_MODE]},{beginKeywords:"constructor",end:/\{/,excludeEnd:!0},{begin:"(get|set)\\s+(?="+i+"\\()",end:/{/,keywords:"get set",contains:[t.inherit(t.TITLE_MODE,{begin:i}),{begin:/\(\)/},_]}],illegal:/#(?!!)/}}}());
-hljs.registerLanguage("json",function(){"use strict";return function(n){var e={literal:"true false null"},i=[n.C_LINE_COMMENT_MODE,n.C_BLOCK_COMMENT_MODE],t=[n.QUOTE_STRING_MODE,n.C_NUMBER_MODE],a={end:",",endsWithParent:!0,excludeEnd:!0,contains:t,keywords:e},l={begin:"{",end:"}",contains:[{className:"attr",begin:/"/,end:/"/,contains:[n.BACKSLASH_ESCAPE],illegal:"\\n"},n.inherit(a,{begin:/:/})].concat(i),illegal:"\\S"},s={begin:"\\[",end:"\\]",contains:[n.inherit(a)],illegal:"\\S"};return t.push(l,s),i.forEach((function(n){t.push(n)})),{name:"JSON",contains:t,keywords:e,illegal:"\\S"}}}());
-hljs.registerLanguage("kotlin",function(){"use strict";return function(e){var n={keyword:"abstract as val var vararg get set class object open private protected public noinline crossinline dynamic final enum if else do while for when throw try catch finally import package is in fun override companion reified inline lateinit init interface annotation data sealed internal infix operator out by constructor super tailrec where const inner suspend typealias external expect actual trait volatile transient native default",built_in:"Byte Short Char Int Long Boolean Float Double Void Unit Nothing",literal:"true false null"},a={className:"symbol",begin:e.UNDERSCORE_IDENT_RE+"@"},i={className:"subst",begin:"\\${",end:"}",contains:[e.C_NUMBER_MODE]},s={className:"variable",begin:"\\$"+e.UNDERSCORE_IDENT_RE},t={className:"string",variants:[{begin:'"""',end:'"""(?=[^"])',contains:[s,i]},{begin:"'",end:"'",illegal:/\n/,contains:[e.BACKSLASH_ESCAPE]},{begin:'"',end:'"',illegal:/\n/,contains:[e.BACKSLASH_ESCAPE,s,i]}]};i.contains.push(t);var r={className:"meta",begin:"@(?:file|property|field|get|set|receiver|param|setparam|delegate)\\s*:(?:\\s*"+e.UNDERSCORE_IDENT_RE+")?"},l={className:"meta",begin:"@"+e.UNDERSCORE_IDENT_RE,contains:[{begin:/\(/,end:/\)/,contains:[e.inherit(t,{className:"meta-string"})]}]},c=e.COMMENT("/\\*","\\*/",{contains:[e.C_BLOCK_COMMENT_MODE]}),o={variants:[{className:"type",begin:e.UNDERSCORE_IDENT_RE},{begin:/\(/,end:/\)/,contains:[]}]},d=o;return d.variants[1].contains=[o],o.variants[1].contains=[d],{name:"Kotlin",aliases:["kt"],keywords:n,contains:[e.COMMENT("/\\*\\*","\\*/",{relevance:0,contains:[{className:"doctag",begin:"@[A-Za-z]+"}]}),e.C_LINE_COMMENT_MODE,c,{className:"keyword",begin:/\b(break|continue|return|this)\b/,starts:{contains:[{className:"symbol",begin:/@\w+/}]}},a,r,l,{className:"function",beginKeywords:"fun",end:"[(]|$",returnBegin:!0,excludeEnd:!0,keywords:n,illegal:/fun\s+(<.*>)?[^\s\(]+(\s+[^\s\(]+)\s*=/,relevance:5,contains:[{begin:e.UNDERSCORE_IDENT_RE+"\\s*\\(",returnBegin:!0,relevance:0,contains:[e.UNDERSCORE_TITLE_MODE]},{className:"type",begin:/,end:/>/,keywords:"reified",relevance:0},{className:"params",begin:/\(/,end:/\)/,endsParent:!0,keywords:n,relevance:0,contains:[{begin:/:/,end:/[=,\/]/,endsWithParent:!0,contains:[o,e.C_LINE_COMMENT_MODE,c],relevance:0},e.C_LINE_COMMENT_MODE,c,r,l,t,e.C_NUMBER_MODE]},c]},{className:"class",beginKeywords:"class interface trait",end:/[:\{(]|$/,excludeEnd:!0,illegal:"extends implements",contains:[{beginKeywords:"public protected internal private constructor"},e.UNDERSCORE_TITLE_MODE,{className:"type",begin:/,end:/>/,excludeBegin:!0,excludeEnd:!0,relevance:0},{className:"type",begin:/[,:]\s*/,end:/[<\(,]|$/,excludeBegin:!0,returnEnd:!0},r,l]},t,{className:"meta",begin:"^#!/usr/bin/env",end:"$",illegal:"\n"},{className:"number",begin:"\\b(0[bB]([01]+[01_]+[01]+|[01]+)|0[xX]([a-fA-F0-9]+[a-fA-F0-9_]+[a-fA-F0-9]+|[a-fA-F0-9]+)|(([\\d]+[\\d_]+[\\d]+|[\\d]+)(\\.([\\d]+[\\d_]+[\\d]+|[\\d]+))?|\\.([\\d]+[\\d_]+[\\d]+|[\\d]+))([eE][-+]?\\d+)?)[lLfF]?",relevance:0}]}}}());
-hljs.registerLanguage("less",function(){"use strict";return function(e){var n="([\\w-]+|@{[\\w-]+})",a=[],s=[],t=function(e){return{className:"string",begin:"~?"+e+".*?"+e}},r=function(e,n,a){return{className:e,begin:n,relevance:a}},i={begin:"\\(",end:"\\)",contains:s,relevance:0};s.push(e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,t("'"),t('"'),e.CSS_NUMBER_MODE,{begin:"(url|data-uri)\\(",starts:{className:"string",end:"[\\)\\n]",excludeEnd:!0}},r("number","#[0-9A-Fa-f]+\\b"),i,r("variable","@@?[\\w-]+",10),r("variable","@{[\\w-]+}"),r("built_in","~?`[^`]*?`"),{className:"attribute",begin:"[\\w-]+\\s*:",end:":",returnBegin:!0,excludeEnd:!0},{className:"meta",begin:"!important"});var c=s.concat({begin:"{",end:"}",contains:a}),l={beginKeywords:"when",endsWithParent:!0,contains:[{beginKeywords:"and not"}].concat(s)},o={begin:n+"\\s*:",returnBegin:!0,end:"[;}]",relevance:0,contains:[{className:"attribute",begin:n,end:":",excludeEnd:!0,starts:{endsWithParent:!0,illegal:"[<=$]",relevance:0,contains:s}}]},g={className:"keyword",begin:"@(import|media|charset|font-face|(-[a-z]+-)?keyframes|supports|document|namespace|page|viewport|host)\\b",starts:{end:"[;{}]",returnEnd:!0,contains:s,relevance:0}},d={className:"variable",variants:[{begin:"@[\\w-]+\\s*:",relevance:15},{begin:"@[\\w-]+"}],starts:{end:"[;}]",returnEnd:!0,contains:c}},b={variants:[{begin:"[\\.#:&\\[>]",end:"[;{}]"},{begin:n,end:"{"}],returnBegin:!0,returnEnd:!0,illegal:"[<='$\"]",relevance:0,contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,l,r("keyword","all\\b"),r("variable","@{[\\w-]+}"),r("selector-tag",n+"%?",0),r("selector-id","#"+n),r("selector-class","\\."+n,0),r("selector-tag","&",0),{className:"selector-attr",begin:"\\[",end:"\\]"},{className:"selector-pseudo",begin:/:(:)?[a-zA-Z0-9\_\-\+\(\)"'.]+/},{begin:"\\(",end:"\\)",contains:c},{begin:"!important"}]};return a.push(e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,g,d,o,b),{name:"Less",case_insensitive:!0,illegal:"[=>'/<($\"]",contains:a}}}());
-hljs.registerLanguage("lua",function(){"use strict";return function(e){var t={begin:"\\[=*\\[",end:"\\]=*\\]",contains:["self"]},a=[e.COMMENT("--(?!\\[=*\\[)","$"),e.COMMENT("--\\[=*\\[","\\]=*\\]",{contains:[t],relevance:10})];return{name:"Lua",keywords:{$pattern:e.UNDERSCORE_IDENT_RE,literal:"true false nil",keyword:"and break do else elseif end for goto if in local not or repeat return then until while",built_in:"_G _ENV _VERSION __index __newindex __mode __call __metatable __tostring __len __gc __add __sub __mul __div __mod __pow __concat __unm __eq __lt __le assert collectgarbage dofile error getfenv getmetatable ipairs load loadfile loadstring module next pairs pcall print rawequal rawget rawset require select setfenv setmetatable tonumber tostring type unpack xpcall arg self coroutine resume yield status wrap create running debug getupvalue debug sethook getmetatable gethook setmetatable setlocal traceback setfenv getinfo setupvalue getlocal getregistry getfenv io lines write close flush open output type read stderr stdin input stdout popen tmpfile math log max acos huge ldexp pi cos tanh pow deg tan cosh sinh random randomseed frexp ceil floor rad abs sqrt modf asin min mod fmod log10 atan2 exp sin atan os exit setlocale date getenv difftime remove time clock tmpname rename execute package preload loadlib loaded loaders cpath config path seeall string sub upper len gfind rep find match char dump gmatch reverse byte format gsub lower table setn insert getn foreachi maxn foreach concat sort remove"},contains:a.concat([{className:"function",beginKeywords:"function",end:"\\)",contains:[e.inherit(e.TITLE_MODE,{begin:"([_a-zA-Z]\\w*\\.)*([_a-zA-Z]\\w*:)?[_a-zA-Z]\\w*"}),{className:"params",begin:"\\(",endsWithParent:!0,contains:a}].concat(a)},e.C_NUMBER_MODE,e.APOS_STRING_MODE,e.QUOTE_STRING_MODE,{className:"string",begin:"\\[=*\\[",end:"\\]=*\\]",contains:[t],relevance:5}])}}}());
-hljs.registerLanguage("makefile",function(){"use strict";return function(e){var i={className:"variable",variants:[{begin:"\\$\\("+e.UNDERSCORE_IDENT_RE+"\\)",contains:[e.BACKSLASH_ESCAPE]},{begin:/\$[@%\^\+\*]/}]},n={className:"string",begin:/"/,end:/"/,contains:[e.BACKSLASH_ESCAPE,i]},a={className:"variable",begin:/\$\([\w-]+\s/,end:/\)/,keywords:{built_in:"subst patsubst strip findstring filter filter-out sort word wordlist firstword lastword dir notdir suffix basename addsuffix addprefix join wildcard realpath abspath error warning shell origin flavor foreach if or and call eval file value"},contains:[i]},r={begin:"^"+e.UNDERSCORE_IDENT_RE+"\\s*(?=[:+?]?=)"},s={className:"section",begin:/^[^\s]+:/,end:/$/,contains:[i]};return{name:"Makefile",aliases:["mk","mak"],keywords:{$pattern:/[\w-]+/,keyword:"define endef undefine ifdef ifndef ifeq ifneq else endif include -include sinclude override export unexport private vpath"},contains:[e.HASH_COMMENT_MODE,i,n,a,r,{className:"meta",begin:/^\.PHONY:/,end:/$/,keywords:{$pattern:/[\.\w]+/,"meta-keyword":".PHONY"}},s]}}}());
-hljs.registerLanguage("xml",function(){"use strict";return function(e){var n={className:"symbol",begin:"&[a-z]+;|[0-9]+;|[a-f0-9]+;"},a={begin:"\\s",contains:[{className:"meta-keyword",begin:"#?[a-z_][a-z1-9_-]+",illegal:"\\n"}]},s=e.inherit(a,{begin:"\\(",end:"\\)"}),t=e.inherit(e.APOS_STRING_MODE,{className:"meta-string"}),i=e.inherit(e.QUOTE_STRING_MODE,{className:"meta-string"}),c={endsWithParent:!0,illegal:/,relevance:0,contains:[{className:"attr",begin:"[A-Za-z0-9\\._:-]+",relevance:0},{begin:/=\s*/,relevance:0,contains:[{className:"string",endsParent:!0,variants:[{begin:/"/,end:/"/,contains:[n]},{begin:/'/,end:/'/,contains:[n]},{begin:/[^\s"'=<>`]+/}]}]}]};return{name:"HTML, XML",aliases:["html","xhtml","rss","atom","xjb","xsd","xsl","plist","wsf","svg"],case_insensitive:!0,contains:[{className:"meta",begin:"",relevance:10,contains:[a,i,t,s,{begin:"\\[",end:"\\]",contains:[{className:"meta",begin:"",contains:[a,s,i,t]}]}]},e.COMMENT("\x3c!--","--\x3e",{relevance:10}),{begin:"<\\!\\[CDATA\\[",end:"\\]\\]>",relevance:10},n,{className:"meta",begin:/<\?xml/,end:/\?>/,relevance:10},{className:"tag",begin:"",returnEnd:!0,subLanguage:["css","xml"]}},{className:"tag",begin:"
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Puck is an experimental, memory safe, structurally typed, interface-first, imperative programming language.
-It aims to be clean and succinct while performant: inspired by the syntax and metaprogramming of Nim, the error handling of Swift, the performance and safety guarantees of Rust, the async/await and comptime of Zig, and the module system of OCaml.
-
-Example: Interfaces
-
# Note: These declarations are adapted from the standard prelude.
-
-## The Result type. Represents either success or failure.
-pub type Result[T, E] = union
- Okay(T)
- Error(E)
-
-## The Err interface. Useful for dynamically dispatching errors.
-pub type Err = interface
- str(Self): str
- dbg(Self): str
-
-## A Result type that uses dynamically dispatched errors.
-## The Error may be any type implementing Err.
-pub type Result[T] = Result[T, ref Err]
-
-## Implements the dbg function for strings.
-## As the str function is already defined for strings,
-## this in turn means strings now implicitly implement Err.
-pub func dbg(self: str) = "\"" & self & "\""
-
-
-
-Example: Pattern Matching
-
## Opens the std.tables module for unqualified use.
-use std.tables
-
-pub type Value = string
-pub type Ident = string
-pub type Expr = ref union
- Literal(Value)
- Variable(Ident)
- Abstraction(param: Ident, body: Expr)
- Application(body: Expr, arg: Expr)
- Conditional(condition: Expr,
- then_branch: Expr, else_branch: Expr)
-
-## Evaluate an Expr down to a Value, or return an Error.
-pub func eval(context: mut HashTable[Ident, Value], expr: Expr): Result[Value]
- match expr
- of Literal(value): Okay(value)
- of Variable(ident):
- context.get(ident)
- .err("Could not find variable {} in context!".fmt(ident))
- of Application(body, arg):
- if body of Abstraction(param, body as inner_body):
- context.set(param, context.clone.eval(arg)?)
- context.eval(inner_body)
- else:
- Error("Expected Abstraction, found body {} and argument {}".fmt(body, arg))
- of Conditional(condition, then_branch, else_branch):
- if context.clone.eval(condition)? == "true":
- context.eval(then_case)
- else:
- context.eval(else_case)
- of _: Error("Invalid expression {}".fmt(expr))
-
Puck is primarily a testing ground and should not be used in any important capacity.
-Don't use it. Everything is unimplemented and it will break underneath your feet.
-
That said: in the future, once somewhat stabilized, reasons why you would use it would be for:
-
-
The syntax, aiming to be flexible, predictable, and succinct, through the use of uniform function call syntax and significant whitespace
-
The type system, being modern and powerful with a strong emphasis on safety, optional and result types, algebraic data types, interfaces, and modules
-
The memory management system, implementing a model of strict ownership while allowing individual fallbacks to reference counts if so desired
-
The metaprogramming, providing integrated macros capable of rewriting the abstract syntax tree before or after typechecking
-
The interop system, allowing foreign functions to be usable with native semantics from a bevy of languages
-
-
This is the language I keep in my head. It sprung from a series of unstructured notes I kept on language design, that finally became something more comprehensive in early 2023. The overarching goal is to provide a language capable of elegantly expressing any problem, and explore ownership and interop along the way.
The basic usage document lays out the fundamental semantics of Puck.
-
The syntax document provides a deeper and formal look into the grammar of Puck.
-
The type system document gives an in-depth analysis of Puck's extensive type system.
-
The modules document provides a more detailed look at the first-class module system.
-
The memory management document gives an overview of Puck's memory model.
-
The metaprogramming document explains how using metaprogramming to extend the language works.
-
The asynchronous document gives an overview of Puck's colourless asynchronous support.
-
The interop document gives an overview of how the first-class language interop system works.
-
The standard library document provides an overview and examples of usage of the standard library.
-
The roadmap provides a clear view of the current state and future plans of the language's development.
-
-
These are best read in order.
-
Note that all of these documents (and parts of this README) are written as if everything already exists. Nothing already exists! You can see the roadmap for an actual sense as to the state of the language. I simply found writing in the present tense to be an easier way to collect my thoughts.
-
This language does not currently integrate ideas from the following areas of active research: effects systems, refinement types, and dependent types. It plans to integrate refinement types in the future as a basis for range[] types, and to explore safety and optimizations surrounding integer overflow.