Macros

istring-nil

Construct with string

An interpolated string s-expression that consists of a string with no interpolations.

istring-cons

Construct with string-past interpolated string-rest

Todo

Use this.

An interpolated string s-expression that consists of a string, a single interpolated value to go after that string, and a remaining interpolated string s-expression to go after that.

foreign

Construct with val

An s-expression that consists of any first-class value.

Most of the built-in macros expect a value embedded this way to be an (obtain-by-unqualified-name …), an (obtain-by-qualified-name …), or an (obtain-directly …).

scope

Construct with unique-ns def-ns qualify

A bundle of a unique namespace, a definition namespace, and a function to qualify unqualified names.

Macros use these values. A macro has access to the lexical scope and uniqueness where it was defined, as well as the lexical scope and uniqueness of its caller.

macro-occurrence

Construct with string

Todo

Document this.

local-occurrence

Construct with string

Todo

Document this.

constructor-occurrence

Construct with string

Todo

Document this.

projection-occurrence

Construct with string main-tag-name

Todo

Document this.

obtain-by-unqualified-name

Construct with name

A foreign occurrence in a Cene code s-expression that indicates something should be looked up by the qualification of the indicated unqualified name, instead of by the qualification of the name of a literal string.

obtain-by-qualified-name

Construct with name

A foreign occurrence in a Cene code s-expression that indicates something should be looked up by the indicated qualified name, instead of by the qualification of the name of a literal string.

obtain-directly

Construct with val

A foreign occurrence in a Cene code s-expression that indicates something should be looked up by just using the indicated value, instead of by the name of a literal string.

isa-stx

Call with val

Returns (yep (nil)) if the given value is a located s-expression (a value containing an s-expression and associated source location information) and (nope (nil)) otherwise.

s-expr-layer-from-stx

Call with stx

Given a located s-expression, returns either a foreign, a cons and nil list of located s-expressions, or a istring-cons and istring-nil string interpolated with located s-expressions. This operation can be repeated recursively to obtain an s-expression value with no source location information at all.

stx-details-from-stx

Call with stx

Given a located s-expression, returns a syntax details value (a value designating the source location information).

stx-from-details-and-layer

Call with stx-details s-expr-layer

Given a syntax details value and an s-expression layer (a foreign, a cons and nil list of located s-expressions, or a istring-cons and istring-nil string interpolated with located s-expressions), returns a located s-expression which returns that s-expression layer when stx-details-from-stx is called. The syntax details are used to enrich the resulting located s-expression’s source location information.

stx-details-empty

Call with (ignored)

Returns a syntax details value that conveys no information.

stx-details-join

Call with outer inner

Given an outer syntax details value and an inner syntax details value, returns a syntax details value that conveys the same information as each of them, one wrapping the other.

stx-details-macro-call

Call with call-stx-details macro-name-stx-details

Given a syntax details value corresponding to a macro call location and a syntax details value corresponding to the location of the macro name in that macro call, returns a syntax details value suitable for tagging syntax created by that macro call.

procure-claim

Call with ns

Monadically, writes to a standard but obscure location known as $$claimed in the given namespace.

The point of this is to ensure that two macro calls that use the same unique namespace will cause an error. All the built-in macros write to this location on their given unique namespaces.

procure-macro-implementation-getdef

Call with ns macro-name

From a standard but obscure location known as $$macro-implementation in the given namespace, obtains a getdef that is used to associate the given macro name with a macro implementation.

cexpr-var

Call with var

Given a name, returns a compiled expression with just that name in its free variables. It represents an expression which looks up a local variable by the given name.

cexpr-reified

Call with val

Given any value, returns a compiled expression with no free variables. It represents an expression that returns the given value.

cexpr-located

Call with stx-details body

Given a syntax details value and a compiled expression, returns another compiled expression that’s effectively the same as the given one, but attributed to the given syntax details.

cexpr-let

Call with bindings body

Given an ordered assoc list from mutually unique names to compiled expressions, and given a compiled expression body, returns another compiled expression with the union of the bindings expressions’ free variables and all but the given variables out of the free variables of body. It represents an expression which runs the binding expressions in order followed by the body expression. The results of the binding expressions are in scope as local variables with the given names in the body expression.

let

Macro. Example: (let a (nil) b (nil) (append a b))

Todo

Document this.

eval-cexpr

Call with mode cexpr

Given a compiled expression, executes it to produce a result. The compiled expression must have no free variables. The given mode must be current, and it must allow for macroexpansion-time side effects.

compile-expression-later

Call with caller-scope stx (fn result)

Monadically, macroexpands the given stx in a later tick, allowing the macro calls to monadically install definitions over the course of any number of ticks, and either monadically invokes the given callback with the resulting compiled expression itself, or passes the callback on to a macro implementation to do it.

Note

This isn’t a built-in operation. It’s defined in era-prelude.cene.

read-all-force

Call with string

Todo

Document this.

def-macro

Macro. Example:

(def-macro list home-scope caller-scope my-stx-details args then
  (basic-pure-macro home-scope caller-scope my-stx-details then
  /fn mode caller-scope s mac
  /foldr args (c mac str.nil /nil) /fn first rest
    (c mac str.cons /cons first /cons rest /nil)))

Defines a macro. The first argument is a syntactic name ((istring-nil <string>) or (foreign <name>)) for the macro. The rest of the arguments are the parameters and body of a curried function. The function will be called immediately with the scope where the macro is defined, and the result will then be called whenever a macro by the given syntactic name is expanded.

When a macro is expanded, its implementation function is called with several arguments: caller-scope my-stx-details args then

caller-scope: A (scope unique-ns def-ns qualify) value representing the caller’s scope.

The caller-scope’s unique-ns: A namespace that is supposedly used exclusively for this macroexpansion. It’s useful in the way that gensyms are typically useful in other macro-capable languages, but the uniqueness is achieved by playing along: If the macro compiles more than one subexpression, each subexpression should be given a unique-ns derived in different ways from each other.

The caller-scope’s def-ns: A namespace that is supposedly shared across all nearby macroexpansions. If the macro needs to install any definitions or look up any definitions using names that come from the caller, this is the namespace for that purpose. It should usually be passed as-is to any compiled subexpressions, except when a macro needs to establish a local definition scope.

The caller-scope’s qualify: A function that takes an unqualified name and returns a qualified name. This is useful for establishing local definition scopes that work by translating the local names to obscure global names.

my-stx-details: A collection of source location information. This is a value user-level code doesn’t know how to deconstruct, but it conveys information about this macro invocation, so the macro can attach it to the located s-expressions it creates in order to receive proper attribution for them; see stx-from-details-and-layer.

args: The cons list of located s-expressions that correspond to the subexpressions at the macro call site.

then: A callable value that takes a compiled expression and returns a monadic effect. Invoking this effect causes the compiled expression to be used as the macro result. A macro should invoke this effect exactly once. The effect doesn’t necessarily need to be invoked right away; the macro can use later to invoke more effects in a future tick.

The macro’s return value is a monadic effect, which will be invoked by the macroexpander.