diff options
Diffstat (limited to 'docs/METAPROGRAMMING.md')
| -rw-r--r-- | docs/METAPROGRAMMING.md | 6 |
1 files changed, 6 insertions, 0 deletions
diff --git a/docs/METAPROGRAMMING.md b/docs/METAPROGRAMMING.md index 17e65a0..191e53a 100644 --- a/docs/METAPROGRAMMING.md +++ b/docs/METAPROGRAMMING.md @@ -6,6 +6,8 @@ Macros take in fragments of the AST within their scope, transform them with arbi 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.) +## Scope + 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 @@ -39,6 +41,8 @@ macro +=(a, b) = a += b ``` +## Usage + 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`. @@ -58,6 +62,8 @@ func meow: Result[bool, ref Err] = let a = stdin.get()? ``` +## Quoting + 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. ```puck |