Ajisai

Introduction

Ajisai is an AI-first, vector-oriented dataflow language for auditable, exact vector computation with machine-readable contracts. A program is a sequence of elements, most of them calls to Words. Values live on a single stack: each Word takes (consumes) its operands from the stack and pushes its result back onto it. Fractions and the Vector as a data structure play the central roles.

When a well-formed operation cannot produce a value, the result is NIL, which carries its reason and is handed on to downstream computation as it is. When the operation or the shape of its input is itself wrong, the result is an error and evaluation stops on the spot. Even a well-formed program is an error once it exceeds the limits the host can support; those limits are covered in 1.2.2 The cost of evaluation.

Why I made Ajisai

I had two reasons for developing Ajisai. One is that I had given up on learning every programming language I tried. The other is that I never wanted to build something with the tool called a language — I wanted to build the tool itself.

The turning point came when I met Forth. Stack orientation: minimalism pared down to the limit. The way it strips away syntactic noise and lays the act of computation bare taught me that a language is allowed to be this small.

But in my everyday working life I am the kind of person who values manuals and established method, and I could not bring myself to give up the robustness that "types" bring to programming. Out of that came a fierce dilemma: "I want to take types seriously, but I do not want to write about types."

The answer to that contradiction was to carry rigor not as annotations attached to values but as machine-readable contracts on the side of the Words. Every Core Word carries a contract stating what it takes and how many, whether it is pure, and what it returns when it cannot produce a value. User-defined Words can declare the same kind of contract, and it is checked against the definition before anything runs. There is nowhere in the language for the programmer to write a type, yet the checking stays with the Words.

Numbers follow the same policy. Whether you write an integer or a decimal, every value is an exact rational, and SQRT extends the number field from there to algebraic irrationals. Nothing is ever rounded. The question of choosing between float, double and decimal simply does not exist.

What turned this uncompromising, extreme design into something real was meeting AI. In an age when AI interprets intent and becomes a powerful development partner, there is no need to dress a language up with sweet syntax for humans (syntactic sugar). If you take "AI-first" as the premise — a new kind of intelligence spinning code alongside you — then a design that lays down only strict, machine-readable rules and leaves the rest to pure dataflow becomes viable. Of that I became convinced.

Exact numbers, and a stack that carries them. When that form settled, the image that came to mind was "water poured into a vessel". What fills the vessel is only water that is never rounded. Yet there is no limit to the shapes of the ripples you can spread across its surface together with AI.

As it happens, there is a flower whose scientific name derives from "water vessel": the hydrangea, ajisai in Japanese. I started development in June in Japan, during tsuyu, the rainy season, when the rain goes on and on. Ajisai is a language made with that scene in mind.

Numeric exactness

Every number is handled exactly. Values are held as exact rationals and as the algebraic irrationals that arise when those are closed under SQRT — the multi-quadratic normal form. Arithmetic and comparison both run without rounding error. The stack display sqrt(2) or 1/1+sqrt(2) writes that normal form as a single token; nothing is truncated or approximated. The Playground's Stack area shows the same token as it is.

What this Reference offers

This Reference explains each feature together with a short, verified sample. Every example has an "Open in Playground" button: one click loads the code into the app's editor, so you can see the actual behavior immediately.

This Reference divides a program into its elements, and divides each element further for as long as it can be divided. What lies at the end of that division is the individual Word, and that is where the Reference ends.

Where this Reference stands

This Reference is for people who use and learn Ajisai. If you are implementing or porting the language itself, consult the Specification, the single design authority. This Reference reorganizes its content for everyday use and learning.

How to read the examples

The Expected value column of each section shows the final state of the stack after the program runs, rendered according to the language's display rules. These are the display rules to know in advance:

1. Basic display rules

• Numbers: shown as exact fractions of the form numerator/denominator. The integer 3 is rendered as 3/1.
• Booleans: shown as TRUE or FALSE.
• Absence of a value: shown as NIL.

These are the standard renderings in the Stack area, and they match what the Expected value column of this Reference states. If the screen shows 3 rather than 3/1, the LaTeX display mode described next is switched on. The setting is remembered by the browser and survives a reload, so it may still be on from an earlier visit. When comparing against the Expected value column, take the unchecked state as the baseline.

2. LaTeX display mode (typeset mathematics)

The Stack area has a LaTeX checkbox, off by default. Turning it on redraws the same values as typeset mathematics.

• A fraction is shown with its numerator stacked over its denominator.
• A numeric Vector is rendered as a matrix.
• A fraction whose denominator is 1 is treated as an integer: 3/1 is rendered as 3.

This is another rendering of the same value; the value itself does not change. In either display mode it stays an exact rational, with no rounding and no silent reduction. Unchecking the box returns to the canonical form. Values with no mathematically unique typeset form — Strings, NIL, Vectors of uneven shape — keep the standard rendering even with the box checked.

3. Abbreviated display of large collections

When a collection has very many elements, the Stack area draws only the leading part and appends a marker such as … 199900 more. The marker is a note about on-screen rendering; the data itself is not truncated. The collection on the stack is held complete, and every Word sees the whole of it. LENGTH returns the real element count.

4. How symbols and tokens are written

Text with a gray background in the body of this Reference is always an Ajisai token. The gray background says the text is part of program code, not prose. A token spelled only with symbols is an ordinary name like any other.

1 Program

An Ajisai program is a sequence of elements.

A program is zero or more elements, written one after another and separated by whitespace.

Elements are written separated by whitespace and evaluated one at a time, left to right. Branching, iteration and definition are Words, written in the sequence like any other element. [ 2 MUL ] 'DOUBLE' DEF is a program of three elements: a Vector, a string and a name.

Two things are said about a program: how its text is divided into elements (1.1 Separating elements), and how the elements in sequence are evaluated (1.2 Evaluation). The elements themselves are the subject of 2 Elements.

1.1 Separating elements (whitespace, #)

Elements are separated by whitespace. The text is first divided into a sequence of tokens, and each pair of square brackets [ ] gathers its tokens into a Vector, giving the sequence of elements. The rules that turn text into tokens are defined once, in spec/grammar.json, and every text becomes either exactly one token sequence or exactly one named source error.

How the lexer works

The lexer reads the text left to right. At each position where a token may start, it tries the four rules below in order, and the first rule that applies consumes the characters there.

1. Whitespace (space, tab, newline and the other Unicode whitespace characters): skip one character. Nothing is emitted.
2. #: a comment. Discard everything up to the end of the line.
3. ': a string literal. Read up to a closing quote ' followed by whitespace or the end of input.
4. Anything else: cut out one word, up to the next whitespace (or the end of input). No character along the way is checked.

A word cut out this way is then classified, in this order. The whole word decides, so there is no rule for individual characters.

1. Exactly [ or ]: a delimiter (the start or end of a Vector).
2. Otherwise containing [ or ]: a source error (bracketMustStandAlone).
3. The shape of a fraction with a zero denominator (1/0): a source error (zeroDenominator).
4. The whole word matches the number grammar: a number literal.
5. Everything else: a name.

Finally, bracket pairing is checked over the whole token sequence: a ] with nothing open and a [ never closed are source errors. Source that fails at any of these stages runs not a single token.

How tokens are separated

Tokens are separated by whitespace (space, tab, newline) and nothing else. No other character splits a token. Symbols and punctuation are all ordinary characters of a name.

The rule has no exceptions, and neither of the following is one.

• [ and ] must stand alone, like any other Word. [ 1 2 3 ] is correct; [1 2 3] is a source error that points out the missing whitespace.
• # starts a comment only at the start of a token. A # attached to the preceding token is part of that name, so ADD# note is not ADD with a comment but an undefined Word named ADD#.

The only brackets Ajisai gives a meaning to are the one pair [ ]: the Vector brackets, which code blocks use too. { } and ( ) have no syntactic role. They are just characters of a name, so writing one alone answers "there is no such Word". See Exact numbers for more.

Operator Words need whitespace

An operator Word is a name too, so it needs whitespace on both sides. 2 ADD is correctly read as the two tokens 2 and ADD. 2ADD is taken as the single name "2ADD" and is an undefined-Word error, not an addition.

The square brackets [ ] are the same. Each is a Word of its own and needs whitespace around it. [ 1 2 ]LENGTH is rejected because ]LENGTH is an invalid token; write [ 1 2 ] LENGTH.

The Playground's Format button fills in this missing whitespace (the same formatting also runs before execution, so in the Playground [1 2 3] runs as [ 1 2 3 ]). Only the source being edited is reformatted; the language's rule is not relaxed. Handing the same source unchanged to the CLI or MCP is an error.

Line breaks

A line break is whitespace just like a space and means nothing beyond separating tokens. A program may span as many lines as you like; written on one line or split across several, it is the same program. The same holds for a Word definition's body: two definitions that differ only in where the lines break are the same Word, and their DIGEST matches. The only thing a line break ends is a comment: from a # at the start of a token to the end of the line.

Comments

# starts a comment that runs to the end of the line. The characters from # to the end of that line are discarded before tokenization. A # inside a string literal is ordinary text, so 'a # b' is a single string.

Examples

Kinds of token

Lexical analysis produces only five kinds of token. Whitespace and comments produce none.

Source errors

These five are the only errors lexical analysis can raise, all classified malformedSource.

1.2 Evaluation

A program is evaluated element by element, left to right. What happens depends on the kind of element:

• A number or string literal: its value is pushed onto the stack.
• A Vector [ ... ]: pushed as a Vector without evaluating its contents. Names inside stay as Symbols, except TRUE, FALSE and NIL.
• A name: if it is bound, its value is pushed; otherwise the Word of that name in the dictionary is called. If it is neither, it is an error (Unknown word).

Values on the stack

Every value evaluation pushes onto the stack belongs to exactly one of seven domains. The domains are disjoint, with no implicit conversion between them.

• Numbers: exact rationals and algebraic irrationals (2.1 Numbers)
• Strings (2.2 Strings)
• Vectors: sequences of values, also read as code (2.3 Vectors)
• Symbols: names held as data (2.4.1 Bindings)
• Booleans: TRUE and FALSE (2.4.2.1 Logic, comparison, arithmetic)
• Records: keys paired with values (2.4.2.3 Keyed data)
• NIL: absence with a reason (1.2.1 Outcomes)

Consumption

An Ajisai Word takes its operands from the stack and pushes its results back. A value that is read is always consumed on the spot and removed from the stack. No modifier changes this. Words that push no result, such as BIND, DEF and DEL, are no exception: they consume their operands too.

Using the same value twice: BIND

To use one value more than once, name it with BIND and write the name as many times as you need. Each time the name is written, its value is pushed onto the stack. 5 'N' BIND N N 1 ADD is 5/1 6/1. Because values are read by name, you can see from the text alone which value is used where.

A Word can be replaced by its body

Every call consumes exactly the operands it reads, so writing a Word you defined as its body instead does not change which operands are consumed. Given [ 2 MUL ] 'DOUBLE' DEF, both 5 DOUBLE and 5 2 MUL are 10/1. This property is what lets you check a program that uses User Words by expanding it into Core Words alone.

1.2.1 Outcomes (values, NIL, errors)

Evaluating one element ends in one of three ways: it succeeds and pushes the outputs its contract registers (some Words have none), it pushes a NIL carrying a reason, or it stops the whole evaluation with an error.

The NIL rule

The failure model fits in one sentence: if a value could not be produced, NIL; if the usage itself is wrong, an error. A well-formed operation that cannot produce a result maps to NIL with a structured reason. Misuse — a wrong type, missing operands — raises an ordinary error.

NIL propagates

Arithmetic and comparison both pass NIL through. A NIL operand does not crash the pipeline; the result simply becomes NIL. EQ is no exception: NIL 1 EQ is NIL, not FALSE.

One condition has one answer. "Past the end" is NIL for GET, TAKE and PUT alike, the same across the whole vocabulary. A count or index that is not even an integer ([ 1 2 3 ] [ 'x' ] TAKE) is still an error — that one is wrong usage.

1.2.2 The cost of evaluation

The cost of iteration

Exact arithmetic changes what a loop costs. Every other section of this Reference is about what a program means; this one is about what repeating it costs, because it is the one place where exactness asks for something in return.

Where the cost comes from

An exact rational is stored as a pair of numerator and denominator, and the product of two fractions has the product of their denominators. Multiply once and nothing happens. But keep multiplying in a loop, and the denominator grows step after step. That is exactly what gradient descent, Newton's method, k-means, power iteration and every other iterative method do. Nothing is lost and nothing is approximated; the number stays entirely correct. But its digits record how the value was computed, and that history grows longer every round.

Here is a relaxation step in which x moves a tenth of the way toward 2 each time. DELTA is the correction and STEP applies it. The loop is a FOLD over a range whose elements are mere counters; the block discards the element and keeps only the accumulator.

The problem is not the size of any one number but the shape of the growth. Run the same loop for 21 steps and you get 359418989131512359209/125000000000000000000: 21 digits over 21 digits, a value of about 2.875. Each further step multiplies the denominator by ten again, so the answer barely moves while the cost per step climbs without limit. A loop that finishes in an instant at 30 iterations can crawl at 300.

Naming the resolution

x d MUL 1/2 ADD FLOOR d DIV rounds a value to the nearest multiple of 1/d (an exact midpoint goes to the larger side). The result's denominator divides d and never grows beyond it. Applied once per step, it throws away the derivation history and keeps only the value.

This is an approximation, and that is exactly the point: it is an approximation you wrote down yourself. The resolution is a literal in the source, at a place you chose, and every value after it is exactly a multiple of 1/d. Nothing is rounded behind your back, and nothing decides on its own how much precision the answer deserves.

MUL, ADD, FLOOR and DIV, which make up this rounding, all lift over Vectors, so a whole parameter Vector is rounded by the same run of Words.

A closed form beats a loop

Before reaching for an iterative method, check whether the problem has a closed form. In exact arithmetic a closed form is not only faster; it is a different kind of answer. Least squares, ridge regression with a rational penalty, k-nearest neighbours, naive Bayes over rational probabilities, decision trees with Gini splits, the perceptron and the simplex method all have exact solutions without iteration. Ajisai returns the coefficients as exactly those rationals: an R² that comes back as 529/532 is the exact answer.

Transcendental functions — exponentials, logarithms, trigonometric functions, arbitrary powers — have no rational answer, and Ajisai does not handle them. SQRT is the only irrational the language constructs exactly, as an algebraic number, and POW with an integer or p/2 exponent stays inside that field. The number domain is this field in its entirety, so every comparison is decided as TRUE or FALSE in finite time.

The other cost: the host's safety controls

The costs so far accumulate naturally from exact arithmetic itself, even in a correctly written program. Separately, the host sets several limits to protect its computing resources. Each is a safety control on the host side, not language semantics, and the concrete numbers are set by the implementation. The same source may pass on a host that declares larger limits. What happens on overrun is fixed, however: if producing a single value exceeds a limit, the result is a reasoned NIL; if the run itself exceeds a limit so far that it cannot continue, it is an error and evaluation stops.

Run-time errors: one result with several reasons

Even a well-formed operation or input is an error once it exceeds what the host can support, and evaluation stops on the spot. There is more than one limit: overruns are reported under at least three names, depending on what was exceeded. The names differ because the fixes differ.

executionLimitExceeded can be set explicitly with the CLI's ajisai run --step-limit <N>. The default is an implementation choice made by the host's runtime, not a fixed number this Reference promises.

The three above are limits the interpreter counts, but the Playground has one more: a wall-clock cut-off. When a single run exceeds 5 seconds, it is stopped together with its worker and reported as Execution timed out after 5000 ms. This is neither language semantics nor an interpreter budget but a host-side guard that only this screen has. That is why it carries none of the names above; instead it comes with a diagnosis that says which guard stopped the run and suggests rewriting with bulk operations or pruning by rounding to a grid. Hover over the resource limits: badge next to the build indicator at the top of the screen to list the host's limits (this guard is listed there too). The MCP host declares a different, stricter materialization limit. That is why the same 0 100001 RANGE succeeds in the Playground but is NIL (spaceExhausted) on the MCP host.

The work done by the whole program and the size of a single value are measured separately. Some Words, such as 0 99999 RANGE UNIQUE, count as one step yet perform as many comparisons internally as there are elements, so the step budget alone does not show how heavy a value is. Recall the fraction whose denominator kept growing in the section on the cost of iteration: grow it without pruning to a grid, and exactly this resourceLimitExceeded is where it ends. recursionLimitExceeded is different again. A Word cannot call itself, so this is not a recursion depth but the depth of a non-cyclic call chain that passes through many different Words, A→B→C→….

Materialization limits: a reasoned NIL

RANGE and FILL have a limit on the size of the Vector one call produces. Even when the request itself is well-formed, trying to materialize beyond that limit gives a reasoned NIL, not an error. The reason is spaceExhausted. A dimension or shape that is itself wrong, such as a negative or non-integer number, is a different matter and is an error, as usual.

Being NIL, it can be replaced with a fallback value so the program moves on: 0 999999999999 RANGE 'S' BIND [ ] S S NIL? SELECT recovers to the empty Vector. An error has no such recovery.

2 Elements

There are four kinds of element.

An element is one of four things: a number, a string, a name or a Vector. A Vector is zero or more elements between [ and ], and it is the only element that contains elements.

Whitespace and comments are not elements (1.1 Separating elements).

Display forms are not elements

What the stack shows is, as a rule, a form that gives the same value when written as elements. The exception is an irrational's sqrt(2) (2.1 Numbers): that is how the value looks, and written as an element sqrt(2) is a plain name. An irrational is built with SQRT. A Record has no look of its own; it is displayed as the program that builds it, such as [ 'x' ] [ 1/1 ] RECORD (2.4.2.3 Keyed data).

2.1 Numbers

Number literals

A decimal literal needs at least one digit on both sides of the point. 0.5 and 5.0 are numbers; .5 and 5. are not. Because of this rule the point is never the first or last character of a number, so a lone . can safely be an ordinary name rather than an incomplete literal.

A number is written in one of four forms. A "run of digits" is one or more of the ASCII digits 0 to 9.

A fraction takes neither a decimal part nor an exponent (1/2.5 and 1/2e3 are names). These forms apply to the whole word. A word that starts like a number but does not end as one is a name, not a malformed number. A full-width digit is a name character.

Exact numbers

Every number in Ajisai is an exact number.

How numbers are written, and their domain

Integer, fraction, decimal and exponent literals are only different notations for the same exact value. 0.5 is exactly 1/2.

The number domain consists of the exact rationals and the algebraic irrationals that arise when those are closed under SQRT — the multi-quadratic normal form. Every number you can build is one or the other.

The stack display of an irrational (sqrt(2), 1/1+sqrt(2)) writes its normal form as a single token. The Playground's Stack area shows the same token. See How irrationals are displayed, and the syntax rule for more.

How irrationals are displayed, and the syntax rule

Irrationals have one display form: the value's normal form written as a single token with no whitespace. 2 SQRT is sqrt(2), 1 2 SQRT ADD is 1/1+sqrt(2), 2 SQRT 3 SQRT SUB is sqrt(2)-sqrt(3), and 8 SQRT is 2/1*sqrt(2) (the radicand is normalized to be square-free). Nothing is truncated or approximated, and inside a Vector it reads as a single element. The stackDisplay of the CLI and MCP hosts and the Playground's Stack area all show this same token. The CLI and MCP also list the same terms, structured, under semantics.exactTerms.

This is display-only output, not source syntax. Writing sqrt(2) in a program gives an unknown name. ( ) are name characters, not syntax, so written in a program they do not act as parentheses.

2.2 Strings (' ')

String literals

A string literal is closed by a quote (') at a token boundary. Here too only whitespace separates tokens, so the closing ' must be followed by whitespace (or the end of input). An apostrophe inside the string does not end it unless whitespace follows. This lets you write a string such as 'It's fine' as a single literal, with no escape character. Conversely, a quote followed by anything other than whitespace stays inside the text, so both 'abc'CHARS and [ 'abc'] are an unterminated string, not two tokens.

Strings (' ')

Strings are quoted with ' and shown with their quotes on the stack. The quotes are a display convenience, not part of the value. PRINT writes the raw text, so 'TEST' is output as TEST; see Output for more. A string nested inside a collection keeps its quotes, though: [ 'AB' 'CD' ] is shown just as written. Conversions between strings and numbers or characters are collected under String operations.

A value domain of its own

A string is one of the seven value domains, not a Vector of code points. 'A' [ 65 ] EQ is FALSE, and arithmetic on a string is an error, not arithmetic on codes. The empty string '' is an ordinary string, not NIL.

2.3 Vectors ([ ])

Vectors ([ ])

A Vector is written by enclosing its element values in square brackets [ ], separated by whitespace. A Vector literal evaluates to that Vector value as it is, and literals nest freely.

Bare names inside a literal

A Vector literal is a literal all the way through. A bare name written inside [ ] denotes a Symbol; it is neither run as a Word call nor an undefined-Word error. So [ FOO BAR ] is the Vector [ FOO BAR ] of two Symbols. If you want text, quote it — [ 'FOO' 'BAR' ] is a Vector of Strings. This is an easy point to trip over once you start naming values. To put the value of a variable, or the result of running a Word, into a Vector, use a run-time collection builder such as COLLECT rather than a literal. See A name inside [ ] is a Symbol for more.

[ ] versus NIL

[ ] is the empty Vector. It is a collection holding no values, but it is an ordinary value you can write, nest and measure: [ ] LENGTH is 0. It is not NIL. NIL is the absence of a value, which is a different thing from a collection that happens to hold nothing. An operation whose result is empty returns [ ], not NIL: [ 1 2 3 ] [ 5 GT ] FILTER is [ ].

Code as data

A code block and a Vector are the same kind of value. [ ] is the only bracket for both; a block is just a Vector holding source to be evaluated later, not a domain separate from data. It is read as something executable only when a Word's contract asks for it as code, so a block on the stack is displayed just like any Vector: [ 2 MUL ] is shown as [ 2/1 MUL ], and [ ] as [ ]. [ 1 2 ADD ] [ 1 2 ADD ] EQ is TRUE — how a value was built (its construction history) is not part of the value, so whether a Vector is "code" or "data" is not decided before it is used. A bare name inside a block — MUL above — is a Symbol and is not looked up when the literal is built. EXEC and the Words that ask for evaluation run it; nothing else does.

Putting a run-time value into a block

A block is source, so values computed while the program runs are not inside it. MAP and FILTER take only a block, which raises a practical question: how do you filter by a threshold known only at run time? [ 5 LT ] compares against the literal 5, but when the number is something the program computed, there is no 5 to write.

A block is an ordinary Vector, so it can be built with ordinary Vector Words. CONCAT joins a one-element Vector holding the run-time value with a one-element Vector holding the Symbol the block needs to run — [ 5 ] [ LT ] becomes [ 5 LT ], and the result is no different from any other block. Even though it was not written with [ ], every Word that takes a block accepts it. No separate bridge is needed; this is the very construction the sample above already showed.

That is all there is to partial application in Ajisai. There is no separate Word for it, and none is needed, because a block is a value whose contents can be computed like any other Vector's.

Blocks and evaluation frames ([ ])

A block has no stack discipline of its own. The Word that evaluates a block decides what the block can reach and what it may leave behind. Read with the wrong rule, an ADD inside a block either finds two operands or finds none. There are five rules, and the block's own text does not say which one applies. The Word that receives the block decides.

So [ ADD ] 'ADDW' DEF followed by 3 4 ADDW gives 7, and so does 3 4 [ ADD ] EXEC, because both see the whole stack. But 100 [ 1 2 ] [ ADD ] MAP is a stack underflow: the block sees only one element, and 100 is not in its frame.

Reread "anything below the top is discarded", because it happens silently. A predicate that leaves two values passes straight through: [ 1 2 3 ] [ 1 GT TRUE ] FILTER keeps everything, because the TRUE on top is the answer and the comparison result below it is discarded. It is an error only when nothing is left. If a higher-order Word's block gives an answer you cannot explain, count how many values it leaves.

When something fails inside a block, the diagnosis names the Word that failed, not the Word that ran the block. [ 1 2 ] [ 'x' 1 ADD ] MAP reports ADD, with the position of the statement that ran and inside MAP attached. This drilling down stops at a Word you defined yourself: that call reports the Word itself, because from the caller's side that is what failed.

A block written inside another block is data where it is written. It is evaluated only when the Word that receives it runs it, and then under that receiving Word's own rule, not the outer block's. That is about evaluation, though, not reference. Even when the name of the Word being defined appears only inside a [ ] passed to MAP or EXEC, DEF's acyclicity rule detects it and rejects the definition itself.

2.4 Names

A name is every word that is not a number, a string or a square bracket. Any character other than whitespace and the square brackets can be part of a name; but a word beginning with # is a comment and one beginning with ' is a string, so a name never begins with either (1.1 Separating elements).

Evaluating a name pushes its value if the name is bound (2.4.1 Bindings), and otherwise calls the Word of that name (2.4.2 Words). A name that is neither is an error (Unknown word). A name written inside [ ] is not evaluated; except for TRUE, FALSE and NIL, it becomes a value called a Symbol.

Symbols and how tokens are recognized

A symbol in Ajisai is simply a name spelled with symbol characters. Every Word is called by its one English name, and no Word has a symbol spelling. + and < are ordinary names too, undefined unless you define them. Because a symbol is just one way of spelling a name, even a multi-character symbol does not complicate the rule above: a token ends only at whitespace, never partway through. A token's meaning is decided by the lexeme of the whole token, not by its first character. For example, 1/2 is parsed as a whole fraction literal, while a lone / is parsed as a plain name.

A name is a Word or a binding, never both

You cannot bind a name that a Core or User Word already has, and you cannot define a Word under a name that is currently bound. Both directions are rejected, so you never have to think about which of the two a name resolved through. Short throwaway names such as W, DX and LIMIT are exactly right here, and unlike Word names they are not subject to naming-convention warnings: they are local, and their scope fits on the screen in front of you.

Name resolution and redefinition

A name resolves in either Core or User, and User never shadows Core. So a Word's name is the whole of its address: there is no qualified form, no dictionary to choose, and no room for a bare name to be ambiguous. Names are case-insensitive, so add10 and ADD10 are the same Word.

2.4.1 Bindings (BIND)

Giving names with BIND

The stack hands you one value at a time, but most expressions worth writing use a value more than once. A residual is used in both the squared error and the gradient; a threshold in both the comparison and the report; a pair of coordinates in both their sum and their difference. An Ajisai Word always consumes the values it reads, so by its second use a value is already gone from the stack.

So BIND gives a value a name. It takes a value and a name, consumes both, and from then on the name is that value. Use it as often as you like, in any order.

With one name, it receives the whole value. With several, it destructures a Vector of the same length position by position. The lengths must match exactly, or BIND raises an error. Letting it through silently would drop the tail when the Vector is longer, and leave some name with nothing when it is shorter — not what the writer meant.

A name inside [ ] is a Symbol, not a value

This is the one place where binding trips people up; read it before you get stuck in your own program. Inside a Vector literal a bare name denotes a Symbol — data until something runs it — and is never looked up. Bound names are no exception. So after 3 'K' BIND, [ K ] is not [ 3/1 ] but the one-element Vector [ K ] holding the Symbol K.

It catches people because this Reference's idioms are written like 0 GET and 3 TAKE, so the natural next move is XS [ K ] TAKE. And that fails, because a Symbol is not the integer TAKE expects. There are two ways to say what you mean.

How far a name reaches

A binding belongs to the frame that made it and lives exactly as long as that frame. A frame is a Word's body, or, for direct input, the run itself. Two rules follow, and those two are the whole story.

A name reaches blocks written inside its frame. The blocks that MAP, FILTER, FOLD and EXEC run are not a new frame for names, so they can read the surrounding names as they are. The isolation these Words enforce is about the stack, and names are not on the stack; see Blocks and evaluation frames for the details of that isolation. This is what lets a predicate test against a value the program could only know at run time.

A name does not reach into the Words you call. A Word's meaning is decided by its operands and the dictionary alone, and by nothing else. That is what makes a Word readable on its own. A body reads only its own bindings, never its caller's. If a value is needed inside, pass it as an operand — that is exactly what operands are for. Get this wrong and you are told so plainly, rather than seeing it reported as an unknown Word.

A Word that binds leaves no names behind for its caller, and a run's bindings disappear when the run ends. This is deliberate: a name that outlived its frame would become a second, editable namespace next to the dictionary. There is only one namespace here. For data you want to keep, define a Word, as in [ [ 1 2 3 ] ] 'XS' DEF. That is exactly the job the dictionary is for.

2.4.2 Words (DEF)

A Word is a named operation registered in the dictionary. Called by its name, it consumes operands from the stack and pushes the outputs its contract registers, if any. The built-in Words are grouped by what they do into families, and each family page ends with the contract of each of its Words. The individual Word is the last unit of this Reference.

Every operation is a Word

Ajisai's lexical structure tells apart only numbers, strings, names and the one pair [ ]. There are no reserved words. Arithmetic and comparison, branching, iteration, definition and binding — even TRUE, FALSE and NIL, which push one value — are ordinary Words, each with one English name, held in the dictionary and called by name.

Every Word is listed under Built-in Words.

Dictionaries and Word identity

Two tiers: Core and User

The dictionary has two tiers, and that is all. Core holds the 78 canonical Words and is sealed: a Core name cannot be redefined or deleted. User holds everything you defined with DEF.

These 78 Words divide into the 48-Word Semantic Kernel and 30 Standard Words. A Kernel Word either builds or observes some kind of value, or is the one explicit way to do something — running a code block, recovering from NIL, changing the dictionary, output. A Standard Word, such as SUB, MIN, SORT or TRIM, gives a frequent idea one fixed name and contract. The division only tells you where a Word sits in the design; it changes nothing about how you use it. All 78 are ordinary Core Words in the same single flat dictionary, reached by their plain names, with the same contracts, examples and error conditions. Each Word's tier is listed with the built-in Words and in each page's contracts, and it is also shown when you look the Word up.

Making a new Word with DEF

A new Word is defined from a code block and a name: [ body ] 'NAME' DEF. The body runs every time the Word is called.

What DEF checks, and what it does not

DEF only stores the body; it does not resolve the names inside it. A definition whose body calls a Word that does not exist is accepted and reported as defined. The failure surfaces the first time the Word is called: [ TOTALL 1 ] 'FOO' DEF succeeds, and only running FOO reports Unknown word: TOTALL.

This is a design choice, not a gap in checking. Names are resolved at call time. This lets a Word call another Word defined after it, so you never have to reorder definitions to match their dependencies.

The price is that a typo in a body lies quietly in wait until something calls it. The headless CLI can catch it in advance: ajisai check resolves every name in a file without running anything and reports the unknown ones, and ajisai check --contract also verifies declared Word contracts. The Playground has no equivalent; inside the app, calling a Word is itself the check.

A Word cannot call itself

The reference graph of the User dictionary has no cycles. If a body contains the name of the very Word being defined, as in [ REC ] 'REC' DEF, DEF rejects it with an error. It does not matter where the name is written: directly in the body, or only inside a [ ] block passed to MAP or EXEC, it is the same.

This extends to indirect cycles. Define A to call B, then try to define B to call A, and the second DEF is rejected: A's body already contains the name B (even though it does not exist yet), and adding a reference from B to A would close a cycle back to A. A new definition is free to call Words that already exist. The only thing forbidden is for the chain to come back to the Word being defined right now.

Iteration cannot be expressed by a Word calling itself. MAP FILTER FOLD SCAN over an already finite Vector are the only means of iteration. With no cycles in the User dictionary no Word can call itself, so every evaluation is structurally finite. This is a stronger property than the run-time step budget (covered under Run-time errors): the budget still limits the cost of a single evaluation, but there is no such thing as a program that would not stop however large the budget.

Managing Words

DEL deletes a user-defined Word by its quoted name. Dependencies are tracked, and a Word that other Words depend on cannot be deleted at all, so dangling references cannot happen. Delete the dependent side first.

Word names are case-insensitive, so add10 and ADD10 are the same Word. By convention they follow a verb-object form such as APPLY-GAIN. How a name is matched to a definition is covered in Dictionaries and Word identity.

Looking up a Word

Put the cursor on a Word and press Ctrl+Alt+L, and the Playground answers from the dictionary in the Output area: a Core Word's Reference entry, or the DEF of a Word you defined, both shown the same way, as text to read — not in a form to put back into the editor. This is something the editor does, not the program. Nothing is pushed, nothing is consumed, and the answer is text rather than a value, so there is no Word a program could call here.

Three other operations exist only as shortcuts: Reset Ctrl+Alt+Enter, Stack clear Ctrl+Alt+S and Editor clear Ctrl+Alt+E, which discard the whole session, the stack, and the text of this input area respectively. None of these four can be typed and run or called from a program. A Word named RESET or LOOKUP, if there were one, would be an ordinary Word like any other name.

Word identity

Every Word has a content identity: a digest over its normalized definition and the identities of the Words it calls. Two definitions with the same identity are the same Word whatever their names, and changing a definition changes the identity of everything that depends on it. This is why DEF and DEL refuse to disturb a Word something else still refers to: the dependency is on the Word, not on its spelling.

Reading the dictionary and contracts from inside the language: DIGEST and CONTRACT

Two Words read, from inside the language, what the machine already knows about the dictionary. The operand that names a Word is a Symbol — a bare name written inside [ ] — not a string (CONTRACT also accepts a code block). 'ADD' CONTRACT is a notASymbol error. A Word that could look a name up from text would break the fact that "no Word turns text into a Symbol", which the cycle check at DEF time relies on.

DIGEST answers, as text, the content identity of a Symbol that names a Word, and the digest of the meaning of any other value. The same digest means the same thing; different digests mean nothing. CONTRACT answers a Word's contract as a Record: the registered contract for a Core Word (inputs, outputs, nil, projection, errors, purity, cost and so on), or the contract inferred from the body for a Word you defined. Pass a code block as it is, and its contract is inferred without running it — the pre-execution check (ajisai check --contract) called from inside the language, with confidence and gaps carrying "what could and could not be verified" as values. This is where the ability to ask about the cost class before running comes from.

Whether a Symbol resolves as a Core or User Word shows in whether CONTRACT answers a contract. A name that is not a Word returns a reasoned NIL, so sym CONTRACT NIL? NOT is that question. NIL? consumes its operand, so only the Boolean remains.

Built-in Words

The 78 Words of the canonical vocabulary, by family, generated from spec/words.json. 48 of them form the Semantic Kernel and 30 are Standard Words; every one is an ordinary Core Word reached by its plain name, and the tier only says where it sits in the design (Dictionaries and Word identity). Choose a Word for its contract — syntax, stack effect, NIL policy, ERROR conditions — or a page for the explanation with samples.

Contracts: Dictionary and names

2.4.2.1 Logic, comparison and arithmetic (AND, EQ, ADD)

Arithmetic

The arithmetic Words work element-wise between Vectors. Each is written with its one English name and has no symbol spelling.

Arithmetic Words

Broadcasting rules

Broadcasting is not merely a rule for stretching one-element Vectors; it is one consistent rule applied across the whole set of axes of multi-dimensional Vectors.

• Axis alignment: two Vectors are aligned axis by axis, starting from the innermost.
• Stretching length-1 axes: an axis the shorter Vector does not reach is taken to have length 1, and a length-1 axis is reused to match the other side's length. [ 1 2 3 ] [ 10 ] MUL is [ 10/1 20/1 30/1 ], and [ [ 1 2 ] [ 3 4 ] ] [ 10 20 ] MUL is [ [ 10/1 40/1 ] [ 30/1 80/1 ] ].
• Shape mismatch: when axis lengths differ and neither is 1, it is an error. [ 1 2 3 ] [ 10 20 ] MUL cannot align lengths 3 and 2, so it is an error.
• Scalars: a scalar needs no axes. It combines with every element, however the Vector is nested, ragged ones included.
• Rectangularity: two Vectors can broadcast against each other only when both are rectangular, that is, when every axis has a uniform length.

Other numeric Words

Beyond the four basic operations, the following numeric Words are provided.

• Sign: negation is written x -1 MUL, and absolute value x 'X' BIND X X MUL SQRT.
• Extremes: MIN (minimum), MAX (maximum)
• Square root: SQRT
• Rounding: FLOOR (round down), ROUND (round half up). Ceiling is written x -1 MUL FLOOR -1 MUL.
• Rounding to a grid: x d MUL 1/2 ADD FLOOR d DIV rounds a value to a multiple of 1/d. Use it to stop denominators from growing in loops and iterative computations. See The cost of iteration for more.

Division by zero does not crash the program; only the affected elements become NIL. See The NIL rule for more.

Powers, and reading integers and rationals: POW, GCD, RATIO

x y POW answers within the exact field. An integer exponent stays in the base's layer (2 10 POW is 1024, 2 SQRT 2 POW is 2), and an exponent p/2 on a non-negative rational base stays in the field as a power of a square root (2 1/2 POW is exactly the same value as 2 SQRT). Any other exponent — a denominator other than 1 or 2, p/2 on an irrational base, an irrational exponent — leaves the field, so it projects domainMiss, even when the answer would be rational (8 1/3 POW). A negative power of 0 projects divisionByZero; a p/2 power of a negative base has no real answer and projects domainMiss; an exponent too large for the machine to hold projects spaceExhausted.

GCD answers the non-negative greatest common divisor of two integers. Euclid's algorithm is an input-dependent iteration, which cannot be written by definition in this language, where iteration runs only over a Vector that already exists — the machine performs this computation all the time to keep every rational in lowest terms, and this Word merely makes it visible. RATIO opens a rational into a two-element Vector of its reduced numerator and denominator. Since the answer is a Vector, arithmetic lifts over it directly. A non-integer argument (GCD) or an irrational (RATIO) projects domainMiss.

Automatic lifting over Vectors

Every numeric Word lifts over Vectors automatically and broadcasts by the same rule as ADD. A rectifier that clamps negatives to 0 is written [ -1 2 -3 ] 0 MAX and gives [ 0/1 2/1 0/1 ]; per-feature standard deviation is a single SQRT over the Vector of variances; and the element-wise smaller of two Vectors is [ 1 5 3 ] [ 4 2 6 ] MIN. None of these needs MAP or a block — reach for those only when the operation itself is not a numeric Word. A lane outside SQRT's domain becomes NIL on its own, so [ 4 -1 ] SQRT is [ 2/1 NIL ] rather than a failure of the whole Vector. This lifting is not limited to numeric operations. A Word whose operand is read as a single value — a string, a Boolean — applies element-wise by the same rule when given a Vector or a Record there ([ 'ab' 'c' ] UPPER is [ 'AB' 'C' ]). A one-element Vector is always treated as a Vector, never as its element.

Comparison and Booleans

There are three comparison Words: EQ, LT and GT. Their result is a Boolean, a kind of value of its own, not a number. The remaining three relations are written with NOT: "less than or equal" is a b GT NOT, "greater than or equal" is a b LT NOT, and "not equal" is a b EQ NOT.

Comparison Words

Exact comparison

Comparison decides exactly across every value the Words can build, rationals and square roots included. So a comparison always returns TRUE or FALSE in finite time.

Logic

Ajisai has two logical Words, AND and NOT, which operate on the Booleans TRUE and FALSE. Like any other Word, each is written by its spelling. Logical OR is written by De Morgan's law as a NOT b NOT AND NOT.

NIL passes through

In a truth position, NIL reads as "unknown" and combines under strong Kleene logic. When the other operand alone decides the answer, that is the answer (an AND with a FALSE is FALSE); when it does not, NIL stays in the result with its reason intact.

Contracts: Logic

Contracts: Comparison

Contracts: Exact arithmetic

2.4.2.2 Vector operations (GET, LENGTH)

Vector indices start at 0. A negative index counts from the end. Reading Words such as GET and LENGTH consume the Vector they read, like every other Word. If you want to use the original Vector later, name it with BIND before reading it.

Reading with GET

The answer takes the shape of the index

Given a bare integer, GET returns the element itself; given a Vector of indices, it lifts element-wise and returns a Vector of the selections, in the order the index gives. So picking out several positions, reordering and reversing are each a single call, and an index that points at nothing leaves NIL in its position instead of ruining the rest.

The answer takes the shape of the index. A Vector of indices stays a Vector even with one element, so the answer is always a Vector too. Even when a computed selection happens to narrow down to one position — the left side of a split, a class with a single member — LENGTH or FOLD written for a Vector keeps working.

Other basic operations

More structural Words: TAKE DROP REVERSE COLLECT FILL PUT. INDEX-OF searches instead of indexing: [ 10 20 30 ] 20 INDEX-OF is 1/1, and a value that is not found is NIL, not an error. To ask only whether a value is present, use MEMBER? ([ 1 2 3 ] 2 MEMBER? is TRUE); for an ascending Vector use BSEARCH ([ 1 3 5 7 ] [ 5 ] BSEARCH is [ 2/1 ] — binary search: the iteration of halving an interval again and again is not something you can write yourself). BSEARCH raises an error when given a Vector that is not ascending.

Ordering, counting and shape

The operations that need to see a whole Vector at once are covered by seven Words. Each of them could be written out using only the rest of the vocabulary, but written out it costs asymptotically more. That alone is why they exist as Words.

A Vector's shape — the length of each axis, listed from the outside in — is the notion element-wise lifting uses to line operands up. The following four Words read and rewrite it from a program. FLATTEN and DEPTH cannot be written yourself: the nesting depth is not known in advance, and a language with neither recursion nor unbounded loops cannot walk a structure of unknown depth.

To apply a block to each value at a known depth, nest MAP that many times. At depth 2 that is [ [ 1 2 ] [ 3 4 ] ] [ [ 10 MUL ] MAP ] MAP, and the result is [ [ 10/1 20/1 ] [ 30/1 40/1 ] ].

The one to reach for first is ORDER. SORT returns what the sorted values are and throws away where they came from; ORDER keeps the positions. So anything that has to carry a payload alongside its key — k nearest neighbours, top-k scores, the position of the median, rankings — takes the form of ORDER followed by GET.

UNIQUE and TALLY work on any value, not only numbers. Labels are usually text, so this is a practical difference. ORDER and SORT, on the other hand, need a flat Vector of numbers, because that is where an exact ordering is defined. GROUP pairs values with keys by position, so its two operands must have the same length.

Contracts: Vectors

2.4.2.3 Keyed data (RECORD, GET)

Named data — a price list, a configuration, one row of a table — is held in Ajisai by the Record, the seventh value domain. A Record pairs a key column with a value column by position; the keys keep the order they were given in, and no key appears twice. Any value can be a key (usually a string). A Record is not a Vector, so Vector Words do not accept a Record and Record Words do not accept a Vector. There is no implicit conversion in either direction.

A Record is made with RECORD, which takes a key column and a value column and pairs them by position. A key with no value to pair is a length-mismatch error, and a key given twice is a duplicateKey error.

It is displayed in the form [ 'x' 'y' ] [ 1/1 2/1 ] RECORD: the very program that builds the Record, which gives the same value when written as it is. A Record inside a Vector is displayed as the elements gathered with COLLECT, as in [ 'a' ] [ 1/1 ] RECORD 1 COLLECT, because a name inside [ ] is a Symbol, so RECORD written there would not build a Record.

Record identity and order

A Record is told apart by its key column and value column alone (identity model). Records with the same keys in the same order and equal corresponding values are the same value, however they were built. Order is observable structure, so [ 'x' 'y' ] [ 1 2 ] RECORD and [ 'y' 'x' ] [ 2 1 ] RECORD are different values. EQ answers this identity, and UNIQUE and TALLY can count Records as elements.

Only arithmetic and comparison lift onto the values

The only existing Words that act on a Record are arithmetic and comparison. Combining a number or a Vector with a Record leaves the keys as they are and applies the operation to each value. Two Records combine value by value only when their key columns are equal; otherwise it is a shapeMismatch error. Every other Word — LENGTH, MAP, AND, CHARS and so on — raises its own operand error when given a Record. To treat a Record as a Vector, cross over explicitly with VALUES.

Missing keys

Reading a missing key with GET is a well-formed question with no answer. So it is not an error: it returns a NIL with reason notFound, and the recovery phrase works on it unchanged. To ask about presence itself, use HAS?. WITHOUT follows the same discipline and returns NIL when asked to remove a missing key. Just as GET, TAKE and PUT project an out-of-range position, a misspelled key never slips through silently.

TALLY and GROUP return Records: TALLY maps "element → count", and GROUP maps "key → the Vector of that key's values", both with keys in order of first appearance. Taking KEYS gives exactly UNIQUE's answer, and taking VALUES gives the Vector of counts or of groups, so no power is lost. Hold a table as a Record of "column name → column Vector", and 'price' GET takes out one column while arithmetic computes column by column.

Contracts: Records

2.4.2.4 String operations (CHARS, JOIN)

Crossing over to Vectors: CHARS and JOIN

A string is not a Vector, so the collection Words do not accept strings. LENGTH, GET, REVERSE and CONCAT all raise an error on a string. Cross over to the Vector domain with CHARS first: 'abc' CHARS LENGTH is 3. Concatenation is done by JOIN, the Word that turns a Vector of strings into one string: [ 'ab' 'cd' ] JOIN is 'abcd'. To concatenate computed values rather than written ones, collect them with COLLECT first, as in 'a' 'b' 2 COLLECT JOIN.

CHARS splits a string into its characters, and TOKENIZE splits it on a delimiter. Both produce a Vector of strings, and JOIN assembles one back into text: 'hello' CHARS REVERSE JOIN is 'olleh'.

Converting to and from numbers: STR and NUM

Upper and lower case: UPPER and LOWER

These convert a whole string to upper or lower case using Unicode's default case mappings. Locale-dependent rules (Turkish dotless i, Greek final sigma) are not applied, so the same text gives the same answer wherever it runs. The mapping table is Unicode's and cannot be written as your own definition with CHARS and JOIN, so it is held as Words. Mappings that change length, such as ß, are applied as they are.

Drawing with a chosen number of digits: FORMAT

Arithmetic never rounds anywhere, and STR declines a number that has no exact lexeme. Still, sometimes you want to see 1/3 to three decimal places. FORMAT is the one place for that. It takes a value and a digit count and returns decimal text rounded by the same rule as ROUND (an exact half goes away from 0) — the language has a single rounding rule. What comes out is text, not a number, so a rounded quantity never flows back into arithmetic. The rounding mode is fixed; making it selectable would only add Words. The digit count must be a non-negative integer (invalidInteger), and the value must be a scalar (nonNumeric). Even for an irrational, the field's order decides every digit through the last, so no digit is guessed.

Converting to and from JSON: JSON-DECODE and JSON-ENCODE

Structured data from the host arrives as JSON. JSON-DECODE turns JSON text into a value: an object becomes a Record keyed by its member names in order, an array a Vector, a string a string, a number the exact rational it spells (0.1 is exactly 1/10), true/false a Boolean, and null NIL. Text that is not a single JSON value (broken, empty, trailing garbage, a member name given twice) projects a NIL with invalidEncoding. The nesting depth is decided by the text alone, so this Word cannot be written as a user definition — the language's iteration runs only over a Vector that already exists.

JSON-ENCODE is the reverse. A Record keyed by strings becomes an object, a Vector an array, and NIL null. Only a number with a finite decimal expansion (a denominator made of 2s and 5s) is written as a JSON number; any other rational is written as its Ajisai lexeme inside a string, such as "1/3", because writing 1/3 as 0.333 would be a different number. A value with no image in JSON — a Symbol, an irrational, a Record with a non-string key — projects a NIL with domainMiss.

Contracts: Text

2.4.2.5 Choice and iteration (SELECT, MAP)

Conditional choice (SELECT)

SELECT takes three arguments: the value when true, the value when false, and the Boolean that decides which. Line them up as [ whenTrue ] [ whenFalse ] [ mask ] SELECT. The Boolean comes last because, as with other Words, the operand that decides what to do goes last.

SELECT evaluates nothing. The two candidates are values the program has already built. That is, each candidate has been computed once, in the order written, before it reaches SELECT. It is not that the side not chosen "does not run"; by the time the choice is made, both are already values. This is the fundamental difference from Words that take a block and run its contents (MAP, EXEC).

So an effect such as PRINT cannot go inside a candidate — if you put it there, both would print. Choose the answer first, then apply the effect once, placing it after SELECT, as in [ 'big' ] [ 'small' ] [ 5 ] [ 3 ] GT SELECT PRINT.

Choosing element by element

If the Boolean is a Vector, the choice happens element by element too. Comparison Words also lift element-wise, so [ 1 2 3 ] [ 2 ] GT answers the Vector of Booleans [ FALSE FALSE TRUE ]. Hand that straight to SELECT and a branch over a whole Vector is a single expression. A length-1 candidate is reused to match the other's length.

To combine several conditions, join the Vectors of Booleans with AND and NOT, which also lift element-wise: [ 3 6 9 ] [ 5 ] GT [ 3 6 9 ] [ 8 ] LT AND is [ FALSE TRUE FALSE ].

Splitting three or more ways

SELECT always chooses one of two. To split three or more ways, nest SELECT. There is no "try from the top and the first match wins" reading; which case takes precedence is visible directly as the shape of the nesting.

When neither is chosen

If an absence (NIL) arrives in the Boolean position, it is UNKNOWN (three-valued logic). UNKNOWN chooses neither candidate and answers the absence it read, reason and all. So you can ask afterwards, with NIL-REASON, "why could this not branch?".

There is no state of "no clause matched". There are always two candidates, and the Boolean is TRUE, FALSE or UNKNOWN, so SELECT always has an answer. This is why forgetting an else clause can never crash at run time.

A bare number cannot go in the Boolean position (nonTruthValue), because 1 and 0 are not Booleans (the domains are disjoint). To decide on a number, write a comparison, such as [ 1 ] [ 0 ] EQ NOT.

Iteration (MAP, FILTER, FOLD, SCAN)

A code block [ ] is a first-class value. Higher-order Words apply a block, or the quoted name of a defined Word, to each element of a Vector.

These four are all the iteration there is. There is no way to repeat by having a Word call itself, because DEF rejects cyclic definitions. So the number of iterations is always written as the length of a finite Vector at hand, visible before you read the block.

What the block leaves becomes the mapped element as it is. A one-element Vector is a one-element Vector, like any other value. So [ 1 2 ] [ 1 COLLECT ] MAP is [ [ 1/1 ] [ 2/1 ] ], and [ [ 1 ] [ 2 3 ] ] [ REVERSE ] MAP is [ [ 1/1 ] [ 3/1 2/1 ] ]. Nothing unwraps a result just because it happens to be short. A cluster with a single point, or a row with a single output, keeps its shape all the way through.

A fold that keeps its progress (SCAN)

SCAN walks the same way as FOLD and answers every accumulator along the way, not only the last one. What the block sees and leaves is identical to FOLD; only what is returned differs.

The answer has the same length as the input. The initial accumulator is a "seed", not a lane, so it is not part of the answer. Because the lengths match, you can ZIP it with the original Vector, or compare it to make a mask for SELECT.

This is the only way in this language to carry one result forward to the next. A Word cannot call itself and there are no loops, so the accumulator is the only means of carrying state along the way. FOLD shows that state once, at the end; SCAN shows it along the way too. Running maxima, balance histories, a state machine stepping along a sequence, recurrences — every computation that takes effect step by step has this form.

An empty Vector answers an empty Vector (zero lanes in, zero lanes out; the seed is not returned). A Vector that is absent (NIL) answers that absence, reason and all. Here it differs from FOLD, which answers the seed in both cases — with nothing to fold, the answer is the seed. These are two sides of the same rule: the shape of the answer follows the shape of the question.

EXEC runs a code block taken from the stack.

Writing a Word that takes two arguments

Several values travel inside a Vector, not on the stack. A Word that needs two arguments takes one two-element Vector. The caller writes it directly, as in [ 3 4 ], or builds it from computed values with COLLECT.

When you need one position rather than a fold, read it with GET: 0 GET is the first element and -1 GET the last. So [ SORT -1 GET ] 'PMAX' DEF answers the larger of two values. REVERSE exchanges the two elements of a pair, and TAKE combined with CONCAT rebuilds one Vector from parts of another.

The tool for duplication is BIND. Name a value and it is pushed every time the name is written, so a value of any kind can be used as many times as needed.

Contracts: Iteration

Contracts: Control

2.4.2.6 Handling absence (NIL?, ABSENT)

Inspecting NIL: NIL? and NIL-REASON

These two Words inspect NIL. NIL? asks whether the top of the stack is NIL; NIL-REASON reads the reason it carries. Like every other Word, both consume the value they inspect and push their answer in its place. If you still need the value afterwards, name it with BIND first.

Declaring an outcome yourself: ABSENT and FAIL

Absence and errors do not belong only to the built-in Words. A program can itself declare "there is no value here" or "this is misuse". ABSENT takes one string and pushes a NIL whose reason is that string. The reason identifier is userDeclared, but what NIL-REASON answers is the string you passed. The string is part of the value, so two ABSENTs made from different strings are different values.

FAIL also takes one string and raises an ERROR with that string as its message (classified declaredFailure). Being an ERROR, it stops evaluation there, and no Word can catch it. FAIL is not a "stronger ABSENT"; it is the Word for drawing the line between absence and misuse from the program's side. Use ABSENT when the caller should be able to recover, and FAIL when it should stop as the caller's mistake.

Supplying a fallback value: BIND, NIL?, SELECT

There is no special syntax for recovering from absence. Name the value being tested with BIND, then line up SELECT and NIL?.

Like every other Word, NIL? consumes the value it inspects and pushes a Boolean saying whether it was absent ([ x ] -> [ bool ]). So name the value once and read it twice. Writing value 'S' BIND fallback S S NIL? SELECT pushes things in exactly the order SELECT asks for (the candidate when true, the candidate when false, the Boolean), giving "the value if there is one, otherwise the fallback".

The fallback is an ordinary operand, so like any other operand it has been computed before SELECT runs. In other words the fallback is computed even when the value is present (see the SELECT section). Do not put a heavy computation or an effect such as PRINT in the fallback position.

NIL? asks about the whole value. Even if one lane of a Vector is NIL, the Vector itself is not absent, so the answer is FALSE. [ 1 NIL ] 'S' BIND [ 0 0 ] S S NIL? SELECT is [ 1/1 NIL ]: the lane's absence is not recovered. To recover a lane, recover inside the Vector rather than outside it.

Contracts: Absence (NIL)

2.4.2.7 Output (PRINT)

PRINT writes the top value of the stack to the output area. Like every other Word, it consumes its operand. To keep the value on the stack as well, name it with BIND and write the name twice. The Playground always shows the final stack, so PRINT is for the output channel, not for seeing results.

Quotes are a display convenience

To tell them apart from numeric Vectors, strings are shown on the stack in single quotes, as in 'TEST'. The quotes belong to the Stack display, not to the value. PRINT writes the raw text, so 'TEST' is output as TEST. Quote characters that are part of the text are kept, though, so a string whose content is T'ES'T is output as T'ES'T. Numbers and Booleans are output exactly as they appear on the stack.

Contracts: Output

Appendix A Common patterns

Ajisai's vocabulary is 78 Words, deliberately kept small. A Word that a user definition can express at the same cost does not belong in Core. So operations such as argmin — the position of the smallest value — or a relaxation loop are written as combinations of short phrases. The common ones are collected below. Each is verified, and if you use one more than once it makes a fine body for your own DEF.

Ordering by key, ties included

Sorting the values and then looking up their original positions is the obvious way to get an ordering, but it gives the wrong answer exactly when it matters. With two equal distances, SORT followed by INDEX-OF finds the same position twice, so "the three nearest" can return two neighbours, or four. ORDER answers the question SORT throws away — which position comes in which order — and answers it stably, so equal keys keep the order they were written in.

Appendix B The identity model

In Ajisai you write ordinary comparison Words such as EQ, LT and GT, but behind the scenes the language keeps several separate "is it the same?" questions.

The comparison Words work only at the top layer. They are exact and total across every Ajisai value, and they answer the mathematical question. The layers below take no part in the value model, so representation and display never affect a comparison's result.