Introduction

Welcome to Final!

Final is a new, modern, stack-based programming language designed by Brad Aisa in the tradition of Forth. “But this ain’t yer granddaddy’s Forth!” Final has all the features a modern programming language needs, such as:

• rich primitive types
• polymorphic operators
• Objects and Types
• Compound classes such as Lists, Maps, Sets, and Dynamic Objects
• Vectors, Matrices, and statistical and model-fitting/predicting operations
• Structured Exception Handling (SEH)
• Dynamically loadable modules (work in progress, local modules only this release)
• support for Http/Web, Json, Threading
• Blitting and Drawing onto a Pixmap for creating images such as PNG/JPEG/GIF
• a final-gui version with support for creating Graphical User Interfaces
• a Simulation/Game framework with animation support, and a Motion/Hit engine
• … and much more

Final was written primarily to be a language for the creation of AI Tools, but it is just as useful as a general purpose stack-based programming language. Final can be run in an interactive Terminal User Interface (TUI), a graphical interface (GUI), or can be embedded in a Request/Response mode in other Go programs.

Final runs on Windows, Mac, and Linux, for both AMD64 and ARM64 cpus.

A custom version of Final for Raspberry Pi 5 (64-bit Pi OS) also exists, with a library of low-level hardware words to access and control the Pi’s breakout pins and peripherals.

You’ll get the most out of this introductory tutorial and user guide by installing Final and following along. So let’s get started…

Installation

Final is available for Windows, Mac, and Linux. This version, v0.0.8 provides support for:

• macOS Apple Silicon (arm64)
• macOS Intel (amd64)
• Windows x64 (amd64), and
• Linux x64 (amd64).

Raspberry Pi and other CPU variants will be included in an upcoming release.

Final is easy to install, and easy to remove, should you wish to do so. It is provided as a simple .zip file, for each supported platform/cpu combination.

Install instructions

1. Go to the downloads page, and download the .zip for your platform/cpu.
2. Move the .zip to your home folder.
3. Double-click the .zip in your UI, or cd to your home folder and run the unzip program for your OS.
4. This should create a folder Final with the final and final-gui binaries (final.exe / final-gui.exe on Windows) in the root, and Final’s bootstrap files, and example programs.
5. Launch that file in your UI.
6. (optional) Select one of the examples in Final/examples and open it in your favorite editor; associate the .fnl extension with your editor.

Troubleshooting

Prefer launching from inside the unzipped Final/ folder. From a shell, cd into Final/ then run ./final or ./final-gui (final.exe or final-gui.exe on Windows).

Uninstall instructions

1. Delete the folder Final in your home folder. That’s it!

The Final TUI

When you launch final from the command line or your GUI you should see the following Terminal User Interface TUI (with empty text boxes.) You can resize your terminal, and the TUI will automatically resize. (Note: the TUI will also work, with some limitations, over ssh.)

Let’s take a quick look at the TUI, starting from the bottom:

Shortcut Bar This bar shows the shortcut key combinations for the most used commands. Mac users: note that Ctrl is used instead of the Cmd key.

Prompt Area This is where you enter Final commands, or code. Enter sends the current text in the area. You can use Ctrl-J to add new lines without sending. And if you Paste text from an editor, with newlines, it won’t send until you hit Enter or press Send.

History Area This shows a running list of the prompts you sent. You can copy code from this text area.

Response Area This shows the result of a Send. If the result contained no text, “(ok)” is printed, as confirmation. Just like History, you can copy text from this text area.

Menu Bar This contains 2 particularly useful commands:

File/Load – let’s you browse for a .fnl file, which is loaded (compiled); Help/Words – this will get you started with Final’s built-in help

Example conventions used in this guide

Code examples in this guide do not try to depict the TUI–this would be both wasteful of screen space, and impossible to copy from. Instead, we use a pseudo bare command line interface that looks like this:

> 1 2 + $

3

• the text after > and any non-empty lines below are the prompt
• a blank line
• the expected output of the prompt, which may be many lines; or (ok) if no output is expected

Working along with the examples, you can either type into the TUI Prompt area, or copy/paste.

On to some code!

The Final GUI version

When you launch final-gui from the command line or your GUI you should see the following Graphical User Interface TUI (with empty text boxes.) You can resize the Window. (Note: for ssh, use the final binary; it will work, with some limitations, over ssh.)

Let’s take a quick look at the GUI, starting from the bottom:

Prompt Area This is where you enter Final commands, or code. Enter sends the current text in the area. You can use Shift-Enter to add new lines without sending. And if you Paste text from an editor, with newlines, it won’t send until you hit Enter or press Send.

History Area This shows a running list of the prompts you sent. You can copy code from this text area.

Response Area This shows the result of a Send. If the result contained no text, “(ok)” is printed, as confirmation. Just like History, you can copy text from this text area.

Menu Bar This contains three particularly useful commands:

File/Load – let’s you browse for a .fnl file, which is loaded (compiled); View – Prompt/History (Response and History) or Stdout/Stderr (standing $ / $$); the current view’s menu item is disabled; Help/Words – this will get you started with Final’s built-in help.

Example conventions used in this guide

Code examples in this guide do not try to depict the GUI–this would be both wasteful of screen space, and impossible to copy from. Instead, we use a pseudo bare command line interface that looks like this:

> 1 2 + $

3

• the text after > and any non-empty lines below are the prompt
• a blank line
• the expected output of the prompt, which may be many lines; or (ok) if no output is expected

Working along with the examples, you can either type into the GUI Prompt area, or copy/paste.

On to some code!

Hello Final!

When you first launch final you are in an interactive interpreter. You can enter numbers and strings, operators, or words, and Final will execute it according to its interpretation rules (which are covered later in Interpreter ).

So one of the first things typically done when introducing a new language is the venerable “Hello World!” example. Let’s do it interactively first. Try the following:

> "Hello from Final!\n" $

Hello from Final!

Your string literal got pushed on DS (see below), then $ “print” printed it out. Easy, peasy!

Let’s try a simple arithmetic example. Enter the following, and observe the result:

> 1 2 + $

3

A central construct in Final is the Data Stack (DS). It has no counterpart in conventional languages. Conventional languages use named parameters in functions to pass parameters, and sometimes global variables.

Final uses the DS to hold intermediate operands, pass operands to Final’s counterpart of a function, called a Word, and return results. When you write a literal value in the interpreter, it gets pushed onto DS.

Some may notice the arithmetic rules in Final work the same as in HP calculators. It is called Reverse Polish Notation (RPN). A nice feature of RPN is that you do not need grouping operators like ( ) to group and order operations, any such expression can be expressed using the RPN/stack-based approach of Final.

This way of thinking does take a bit of getting used to, but it is the “secret sauce” that makes all Final-like languages so uniquely flexible and efficient, in terms of code factoring, and code reusability.

Try out a more complicated example. This requires parentheses in a conventional language, due to order of operations and operator binding. You do it in Final by working inside-out, then left to right at each grouping level: ((3 + 1) * (11 - 6)) / 4 . Tip: you enter operands for things like - and / in reading order, so: a - b is entered as “a b -”.

> 3  1 +  11 6 - * 8 / $

2

If you have a sharp eye, you will know that the result is actually 2.5, not 2. The cause is Final’s type coercion rules. If all the input operands to arithmetic operators are integers, the result will be an integer, due to integer truncation of rounding. To make it be a float, just change one of the operands to include a decimal point. This causes it to be interpreted as a float, and Final’s coercion rules always promote the result of mixed int/float operations to have a float result, so the “float virality” will propagate through. Try it!

> 3  1.0 +  11 6 - * 8 / $

2.5

Now let’s write our first word in Final. Words are stored in something called a Dictionary; there are at least 2 dictionaries when you start Final:

• the sealed core Dictionary that contains the words of the Final language
• a (mostly) empty local dictionary in your Session, into which you can add new definitions

Let’s write one now, enter this:

> : helloFromFinal "Hello from Final!\n" $ ;
helloFromFinal

Hello from Final!

You just created your first Final word called helloFromFinal, and then invoked it! Here is the anatomy of what is called a colon definition

1. opening : then a space; this puts Final into compiling mode
2. the name of the new word
3. the literals, operators, and words making up the definition
4. ; closes the definition and adds it to your local dictionary

The helloFromFinal following the definition then invokes it, causing the word to print the text.

Creating new words is as simple as that. When you create new words, you can include words you have previously defined along with core words.

Simple Input

Final doesn’t provide a way to directly prompt for input from the Prompt area, but it has a simple API for raising a modal dialog to either ask for a confirmation, or request a few fields of information. We provide a quick example of the latter here, and cover the topic in more detail in the Input/UI Dialogs topic.

No introduction would be complete with some Monty Python. The following example is in examples/dialog/ask-demo.fnl.

: ask-demo
  ( "What is your name?" "What is your quest?" )
  Dialog.ask^ if
    "Nice to meet you, %s. Off you go — \"%s\" is a fine quest.\n" fmt $
  else
    "Then we shan't proceed. Nobody expects the Spanish Inquisition.\n" $
  then
;

The code provides the requested field labels using the convenient Paren operators for building a List. It then asks Dialog to post the dialog via the ask method, which returns one of two types of result shape:

• true then a List of the replies, in order of request
• false and no List

You test for the response type using an if statement, and if true can then pass the List directly to a fmt statement and print it out. If false, you can print a default reply, as above.

Dialog is covered in more detail in Input/UI Dialogs, Paren operators in Compound Builders and fmt in Output Formatting.

Let’s now move on, and dig a little deeper into Final…

Basic Types

Final has a set of basic, primitive types, and a rich set of collection and other compound object types. We’ll cover the basic types here.

Basic types are immutable, meaning that once created, their value does not change. In operations using the value and returning a value, a new value is created; you cannot alter or change an instance of a basic type.

Null

The Null type has only one value: null. It exists primarily to support Json. It’s use otherwise is discouraged. Final has a pattern it widely uses for indicating there is “no value” returned from an operation, so Null is not used by Final, except when generating or parsing Json, or initializing strongly typed fields with no value yet.

Bool

The Bool type has the values true and false. It is not a numeric type. However, Final has the concept of “Truthiness”, which enables some of the other types to be used as if they were Bool.

Numeric types

Final has two integral types, and one real type.

• Int - a 64 bit signed integral value;
• Uint - a 64 bit unsigned integral value;
• Float - a 64 bit IEEE-754 floating point value;
• Rune - a synonym for Int, representing a 32 bit unicode character.

Int is the type you should use for most integral operations and representations, even in contexts such as an ordinal index, in which negatives do not occur. Almost all of Final’s apis that use or return an integral value use Int.

Uint is provided primarily for contexts which require integral values larger than 2^63-1, or for flags or bitfields that use bit 63, in which you don’t want the natural printing to default to displaying a negative, 2’s complement interpretation. Note that Int and Uint do not interoperate in dyadic operations; type coercion is covered in the next topic. You create a Uint literal by appending an integral value with the u suffix.

Rune is a synonym for Int, and is used in contexts involving Unicode code points, called runes. A Unicode rune is a 32 bit integer value.

String

A Final String is an immutable sequence of Unicode characters using Utf-8 encoding. All mutating operations on strings accept immutable string inputs, and return a new immutable string value. (Final provides mutable StringBuilder to successively build a String from parts.) Strings are not 0-terminated. Strings are copied by reference throughout the runtime, so there is only one underlying value, regardless how many times it is moved or copied.

Utf-8 encoding provides an excellent compromise between byte size, efficiency, and interoperability with the Web and Json, as well as other benefits. ASCII-7, i.e. 7-bit ASCII is a proper subset of Utf-8, so an ASCII string in bytes is identical in Utf-8. Unicode runes beyond ASCII are encoded in either 2, 3, or 4 byte sequences, with the majority of Western/Latin characters only needing 2 or 3 bytes. It is thus more storage efficient than Utf-32, which uses a fixed 4 bytes per character.

One caution: the concept of “length” in Unicode in general, and especially Utf-8 requires decoding the entire string, so Final does not provide a true string length. The String.len property is the length in bytes of the encoding. If the string is known to contain only ASCII-7, then that is also the length. Final provides an efficient mechanism to iterate the Runes of a String, which is explained in the String topic.

Any

Any is a type that can hold any other Final type, basic or compound/object. The DS is composed of a growable stack of Any values. So when a concrete type goes on DS, it will always be wrapped in an Any.

“Truthiness”

For convenience, you can use a value of the following types in most operations expecting a Bool, such as boolean logic operators, and if and case control structures.

• Numeric types: exact 0 is false, non-0 is true
• String: empty “” is false, anything else is true

No other types are accepted, and will raise a runtime error if used.

DateTime and Interval

These are also basic types, but discussion is deferred to DateTime and Interval.

Let’s move on to a discussion and demonstrations of the Final Interpreter, which includes details on expressing literal values of the basic types in the interpreter and compiled words.

Interpreter

When you first start the Final TUI, Final is in intepreter mode. This is an interactive request/response type of interface. When you start a colon definition with : Final goes into compiling mode. We will discuss the basic lexical rules of Final text, which applies both to the iterpreter and compiler, then cover the interpreter itself.

Final Lexical Rules

Final source is Utf-8, of which regular ASCII-7 is a proper subset. Note that Final does not accept “Code Pages”, which are the early DOS and Windows era “hack” for creating overlays in the top 128 bits of ASCII. Such sources will be mis-interpeted by Final.

Final text is parsed as tokens, which are whitespace separated values as defined by the parsing rules. Individual Final operators and words must be separated by whitespace, unlike languages which permit whitespace eliding in many contexts. (The one exception to this is Final’s compound object path syntax, covered later.)

Valid whitespace is: space, tab (“\t”), newline (“\n” aka linefeed), or carriage return (“\r” aka return.) In an operation counting or splitting lines, Final accepts “\r\n” Windows-style newlines to be a single end-of-line marker. It is suggested that you uniformly use the single “\n” form for both Final source files, and textual data files. No other whitespace, including Unicode whitespace characters, are accepted.

These are the types of tokens in Final

• Null literal: null;
• Bool literal: true or false in lowercase;
• Int literal: any valid decimal, octal, hex, or binary number, without a . decimal
  eg, “10” “0x7F” “0b101010” “-49”
  note: numbers may not be preceded with +, only -;
• Uint literal: a valid positive integer, with “u” affix, eg. 25u;
• Float literal: a valid number, that contains a decimal point; exponential notation is allowed;
• Quoted String: a textual value enclosed in quotes; Go-style escapes \n \t \xHH \uHHHH \UHHHHHHHH; literal Unicode (emoji, non-English) is accepted in the source unless it is a dangerous character (see below). Dangerous characters may appear in the string value only via \x / \u / \U;
• Raw String: a textual value enclosed in back ticks: the rain in spain; the entire text is interpreted literally, including line breaks; no escapes. Dangerous Unicode in a raw string is a parse error;
• Unicode Rune: a single rune in single quotes; printable characters, C-style escapes, \xHH, \uHHHH, \UHHHHHHHH;
• // Comment: the // characters signify a comment, to the end of the line;
• /* */ Comment: a comment that can span multiple lines; it can include embedded // comments (which are just considered part of the whole comment text) but cannot include nested slash-star comments;
• Compound Path accessor: a valid compound path accessor (covered later);
• an identifier, which is either the name of an existing word, or based on the previous operator such as var: will become a new word; identifiers may not start with a number, and must be printable Unicode characters.

Identifiers

Identifiers in Final are far more permissive than in most other languages–they can contain combinations of letters, numbers, and most special characters.

Most of the special characters are used by Final to convey a family of related operations, so before going wild and using them in your identifiers, take the time to learn the lexicon, and ask if your new word belongs in that group.

Some characters and patterns are reserved by Final, and may not be used in identiers. Here is a summary of the rules, or disallowed characters:

• an identifier cannot begin with a number
• the characters must be Printable/non-whitespace Unicode characters
• the following characters cannot be used: . @ ! \ ^ ~ " ` '
• Source text may not contain “Dangerous” characters: Trojan-Source / invisible Unicode (Bidi marks, zero-width characters, variation selectors, and similar). The parser stops at that code prints out the value in hex. If you absolutely must use those characters, put them in a quoted string or rune using \x, \u, or \U.

Naming Guidelines

Final follows a standard of using camelCase for most identifiers. Exceptions are Types and constants, which are in PascalCase. You may also choose to use hyphen-naming instead of camelCase if you wish.

Final encourages the use of code factoring to keep individual words small, and to convey the purpose of a piece of code by way of its name, as opposed to relying on comments. To avoid name collisions in your User dictionary, it is suggested to factor by keeping the main word name, then an underscore, followed by the factored name. Subwords within a word, are also supported, and often more convenient.

The Final Interpreter

Final’s interpreter uses simple rules. It skips whitespace, then reads a token. Based on the type of the token, it does the following:

1. Comment: discard it
2. Literal: push it on DS
3. Identifier: look that up in the current Dictionary search path if it is found, then the word is executed
4. else signal an error

If the word is : then Final is put into Compiling state. It leaves compiling state and re-enters interpreting state after the ;.

So for you, the user, this is very convenient, because you can use the interpreter for interactive purposes, including compiling and testing new words. Likewise, a Final source file can intermix immediate, interpretive behavior with compilation of new words. This has a number of useful use-cases, which we will mention as we get to the features involved.

Let’s take a quick look at compiling state, and how Final compiles new words. Then we’ll move on to a quick intro to Final’s control flow blocks, and its collection types.

Compiler

The Final compiler creates new compiled words from existing words. Final code gets compiled into a Code Block (CT) table that contains the OpCodes of Final axioms, as well as some prefix modifiers, and immediate values to an OpCode, branches, and so on. The code is then exececuted in a tight run loop with an IP pointing the current instruction. OpCodes get dispatched via an efficient Go-compiled jump table. The resulting execution is highly efficient and fast, and for some operations can rival the performance of natively compiled machine code, due to CPU code and data caching. For details on how Final works, see How Final Works.

Final Compiler

The Final Compiler is used to compile a new colon word. It follows rules somewhat parallel to that of the Interpreter. Here is how it handles tokens;

• Comments are dropped and ignored.
• A literal value is compiled into the code as a literal; at runtime, the value gets pushed on the DS
• a compound path accessor is broken into its parts, and compiled into the CT
• an identifier is looked up as a word
  if found, it is compiled into the word as a Nest call to that word’s DC/CT index
  if not found, an error is raised, and compilation stops

Some words, such as control flow words, have a more complex compile-time behavior; these words combine immediate interpretive behavior, along with emission of compiled code. For example, control flow constructs need to keep track of the IP address during compilation, place dummy values into the CT that will hold branch addresses, then resolve those branches when closing words are reached. But the outcome is the same: directly executed compiled code is what executes at runtime.

Speaking of control flow words.. enough theory! Let’s move on to a quick overview of Basic Operators, then from there to control flow words, along with examples.

Basic Operators

Final has the basic set of operators that most languages provide, for things like arithmetic, boolean logic, bitwise operations, compares, and so on. Each family is briefly described below, with the operators. Type help <op> in the prompt to see a description of the operator, and its stack effects.

The type coercion/promotion rules are also listed for each family. A decision has been made in Final to not try to coerce/promote arithmetic operations mixing Int and Uint. The reason is that there are many cases where coercion cannot be inferred. The user must decide how the two values are to be interpreted, and apply the >Int or >Uint bitwise coercion operator that makes sense in the context. Mixing the two types in many operators causes a runtime error. If you are unsure, try mixed values first in the interpreter, before including it in your code.

Try out some of the operators in each category in the UI!

Arithmetic

Dyadic

+ - * / % modrem

Monadic

abs

Promotion / coercion

• Same type → result is that type (Int/Int, Uint/Uint, Float/Float).
• Any operand is Float → the other is converted to Float; result is Float.
• Mixed Int and Uint → runtime error. Cast one side with >Int or >Uint first.
• % and modrem require matching integral types (Int/Int or Uint/Uint); mixed Int/Uint → runtime error.

Boolean

Dyadic

&& ||

Monadic

not

Promotion / coercion

• Operands must be Truthy: Bool, Int, Uint, Float, or String.
• Numeric zero and empty String are false; anything else in that set is true; Bool is itself.
• Other types (lists, maps, objects, …) → runtime error.

Bitwise

Dyadic

& | xor bitset bitclear bittoggle
<< – logical shift left
>> – arithmetic shift right
rotl rotr – rotate left/right

Monadic

bitnot

Promotion / coercion

• Operands must be integral (Int or Uint); non-integral → runtime error.
• Dyadic & | xor: both the same type → that type; otherwise result is Int (any Uint is reinterpreted as Int). Never auto-promotes Int → Uint.
• bitnot: result matches the operand’s type.
• Flag mutators (bitset bitclear bittoggle): result matches the flags value being updated.
• Shifts and rotates: result matches the value being shifted; the count may be Int or Uint (non-negative). Counts are automatically capped by the runtime to 64 bits.

Equality and Comparison

Dyadic

== <> < <= > >=

Monadic

==0 <>0 <0 <=0 >0 >=0

Promotion / coercion

• Result is always Bool.
• Both operands must be in the same family, or → runtime error:
  • String — both String (ordering is Unicode byte ordering, see: Strings.
  • Numeric — both numeric (Int / Uint / Float), with the same promotion rules as arithmetic (including: mixed Int/Uint → runtime error).
  • Truthy — both Truthy, but not both Numeric and not both String (each coerced to Bool, then compared).
• Examples: 1 true == is fine (Truthy); 1.0 1u == is Numeric; "a" 1 == → runtime error.
• Zero-compare forms push a typed 0 matching the value (Int/Uint/Float), then compare — so Uint stays unsigned.

Casts

Use these when you need an explicit type change or a membership test. The ? forms leave a success flag instead of raising an error; the forms without ? raise an error on failure. Details: help on each word.

Type probes

Null? Bool? Int? Uint? Float? String?

Exact runtime type only — no conversion. Leave a Bool. ( value – is:b )

Representation casts

>Bool >Int >Uint >Float
>Bool? >Int? >Uint? >Float?

Compatible primitives only — no string parsing.

Semantic casts

>>Null >>Bool >>Int >>Uint >>Float >>String
>>Null? >>Bool? >>Int? >>Uint? >>Float? >>String?

Like representation casts, plus string parsing where it applies (e.g. "42" >>Int).

Trancendentals and Related

Final provides a set of trancendental operators and constants, such as sin, cos, Math.pi etc. The operators take any type of numeric value, and typically return a Float. Enter list-math for the list, then help on each operator for its description and stack effects.

Float provides some useful constants like Float.NaN and tests like Float.isNaN^ and Float.isInf^ to help deal with the thorny corner cases of IEEE-754 NaNs and Infs. use help Float to list them.

Monadic

Dyadic

Contants and Helpers on Float

Notes:

1. Can be compared to valid Float values; use .isInf to test for +-Inf;
2. .NaN is only for producing the NaN sentinel, if needed; use .isNaN to test for NaN; all float operations using NaN as an input return NaN; NaN <> NaN in comparisons

Contants on Math

Control Flow

A set of Control Flow words are used to create control flow blocks. Final has a rich set of control flow blocks. All Final Control Flow blocks must be used in a colon definition; you will get an error if you try to use any of these in the interpreter.

Before diving in to the blocks, this is a good time to introduce Final’s convention for describing the stack effects of a word, called its “context effects”. The convention follows simple rules for writing a comment that describe the state of the stack on input, and its shape on output. When placing a comment before a word, it is a good idea to use the /* */ form, and place the context effect line last. The compiler picks up a last comment before a word, and stores it in the .doc field of the Word. This lets you print it by going help wordname. This is the comment for +

/*
Add two numbers, and return the sum.
( a:n b:n -- c:n )
*/
: + ... etc.

The ( ) indicate a stack effect. The left hand side lists the expected input values, if any. you can optionally give them a mnemonic name, eg a and b here, a colon, and the type of the value. There are codes for common values:

• b or t Bool or Truthy, most Bool contexts take Truthy (note: Json requires Bool only)
• i Int
• u Uint
• iu integral, Int or Uint
• f Float
• n numeric, any of Int Uint Float
• s String
• a Any

For other types, such as objects, collections, etc. the convention is to write out the entire typename. There are a few shortcuts for common types, such as DO for DynamicObject. This is covered in more detail in Word Doc Guidelines

Let’s dive in to the blocks. We introduce each with an example that you can enter and try.

• Definite:
  • if else then
  • switch … /switch
• Loops:
  • infinite: forever … /forever
  • iterated: foreach … /foreach
  • pretest: begin … while … repeat
  • post-test: begin … until (also: begin … again for a legacy infinite loop)
• Break and Continue
  • break: break
  • continue: continue

Definite Blocks

if / else / then

Takes a Truthy value. The else arm is optional — skip it when you only care about the true path.

> // ( yes:b -- )
: announce
  if "yes!\n" $ else "nope.\n" $ then
;
true announce

yes!
> false announce

nope.

switch

The switch statement is Final’s pattern matching statement. It takes a value, called the target, and any number of case clauses that expect a truthy value. You may use any kind of comparison or matching operation for each case. The target value provided at the start is available anywhere within the switch using the keyword a. If you nest switches, you can access the target value of up to two outer containing switches with b and c.

Typically, each case expression will start with a followed by an equality or similar matching statement. However you are not required to use the target in any arm, enabling you to mix pattern matching with other logic. For strings, in addition to simple == statements, you could also use Regex, or any of the str:: expressions, such as str::indexOf.

The case clauses are executed in lexical order, until a case matches; when that case clause reaches /case the switch ends, and control is passed to the next statement after /switch. An optional default clause will execute if no case matches.

> // ( choice:i -- )
: pick
  switch
    a 1 == case "got 1\n" $ /case
    a 2 == case "got 2\n" $ /case
    default
      "got something else\n" $
    /default
  /switch
;
1 pick

got 1
> 99 pick

got something else

Tip: if arms don’t need a target value, push a dummy (null, false, …) before switch; your case expressions can be any legal truthy expression.

Loops

Infinite: forever

An empty forever loop just spins. Press Ctrl-B (Break) in final or Run/Break in final-gui to stop it.

> // ( -- )
: hang
  "This loop runs forever! Press Ctrl-B to Break!\n" $ 
  forever
  /forever
;
hang

Iterated: foreach

The foreach block is Final’s workhorse iterated loop. It can be driven from a variety of compound data structures, such as Lists, Maps, and Objects. You can also use it to easily iterate counted ranges. In all cases, the keyword i in the loop refers to the current value of the type being iterated. You can even iterate the Unicode runes in a String this way!

range builds an inclusive numeric range. Try a number from 1 to 10 — here 5 prints 1 through 5, each followed by a space, then a newline after the loop.

> // ( end:i -- )
: countTo
  1 swap range
  foreach
    i $ sp
  /foreach
  nl
;
5 countTo

1 2 3 4 5

Pretest: begin … while … repeat

Condition is tested at the top of every iteration. Zero or more times.

> // ( n:i -- )
: drain
  begin
    dup while
      dup $ sp
      1 -
  repeat
  drop nl
;
3 drain

3 2 1

Post-test: begin … until

Body runs at least once; the test comes after. Loop continues while the condition is falsy, and exits when it becomes truthy.

> // ( n:i -- )
: blastoff
  begin
    dup $ sp
    1 -
    dup 0 == until
  drop nl
;
3 blastoff

3 2 1

break and continue

break can be used to exit completely from the innermost enclosing loop among:

• foreach … /foreach
• forever … /forever
• begin … until
• begin … while … repeat
• also legacy begin … again

continue — only in:

• foreach … /foreach
• forever … /forever
• (Not on until or while … repeat.)

Both words can be used in a conditional if block–the break or continue applies to the containing loop.

To percolate either in an outer loop, pass a flag or sentinel from the inner loop, checked by the outer.

Objects and Types

Final provides first-class support for objects, including a concise, expressive syntax and operator set for accessing the members of an object.

All objects in Final are instances of a Type, which is Final’s object that holds the definition of an object’s members.

An object may have any of the following:

• instance properties, which can be read only
• instance methods, which perform an operation
• class properties, often used for constants
• class methods, often used for instance factories
• ordinal accessors, such as for lists: @() and !()
• name accessors, such as for Maps: @{} !{} and ?{}
• vec and matrix accessors: @[] and ![]

You can get detail on all the properties and accessors provided by a type, by entering help <typename> in the UI.

Final’s type system is hierarchical, and supports a form of inheritance called prototype inheritance. This is primarily a conceptual concept, that groups members common to a family of concrete instance types. Such types have names like ProtoList and ProtoMap. It is also used by a number of Final capabilities, such as Json rendering, to provide Final methods that will apply to all the child types. Json uses this to generate Json arrays for all List types, and Json objects for all Map types, even those that have no implementation relation, such as Map and DynamicObject.

Many of the Types that Final uses and exposes for your use are written in Go, Final’s implementation language. But all Objects and Types, whether they are go-native or instances of your defined objects, such as Dynamic and Typed Objects, share the same means of access and operation, introduced next.

Compound Path Operations

Legacy Forth had a basic policy that all operations be expressed by single, whitespace-separated tokens. During development of Final’s Type and Object system, this approach to object operations was found to be lacking in terms of user understanding, and convenience. So a special sub-language of composable object operations was created. These “Compound Path Operations” are a core part of Final, and used extensively. We cover the basics here, but invite you to dive deeper in the Objects deep-dive.

The simplest example of an object operation is accessing a readonly constant value of a Type. This convention is used to provide enum values, Type-related values, and math constants. To do this, you simply go TypeName.property. Here are common examples:

Math.pi // pushes 3.14 etc on DS
Int.maxInt
Float.NaN / pushes the IEEE-754 NaN value

Many types provide factory methods for creating a new instance of the type. Here is an example of creating a DynamicObject, and then moving it to the Temp Stack for further operations. (Final’s extended set of auxilliary stack are covered in-depth in the topic Stacks). The following sequence shows the steps in creating an instance of a DynamicObject, setting some field values, then reading them.

DynamicObject.new^ // ( -- do:DynamicObject )
>ts // ( do:DO -- ) t( -- do:DO ) move it to Temp Stack
1 t:.one! // ( 1 -- ) t( do:DO ) creates/sets .one property to 1
t:.one@ // ( -- 1 ) t( do:DO ) fetches the value of .one property
".one is: " $ $ nl // nl prints a newline

.one is: 1

Common Path operations:

• moving values to/from auxilliary stacks use eg for Temp Stack, >ts ts>
• the “Context Selector”, which specifies on which stack the object resides, uses the cs: prefix, where cs can be: t x y z o If you see cs: that means that “cs” will have one of those actual values
• Methods are invoked with .name then using the ^ affix operator.
• Property values are referenced with .name
  • to store a value, the value should be on DS, then use the ! “store” affix
  • to retrieve a value, which goes to DS, use the @ (“fetch”) affix
  • readonly/const properties can omit the @ affix

Due to the logic of how stack-based languages use the Data Stack for the results of operations, it was decided in Final that most compound path operations must start with the object, called the “receiver” (i.e. receives the access commands), on an auxilliary stack. So a common sequence in Final is creating a new object instance using a factory method, which results in the object on DS, then moving it to an auxilliary stack for all further operations.

Final provides convenience operators for the most common ordinal and by-name operations on objects that support those operations, like lists and maps. Here is a quick summary:

• cs:@() // ( index:i – value ) cs( obj )
• cs:!() // ( value index:i – ) cs( obj )
• cs:@{} // ( name:s – value ) cs( obj )
• cs:!{} // ( value name:s – ) cs( obj )
• cs:?{} // ( name:s – exists:b ) cs( obj ) Matrix operators, examples for 2d mats
• cs@[] // ( row:i col:i – value )
• cs![] // ( value row:i col:i – )

The help for every Type lists the accessors that are supported by instances of that type. Usually an object only supports the () set or {} set, but some, like DynamicObject, support both. Mats support the () accessors for flat indexed access of the values, and the [] accessors for eg row/col in 2d Mats.

Paths can be used to walk object hierachies, that include nested instances of other objects. You just use .propertyname for the contained instances. The intermediate objects fetched during such a “path walk” are automatically instantiated and elided by the path walker, so never appear on any stack. For example, to find the length of your current dictionary, you walk a path starting with the DictionaryContext DC value:

dc.dict.len $

24

Indicating you have defined 24 words in your local dictionary so far.

Compound Types

Final provides a useful set of compound objects. These are described briefly below, and covered in detail in the section Compound Types.

Lists

List is Final’s dyanamically sizable array type. A List starts out empty, after which items can be added, inserted, or deleted. A List can grow to any size.

Lists provide the @() and !() ordinal accessors for convenient reading/writing of existing elements. The List Type object provides the remaining API for adding, inserting, and deleting.

Lists can be iterated in a foreach loop. Just put the List on DS prior to your foreach statement, and the iterator is then automatically provided. The i value is the current item in the iteration. Iteration is deteriministic over the range 0..Len-1.

List

The type called List is Final’s general purpose list. Its items are of type Any, so it can hold any Final basic or object type. Items do not have to be the same type.

StringList

StringList is optimized for the common case of a List of String values. It may only hold values of type String.

Numeric Lists

Final provides a strongly typed, memory-efficient list for all the following numeric types: int8, int16, int32, int64 (aka Int), unsigned 8-bit (ByteList), uint16, uint32, uint64 (aka Uint), float32, float64 (aka Float). Values are automatically boxed/unboxed to Any on read/write.

As an example, a ByteList (unsigned 8-bit bytes, 0…255) provides a 16x reduction in memory required to store byte-sized values, compared to List. ByteList also finds use in the Final runtime for interoperation with String, whose values are stored in an underlying array of bytes; ByteStreams, that are used for byte read/write of files; and in some Http scenarios.

StringKeyValueList

This specialized list is used in Http classes for defining query parameters, and to hold Http headers, all of which are allowed to have multiple instances of the same key, therefore, Map-like objects cannot be used for these cases. The List stores values of type StringKeyValue in which .Key and .Value are both of type String. The list preserves the ordinal order of the source, such as in HttpRes headers.

The i for foreach iteration is a StringKeyValue object.

Maps

A map is a collection of key:value pairs. Access is by key. The first write of a key value creates the entry. Subsequent writes to that key, overwrite the previous value.

Maps provide the @{} and !{} accessors for reading/writing a value by its key. For reads, the key must exist, otherwise an error occurs. The ?{} accessor can be used to determine if the key exists.

Maps can be iterated. Place the Map object on DS prior to a foreach. The order of iteration is indeterminate. i is an object of type KeyValue, providing the key and the value of the entry.

Final provides 2 Map variants.

Map

Map holds keys and values of type Any. The values can be of any type, but the key must be a type that can be compared, such as String or Numbers. If you try to use an object as a key, an error will occur. Map is provided primarily to support the scenario of using numeric keys.

StringMap

StringMap is specialized for the common case of a map whose keys are Strings. Only a String is accepted as a key. Like Map, values can be of any type.

Set

Set holds values of any comparable type. It only contains one instance of any value added.

Sets have operations for producing a new Set from 2 input Sets: union, intersection, difference, and symmetric difference. Sets can be iterated

StringSet

StringSet is specialized for the common case of a set whose values are Strings. .

Vecs and Mats (Vectors and Matrices)

A Vec is a one dimensional ordinal collection of values with a fixed length set at construction time. Final provides VecNf which holds Float values, and can be created with any length. Vec use and its operators are covered in the Linear Algebra section.

A Mat is a multi-dimensional ordinal collection of values, with fixed dimension sizes set at construction time. Final currently provides a variety of 2-dimensional Mats, addressed using the row/column convention. They are stored in row-major order into an underlying flat array of values. The Mat2f Mat type, in addition to being useful generally, also has special operators and roles in the Linear Algebra/Ordinary Least Squares regression system.

Mats and Vecs both use the @[] and ![] accessors to read and write values. No additional method-based API is provided. For Vecs, you provide one index, For Mats you provide the indexes in order of outer-level to inner-level; for 2-d mats, your provide ( row:i col:i – value ) for @[] and ( value row:i col:i – ) for ![].

Mat2TN

Where T is type, N is bits. A family of numeric Mats that hold signed/unsigned integral or float values, of different sizes. Some, in addition to being useful generally, also have special use in the Drawing/Blitting framework.

Mat2c

A Mat that stores Color values; also used in Blitting.

Mat

A mat, comparable to List, that can store any Final basic, compound type, or object instance.

DynamicObject

DynamicObject (DO) is a little dynamo of a type, and is used often by the Final runtime, and in Final code. A DO is similar to a Map, but has less overhead, and is faster to read and write than a Map for a number of entries in the range of less than ~64 (however it does not have a size restriction, and automatically optimizes access for field counts greater than 64.). You can also access the fields by name using the dotted .fieldName accessor.

You can use it like an object, creating fields dynamically using the .fieldName! notation, or like a map, using the !{} accessor. A field must be created before it may be read; if a read is attempted on a field that does not exist, a runtime error occurs. Like Map, DO provides the ?{} accessor.

Unlike Map, DO preserves the order of field entry. When you iterate a DO, it iterates in order of field creation. DO also provides a highly optimized set of ordinal accessors @() and !() which read and write a value by its ordinal order of creation. This form of access avoids the more expensive field name lookup, when you are certain of the order. Dyanamic vectors such as .x .y .z for example, can be accessed like an array[2] type of object.

DynamicObject instances are one-offs, but they can be (shallow) cloned, or used as a prototype to create instances of StaticObject.

StaticObject

A StaticObject is used much like a DynamicObject. The major difference is that a StaticObject is created from a DynamicObject that serves as its prototype. Once created, a StaticObject has only the fields of the DynamicObject at the time of its creation. You cannot add new fields to a StaticObject.

StaticObject instances use much less memory than a DynamicObject, and are used for things like Database query result sets, and Table rows.

TypedObject

TypedObject is similar to DynamicObject, but its fields are more formally defined, with a schema of fieldname:Type pairs. Once defined, a TypedObject becomes its own Type in the Final Type registry, and can be used to create new instances.

A TypedObject may also have methods, written in Final.

Runtime behavior of a TO instance is similar to a DO, including definite iteration in order of field definition and ordinal accessors for faster access.

When you use the .methodName^ syntax to invoke a Final method on a TO instance, the instance exists on the OS for the duration of the method, providing convenient access to its members via the o: prefix accessor. The instance remains on OS for the lifetime of the method, and is removed automatically by the runtime when the method returns.

Table

A Table is a set of rows with a header, similar to a spreadsheet. It supports sorting of the rows by any column using progressive stable sorting, which preserves the order of the previous sort-step for ties.

A Table can be made from a DynamicObject, which then becomes a prototype for StaticObject rows. It can be created from a TypedObject, for instances of that type. It can be created from a Type that has fields, in which case, the fields become the column names. It can also be used manually by supplying a list of column names, and then adding any compatible objects as rows. A “compatible object” is any object that provides named or ordinal field access.

The dbIter>table word efficiently creates a table from the result set of a Database query.

Features

This entry contains a whirlwind list of Final’s other features. Each it explained in detail in its own entry. Now that you’ve had a basic introduction to Final, you are free to browse around. However it is recommended to first read the topics in the Foundations section, to get a good grounding of Final’s core constructs and operations.

• efficient OpCode-based VM with fast jump-table dispatch
• full support for Types and Objects
• concise, expressive “compound path” syntax for object operations
• auxilliary stacks, for convenient object parking and access
• support for Interators, and convenient foreach iterated loop
• excellent assortment of often-used collection types
• { … } and sm} builders for DynamicObject and StringMap; DynamicObject .clone^ for prototype-style copies; StaticObject via do.newStatic^ for fixed-schema rows
• TypedObject class constants plus Final methods via : Type#method … ; (instance) and : Type##method … ; (class)
• Table — columnar collection with schema from DynamicObject / TypedObject / Types; StaticObject rows; stable sortByOrd / sortByName
• full support for Unicode strings as Utf-8, including efficient Rune iteration; wide variety of str:: operations
• DateTime and Interval support, with formatting via dt::fmt (plus constants such as DateTime.iso, Interval.clock)
• expressive and convenient ( ) operators for creating value list to fmt operator
• support for a variety of variants of TextStream and ByteStream interfaces:
  • files
  • strings (reading) StringBuilder (writing)
  • stdio
• File system — File, FileInfo, Dir, Path; metadata, copy/move/delete, directory iteration
• Regex, including compiled regex, matches, selectors
• full Json rendering and parsing
• Threading, Pipes, and Atomic threadsafe objects
• Web Dial (Http GET/POST) and Web Listen (HttpListener — ServeMux routes, path params, REST methods, Pip-per-route handlers)
• SQL databases via DbProvider (Postgres, MySQL, SQLite); iterable result rows as DynamicObjects; iter>list
• Env and Moniker — cwd .env + process environment; opaque DSN / secret handles with $KEYNAME substitution
• Cryptography — Hash (MD5 checksum, SHA-256), Hex/Base64, SecureRandom, Key, Cipher (AES-256-GCM / ChaCha20-Poly1305), Ed25519 / X25519, Mac (HMAC-SHA-256), Kdf (HKDF-SHA-256, Argon2id)
• Linear Algebra: VecNf / Mat2f, vec:: / mat::, OLS fit / compare / predict
• try / catch / finally / throw — recoverable exceptions (invalid JSON throws rather than panicking)
• Modules (local install / import) and .fnlp projects (loadProject)
• Session configuration (sess.config) and pluggable logging (logInfo, …)
• forget: reload marks — inclusive wipe back to a mark word for load → try → reload without process relaunch
• Security Restrictions, to restrict operations like file access, web dialing, listening, databases, crypto, threading, and module install/import, for embedded/AI scenarios
• LockSession — exclusive Send hold so an agent turn is not interleaved
• full example of a Web-based chat-like app that provides Final as a tool for the Agent
• finalembed / finalgo Go packages for embedding Final in other Go programs, with Session and Send semantics
• VS Code / Cursor Final extension for .fnl — TextMate highlighting, 2-space indent, sandwich snippets (local VSIX / F5 install)
• Raspberry Pi 5 support, for writing Pi-based control systems.
• Command line support, OS pipes, shebang scripts (Unix-like only)
• Raster blitting and drawing operations (all Final versions)
• GUI support via Fyne controls, final-gui binary
• support for Games and Simulations via SimGame framework
• Sound support via SoundPlayer and Sound objects

Near-term Features Planned

• Language-server features for the editor (dictionary completion, stack-effect hover, diagnostics)
  • build on compiler execution state tracking
• Compiler execution state tracking
  • catch stack bugs: underflow/leak
  • find opportunities to use strongly typed axioms rather than polys
• Markdown parsing
• Html and Xml rendering
• Interactive Web tutorials, using a sandboxed Final Session

Stacks

Up to now, we have been mostly mentioning the Data Stack (DS). But Final also defines four auxilliary stacks, all of which have the same capabilities, and a special Object Stack (OS) that contains the object instance when a Final method runs. The stacks, stack operators, and context selector prefixes are described in the following entries.

Stack Summary

Programmer accessible runtime stacks are a defining feature of stack-based languages like Forth and Final.

Final has seven(!) stacks, defined below. Note that this may seem to be a LOT of stacks, in comparison to Forth, which only had rs and ds. But the needs of a modern language, which will typically involve the use of several objects in an operation, along with the many shortcomings and dangers of Forth’s need for complex ds juggling have led to this design.

Return Stack (rs)

The Final Return Stack is similar to the singular “stack” in convenional languages and machine code. It’s primary purpose is to hold return addresses when a nested defined word runs. It also holds some additional values, such as a ContextMark containing the depths of all other stacks, and Dictionary-related lengths for some operations. The foreach iterated loop stores the iterator on rs.

The Return Stack is not user accessible in Final; it is used solely by the runtime.

Data Stack (ds)

This is the core stack used for holding values during an operation, and is almost directly comparable to Forth’s “stack”. Unlike procedure-based languages, parameters to, and results from most low and high level operations in Final are done via DS. This enables a system of operation decomposition and composition which provides numerous advantages over the procedural approach, in which a simple factoring for readability, testability, or reuse, requires a re-expression of all the parameters in the function call and return. In Final, you just factor, and the stacks hold what they have at the factor point.

Final allows compound operations, such as property and method access on objects, indexed accessors on Lists, and named accessors on Maps, to originate from objects on any stacks. But the convention for all those operations is for the parameters and results to be located on DS. DS thus serves as a common “hub”, for the source of parameters, and target for results of most operations.

Auxilliary Stacks (ts, xs, ys, zs)

Final provides four additional stacks, which all have the same capabilities. These can be used to help stage source and destination objects during a sequence of operations, without choking ds with multiple values that need to be constantly juggled. Doing this in Forth required constant juggling of ds via sundry dups drops overs nips tucks rots etc. which are difficult to reason about and get correct while writing, and almost impossible to track when trying to read code.

In addition to their general purpose uses, ts, the “Temp Stack”, is, by convention, the stack for short-lived parking: compound handles during t:, and interpret/compile temps. Prefer ts over the other stacks for any word-local intermediates.

Guidelines for effective use of the auxilliary stacks is provided in Writing Clean Final Code

Object Stack (os)

The Object Stack (os) is used exclusively by the runtime, to push the instance of an object for a Final Method call.Therefore, the runtime of such methods always access their instance via os.tos; and the appearance of the instance on a stack during the call doesn’t interfere with whatever are the context of objects and values already existing on the other stacks. (Note: Class methods push the Type on os, not an instance. Thus, other class methods and properties are accessible in that calling context.)

The Object stack can use the instance as a root for all OO accessor operations, by prefixing the operation or sequence with o: as with txyz.

However unlike the other stacks, you may not perform stack manipulation operations on os (e.g. o:drop, o: dup etc) nor may you push values onto os; there is no >os and os> operator pair. The runtime takes care of pushing the inst value to os before the method dispatch, and popping it after the method finishes. Note that this mechanism fully enables nesting Final method calls; the latest inst is always the one on os when that method runs.

Context Selectors

Given that Final has six user-accessible stacks, a means is obviously needed for operations to specify to which stack you are referring. This is called Context Selection. It arises in two areas:

1. Many stack operations can be performed on any stack, so in this case, a Context Selector (cs) specifies which stack the operation should be performed on.

2. Compound Path operations can start with an object–the “receiver”–on most any stack, so the cs is required to specify which stack.

A cs is simply the stack letter, followed by a colon, eg

• t: prefix for Temp Stack
• x: prefix for X Stack
  etc.
• o: prefix for O Stack

The Data Stack does not have a cs selector; an operation that supports a CS, without one, is assumed to apply to DS.

Note that not all compound path operations are supported with the receiver on DS; most require the receiver to be located on an auxilliary or the O Stack.

Stack Operators

Final has two kinds of stack operators:

• explicit stack selection
• Context Selector (cs) stack selection

As explained in the previous section, cs-aware operators referring to the Data Stack do not use a selector, DS is the default.

Some of these operators have been inherited from Forth, which as explained earlier, often required programmers to engage in mind-numbing stack value juggling; Final’s design and coding conventions have greatly reduced the need for such juggling, so don’t worry about words like rot or pick and such–they don’t find much use in Final. dup drop peek and the interstack movement operations make up the vast majority of Final’s stack repertoire.

The term tos means Top of Stack.

Explicit Stack Selection Operators

These operators explicitly state the stacks involved. All the to/from ones imply DS as the unspecified half. These operators are used frequently.

CS-Aware Stack Operators

These operators act on the stack selected by a Context Selector (t:, x:, y:, z:, or none for DS).

Control Flow

The Quick Tour already introduces Final’s control-flow blocks (if / switch, loops, break / continue) and the context-effect comment convention.

This section goes deeper on a few of those items:

All of these words are compile-only: they belong inside a colon definition (: … ;). Trying them at the interpreter prompt raises an error.

try / catch / finally / throw are also compile-only; they are covered in Error and Exception Handling.

For stack effects and short descriptions, use help on the word name (for example help foreach, help forever).

range and rangeby

Final provides two useful words for setting up counted iterated loops. range is for a definite counted loop with an increment of 1. rangeby is more flexible. They are described below. For detailed descriptions and stack effects, use help.

range

range takes an inclusive Int start and end value, and can then provide an Iterator for foreach. i is the value of the iteration value for that step, and starts with beg and ends with end. When using range to iterate over a counted zero-based range, you set beg to 0 and the end to be count-1. If the count is 0, no iterations are performed. The resulting i will be an Int.

> // ( -- )
: count1to5
  1 5 range
  foreach
    i $ sp
  /foreach
  nl
;
count1to5

1 2 3 4 5

Zero-based index style (here: three slots, indices 0 1 2):

> // ( count:i -- )
: indices
  0 swap 1 - range
  foreach
    i $ sp
  /foreach
  nl
;
3 indices

0 1 2

An empty range is legal and runs zero iterations — useful when a computed end would otherwise need a special “nothing to do” case.

rangeby

rangeby takes a beg, end, and step value. Step can be negative if beg>=end. The values can be of any numeric type, but they must all be the same type. This enables fractional Float step values. The iteration stops when the value goes beyond the end value. As with range, an empty range that has no first value is legal, and results in no iterations. i is the same type as the inputs.

> // ( -- )
: byTens
  0 40 10 rangeby
  foreach
    i $ sp
  /foreach
  nl
;
byTens

0 10 20 30 40

Float step:

> // ( -- )
: halves
  0.0 2.0 0.5 rangeby
  foreach
    i $ sp
  /foreach
  nl
;
halves

0 0.5 1 1.5 2

Counting down (negative step; beg >= end):

> // ( -- )
: countdown
  5 1 -1 rangeby
  foreach
    i $ sp
  /foreach
  nl
;
countdown

5 4 3 2 1

Iterators: foreach

Final supports the modern concept of Iterators. An iterator is an object produced from a source object, that knows how to iterate over values of the source. Many Final Types can provide an iterator, and their values can thus conveniently be iterated over in a foreach block.

To use them, you simply put the instance on DS prior to the foreach; foreach automatically retrieves the iterator, and starts the loop (if the iterator is not empty, eg an empty List). You access the item with the keyword i; in each case i is defined by the object, and is typically the natural value of the container.

You can nest foreach loops. Each level accesses its items via i. You can access the items above your level via the j keyword (next level up) and k (second level up.) Nested foreach loops use i, then j, then k for the current item at each nesting level.

The i/j/k accessors are only defined within the static lexical nesting of foreach loops. They are only defined within the word that has declared the loop; you cannot call another Final word, and use them in that context. You can however freely use them in subwords, provided they exist at the time the subword accesses them; i.e. you are calling the subword from within a foreach where i/j/k (as applicable) exist.

The following types support iteration.

range and rangeby

As described in Ranges.

> // ( end:i -- )
: countTo
  1 swap range
  foreach
    i $ sp
  /foreach
  nl
;
5 countTo

1 2 3 4 5

Lists: List, StringList, all Numeric Lists, StringKeyValueList

• Most Lists: iterate over the values; i is the list item; the list is iterated in 0-based order
• StringKeyValueList: i is a StringKeyValue object (Key and Value are strings); this List is principally used for Web query parameters and headers; thus, unlike Maps, keys can be repeated.

> // ( -- )
: showList
  ( "alpha" "beta" "gamma" )
  foreach
    i $ sp
  /foreach
  nl
;
showList

alpha beta gamma

StringKeyValueList — print each pair (.add^ takes value then key):

> // ( -- )
: showPairs
  StringKeyValueList.new^ >ts
  "1" "a" t:.add^
  "2" "b" t:.add^
  ts>
  foreach
    i >ys
    y:.key@ $ "->" $ y:.value@ $ sp
    y:drop
  /foreach
  nl
;
showPairs

a->1 b->2

Map family: Map, StringMap, DynamicObject, StaticObject, TypedObject

• Map, StringMap: iterates over all entries in an indeterminate order; i is a KeyValue object
• DynamicObject, StaticObject, TypedObject: iterates deterministically in order of field definition; i is a KeyValue object

> // ( -- )
: showDO
  DynamicObject.new^ >ts
  10 t:.x!
  20 t:.y!
  ts>
  foreach
    i >ys
    y:.key@ $ "=" $ y:.value@ $ sp
    y:drop
  /foreach
  nl
;
showDO

x=10 y=20

Creation order is preserved for DynamicObject / TypedObject; Map / StringMap order is not defined — do not rely on it.

Sets: Set, StringSet

foreach yields each value (not a KeyValue). Order is not defined.

( 1 2 3 set)
foreach
  i $ sp
/foreach
nl

VecNf and Mat2*

foreach yields each value. A vector walks 0 … len-1. A matrix walks flat row-major cells. For row/column coordinates see Vectors and Matrices.

Mats provide a convenient getRowIter and getColIter that are basically ranges set to the proper values for the row and column size respectively.

Pipes

Pipes provide a special purpose iterator that enables you to block waiting for the next value to be received, get that value via i, then resume checking for the next value. When the pipe is closed by the producer, the foreach exits. see Threading.

Other Loops

The Quick Tour shows foreach for iteration. Final also has indefinite loops that are not driven by an iterator. This page covers those, plus break and continue.

Like all control-flow blocks, these words are compile-only — use them inside : … ;.

Infinite: forever … /forever

No parameters. Loop until break, a fault, or an interactive Break (Ctrl-B in final).

> // ( n:i -- )
: tickN
  forever
    dup 0 <= if drop break then
    dup $ sp
    1 -
  /forever
  nl
;
3 tickN

3 2 1

An empty forever … /forever spins forever — use Ctrl-B to stop it in the TUI.

Pretest: begin … while … repeat

Words between begin and while run each attempt; while consumes a Truthy flag. Truthy → run the body through repeat and branch back to begin. Falsy → exit after while (skip the body).

> // ( n:i -- )
: drain
  begin
    dup while
      dup $ sp
      1 -
  repeat
  drop nl
;
3 drain

3 2 1

If the first test is already falsy, the body never runs:

> // ( -- )
: never
  0
  begin
    dup while
      "should not print\n" $
  repeat
  drop
;
never

Post-test: begin … until

The body runs, then until consumes a Truthy flag. Falsy → loop back to begin; truthy → exit. So the body always runs at least once.

> // ( n:i -- )
: blastoff
  begin
    dup $ sp
    1 -
    dup 0 == until
  drop nl
;
3 blastoff

3 2 1

Legacy infinite: begin … again

Same idea as forever, but older spelling. Prefer forever … /forever in new code — again does not support continue.

> // ( n:i -- )
: tickAgain
  begin
    dup 0 <= if drop break then
    dup $ sp
    1 -
  again
  nl
;
3 tickAgain

3 2 1

break

Exit the innermost enclosing loop among:

• foreach … /foreach
• forever … /forever
• begin … until
• begin … while … repeat
• legacy begin … again

Typical pattern: test inside the loop, then if break then.

> // ( -- )
: findThree
  1 10 range
  foreach
    i 3 == if break then
    i $ sp
  /foreach
  nl
;
findThree

1 2

When i is 3, break exits before the print, so only 1 2 appear.

continue

Skip the rest of the current iteration. Allowed only in:

• foreach … /foreach
• forever … /forever

Not in until or while … repeat.

> // ( -- )
: oddsOnly
  1 6 range
  foreach
    i 2 % 0 == if continue then
    i $ sp
  /foreach
  nl
;
oddsOnly

1 3 5

Inside forever, continue jumps back to the top of the forever body (here: skip printing 2):

> // ( -- )
: demoSkip
  3
  forever
    dup 0 < if drop break then
    dup 2 == if 1 - continue then
    dup $ sp
    1 -
  /forever
  nl
;
demoSkip

3 1 0

Both break and continue may sit inside an if / else / then — they still apply to the containing loop, not to the conditional.

To affect an outer loop, set a flag or sentinel in the inner loop and test it in the outer loop after /foreach or the matching closer.

Subwords

Final lends itself well to factoring complicated words into smaller worker words. This can be done at a macro level by defining new colon words, and then delegating to them in a main word.

But such factoring can be inconvenient or have drawbacks for several reasons:

• Final has a global namespace, so mnemonic words like “init” are not good factored word names;
• a delegated colon word doesn’t inherit locals set up in the calling word;
• when reading a file, it can be difficult to determine if a word is called in more than one place, or is a just a factor word;
• calling a colon word has overhead, which makes them less desirable for hot inner loop steps.

To address these issues, Final has subwords. A subword is a word defined inside a main colon word. Subwords are much lighter and more efficient than colon words, so are well suited for factoring code in inner loops or switch cases, to make the main flow more readable.

Here is an example use:

: main-word
  :s init
    // some factored init code, for clarity
  ;s
  
  // ( item -- )
  :s do-item
    // code to handle one item in a loop
  ;s

  init
  myList
  foreach
    i do-item
  /foreach
;

A subword has access to all the context of the main word, especially the local variables, and the i/j/k variables of foreach loops, and the a/b/c variables of switch statements. (And of course the stack contexts, which factored colon words also have access to.) Unlike a factored colon word, a subword may compile i/j/k/a/b/c without those blocks lexically around the use — they are checked at runtime against the shared frame. In the main body of the word, the usual static nesting rules still apply.

Subword definitions must be the first elements in a main word. There can be no main word code until the last subword definition. Subwords themselves cannot be nested; no :s in an outer :s.

You use subwords exactly like any colon word in your code, as demonstrated in the examples.

The subword names are only visible inside the main word, not outside it. You cannot invoke a subword inside one word from another. The same ordering rules that apply to words apply to subwords: a subword may call another subword that is lexically defined before it, but not after.

Subwords cannot call themselves. The recurse statement can be used, but it causes a new invocation of the main word, not the subword.

You can use most of the structured control blocks in a subword, such as if/then, foreach, etc. But the following restrictions apply:

• you may not define a try/catch block (but you can use throw)
• if you define a foreach loop, then it will nest inside any active outer foreach; you can access those using j/k but only if they are active when you call the subword
• the same rule applies for switch and b/c/ accessors

Most importantly, you can access all the locals defined in the main word, or subwords, within a subword. A subword can also add locals. Since local variables are resolved when they are accessed, not when they are compiled, it doesn’t matter if they are defined lexically later than where they are used. That said, for clarity, you may choose to initialize the locals that will be used throughout the words, in a subword like the init I gave in the example–this will make scanning the subwords prior to reading the main code more clear.

Subword invocation is extremely efficient. A subword is basically like a machine language subroutine, calling one is just a short brsub axiom, and returning is a retsub axiom, using a fast simple return stack in the ColonFrameMark of the main word. Using one will add negligible overhead even to hot inner loops, due to CPU caching. Therefore, subword factoring is encouraged even for hot paths, if it makes the code clearer.

Objects

The Quick Tour introduced Types, members, and the basics of compound path access. This Foundations section goes deeper on the APIs and the path syntax you use every day.

Everything you reach through a path—Go-native types, DynamicObject / StaticObject, TypedObject, Words, collections—uses the same API:

Parameters and results for member ops still use DS. The receiver (the object the path acts on) usually lives on an auxilliary stack (t: / x: / y: / z:) or on OS (o:) inside a Final method. See Stacks and Writing Clean Final Code.

Concrete collection APIs (List, Map, DynamicObject, StaticObject, TypedObject, Table) are in Collection Types. DynamicObject also offers .clone^ (shallow prototype copies) and .newStatic^ (mint a StaticObject from a DO prototype). Use help TypeName in the TUI for the full member list of any type.

In this section

• Types — Type objects, class vs instance members, factories
• Properties — fetch, store, const, refs
• Methods — instance and class methods, ^, Final methods on OS
• Collection Accessors — @() !() @[] ![] @{} !{} ?{}
• Compound Path Syntax — path elements, stacking rules, nested walks, examples

Types

A Type is Final’s description of a value family: instances of which can have properties, methods, and collection accessors. A Type may also have class properties and class methods, both accessed through the Type itself.

Types are first-class objects. CapCase names such as Int, List, and DynamicObject are dictionary words that push the Type onto DS.

List $          // prints the Type
List.new^ $     // factory: empty List on DS

Primitives (Int, String, Bool, …) do not have object instances, but they still have a Type with useful class members (constants, conversions, factories). Reference types (List, Map, Word, …) have both class members and instance members.

Class vs instance

Class methods are never invoked from an instance (myList.new is invalid). Factories live on the Type: List.new^, Person.new^.

By convention:

• default factory is new — ( -- inst ) with default values or zeros in the properties
• parameterized factories use names like newWithCapacity, newFromString, etc.

16 List.newWithCapacity^ >ts
"Ada" StringBuilder.new^ >xs

Exploring types

help List
help DynamicObject
help Word

help lists properties, methods, class members, and which item accessors the type supports.

Prototype families

Final groups related concrete types under prototype parents such as ProtoList and ProtoMap. That is mainly a catalog / sharing story (for example Json rendering treats all list-like and map-like types uniformly). Day-to-day code still names the concrete type (List, StringMap, DynamicObject).

Your own types

TypedObject registers a named schema in the catalog. After makeType, the new CapCase name behaves like any other Type: YourType.new^, dotted fields, optional Final methods.

Properties

A property is a named member of a Type accessed with .name plus a fetch or store affix. Backing may be a stored slot or a computed getter/setter; the API is the same.

Property names and instance method names on one Type are disjoint. Use help TypeName to see which is which.

Fetch and store

Value in / value out always on DS. The rooted receiver stays on the context stack.

DynamicObject.new^ >ts
"Ada" t:.name!
36 t:.age!
t:.name@ $ sp t:.age@ $ nl    // Ada 36
t:drop

Store paths onto a parked receiver need an explicit context selector (t: / x: / …). A bare store on DS without a prefix is rejected (d: does not help). Ident-rooted paths are allowed without a selector (1 sess.config.paramA!), as are l.field! and pls.field!.

Readonly / const properties (including many class constants) may omit @:

Math.pi $
Int.maxInt $
Float.NaN $
TokenType.TokenEOF $

Const vs ordinary

• Const / IsConst — fetch returns the value immediately; there is no lasting PropertyRef. Typical for math constants and enum-like class properties.
• Ordinary — fused .name@ / .name! are one-shot (no ref left on the stack). Mid-path .name also fetches the value and continues the walk with that value as the next focus.

Property refs (~)

When you need the ref itself (for example read–modify–write with separate @ / !), materialize with the ~ affix. ~ must be the last segment of that path token.

// Word on DS; materialize name ref, then Forth-style R-M-W
"dup" find
.name~
dup @          // fetch current name
drop
"fresh" swap ! // store; consumes ref

Standalone @ and ! consume a PropertyRef on the context stack. Fused .name@ / .name! never leave a ref behind.

You cannot fuse ~ with @ in one token (name~@ is illegal). Use .name~ then a separate @ or !.

Nested property walks

Intermediate .prop segments fetch the contained object and continue; intermediates are not parked on a stack:

dc.dict.len $     // DictionaryContext → dict → len

See Compound Path Syntax for the full segment vocabulary.

Methods

A method is a named operation on a Type. Invoke it with the ^ (“run”) affix. Bare .method without ^ is an error.

Operands and results use DS. The receiver stays on the context stack for rooted calls.

Instance methods

List.new^ >ts
10 t:.append^
20 t:.append^
t:.len@ $ nl      // 2
t:.clear^
t:drop

StringBuilder.new^ >ts
"hi" t:.writeString^
t:.toString^ $ nl    // hi
t:drop

Class methods

Class methods run with the Type as receiver. Factories are the common case:

List.new^                         // ( -- list )
16 List.newWithCapacity^          // ( cap:i -- list )
5 List.newWithLen^                // ( len:i -- list )

Other class methods query or compute without an instance handle:

Float.NaN Float.isNaN^ $ nl    // true
2 10 Float.pow^ $ nl           // 1024.0

For string→number conversion, use the cast operators from the Quick Tour ("42" >>Int?), not a Type method.

Final methods (TypedObject)

Methods written in Final are defined on a TypedObject type (see TypedObject) with : Type#name … ; (instance) or : Type##name … ; (class). Registration happens at ; — no dict word is left behind. While the method runs, the receiver is on the Object Stack. Use the o: prefix; you may not push or drop OS yourself; the runtime takes care of pushing the instance prior to invoking the method, and then dropping it when the method returns.

: Person#describe
  o:.name@
  o:.age@
  "%s (%d)" fmt
;

Person.new^ >ts
"Ada" t:.name!
36 t:.age!
t:.describe^ $ nl    // Ada (36)
t:drop

Nested o:.… paths behave like any other rooted compound path for the duration of the call.

Collection Accessors

Some Types expose item access in addition to named properties and methods. Items are not properties: they use the fused collection affixes below. Index or key operands are on DS; with a context selector (t:@(), …) the collection receiver stays on that stack.

help TypeName shows which of @() / !() / @[] / ![] / @{} / !{} / ?{} that type supports. Most types support either the () set or the {} set; DynamicObject and TypedObject support both. Mat2f supports flat () and coordinate [].

Ordinal @() / !()

Zero-based index. !() does not grow a list — use .append^ / .insertAt^ for that.

List.new^ >ts
10 t:.append^
20 t:.append^
30 t:.append^
1 t:@() $ nl          // 20
99 1 t:!()            // replace index 1
1 t:@() $ nl          // 99
t:drop

On DynamicObject / TypedObject, @() / !() use field creation (or declaration) order, not a hash order:

DynamicObject.new^ >ts
1 t:.x!
2 t:.y!
0 t:@() $ nl          // 1
t:drop

On Mat2f, @() / !() are flat row-major. Use @[] / ![] for (row, col) — Vectors and Matrices.

Mat @[] / ![]

These accessors take a row/col pair, and return or set the value in that cell.

2 3 Mat2f.new^ >ts
// set row 0, col 2 to a value
1.0 0 2 t:![]
// retrive the value
0 2 t:@[] $ // 1
tdrop

When iterating in nested foreach loops, the following pattern is common:

( mat -- )
>ts
t:.getRowIter^
foreach
  t:.getColIter^
  foreach
    j i t:@[]
    // do something with the value
  /foreach
/foreach
tdrop

Named @{} / !{} / ?{}

StringMap.new^ >ts
100 "count" t:!{}
"Ada" "name" t:!{}
"name" t:@{} $ nl
"missing" t:?{} $ nl  // false
t:drop

@{} on a missing key is an error. Probe first with ?{} (or a type’s hasKey method when provided).

"city" t:?{} if
  "city" t:@{} $ nl
else
  "n/a" $ nl
then

Prefixed vs bare

Day-to-day code should park the collection and use a selector:

0 t:@()
"k" t:@{}

A bare @() / @{} path whose receiver is on DS (no t: / …) is a one-shot form that elides the receiver after the access. Prefer the rooted cs: form so the handle remains for the next operation.

Chaining after a get

Because @() / @{} leave a value on DS, further member access on that value usually means moving it to a stack first:

"tags" t:@{} >xs
0 x:@() $ nl
x:drop

Or nest through properties when the path stays inside one walk — see Compound Path Syntax.

Collection type APIs (append, clear, iteration, …) are documented under Collection Types.

Compound Path Syntax

A compound path is a single lexical token that chains object operations with no whitespace. It is Final’s compact notation for property access, method invoke, and collection get/set. Paths compile and interpret as a left-to-right walk of fixed segments.

The Quick Tour covered the everyday forms (t:.name@, List.new^, t:@()). This page enumerates the path elements, stacking rules, and longer examples.

Why paths

• Clarity — one token states the whole access intent
• Brevity — nested objects need not be parked mid-walk
• Efficiency — the walker materializes and elides intermediates for you

Rooted paths preserve the root receiver on the context stack, so you do not dup before each member op. That is the pattern recommended in Writing Clean Final Code.

Path shape

[ cs: ] [ RootIdent ] { Segment }…

Examples:

Elements

1. Context selector (cs:)

Optional prefix naming which stack holds the receiver:

List.new^ >ts
t:.len@ $ nl

See Context Selectors.

2. Root

How the walk starts:

TokenType.TokenEOF $     // Type root + class const → value on DS
"dup" find .name@ $      // instance already on DS + property fetch

3. Member segment: .name

Dot plus a member name. What happens depends on the following affix (or whether more path follows).

Mid-path .inner always means “fetch this property and continue with its value”:

dc.dict.len $

4. Affixes

Fused forms you will see constantly:

t:.count@          // .  count  @
t:.count!          // .  count  !
t:.reset^          // .  reset  ^
t:.count~          // .  count  ~

Illegal: t:.count~@ (~ cannot be followed inside the same token). Use t:.count~ then @.

5. Collection affixes

Each of these is one segment cell:

0 t:@()
99 0 t:!()
"name" t:@{}
"Ada" "name" t:!{}
"name" t:?{}

Details and type coverage: Collection Accessors.

Receiver and DS roles

Common factory then park:

DynamicObject.new^ >ts     // inst on DS → TS
"Ada" t:.name!
t:.name@ $ nl
t:drop

Stores (.name!, !(), !{}) onto a receiver parked on a stack need t: / x: / y: / z: / o:. Ident-rooted paths do not (1 sess.config.paramA!). l. / pls. stores are the same. A bare .name! on DS is rejected (d: does not change that).

Class paths vs instance paths

// Class — Type name in the path
List.new^
Math.pi
Int.maxInt

// Instance — receiver on a stack
List.new^ >ts
10 t:.append^
t:.len@ $
t:drop

Nested walks and elision

Interior objects fetched mid-path are not left on stacks. Only the root receiver (when rooted) and the terminal product (on DS) remain.

// TypedObject instance on TS with a List field .tags
Person.new^ >ts
List.new^ >xs
"lang" x:.append^
"math" x:.append^
xs> t:.tags!

t:.tags@ >xs
0 x:@() $ nl       // lang
x:drop
t:drop

When a property yields another object you will keep using, park it (>xs) rather than relying on a one-shot DS value.

Refs and read–modify–write

"dup" find >ts
t:.name~
dup @
drop
"DUP" swap !
t:.name@ $ nl      // DUP
t:drop

Standalone @ / ! / ^ consume the ref. Fused path terminals elide the ref automatically.

Worked examples

Build and inspect a list

List.new^ >ts
10 t:.append^
20 t:.append^
30 t:.append^
t:.len@ $ nl       // 3
1 t:@() $ nl       // 20
40 1 t:!()
1 t:@() $ nl       // 40
t:drop

Map upsert and probe

StringMap.new^ >ts
1 "a" t:!{}
2 "b" t:!{}
"a" t:@{} $ nl
"c" t:?{} if
  "c" t:@{} $
else
  "missing" $
then
nl
t:drop

DynamicObject fields and ordinals

DynamicObject.new^ >ts
1 t:.x!
2 t:.y!
3 t:.z!
t:.y@ $ nl         // 2
1 t:@() $ nl       // 2  (creation order)
"z" t:?{} $ nl     // true
t:drop

Class const plus rooted instance work

Type constants and factories use a CapCase root; instance work parks the handle:

Math.pi 2 * $ nl

StringBuilder.new^ >ts
"maxInt=" t:.writeString^
Int.maxInt "%d" fmt t:.writeString^
t:.toString^ $ nl
t:drop

Final method with o:

: Box#label
  o:.title@
;

Box.new^ >ts
"inbox" t:.title!
t:.label^ $ nl
t:drop

Inside Box#label, o:.title@ is an ordinary rooted path on OS.

Segment checklist

Allowed punctuation / affix cells inside a compound token:

. @ ! ^ ~ @() !() @{} !{} ?{}

Rules of thumb:

• no whitespace inside the token
• ^ and ~ only as the last segment of that token
• member names: letter or _ start; then letters, digits, _, -, $, ?
• prefer t: / x: / … for any sequence of ops on one object

Related: Properties, Methods, Collection Accessors, Stacks.

Compound Types

Final’s compound types hold related values together: ordered sequences (Lists), keyed tables (Maps), Sets, named field objects (DynamicObject / StaticObject / TypedObject), Vecs and Mats, and columnar grids (Table).

The Quick Tour already introduced what each family is for. This section focuses on the APIs you use day to day, with short examples. For the path syntax behind .append^, @(), !{}, and friends, see Objects.

Use help TypeName in the TUI for the full member list of any type.

Note: Mat2f has additional uses and dedicated mat:: operations; it is documented along with VecNf vectors and OLS under Linear Algebra.

Lists

A List is Final’s growable ordered sequence. Items are addressed by zero-based index. Most list types share one API; the specialized types mainly change what may be stored, and a few add sort and shuffle.

Creating a list

List.new^                    // empty list
16 List.newWithCapacity^     // empty, room reserved for 16 items
5 List.newWithLen^           // length 5, slots filled with zeros for that type

newWithCapacity is useful when you already know about how many items you will append. newWithLen is useful when you will fill the default zero slots by index with !().

Common API

These members are available on List, StringList, and the numeric list types.

Indexed access

cs:@()   // ( index:i -- value )   read
cs:!()   // ( value index:i -- )   write existing slot

The receiver stays on the context stack. Writing with !() requires a valid index in 0 .. len-1; use append / insertAt to grow the list.

Iteration

Put the list on DS, then foreach … /foreach. The loop value i is each element, in order from index 0 to len-1.

Typical pattern

List.new^ >ts
10 t:.append^
20 t:.append^
30 t:.append^
0 t:@() $ nl        // 10
1 0 t:!()           // replace index 0 with 1
t:.len@ $ nl        // 3
t:drop

The following pages cover what makes each list family different.

List and StringList

Both types share the common List API. They differ only in what they store, and StringList adds sorting.

List

List is the general-purpose sequence. Each cell holds Any: numbers, strings, Bool, Null, or other objects (including nested lists and maps). Items do do not need to be the same type.

List.new^ >ts
"hello" t:.append^
42 t:.append^
true t:.append^
null t:.append^
t:.len@ $ nl    // 4
t:drop

Use List when the element type varies, or when you are building a temporary list of mixed values (for example before rendering Json).

StringList

StringList stores only String values. That keeps storage compact for the common “list of text” case, and rejects non-string appends.

StringList.new^ >ts
"alpha" t:.append^
"Beta" t:.append^
"gamma" t:.append^
t:.sort^
t:peek foreach
  i $ sp
/foreach
nl
t:drop

sort

// ( -- )
.sort^

StringList#sort orders by Utf-8 byte values. In plain ASCII that puts uppercase before lowercase ("Beta" before "alpha"). It is not locale-aware alphabetic sorting.

List (Any cells) does not provide sort.

Numeric Lists

Numeric lists use the common List API, but store a single numeric width in each cell. Values are widened to Int, Uint, or Float on the Data Stack when you read them, and narrowed again when you write.

They exist so large sequences of numbers do not pay the cost of a fully general List cell. A ByteList, for example, is far more compact than a List of small integers, and is the natural home for raw byte buffers used with strings and byte streams.

Types

ByteList is the unsigned 8-bit list — not a signed “char” width. Use Int8List when you need signed 8-bit storage. Unicode code points fit in Int32List when you want a dense list of them; day-to-day text work usually streams runes instead.

Example

5 FloatList.newWithLen^ >ts
3.14 0 t:!()
2.71 1 t:!()
1.41 2 t:!()
0 t:@() $ nl     // 3.14
t:.sort^
t:drop

ByteList.new^ >ts
65 t:.append^    // 'A'
66 t:.append^
t:.len@ $ nl
t:drop

sort

Every numeric list type supports:

// ( -- )
.sort^

Sorting uses the natural order for that numeric type.

VecNf / Mat2f are fixed-shape dense Float arrays for linear algebra, not Lists — they do not grow. See Linear Algebra.

StringKeyValueList

StringKeyValueList is a specialized list of string key / string value pairs. Unlike Map / StringMap, the same key may appear more than once, and insertion order is kept. That matches HTTP headers and query parameters, where repeated keys are legal.

It does not use the ordinary List append / @() API. Use the members below instead.

Creation

StringKeyValueList.new^
16 StringKeyValueList.newWithCapacity^

API

Keyed accessors

Use add when you intentionally want a second header with the same name. Use !{} when you want to replace the first occurrence.

Example

StringKeyValueList.new^ >ts
"text/html" "Content-Type" t:.add^
"1" "X-Count" t:.add^
"2" "X-Count" t:.add^          // second X-Count kept
"application/json" "Content-Type" t:!{}   // replaces first Content-Type

"Content-Type" t:@{} $ nl      // application/json

t:peek foreach
  i >xs
  x:.key@ $ ": " $ x:.value@ $ nl
  x:drop
/foreach
t:drop

In foreach, i is a StringKeyValue (same shape as KeyValue): read .key@ and .value@.

Maps

A Map is a table of key → value entries. The first write of a key creates the entry; later writes replace the value. Reads of a missing key are an error unless you test first with ?{} or hasKey.

Final provides two map types that share the same programming model.

Common API

Keyed accessors

Iteration

Put the map on DS, then foreach … /foreach. Order is not defined. The loop value i is a KeyValue with .key@ and .value@.

Map

Map accepts keys that are comparable primitives (typically String or numbers). Values may be any Final type. Compound objects cannot be used as keys.

Prefer Map when you need numeric (or other non-string) keys.

Map.new^ >ts
"red" 1 t:!{}
"green" 2 t:!{}
1 t:@{} $ nl           // red
1 t:.hasKey^ $ nl      // true
1 t:.deleteKey^
t:.len@ $ nl           // 1
t:drop

StringMap

StringMap is the usual choice for string-keyed dictionaries. Only a String is accepted as a key; values may still be any type. It inherits the common Map members (len, clear, and so on).

StringMap.new^ >ts
100 "count" t:!{}
"Ada" "name" t:!{}
"name" t:@{} $ nl
"missing" t:?{} $ nl   // false
t:peek foreach
  i >xs
  x:.key@ $ "=" $ x:.value@ $ nl
  x:drop
/foreach
t:drop

For small named records where field order matters, or where dotted .field access is nicer, see DynamicObject. For a reusable schema, see TypedObject.

Sets

A Set is similar to a Map without values. It holds a single instance of any key entered. Sets, like Maps are unordered, so you can query for the existence of a value, but not access the values in ordinal order.

Set operators are provided as follows:

• set::union – produces a set that contains the elements of both sets
• set::intersection – produces a set with only the items in both sets
• set::difference – produces a set of the items of the first set, with those in the second set removed from it
• set::symmetric difference – is like an XOR, it returns the unique elements in each set, but not those shared by both sets

Final provides two Set objects:

• Set, which can take any comparable type, like numerics and String
• StringSet, which holds String values

A Set can be iterated with foreach; i returns the value.

A Set can be created using the List operators ( ... set) for a Set and ( ... sset) for a StringSet.

A Set is rendered in JSON as an array; the items are in an undefined order. A Set cannot be produced by a JSON string.

Mats

A Mat (Matrix) is a multidimensional container whose shape is set at construction time. Final currently supports 2-dimensional mats that can hold a variety of strongly typed or Any-typed values. The two dimensions of Final’s 2d Mats are its rows and columns. The cells are stored in row-major order, meaning the column cells are adjacent in the underlying array holding the values. A Mat cannot be resized once created.

The factory for all Mats has the following form, using Mat2f as an example:

2 3 Mat2f.new^ // creates a mat with 2 rows and 3 columns

The value in a cell is accessed either by the row/col matrix accessors @[]/![] or using a flat index, where cell index = row*cols + col using the ordinal accessors @()/!().

Mat is iterable, and returns the items of the Mat in flat ordinal order. There are two convenience iterator accessors, which are basically shortcuts for a range operator:

• getRowIter // provides the indexes 0..rows-1
• getColIter // provides the indexes 0..cols-1

Typically used like this:

  myMat l.mat!

  l.mat.getRowIter^
  foreach
    l.mat.getColIter^
    foreach
      j i l.mat@[] // retrieves item at row j col i
      ...
      newVal j i l.mat![]
    /foreach
  /foreach

The following Mats are provided. Some serve special purposes, as noted

Notes:

1. unsigned value set/returned in an Int
2. unsigned value set/returned in a Uint
3. special use in Blitting operations
4. value set/returned in a Float
5. special use in linear algebra, regression/model testing, and mat:: operators

DynamicObject

DynamicObject (DO) is Final’s lightweight named-field object. You create fields as you go; there is no separate schema. It is a frequent choice for Json objects, ad-hoc records, and small configuration-style payloads.

Compared with StringMap, a DO is typically leaner and faster when the number of fields stays modest (on the order of tens). It also preserves field creation order, and supports both name and ordinal access.

Creation

Empty instance:

DynamicObject.new^   // ( -- o:DynamicObject )

newdo is a short alias for the same factory.

{ … } literal

Prefer the { … } builders when you already know the fields. { marks stack depth (like (). } gathers value / name pairs down to that mark into a DynamicObject. Use sm} instead of } to build a StringMap the same way.

{ 1 "x" 2 "y" 3 "z" } >ts
t:.x@ $ sp t:.y@ $ sp t:.z@ $ nl    // 1 2 3
t:drop

{ "Ada" "name" 36 "age" } >jsonp $ nl
{ "London" "city" "UK" "country" } sm} >ts
"city" t:@{} $ nl
t:drop

Stack order is value then name (same as !{}).

Access

A field must be created (with .name! or !{}) before it can be read with .name@ or @{}.

DynamicObject does not expose Map’s len / clear / hasKey methods; use ?{} for existence, and build a fresh DO when you want a clean slate.

Example

{ 1 "x" 2 "y" 3 "z" } >ts
t:.x@ $ sp t:.y@ $ sp t:.z@ $ nl    // 1 2 3
0 t:@() $ nl                         // 1  (first field created)
"x" t:?{} $ nl                       // true
t:drop

When you need to grow fields after creation, start empty and set as you go:

newdo >ts
1 t:.x!
2 t:.y!
t:drop

Cloning (prototypes)

.clone^ returns a shallow copy with the same fields and values. Use a prototype DO with defaults, then clone for each working instance so mutations stay isolated.

{ "" "string" 0 "int" } >xs

x:.clone^ >ys
"y mutate" y:.string!
1 y:.int!

x:.clone^ >zs
"z mutate" z:.string!
2 z:.int!

xs> >jsonp $ nl    // prototype unchanged
ys> >jsonp $ nl
zs> >jsonp $ nl

For a fixed field set with lower per-instance overhead, mint a StaticObject from the same prototype via .newStatic^.

Iteration

foreach walks fields in creation order. The loop value i is a KeyValue: .key@ is the field name (String), .value@ is the stored value.

{ "Ada" "name" 36 "age" } >ts
t:peek foreach
  i >xs
  x:.key@ $ ": " $ x:.value@ $ nl
  x:drop
/foreach
t:drop

A DynamicObject is a one-off instance: its field set is not a reusable type. When you need a named type you can mint repeatedly (optionally with Final methods), use TypedObject.

Optimizations for Large Field Sets

Since DynamicObject is the object returned when parsing JSON, it is optimized “under the hood” to support almost unlimited field sizes. This is not a typical use case in normal use of DO as an Object-type, but helps it become an efficient hybrid of an Object and a Map for large machine-generated field sets, such as cache key results that can run into the thousands. If DO has more than 64 fields added, it switches under the hood to use a map-like ordinal lookup, rather than an interated lookup. This operation does not affect how DO behaves or is used. For an object that follows purely Map-based semantics, the Final Map or StringMap types are still recommended.

StaticObject

StaticObject (SO) is a fixed-schema record whose field names live on a prototype DynamicObject; each instance holds only a dense value array. Access looks like DynamicObject (named fields, keyed and ordinal items, foreach), but the field set cannot grow after construction.

Typical uses: many rows that share one schema — Table rows, SQL-style result shapes, directory-listing style records — when you want DO-like accessors with lower per-instance overhead than cloning full DynamicObjects.

Creation

Build (or obtain) a prototype DO, then call .newStatic^ on that instance:

{ "" "name" 0 "age" } >xs          // prototype: field names + defaults

x:.newStatic^ >ts
"Ada" t:.name!
36 t:.age!
t:.name@ $ sp t:.age@ $ nl         // Ada 36
t:drop
x:drop

.newStatic^ is an instance method on DynamicObject:

proto.newStatic^   // ( -- so:StaticObject )   cs( proto -- proto )

It shallow-copies the prototype’s current field values into the new StaticObject. Later stores on the instance do not change the prototype’s values; later stores on the prototype do not change existing instances.

There is no StaticObject.new^ factory — every SO is minted from a DO prototype.

Access

Same API as DynamicObject:

Difference from DynamicObject: setting an unknown name panics — the schema is frozen at newStatic. Use ?{} to test membership against the prototype’s names.

Example (Table-style rows)

: makePrototype
  { "" "name" 0 "age" }
;

makePrototype const: proto

: addRow   // ( name:s age:i tbl:Table -- )
  >ys
  proto.newStatic^ >ts
  t:.age! t:.name!
  ts> y:.append^
  y:drop
;

proto Table.newFromDynamicObject^ >zs
"Ada" 36 z:peek addRow
"Bob" 24 z:peek addRow
z:drop

Iteration

foreach walks fields in prototype registration order. The loop value i is a KeyValue (.key@ / .value@), same as DynamicObject.

Related

• Prototype / ad-hoc DynamicObjects: DynamicObject (including .clone^)
• Named types with typed fields and Final methods: TypedObject
• Columnar grids: Table

TypedObject

TypedObject is how you define your own record types in Final: a fixed set of named fields, each with a declared Type, registered in the type catalog. After registration you create instances with YourType.new^, read and write fields like other objects, attach class constants, and define Final methods with a simple naming convention.

Unlike DynamicObject, the schema is declared up front and shared by every instance of the type.

Define and register a type

Typical flow:

1. TypedObject.newTypeDef^ — empty schema shell (.name, .fields, .constants)
2. Fill .name and .fields (each field value must be a live catalog Type, such as String or List, not a type-name string)
3. Optional: fill .constants with value .name! (readonly class consts)
4. TypedObject.makeType^ — seal and register the type
5. Optional: : YourType#method … ; / : YourType##classMethod … ; — Final methods
6. YourType.new^ — create instances

Example schema

The schema for a TypedObject is most conveniently defined using paren operators, as in this example:

// you will be building DynamicObjects, with nesting
{
  "Person" "name" // your type name

  // now define your fields
  // you provide the Type object of each field (not the name in quotes)
  {
    String "firstName"
    String "lastName"
    Int    "age"
  } "fields"

  // optional: define class readonly constant values
  {
    111 "defaultAge"
  } "constants"
}
TypedObject.makeType^ // your type is now available to use or add methods to

Person.defaultAge@ $ nl    // 111

Create and fill an instance

Person.new^ >ts
"Ada" t:.firstName!
"Lovelace" t:.lastName!
36 t:.age!

t:.firstName@ $ sp t:.age@ $ nl
0 t:@() $ sp                  // firstName by declaration ordinal
1 t:@() $ nl
t:drop

Field stores are checked against the declared type. Accessors:

foreach on a TypedObject walks fields in declaration order; i is a KeyValue.

Final methods

After makeType, define instance methods with : TypeName#methodName … ; and class methods with : TypeName##methodName … ;. The ; registers the method on the type; no dictionary word remains.

The instance (or, for ##, the Type) is on the Object Stack; use the o: prefix. (You do not push or drop OS yourself, the runtime takes care of that.)

/*
Print the fieldnames and values for the instance.
( -- )  o( inst:Person )
*/
: Person#print
  ( o:.firstName@ o:.lastName@ o:.age@ ) "%s %s (%d)\n" fmt $
;

/*
Create a new Person with defined default values.
( -- person:Person )  o( type:Person )
*/
: Person##newDefault
  o:.new^ >ts
  "anon" t:.firstName!
  "" t:.lastName!
  Person.defaultAge@ t:.age!
  ts>
;

Person.newDefault^ >ys
y:.print^
"Bilbo" y:.firstName!
"Baggins" y:.lastName!
y:.print^
y:drop

Member names are unique across fields, constants, and instance/class methods on that type.

If you include the recommended prefix /* */ comments before your method, it gets included in your type catalog, for later listing using help MyType.

While a Final method runs, o: keeps the receiver in view for nested property and method paths.

Base Types

Some Final Types are designed to be used with an instance of a TypedObject, so that the base object can invoke Final callback methods and event handlers on the TypedObject, called the delegate. The documentation for such types will specify the need for your delegate instance. When you define such a TypedObject, you include an additional specifier, baseType. The following example uses the final-gui SimGame type as an example:

// you will be building DynamicObjects, with nesting
{
  "Person" "name" // your type name
  SimGame  "baseType" // this will create a `base` field that will be a SimGame
// same as a regular type: fields and optional constants

When you create an instance of your type, it automatically creates an instance of the base type, and sets that into the base field that is automatically added to your type. The base type will have a field named del (for delegate) that it initializes with your TypeDef object. It uses that to forward callback and event method invocations.

A Base Type will typically require you to implement certain named methods on your type. For example, SimGame requires a #preInit and #postInit pair, which it calls during its #init. A base type may include optional methods that are required if you enable a specific feature of the base type. For example, SimGame has options for keyboard and mouse event handling, and when you enable those features, it requires you to define handler methods for those events. See the documentation for individual base types for the properties and methods of the base type, and the methods, and possibly fields it requires you to implement on your delegate TypedObject type.

Most Base Types will have a template in the examples folder that provide stub implementations of the required and optional events, and a stub TypeObject schema. You can copy this template, rename the file and the type name instances in the file, and you will be ready to add your own custom code.

Table

Table is a named-column row collection. Column names are fixed at construction; you append rows afterward. Sort is stable, so successive sorts compose (later keys break ties without scrambling earlier order).

Rows can be any objects that expose the schema’s columns — commonly StaticObject instances minted from a DynamicObject prototype, DynamicObject clones, TypedObject instances, or other typed values with matching properties / @() / @{}.

Construction

Members

Sortable cell types: Bool, Int, Uint, Float, String, DateTime. Compared cells must share a type.

Table is Iterable — foreach walks rows.

Example (DO proto + StaticObject rows)

: makePrototype  ( -- proto:DynamicObject )
  { "" "name" 0 "age" }
;

makePrototype const: proto
proto Table.newFromDynamicObject^ const: table

: addRow  ( name:s age:i -- )
  proto.newStatic^ >ts
  t:.age! t:.name!
  ts> table.append^
;

"Gopher" 13 addRow
"Alice"  20 addRow
"Bob"    24 addRow
"Alice"  55 addRow

table >ts
0 Table.SortAsc t:.sortByOrd^     // sort by name (column 0)
t:.rows >jsonp $
t:drop

proto.newStatic^ builds a StaticObject: field names live on the prototype DO; the instance holds a values array. Same .name! / .age@ API as a DynamicObject for those fields.

Successive sorts: sort by age, then by name (or the reverse) — stability preserves relative order for ties.

table >ts
1 Table.SortAsc t:.sortByOrd^           // by age
"name" Table.SortAsc t:.sortByName^     // then by name
t:drop

Notes

• Append does not deeply validate row shape — supply rows that match the schema accessors the Table was built for.
• Prefer a DO prototype + newStatic when you want light row instances with a shared column layout.
• For reusable typed rows with Final methods, mint a TypedObject type and use Table.newFromTypedObject^.
• dbIter>table (from a DbProvider.query^ iterator) builds the Table from the query’s DynamicObject prototype and appends StaticObject rows. See SQL Databases.

Use help Table in the TUI for the full member list.

Compound Builder and Filler Operators

Final provides a concise, convenient set of operators to build or fill many of the most-used collections and objects. The operators work interactively in the interpreter, or can be compiled into code. There are three families of operators, each starts with an opener operator, followed by zero or more elements, then a close operator. Close operators can have variants that control the exact type of the collection from the family that is rendered or filled.

• ( opens a List or Set builder
• { opens an Object or Map builder
• [ opens a Vec or Matrix filler (note: not a builder)

When you enter the opening operator, Final marks the location on DS. The closing operator then gathers up all the items placed on DS after the mark, and puts them into the collection. Easy-peasy!

The operators are best explained by example.

List and Set Builders

There are several List terminators:

• ) builds a List; the elements can be any Final type
• s) builds a StringList; the elements must be of String type
• i) builds an IntList; the elements must be of Int type
• b) builds a ByteList; the element must be of Int type, 0-255

And two Set terminators:

• set) builds a Set; the elements can be any comparable type: numerics or String
• sset) builds a StringSet; the elements must be of String type

// ( -- l:List )
( 1 2 "buckle" )

// ( -- sl:StringList )
( "my" "shoe" s)

// ( -- il:IntList )
( 1 2 3 4 5 i)

// ( -- bl:ByteList )
( 0 1 2 255 b)

(The set operators behave identically, but produce the requested set type.)

Object Builders

The Object operators build a new DynamicObject, or a new StaticObject created from a supplied DynamicObject prototype, or a StringMap. The items must be in pairs: the first element is the value, the second element is the field name.

// ( -- do:DynamicObject )
{
  1 "one"
  2 "two"
}

// Creates a StaticObject minted from proto
// In this example, we use the previous DO as the prototype
// The field names used must be defined in the DO
// ( proto:DynamicObject -- so:StaticObject)
{ 
  1.0 "one"
  2.0 "two"
so}

// Creates a StringMap
// ( -- sm:StringMap )
{ 
  1 "one"
  2 "two"
sm}

Vec and Matrix Fillers

Unlike the ( and { operators, the [ operators fill an instance you supply; they do not create a new instance. The pattern of use is creating the instance with the new factory operator, then using the Paren operators to provide the values. Vec values are provided in 0-based order; Matrix values must be supplied in row-major order, i.e. for a 2D Matrix, the first row supplies col0 to col(cols-1), etc.

NOTES:

• every value based on the length of the Vec/Mat must be supplied, otherwise the closer will fault;
• the values must be compatible with the cell type of the matrix; no numeric coercion is done.

// fill a Mat2f Matrix
// ( mat:Mat2f )
2 3 Mat2f.new^
[ 
  0. 1. 2.
  3. 4. 5.
]

// fill a Vec
// ( vec:Vec )
3 VecNf.new^
[ 1. 2. 3. ]

Full Vec/Mat API, operators, and OLS: Linear Algebra.

Nesting Operators

You can nest operators to build complex compound objects. There is no practical limit to the nesting level. The rules are:

• the operators must be in family pairs
• you cannot span inner closers across outer opener boundaries eg. no ( 1 “two” { 3 “three” ) }
• the inner collection you build must be a valid type for the outer collection you are building

Word Invocations while building/filling

You are allowed to invoke (interpret) or compile (compiling) a word inside unclosed Paren blocks. This can be useful to factor repeated patterns, perhaps with a computation, into a worker word.

: gen3 0 2 range foreach i /foreach ;

( -2 -1 gen3 ) // adds 0 1 2

Tips, Cautions, and “Gotchas”

Tips

You can use code inside the operators, and this is often useful. For example, to get the value of the “num” field from an object on xs you can do this:

( ... x:.num@ ... )

You can do computations inside the operators. For example, to fetch two values and add them, putting the sum on a list slot, you can do this:

( ... x:.num@ y:.num@ + ... )

Cautions and Gotchas

Final provides comprehensive nesting, semantic, and closing checking on block control structures inside Colon words. But in order to retain the flexibility of interactive as well as compiled operation of Paren operators, Final does almost no static checking of the nesting/closing rules of the Paren operators. Therefore, it is incumbent on the developer or agent to take special care in use of the operators.

In general, Final doesn’t care how or how much you mutate DS during the build, as long as you do not drop any values that were on DS after the opening operator. Doing so will have undefined effects, and will likely result in a a stack fault. eg.

// ( val:a -- ? ) will likely fault
( drop ... )

The operators only work on DS items added after the opening operator; they do not include any values already on DS. If you want to include eg. DS.tos, you could do this:

// ( myVal:a -- myVal:a l:List )
( peek ... )

If you wanted the top 2 values, in order you could do this:

// ( val0:a val1:a -- val0:a val1:a l:List )
( over over  ... )

Any more than that, requires moving eg. to an aux stack.

Strings

The Quick Tour already introduced String: immutable Utf-8 text, ASCII-7 as a proper subset, and the caution that str::len is a byte length, not a character count. Literals (quoted, raw, and rune ticks) are covered under Interpreter. Comparison of two Strings uses Utf-8 byte ordering (Basic Operators).

This section is the day-to-day API for working with text:

A few design points that shape every API below:

• Immutability — every str:: “mutation” returns a new String; the inputs are unchanged.
• Stack operators, not instance methods — text helpers are the str::… words (same family style as other axiom groups). Park a String on ts only when you need several rooted object ops around it; for pure string transforms, keep values on DS.
• No byte-indexed substring — cutting at an arbitrary byte offset can split a multi-byte character. Build pieces with StringBuilder, use str::indexOf /str::sub / str::split, or iterate runes (this section and TextReader).
• Truthy — "" is false; any non-empty String is true (Basic Types).

For line-oriented or file-backed text, prefer Text and Byte Streams. For pattern matching, see Regex (later in the survey).

Unicode and Utf-8

Final stores every String as a sequence of Utf-8 bytes. A Rune (documented under Basic Types as an Int synonym) is a Unicode code point — the abstract character value — not a byte. One Rune encodes as one to four Utf-8 bytes.

You already know that ASCII-7 is a proper subset of Utf-8: English source, Json keys, and HTML tags that stay in ASCII look identical as bytes whether you call them “ASCII” or “Utf-8.” Final source itself is Utf-8; old DOS/Windows “code pages” are not accepted (Interpreter).

How the encoding works

Utf-8 uses the high bits of each byte to mark where characters start and how long they are:

Examples:

• 'A' → one byte 0x41
• 'é' (U+00E9) → two bytes 0xC3 0xA9
• '日' (U+65E5) → three bytes
• '🙂' (U+1F642) → four bytes

Only the shortest encoding of a code point is legal. Overlong forms (for example encoding ASCII as a two-byte sequence) are invalid. That rule is part of what keeps the encoding unambiguous.

Qualities that matter in practice

These properties are why Final (like Go) can treat Utf-8 as the everyday string encoding without a large runtime tax.

Deterministic find; no ambiguous overlaps

Because ASCII bytes never appear inside a multi-byte sequence, a search for an ASCII needle — "/", ".fnl", "\n", a Json delimiter — cannot false-match in the middle of an emoji or accented letter. str::startsWith, str::endsWith, str::indexOf, and str::split are byte scans that stay boundary-safe when the probe itself is well-formed Utf-8 (including plain ASCII).

The same bit pattern that marks continuation bytes (10xxxxxx) also makes Utf-8 self-synchronizing: from a random offset you can walk forward to the next start byte without restarting from the beginning of the string. That is the engineering reason “find” and “split on ASCII” stay simple and reliable.

ASCII-majority text stays fast

Most Final programs spend their time on source text, paths, protocol tokens, and similar ASCII-heavy material. For those, length checks, concatenation, prefix/suffix tests, and splits are ordinary byte operations — the same cost model as a classic C string, without a hidden per-character decode on every call.

You pay for decoding when you ask for characters: foreach over a String, TextReader.getNextRune, or converting with r>s before $ / $$. That cost is linear in the text you walk, and for ASCII the decoder’s fast path is essentially “one byte → one rune.”

Kernighan and Donovan’s The Go Programming Language walks through this model in detail (strings as bytes, range/decode for runes, and why indexing by “character” is the wrong default). The short version for Final users: Utf-8 is not a tax on every string op; it is a compact encoding with a clear, cheap ASCII fast path and an explicit decode step when you need code points.

What “length” means

Because multi-byte Runes exist, str::len and the rune count are different whenever the text leaves ASCII. That is expected, not a bug.

Safety model (short)

Next: the concrete String Operators.

String Operators

All everyday String helpers are str:: stack operators. They take String operands on DS and leave results on DS. Non-String inputs panic at runtime.

Operands are never modified in place: “mutating” words return a new String.

Type list-string and then eg help str::len (and friends) in the UI for the operator description an stack effects.

Inquiry

"hello" str::len $ nl          // 5
"é" str::len $ nl              // 2  (one rune, two bytes)
"" str::isEmpty $ nl           // true

Empty String is also false under Truthiness, so str::isEmpty and a bare if on the string agree for control flow — prefer str::isEmpty when you want the intent obvious.

Trim

Whitespace follows Unicode space classes (not only ASCII ' ').

"  x.fnl  " str::trim ".fnl" str::endsWith $ nl    // true

Case

Applies Unicode casing rules (not ASCII-only).

"Hello" str::toLower $ nl    // hello
"αβγ" str::toUpper $ nl      // ΑΒΓ

Substitution

Returns a new String. If find is absent, the result equals str. Substitution is exact string match (not Regex).

"banana" "a" "o" str::sub $ nl    // bonono
"foo" "x" "y" str::sub $ nl       // foo
"aa" "a" "aa" str::sub $ nl       // aaaa

For pattern-based replace, see Regex.

Concatenation

"hello" " " str::+ "world" str::+ $ nl    // hello world

For a few pieces, str::+ is fine. For building a large result in a loop, use StringBuilder instead of repeated str::+ (each concat allocates a fresh String).

Prefix / suffix / find

"internal/final/core/0046-parse.fnl" >ts
t:peek "internal/" str::startsWith $ nl     // true
t:peek ".fnl" str::endsWith $ nl            // true
t:peek "/" str::indexOf $ nl                // 8
t:drop

"banana" "an" str::contains $ nl             // true
"banana" "xy" str::contains $ nl             // false

Split and join

str::split and str::join round-trip cleanly with StringList. str::join also accepts a List whose every element is a String (non-String items panic).

"a,b,c" "," str::split >ts
t:peek foreach
  i $ sp
/foreach
nl
"," t:peek str::join $ nl    // a,b,c
t:drop

"alpha\nbeta\n" str::splitLines >ts
t:.len@ $ nl                  // 2
0 t:@() $ nl                  // alpha
1 t:@() $ nl                  // beta
t:drop

Notes on str::splitLines:

• The empty String yields an empty StringList (not a single empty line).
• A final \n does not create an extra empty trailing line.
• Only \n is the separator; a lone \r is left in the line text (CRLF files are usually normalized by TextReader.readLine, which strips a trailing \r).

Patterns you will see in core

Error messages and path checks often chain concat and probes without parking:

"WARNING: word not found: " "compileFromFile" str::+ $ nl

"notes.fnl" ".fnl" str::endsWith not if
  "expected a .fnl path" $ nl
then

When the next step is list processing (sort, foreach, Json), keep the StringList from str::split / str::splitLines on ts and use the List API.

Next: Iterating Runes when you need code points rather than bytes.

Iterating Runes

A Rune is a Unicode code point carried as an Int (Basic Types). To walk the characters of a String — not its raw bytes — put the String on DS and use foreach … /foreach. The loop variable i is each successive Rune.

You already met foreach for lists and maps in Iterators: foreach. String participates in the same protocol: foreach obtains a fresh rune iterator and drives the loop until the text is exhausted.

"aé🙂日" foreach
  i r>s $ sp
/foreach
nl
// prints: a é 🙂 日

Print a single Rune with r>s $ (r>s is ( rune:i -- s ); $ prints the String). Ordinary $ on an Int prints the decimal code point, which is rarely what you want for text. Inside a fmt string, use %c with the Int code point instead of converting first.

TextReader is also iterable by rune (Stream Types). Prefer foreach on a String when the text is already in memory; prefer a reader when the source is a file or you want line APIs as well.

Byte length vs rune count

: runeCount ( s:String -- n:i )
  0 swap
  foreach
    drop
    1 +
  /foreach
;

"é" dup str::len $ sp    // 2
runeCount $ nl           // 1

That gap is exactly the Utf-8 story from Unicode and Utf-8: str::len is storage; foreach is characters.

Example: source file rune census

This small program reads a Utf-8 source file into a String, walks every Rune, and prints a compact summary: how many code points, how the Utf-8 widths break down, and which non-ASCII characters appear. It is a handy sanity check when a file “looks fine” in an editor but something downstream complains about encoding — and it shows foreach, str::len, and StringBuilder working together.

: utf8Width ( r:i -- n:i )
  dup 0x80 < if
    drop 1
  else
    dup 0x800 < if
      drop 2
    else
      0x10000 < if
        3
      else
        4
      then
    then
  then
;

: readFileString ( path:s -- s:String true | err:s false )
  TextReader.newFromFile?^ not if
    false
  else
    >ts
    StringBuilder.new^ >xs
    t:peek foreach
      i x:.writeRune^
    /foreach
    t:.close^
    t:drop
    x:.toString^
    x:drop
    true
  then
;

: printRuneCensus ( path:s -- )
  dup >ys
  readFileString not if
    "cannot read: " y:peek str::+ $ nl
    "  " swap str::+ $ nl
    y:drop
  else
    >xs
    newdo >ts
    0 t:.runes!
    0 t:.w1!
    0 t:.w2!
    0 t:.w3!
    0 t:.w4!
    StringBuilder.new^ >zs
    x:peek foreach
      t:.runes@ 1 + t:.runes!
      i utf8Width
      switch
        a 1 == case
          t:.w1@ 1 + t:.w1!
        /case
        a 2 == case
          t:.w2@ 1 + t:.w2!
        /case
        a 3 == case
          t:.w3@ 1 + t:.w3!
        /case
        default
          t:.w4@ 1 + t:.w4!
        /default
      /switch
      i 0x80 >= if
        i z:.writeRune^
        32 z:.writeRune^
      then
    /foreach
    "File: " y:peek str::+ $ nl
    "  bytes (str::len): " x:peek str::len "%d" fmt str::+ $ nl
    "  runes:            " t:.runes@ "%d" fmt str::+ $ nl
    "  utf-8 widths:     " $
      t:.w1@ "%d×1 " fmt $
      t:.w2@ "%d×2 " fmt $
      t:.w3@ "%d×3 " fmt $
      t:.w4@ "%d×4" fmt $ nl
    "  non-ASCII runes:  " $
    z:.toString^ dup str::isEmpty if
      drop "(none)" $ nl
    else
      $ nl
    then
    z:drop
    t:drop
    x:drop
    y:drop
  then
;

"examples/stringRune-iter.fnl" printRuneCensus

Sample shape of the report (counts depend on the file):

File: examples/stringRune-iter.fnl
  bytes (str::len): 218
  runes:            210
  utf-8 widths:     204×1 2×2 0×3 4×4
  non-ASCII runes:  é 🙂 日

The interesting lines are the ones where bytes ≠ runes and the width histogram is not “all ×1”: that is Utf-8 doing its job, and foreach making the character stream easy to measure without hand-rolled decoding.

Next: StringBuilder for the mutable side of building text.

StringBuilder

StringBuilder is the mutable partner to immutable String. Append runes, strings, or lines as you go, then take a snapshot with toString. Use it when a loop would otherwise call str::+ over and over (each concat allocates a new String).

You already saw a short builder example under Methods and the stream-shaped write members under String Streams. This page is the full API.

Park the builder on ts (or another aux stack) for a session of writes, then t:drop — same nesting style as other objects (Writing Clean Final Code).

Factories

StringBuilder.new^
"  " StringBuilder.newWithPretty^

Pretty builders are aimed at structured renderers (for example Json). For ordinary path joins, messages, and file assembly, plain new is enough.

Properties

Write and snapshot

StringBuilder.new^ >ts
"hello" t:.writeString^
32 t:.writeRune^
"world" t:.writeLine^
t:.toString^ $              // hello world\n
t:drop

toString does not clear the builder; further writes keep appending. Build a fresh StringBuilder when you want a clean buffer.

Pretty / nesting helpers

Only meaningful when pretty is true (newWithPretty). Plain builders treat the pretty writes as ordinary writes (or no-ops where noted).

"  " StringBuilder.newWithPretty^ >ts
"{" t:.writeString^
t:.writeWhitespacePretty^
t:.nest^
"\"name\"" t:.writeStringPretty^
t:.writeSpacePretty^
":" t:.writeString^
t:.writeSpacePretty^
"\"Ada\"" t:.writeString^
t:.unnest^
t:.writeWhitespacePretty^
"}" t:.writeString^
t:.toString^ $ nl
t:drop

Typical pretty output:

{
  "name" : "Ada"
}

When to choose what

Strings remain Utf-8 end to end: every writeRune encodes a code point; toString yields a normal immutable String ready for str:: operators or $.

Using a StringBuilder as a TextWrite value

StringBuilder implements the TextWrite interface. This means you can supply a StringBuilder to contexts that accept a TextWrite, such as when you want to capture the stdout/stderr of a Pip (thread); or in Http bodies expecting a TextWrite Stream.

DateTime and Interval

The Quick Tour deferred these two basic types here. DateTime is a calendar date and/or clock time; Interval is a length of time (a duration). Both are immutable sealed values.

They are not part of the numeric family. Ordinary + - * / and compares do not apply — use the dt:: family below. Invalid operand pairs panic.

Related material already covered elsewhere:

• $ can print a DateTime (stdin/out Streams).
• Json rendering emits DateTime as an RFC 3339 string (Json Rendering).
• Pattern formatting for DateTime and Interval is covered in Formatting with dt::fmt below; general % message formatting is in Output Formatting.

Type list-datetime for all the DateTime/Interval related words, then e.g. help DateTime, help Interval, help dt::+, or help dt::fmt in the UI for the detailed documentation and stack effects.

DateTime

Factories create values in UTC. DateTime.now returns UTC as well (the current instant).

Construction takes a List of Int components — typically written with ( … ) — rather than a long stack of loose numbers.

( 2026 7 4 ) DateTime.newDate^ $ nl
( 14 30 0 ) DateTime.newTime^ $ nl
( 2026 7 4 14 30 0 250 ) DateTime.newDateTime^ $ nl
DateTime.now^ $ nl

Park a DateTime on ts when you need several property reads:

DateTime.now^ >ts
t:.year@ $ sp t:.month@ $ sp t:.day@ $ nl
t:drop

Interval

An Interval is a duration. Build one from unit class constants (then scale with dt::*), or from a List of clock-length components.

Interval.second $ nl
5 Interval.second dt::* $ nl          // 5s
5 Interval.second dt::* .milliseconds@ $ nl  // 5000
( 1 30 0 ) Interval.newInterval^ $ nl // 1h30m0s
( 0 0 5 500 ) Interval.newInterval^ $ nl

Unit constants are class properties (same style as Math.pi / Int.maxInt — see Properties).

dt:: operators

All take operands on DS. Same-kind compares only (two DateTimes, or two Intervals). Mixed kinds and unsupported arithmetic pairs panic.

Formatting with dt::fmt

$ prints a DateTime or Interval’s natural string. For a composed layout — ISO, a prose date, a stopwatch clock — use dt::fmt with a pattern String.

dt::fmt  // ( val:DateTime|Interval  fmt:s -- result:s )

• One word for both types; the lexicon is chosen from val’s type.
• fmt is always a pattern String (or a class constant that holds one). Wrong tokens for that type panic.
• Patterns use letter-run codes familiar from app languages (yyyy-MM-dd, HH:mm:ss).

DateTime.now^ "yyyy-MM-ddTHH:mm:ss.sssZ" dt::fmt $ nl
DateTime.now^ DateTime.iso dt::fmt $ nl
5 Interval.minute dt::* "HH:mm:ss" dt::fmt $ nl
Interval.second Interval.clock dt::fmt $ nl    // 00:00:01

General message formatting (fmt / %d / %s) is separate — see Output Formatting.

DateTime patterns

Case-sensitive. MM ≠ mm; HH ≠ hh; a ≠ A. Values are formatted in UTC.

Hours / meridiem: hh does not add AM/PM by itself — include a or A when you want it.

Fractional seconds: after ss, an optional . plus a run of s sets the digit width (ss.sss = milliseconds, up to nine s for nanoseconds). A . elsewhere in the pattern is a literal.

Literals (no quotes needed): space, T, Z, and usual separators (-, :, /, ,).
Z is the letter Z (UTC designator in ISO-style patterns), not a computed offset.

Quoted literals: wrap text in '…' when you need a letter or . that would otherwise be a token (e.g. ss'.' for a literal dot after seconds with no fraction). '' inside quotes is a single '.

DateTime.now^ "EEEE, MMMM d, yyyy" dt::fmt $ nl
DateTime.now^ "hh:mm A" dt::fmt $ nl
DateTime.now^ "yyyy-MM-ddTHH:mm:ss.sssZ" dt::fmt $ nl

DateTime format constants

Class properties (same style as Math.pi) — each pushes a pattern String:

DateTime.now^ DateTime.iso dt::fmt $ nl
DateTime.now^ DateTime.longDate dt::fmt $ nl

Interval patterns

Case-insensitive (the runtime lowercases the pattern before parsing). You may write HH or hh — same meaning. No meridiem, no calendar month/year names, no weekday tokens.

Cascade: only units that appear in the pattern participate. Among those, the largest unit absorbs overflow; smaller units are remainders. Absent units are not filled in silently.

Sign:

• Format the absolute duration with the numeric fields.
• If the pattern contains +, emit space when val ≥ 0, - when val < 0, at that position.
• If there is no + and the value is negative, prefix a single -.
• Zero is non-negative → space when + is present.

( 1 30 0 ) Interval.newInterval^ "hh:mm:ss" dt::fmt $ nl     // 01:30:00
50 Interval.hour dt::* "d hh:mm" dt::fmt $ nl                // 2 02:00
50 Interval.hour dt::* "dd hh:mm" dt::fmt $ nl               //  2 02:00
1250 Interval.millisecond dt::* "ss.sss" dt::fmt $ nl        // 01.250

// negative: leading - when no + in pattern
5 Interval.hour dt::* -1 dt::* "d hh:mm:ss" dt::fmt $ nl     // -0 05:00:00
5 Interval.hour dt::* -1 dt::* "+d hh:mm:ss" dt::fmt $ nl    // -0 05:00:00

Interval format constants

( 1 30 0 ) Interval.newInterval^ Interval.clock dt::fmt $ nl
50 Interval.hour dt::* Interval.daysClock dt::fmt $ nl

Token overlap

The same letters appear in both lexicons with different meanings (hh is 12-hour on a DateTime, hours-of-duration on an Interval). val’s type selects which table applies. Do not pass a DateTime ISO pattern to an Interval (or the reverse).

Examples

Elapsed time

Capture a start instant, do work, then subtract with dt::-. From a parked start, .since^ is the same idea (elapsed until now):

DateTime.now^ >ts
// … work …
DateTime.now^ ts> dt::- $ nl    // elapsed Interval

Deadline from now

Advance the current instant by a duration, then compare:

DateTime.now^
5 Interval.minute dt::* dt::+ >ts   // deadline = now + 5m

DateTime.now^ t:peek dt::< $ nl     // true while still before deadline
t:drop

Average of several Intervals

Scale and divide with dt::* / dt::/ (metrics-style averaging):

( 0 0 10 ) Interval.newInterval^    // 10s
( 0 0 20 ) Interval.newInterval^    // 20s
dt::+
2 dt::/ $ nl                        // 15s

Notes

• Immutability — dt::+ / dt::- and friends return new values; inputs are unchanged.
• No DateTime + DateTime — elapsed time is dt::- (later minus earlier), not addition.
• Printing — $ uses the DateTime natural string (ISO-style for full dates; clock-only for newTime values). Interval prints in a compact duration form (e.g. 1h30m0s). For controlled layouts, use dt::fmt and the pattern tables above.
• Json — only DateTime participates in >json / json> as a string; see Json.

Word- and Pip-local variables

Final provides the ability to define named variables within a word, called local or l variables, and in the context of a single Pip (thread), called pip-local or pls variables. The two have different use cases, but operate almost indentically, so we cover both here.

Word-local variables via l

Word-local variables are helpful in cases where a certain value, sometimes a flag, wants to be available to all words at all block nesting depths within a word. Maintaining such a control variable will typically require dedicating a stack to it, and modifying it requires pops/drops/repushes. They are also useful generally, as a way to provide named access to local values, rather than trying put them on auxiliary stacks, and then try to remember which stack holds which value. A more convenient alternative is a local variable, accessed via the keyword l.

l accesses a DynamicObject that is just-in-time instantiated when you first access l. The usual pattern is to initialize your variable or variables on entry to the word, and then query or mutate as needed within the word. The compiler provides special support for l by enabling you to just type eg. false l.myFlag! then l.myFlag@ to access it anywhere in the word.

Pip-local storage via pls

Pip-local storage works almost identically to Word-local variables, except the scope of visibility and lifetime are that of the Pip, not a word. For the root Pip, they thus function much like a global variable such as var: . This feature should be used sparingly.

Since the visibility of pls is the entire Pip, and any words that run in it, you should take care to use a top-level field unlikely to be used by or conflict with other words. Consider adding a “namespace” prefix to your field names.

You access Pip-local storage in a similar way as locals, by using the pls. keyword.

Here is an example of moving the Pip Params object onto pls for availability to all words in your Pip:

/*
Launch word of the Pip.
Move pp to pls for Pip-global access.
( pp:PipParams -- )
*/
: myPip
  pls.pp!
  // remaining init logic
;

Events and the EventLoop

Under the hood, both final and final-gui use what is called an Event-driven paradigm. When you enter text in the prompt, or load a file, project, or module, the operation is dispatched via an Event sent to Final’s core EventLoop.

An event-driven architecture provides benefits that a conventional procedure-driven architecture cannot, and can greatly simplify designs for such as simulations and games, low-level Pi 5 controller programs, and Graphical User Interfaces. All those topics are covered in later chapters, but it is a good idea to get a grounding in this foundation now.

Events

An event is an occurence such as a key press, mouse movement, regular ticker notification, or single-shot timer firing. Event-driven programs operate quite differently from procedure-driven programs. Look at this startup code for Shape Zombies:

: shape-zombies
  CircZomb.new^  >zs
  z:.base >ys // the SimGame base type
  y:.init^
  y:.makeUi^
  y:.startPaused^
  y:.doRender^
  y:[email protected]^
  ydrop zdrop
;

Notice that there is no call to a main processing routine–the code shows the main window of the game, then exits. The reason is because the actual program is distributed across a variety of event handlers, which are methods that are called by the system when their corresponding event occurs. Here is the handleKeyDown event; this gets called when you press a key (a separate event happens when the key is released)

/*
KeyDown event handler.
Attached to Window.KeyDown events
( ke:KeyEvent -- ) o( inst )
*/
: CircZomb#handleKeyDown
  CircZomb_onKeyDown
;

You can see that the handler routine is passed something called a KeyEvent, which has the name of the key that was pressed. The handler code in onKeyDown then looks for the arrow keys, and if so, moves the position of the user hexagon.

EventLoop

The Final EventLoop is written in Final; it listens on a Pipe for a new event, and when one arrives, dispatches it to the registered handler.

Note that if you block the main thread by executing a continous loop, or call delayMs with lengthy delays, event processing will stall. For this reason, time-based occurrences are best handled with Timer Events (covered next).

The EventLoop is the most fundamental piece of code in final / final-gui – if you do a stack dump with *$ you can see it sitting on the bottom of the O Stack, since it persists for the entire life of the program.

Events can originate from many sources, and do not have to come from the main thread. UI Events come from its UI thread, which is the application main thread. MotionHit events in SimGame originate on the MotionHitEngine background thread. Timer and Ticker events come from a dedicated thread. But they all get dispatched in the main Pip/thread of your program. (Only the main thread has an EventLoop; Pips cannot use event handlers, but they can send events.)

The Final UI itself is event-based, and uses an event to handle prompts sent from the main window.

Event-based Programming

Note that you are not required to write your Final programs using an event-driven approach, unless you want to use features such as Ticker/Timer events, the Fyne UI, the SimGame framework, or Pi controllers.

Event-base programming is a different paradigm than a single procedural program, but it doesn’t take much to get used to it. It is highly beneficial in many ways, because rather than one huge omnibus program with giant switch statements and interminable numbers of sub-words, each event handler in eg the SimGame framework is dedicated to handling just one specific kind of occurence. The code there can remain focused and simple. Look at the event. Determine what to do (if anything). Do it. End.

Examples

EventTicker and EventTimer Events

see: examples/events/ticker-timer-demo.fnl

This demo will run on both versions of Final.

It shows how to:

• create a TypedObject to handle events
• write the handleTicker and Timer events
• create the Ticker and Timer, attaching to the handlers
• start the timers
• handle the timer events

EventAgain (no-delay re-arm)

When a controller should run as fast as it can but still yield to the EventLoop (Esc, GPIO, UI), use EventAgain instead of a zero-interval ticker or a forever poll loop.

• EventAgain.new^ binds a handler; nothing fires until .again^.
• Call .again^ once from #init to kick, and again at the end of the handler to re-arm.
• .close^ stops further re-arms (typical Esc / shutdown path).

see: examples/pi/i2c-ssd1306-life.fnl

SimGame Events

This is an advanced look at handling events in the SimGame Framework. This program only runs in final-gui.

examples/gui/simgame/invaders.fnl

Have a look at the various events in Invaders to get a feel for the paradigm. Most event handlers are named handle<EventName> such as handleRender for drawing, or handleUpdate for the periodic update event you can enable, or handleMouseMove for mouse movements.

Error and Structered Exception Handling (SEH)

Sometimes, processing cannot continue because some form of error has arisen. Sometimes these are developer-caused, such as integral divide by zero, or passing an incompatible type to an operator or method. Other times it can relate to unexpected service failures, such as a database or web call timeout. And other times it is caused by external input, not under the developer’s control, that is nevertheless needed to continue. An example is missing or invalid input data, such as an invalid JSON string.

Final has three (well… two and a half…) ways in which it can deal with errors:

• panic, which is used by axioms or other runtime code
• in Final, an error call, which uses panic under the hood
• an exception, via the throw word

Of the three, panic (and thus error) is the nuclear option. When a panic occurs, the runtime does the following:

• if it occurs in a child Pip, it will virally cause all child Pips of the Session to end
• if in the main Session Pip, or propagated up from a child Pip, the main Pip is reset via a “Warm Boot”. The stacks are cleared, and the interpreter is then invoked and entered as if from a new Session (the Dictionary remains intact however.)

Final’s philosophy is to panic or error in any situation that could have been prevented; basically all situations of programmer error, such as requesting integral division by zero, or passing a number to a routine that required a String.

In situations involving non-preventable errors, particular those arising from external inputs, Final uses the throw statement, which is an error that you can trap by way of a try/catch block in your code. throw is particularly useful in deeply nested code, in which trying to carry some kind of termination flag, along with the extra code at every level also testing for this flag, results in overly complex code that intermixes normal processing with tests for the error state. A good example is JSON parsing, which can be deeply recursively nested as it processes arrays and objects within outer arrays or objects, or which can encounter an unexpected end of stream before parsing is complete. Final’s json> operator uses the throw statement in many places, when it encounters invalid input, or unexpected end of stream.

You can use throw in your own code, instead of error when you want to be able to trap the error at a higher level, and can recover without causing the nuclear option.

To catch Exceptions, you use the try/catch block as follows; finally is optional, and will be explained below:

try
// words that might throw
catch // ( -- errmsg:s )
// your exception handling logic
finally // optional
// code that will always execute
/try

try signifies the beginning of an exception handling block. try blocks can be nested, both within the same word, as well as being nested by way of outer or inner words that may also have try blocks. In normal processing, the code between try and catch executes; the catch clause is skipped over, and if present, the finally clause executes.

If a word inside the try block, or any word it invokes, throws an exception via throw, then the following happens:

• the returns from every nested word are popped off of RS, to get the VM cleanly back up to the nesting level of the try block
• the data stack and all auxilliary stacks have their content restored to what it was at the entry to try
• the code in the try block stops executing
• the code in the catch block executes
• if the catch block does not then throw its own exception, the finally clause, if present, executes
• normal execution then resumes after the /try statement

If a throw occurs in runtime code, and there is no try block active at that time, the situation is handled just like panic.

How to use (and not use) exceptions and handlers

When to use throw

Use throw for unexpected error conditions, typically those cause by invalid externally supplied data, over which you had no control. It is especially indicated in operations involving multiple steps, or that may become deeply nested.

Document in a word that has throw, and outer words that invoke it, that it throws. That provides some guidance that an exception handling block when invoking that operation may be helpful.

Don’t use throw…

• as a new “short-circuit” channel for communicating results; throw is about exceptional error situations, not normal processing situations.
• as a replacement for having clear, sensible, understandable input requirements; there is not much point in using throw for programmer error; that deserves an error (or implicit runtime panic)

When to use try/catch

Don’t think you need to include a try block just because something you are calling can throw; the question you need to ask, is whether there is anything reasonable you can do at the point. In many cases there may be, such as sending an error result on a result pipe, or returning a modal false result to a caller. But if there is nothing you can do, just let the exception continue up the chain, where something else might catch it, or in the worst case, the system will have to treat it as a panic.

Important Caveats and Limitations

SEH in a stack-based language is not as deterministic as in a procedural language. If your try block either consumes values from any stacks, or in normal execution leaves new or altered values on any stack, then this will likely NOT be the case if execution falls through to after /try. Therefore, you should base your handling logic on this fact.

Typically, you might want your try block to span your entire word, or at least be the last code in the word. If your word follows a modal ( ? – result true | false ) pattern, your catch block can drop any input values on eg. DS that were restored by the handler, then push a false and fall thru.

As with all languages that support SEH, the side effects caused by intermediate words of your normal chain are in an indefinite state from your viewpoint, since you may not know how much executed prior to the throw.

Writing Clean Final Code

Stack-based languages like Final have unique beneficial qualities, but also come with hazards and potential pitfalls.

Because Final uses stacks and stack manipulation operators, it is missing the symbolic anchors of the named parameters of procedural languages. And due to these stack manipulations, it is also fairly easy to create defective code, that does these potential things:

• underflow a stack: use or discard a value under the intended current context;
• leak values on a stack, failing to drop a no-longer needed value;
• confuse the order of operands;
• mistake a stack value for something it isn’t.

Use Local Variables

The best way to avoid stack confusion and bugs is to use local variables. A local variable provides a simple mnemonic way to refer to parameters or subparameters, without having to remember what is currently on each stack.

Follow these guidelines

• consider moving stack-provided parameters to local variables, unless they are consumed only once;
• if the method is an object method, consider pulling fields you will access repeatedly from your o: instance and put them in a local;
• you don’t have to define all your locals at the top, it can be clearer to define them “just in time” ahead of the code that needs them;
• if your subwords also access locals, you might consider defining those in a preliminary init subword, so they are defined when reading the the subword code. (Note: locals are resolved when used, and do not need to be lexically defined prior to use, so subwords are allowed to use locals that are only defined later in the file, either by other subwords, or the main word code.)

Factor!

Final enables you to factor your code in two ways:

• by defining conventional Final words, and delegating work to them;
• using a subword within a word.

Break long stretches of code, that has identifiable stages, into either subwords or another colon word.

“Clean coding” for procedural languages also recommends factoring larger procedures into small ones to which the main procedure delegates. But this often entails a fair bit of runtime overhead, insofar as you typically need to pass in a variety of parameters from the parent context to the delegate. At runtime, this is not cheap, since the runtime has to create new stack frames, copy parameter values, and so on.

Final by contrast enables much lower overhead factoring, especially for subwords. Since the values needed for an operation are already on the stacks, or also in locals for subwords, factoring is mostly a process of subdividing the work, and naming it clearly.

Factoring also lets you successively simplify your stack contexts, to narrow the values to just what a single step requires. This makes the factored code much easier to reason about, and to get correct.

General Guidelines

Benchmarking has demonstrated that Final code runs very efficiently on modern CPUs. Because Final has a limited quantity of underlying machine code, its machine code tends to stay hot in local CPU caches, which provides a comfortable cushion to write the safest, most understandable code, not worrying about saving an operation here and there.

Another example, is code that moves an object to eg TS, for receiver operations, and that will need to be dropped at the end. Sometimes these operations have a pattern like:

// ( obj:a -- )
>ts
  t:peek /...
  t:peek /...
  // last operations, which do i choose?
  ts> / ...
  // or:
  t:peek
t:drop

You can save one instruction by moving the value on ts to ds on the last operation. But writing the code like the second example makes all stanzas identical, thus easy to reason about, and dropping ts.tos is an explicit end step, closing the >ts. The second is the far better form, because it makes every stanza identical, thus the reader (which will be you!) sees that every stanza does the same thing, that the last stanza is not some exception to the workflow, and the stack hygiene is separated from the logic of the operations.

In the last example, I also demonstrated a helpful convention, which is, where possible, to nest code relating to the content of an auxilliary stack, opening and closing with the value going on then off the stack. This provides clear visual highlighting that all the nested code is working from the same value on eg ts.

Final Programming Conventions

Object operations that return a value, such as property reads, list item read, etc. do so on ds. If you start an attempted sequence of such operations against a single object, such as reading several properties to perform a check or perform an operation, you immediately hit a problem if you start with the object on ds. After the first read, the result is now ds.tos, so the instance is no longer available for the next operation. Rather than engaging in interminable ds juggling, which gets ever-more complex the more values you need to read, you should move the object to another stack, and root your operations there.

Rooted compound object operations always preserve the root object, so you never have to manually dup before a rooted operation. This makes the auxilliary stacks more convenient, and understable (writing and reading code).

Here are the stack usage guidelines that Final code follows, and that are suggested for user code as well. These guidelines suggest when and how to user auxilliary stacks, and how to make the choice of which stacks to use, and in what order. It should be noted that correct code operation does NOT depend on following these guidelines; all legal code that references the correct objects for its implementation will work; the guidelines just help provide semantic structure and familiarity of patterns.

Do continue to follow the Forth-like pattern of accepting the input parameters on ds, and placing the output parameters on ds as well, consuming the input parameters.

Modal Result-shape Operations

For operations that either can return a result or not, depending on factors determined by that operation, provide two return effects:

• when the operation succeeds: ( ? – result true)
• when the operation could not provide the result: ( ? – false ) This pattern lets the consumer code be structured naturally, with a single test, whose false branch (not if) doesn’t try to use the non-existent result, but whose true branch consumes the result.
• you typically mark this pattern by using ? affix in the name

If the result is truthy when it succeeds, but falsey when it doesn’t, you can use this abbreviated pattern, along with ?dup that only duplicates a truthy result. This is suitable for a result that is an Int or String, where 0 or “” signal failure, but <>0 or <>“” signal success:

• when operation succeeds or fails, return the truthy or falsey result: ( ? – result ) then you use code like this:

operation ?dup if
  // use the result, it was duped
else
  // no value to drop
then

For operations that don’t produce a result, but need to signal an ok or an error, it is suggested to use the following pattern:

• when it succeeds: ( ? – true );
• when it fails: ( ? – err false ).

You can use the nif variant of if in these situations

operation nif
  ( err )
  // handle error
then

Auxilliary Stack usage Conventions

Although all auxilliary stacks are identical in operation, by convention, ts is thought of as being the “Temp Stack”, and xyz as “parking” stacks.

So ts is your first goto for a short sequence of operations that will typically only involve a single object operand. For example:

// MyObj
//   .prefix
//   .name
//   .affix

: printFullName ( inst:o -- )
  >ts
  ( t:.prefix@ t:.name@ t:.affix@ )
  "%s%s%s" fmt $
  t:drop

Sometimes an operation may be a bit more complex, and involve one or more input operands, and then the fetching of materializing of one or more objects in its code. While it is always desirable to factor Final operations for the goals of readability, testability, or reusability, such factoring can itself involve careful design of the factor word, plus dealing with the potential problems of use by other code, which turns the factor word from an internal-intended part of the parent word into a public artifact, which could cause client use of the word to break if the parent word itself needs to refactor the api or semantics of the factor word. (A planned feature of nested words and local-only namespacing will help, when that lands.)

Other scenarios involve a top-level word used to perform some operation using one or more operand words, one or more internally sourced or materialized words, and output results.

All these types of words benefit from continuing to use ts for localized operations, with a beginning-middle-end, and then x y and z in a loose priority order, depending on need.

Auxiliary Stack Usage Heuristic

The basic heuristic, as mentioned, not enforced in any way, is to use the three stacks in reverse order of permanence or importance. So operations then dealing with a second object whose lifetime is longer than the use of ts, can use xs. A lifetime longer than xs can use ys. Etc.

In a situation where the top operation word is using or producing more than one word, and you want to keep those parked stably as you dispatch lower-level operations, you can follow a convention wherein input or source words are in order: xs, ys, zs; and outputs under construction parked in reverse order zs ys xs. Obviously this breaks down for more that three primary words, but rather than engaging in our unfriendly stack juggling, Final offers convenient help with Dynamic Objects.

If you are dealing with more state on input or output than you can reasonably juggle on txyz, you can easily create a DynamicObject to encapsulate the related items in a single object, which is then what you deal with, rather than disparate individual objects. This is also helpful to limit the number of parameters that need to be supplied on ds to an operation, or that are returned.

Word Doc Guidelines

The Quick Tour introduced context effects: a short comment that describes what a word expects on the stacks and what it leaves. This page is the full convention for writing those docs — the format the compiler stores, how help shows them, and how to document Type members (including your own TypedObject types).

Everyday API pages already point you at help for the same text (help +, help Regex#find, help DateTime, …). Good docs make that useful.

Recommended comment form

Prefer a block comment with /* and */ each on their own line, and the body flush left (no indent inside the block):

/*
Add two numbers, and return the sum.
( a:n b:n -- c:n )
*/
: + ...

That is the form used throughout Final’s own core docs (for example + in the basic-ops doc file). Single-line // … comments also work for a one-liner, but the block form is clearer once you have more than a sentence.

Place the comment immediately before the word it documents (the colon definition, or a :doc line — see below). The compiler takes that last comment and stores it on the dictionary entry’s .doc property. Typing help wordname in the UI prints that text.

What to write

Keep three layers, in order:

1. Opening sentence — one complete sentence that states the purpose of the word. Lead with the verb or outcome (“Add…”, “True if…”, “Create a new empty…”). Don’t repeat the word name.
2. Additional detail — more complete sentences only when needed (panics, modal results, related words, nesting rules). Prefer short lines; skip anything the effect line already says.
3. Last line — the context / stack effect. Put nothing after it inside the comment.

Be succinct. Help text is read in the UI; long essays belong in these intro pages, not in .doc.

Good pattern

/*
Divide a by b and return the result.
Panics on divide by zero for integral types.
Returns Float.Inf for Float divide by zero.
( a:n b:n -- c:n )
*/

Modal results

When a word uses the success/failure shapes from Writing Clean Final Code, spell both arms on the effect line:

/*
First match substring in s, or false if none. Modal.
A successful empty match is "" true (not false).
( s -- found:s true | false )
*/

Follow the same pattern if the word accepts a modal result.

Auxilliary stacks and the Object Stack

Bare ( … -- … ) is the data stack. When the word also uses or changes ts / xs / ys / zs , write those aspects with a letter prefix. Since the OS cannot be manipulated by user code, don’t include before/after, only the one value that persists for the method:

/*
Render newline-separated ops onto the parked StringBuilder.
( text:s -- ) z( sb:StringBuilder -- sb )
*/

/*
Final method body: receiver is on OS for the duration of the call.
( -- s ) o( inst:Person )
*/

Only document aspects that change; omit stacks that are untouched, unless you want to emphasize they have a value that must flow through to code called in the word. In that case, you can use the flowthru convention.

/*
Helper word for parsing.
( -- ) z( sb:StringBuilder )
*/

Stack-effect notation

Inside ( … -- … ):

• Left of -- — inputs (deepest first; TOS is rightmost).
• Right of -- — outputs after the word runs.
• Optional name:type labels (e.g. a:n, list:List).

Common type codes

For other types, write the full type name (List, Regex, HttpReq, …).

Attaching docs to your TypedObject with :doc

Final provides the :doc helper to attach documentation to an existing word or Type. You cannot attach such docs to sealed core or module words, but you can document your own TypedObjects this way.

Syntax:

/*
…doc text…
*/
:doc wordName // e.g. your new TypeDef

/*
…doc text…
*/
:doc TypeName#memberName // for your instance and class properties, if you want to document them

:doc reads the next identifier and attaches the last comment to that target’s .doc. For members, use a single # between the type name and the member name — the same spelling you use in help:

Then, to refresh your memory on how your type works, you just need to type:

help MyType

Documenting type members

Core Final documents members this way (excerpt from the maps/objects doc file):

/*
True if the Map contains an entry for the key.
( key:a -- has:b )
*/
:doc Map#hasKey

/*
Create a new empty DynamicObject.
( -- o:DynamicObject )
*/
:doc DynamicObject#new

Your TypedObject types

If you define a TypedObject (see TypedObject), document its fields and Final methods the same way. After the type exists in the catalog:

/*
Person record: display name and age in years.
*/
:doc Person

/*
Display name.
*/
:doc Person#name

/*
Age in years.
*/
:doc Person#age

/*
One-line "Name (age)" description.
( -- s ) o( person -- person )
*/
:doc Person#describe

Prefer documenting members when you register them, so help Person and help Person#describe stay useful for anyone using your type — including yourself later.

You may still put a /* … */ block immediately above : Person#describe so the dictionary Word gets .doc automatically; use :doc Person#describe when you want the text on the type member that help Type#member and the type’s member listing show.

Quick checklist

• /* and */ on their own lines; body flush left.
• First line: one complete purpose sentence.
• Extra sentences only for what the effect line cannot say.
• Last line: context/stack effect; nothing after it in the comment.
• Use :doc name or :doc Type#member when the target is not the word you just defined.
• Document TypedObject fields and methods so help works for your types.

Recursive Techniques

Final provides support for writing recursive code, and code that uses forward references. A good example is Final’s own json parsing code. The words that parse individual Json types, needs to be able to deal with any Json type. For example, a Json array can contain items of any Json type.

This is re-entrant recursion, and is an appropriate technique when the depth is not expected to be too deep. (What is “too deep”? We’ll get to limits later.)

Other times, an algorithm can be succinctly expressed as a step that subdivides or simplifies the work, then calls itself. Factorial is an often cited example.

Simple Recursion

During compilation of a Final word, the word itself is not yet visible in the dictionary. This presents a challenge in trying to use the word itself within itself. In this situation, Final provides a keyword, recurse; this has the same effect as naming the word itself; at runtime, it will nest into a new instance of the word.

// ( N:i -- N!:i )
: factorial
  dup 1 > if
    dup 1 - recurse *
  else
    drop 1
  then
;

When N > 1, the word keeps a copy of N, computes (N-1)! via recurse, then multiplies. For 0 and 1, the base case drops the input and leaves 1.

Forward References

Json parsing is a good example of re-entrant recursion. In this type of code, a word may not itself be recursive, but will indirectly call code that causes the nesting level of the overall algorithm to increase.

In this type of code, there is typically a chicken/egg in which earlier defined code must be able to call later-defined code. However Final, as it is defined, cannot directly support forward-references–a Word needs to be defined before it can be compiled.

In this case, Final provides defer:. It creates a word with no behavior yet. You assign the behavior later:

&of realWord is deferredWord

&of names the word that does the work. is makes that the behavior of the deferred word. You can compile calls to the deferred name before the real word exists. Until is runs, calling the deferred word panics.

You can also change that behavior later. A program can start with a basic version, then replace it once more of the system is defined.

Here is a short piece of Final’s own Json parser. Arrays and objects both contain values, and a value may itself be an array or object, so jsonParseArray and jsonParseObject call jsonParseValue before that word’s body is written:

// sole cycle: object/array members → value → object/array
defer: jsonParseValue

// ( -- list:List )
: jsonParseArray
  …
  jsonParseValue    // may nest into another array or object
  …
;

// ( -- obj:DynamicObject )
: jsonParseObject
  …
  jsonParseValue
  …
;

// ( -- v:a )
: (jsonParseValue)
  …
  // '"' → string | '{' → object | '[' → array | …
;

&of (jsonParseValue) is jsonParseValue

defer: jsonParseValue creates the name so the array and object parsers can call it. The real work is (jsonParseValue). The last line assigns that word’s behavior to jsonParseValue. Until that line runs, calling jsonParseValue panics.

Limits

Recursive and Re-entrant code can often provide a concise, easy to reason about algorithm. However these techniques are only suitable within limits of the level of recursion that happens at runtime. Final places depth limits on all its stacks, including the Return Stack. These limits are well above what almost any typical code would stress. But a recursive algorithm that results in excessive nesting can hit a data stack or return stack limit. In Final, that is a bit over 1,000.

So recursive/reentrant code needs to itself have limits. Recursion can always be replaced with iteration, so if the data set or recursion depth will exceed Final’s limits, then it should be reworked using an iterated type of approach.

Output Formatting

$ prints one value’s natural string to stdout. $$ prints one value’s natural string to stderr. In final-gui and final, use View ▸ Stdout/Stderr to show the standing stream panes (Prompt stays); View ▸ Prompt/History returns to the Response and History panes.

When you need a composed message — several fields, fixed widths, decimals, hex, a quoted string — use fmt with a List of values and a format string.

You have already seen this pattern in Writing Clean Final Code and in object examples, e.g. "%s (%d)" fmt. DateTime also uses ( … ) to build component Lists for factories. This page is the API detail for those sandwiches and for fmt itself.

API at a glance

Typical print pipeline:

( values… ) "format…" fmt $

fmt returns a String on DS. Print it with $, concatenate with str::+, or hand it to a TextWriter (writeString, writeLine).

The ( ) and ( s) sandwiches

Both sandwiches share the same open word (. The closer chooses the list type:

How they work

1. ( records the current Data Stack depth (a context mark on the return stack). It does not push a value.
2. Between ( and the closer, push the items you want in the list — literals, property reads, method results, anything that leaves a value on DS.
3. ) (or s)) gathers only the values pushed after (, packs them into a list in writing order, and leaves that list on DS.

List order matches left-to-right source order: the first value after ( is list[0]; the last (TOS before the closer) is list[n-1]. That is also the order fmt walks for successive % markers.

( 10 20 30 )          // List: 10, 20, 30
( "a" "b" "c" s)      // StringList: "a", "b", "c"

s) requires every gathered cell to be a String (non-strings panic). Use ) when cells may be Int, Float, Bool, or mixed.

Empty sandwiches are legal: ( ) → empty List; ( s) → empty StringList.

You can also build a List with List.new^ / .append^ and pass that to fmt. The sandwich is the concise form for a fixed handful of values.

Only new values — a common trip-up

The sandwich does not include values that were already on DS when ( ran. It collects solely the new cells placed on DS after the open.

"Ada" 36
( ) "%s (%d)" fmt $     // WRONG: empty list — Ada and 36 sit *below* the mark

"Ada" 36
( "Ada" 36 ) "%s (%d)" fmt $   // works, but duplicates the literals

If the values you need are already on DS (or live on an object you are using), do not expect ) to “reach under” the mark. Produce them inside the sandwich, or park them first and push fresh copies/reads after (.

Prefer parking on an auxiliary stack

Final’s aux stacks exist for this kind of problem (Stack Operators, Clean Final Code). Park handles or operands, then emit values inside ( … ):

: printFullName ( inst:o -- )
  >ts
  ( t:.prefix@ t:.name@ t:.affix@ )
  "%s%s%s" fmt $
  t:drop
;

"Ada" >ts
36 >xs
( t:peek x:peek ) "%s is %d" fmt $
x:drop t:drop

Cautions

• Stack juggling after ( to pick / over values from below the mark can work (a copied cell is “new”), but it is hard to read and easy to get wrong — park instead.
• Ops inside the sandwich that drop or rearrange cells below the mark can corrupt the caller’s stack. Keep the sandwich body a straight sequence of pushes (and rooted reads that leave results on DS).
• s) will reject non-String cells; if you need mixed types for fmt, use ).

fmt

// ( values:List fmtString:s -- result:s )
( 42 "widgets" ) "%d %s" fmt $ nl    // 42 widgets

Rules of thumb:

• One value in the List per % substitution (not counting %%).
• Prefer an explicit type marker (%d, %s, …) over a catch-all when you know the type.
• A count mismatch does not always abort the word; missing or extra substitutions show up as error text inside the result. Keep the List and the format string in sync.

fmt is for building a String. It does not write to stdout by itself — follow with $ or a writer method when you want output.

Format codes (cheat sheet)

Format strings are ordinary Final Strings. Substitutions use % markers (C-style). Literal text copies through unchanged. Use %% for a literal percent sign.

Type markers (Final-relevant)

%v is a reasonable default when exploring. For production messages, prefer the typed codes so Int/Float/Bool/String stay obvious at the call site.

%c wants an Int code point (same idea as r>s $ — interpret the Int as a character), not a one-character String. Prefer %c inside fmt; use r>s when you need a String for $ / $$ or other String APIs.

Width and precision

Insert width and precision between % and the type letter:

Width applies similarly to %s, %d, %x, and friends. Precision for %s caps the number of characters taken from the string; for integers it is less often useful than for floats.

( "n" 7 3.5 ) "%s=%02d rate=%.1f%%" fmt $ nl
// n=07 rate=3.5%

DateTime and Interval

fmt is for general messages (%d, %s, width/precision). It is not the DateTime/Interval layout API.

To format a DateTime or Interval with a letter-run pattern (or a curated constant such as DateTime.iso / Interval.clock), use dt::fmt:

DateTime.now^ DateTime.iso dt::fmt $ nl
5 Interval.minute dt::* Interval.clock dt::fmt $ nl

Full pattern tables, cascade rules, sign handling, and format constants: DateTime and Interval — Formatting.

Examples

Several fields, then print

( "sensors" 3 true ) "%s: count=%d enabled=%t\n" fmt $

Single value still needs a List

( Int.maxInt ) "%d" fmt $ nl
( 255 ) "0x%02X" fmt $ nl

Join strings with ( s)

( "alpha" "beta" "gamma" s) ", " str::join $ nl
// alpha, beta, gamma

(str::join is covered under String Operators; ( s) is the handy way to hand it a StringList.)

Write into a builder / file

StringBuilder.new^ >ts
( "maxInt" Int.maxInt ) "%s=%d" fmt t:.writeString^
t:.toString^ $ nl
t:drop

Notes

• $ vs fmt — $ is one-shot natural print. fmt builds a String you can print, store, or send elsewhere.
• Objects — prefer pulling primitive fields (with rooted reads) into the sandwich rather than formatting a whole compound with %v.
• Related — stdin/out Streams for $ / $$ / r>s; StringBuilder and TextWriter for sinks; DateTime for ( parts ) factory Lists and for dt::fmt pattern formatting.

Input/UI Dialogs

When your Final code runs inside final or final-gui, you can raise modal dialogs that pause the script until the user chooses Ok or Cancel.

These APIs live on the class-only type Dialog. The mechanisms used to build and show these dialogs are the same for both final and final-gui. (You do not need to know anything about Fyne and final-gui.)

There are three kinds:

All three are blocking: the call does not return until the dialog closes. Esc (and Break / Ctrl-B) means Cancel. Only one dialog may be open at a time.

You already know the pieces these APIs lean on:

• Class methods with ^ — Methods
• Class constants such as Dialog.btnOk — Properties
• fields DynamicObjects for Field Dialogs — DynamicObject
• The modal result shape ( … -- result true \| false ) for Field Dialog Ok vs Cancel — Writing Clean Final Code

The next two pages cover the exact stack effects, parameters, and short worked examples.

Simple Prompt Dialogs

A prompt dialog shows a short message with Ok and Cancel. Use it when you only need a confirmation, not typed input.

API

showDefaultPrompt always uses title "Prompt" and focuses Ok by default. You pass only the body string. The body is shown centered; keep it short (about three lines).

Compare the returned Int to Dialog.btnOk / Dialog.btnCancel (or use == / <> against those constants).

Example

> "Overwrite notes.txt?" Dialog.showDefaultPrompt^
Dialog.btnOk == if
  "overwriting…" $ nl
else
  "left alone" $ nl
then

overwriting…

(In the run above, the user pressed Ok. Cancel or Esc would print left alone.)

A minimal check that only cares about Ok:

> "Continue?" Dialog.showDefaultPrompt^ Dialog.btnOk == $

true

Notes

1. The call blocks your Final word until the dialog closes; the rest of the UI (menus, Break) still works.
2. For a simple way to collect one or a few string fields, use an Ask Dialog.
3. For collecting typed fields rather than a yes/no, use a Field Dialog.

Simple Ask Dialogs

The Ask Dialog api provides a simple means for collecting from 1 to 7 string-typed values from the user, with a default prompt message.

The following example is in examples/dialog/ask-demo.fnl.

: ask-demo
  ( "What is your name?" "What is your quest?" )
  Dialog.ask^ if
    "Nice to meet you, %s. Off you go — \"%s\" is a fine quest.\n" fmt $
  else
    "Then we shan't proceed. Nobody expects the Spanish Inquisition.\n" $
  then
;

The code provides the requested field labels using the convenient Paren operators for building a List. It then asks Dialog to post the dialog via the ask method, which returns one of two types of result shape:

• true then a List of the replies, in order of request
• false and no List

You test for the response type using an if statement, and if true can then pass the List directly to a fmt statement and print it out (or use the replies however otherwise). If false, you can print a default reply, as above.

Dialog is covered in more detail in Input/UI Dialogs,
Paren operators in Compound Builders, and
fmt in Output Formatting.

Field Dialogs

A field dialog asks the user to fill in a small form and returns the edited values (or Cancel). Dialog.newFieldDialogParams^ mints a params DynamicObject with defaults; you customize title, body, and the nested fields object, then call Dialog.showFieldDialog^.

API

Outer params (after newFieldDialogParams)

You may set title, bodyText, and defaultButton on the params DO, and add rows to fields, before calling showFieldDialog. The factory already created the nested fields object; park it (t:.fields@ >xs) and store your defaults there.

Fields object

• 1 to 8 fields. An empty object panics at show time.
• Creation order is display order.
• Each field name is the label shown in the UI.
• The default value’s type chooses the control:

Any other default type panics when you show the dialog. User field names live only under fields, so they never clash with outer keys such as title.

On Ok, showFieldDialog pushes the edited fields object (not the outer params) and true. On Cancel / Esc / Break, it pushes only false — the modal result shape you already use elsewhere.

Example

Collect a small account form, then print what the user entered:

> Dialog.newFieldDialogParams^ >ts
"Account" t:.title!
"Enter name, age, and admin flag." t:.bodyText!
t:.fields@ >xs
"" x:.name!
0 x:.age!
false x:.admin!
x:drop
ts> Dialog.showFieldDialog^ not if
  "cancelled" $ nl
else
  >ts
  "name=" $ t:.name@ $ nl
  "age=" $ t:.age@ $ nl
  "admin=" $ t:.admin@ $ nl
  t:drop
then

name=Ada
age=36
admin=true

(Again, the printed lines assume the user filled those values and pressed Ok.)

A shorter pattern when defaults are enough and you only customize the title:

> Dialog.newFieldDialogParams^ >ts
"Connect" t:.title!
t:.fields@ >xs
"localhost" x:.host!
8080 x:.port!
x:drop
ts> Dialog.showFieldDialog^ not if
  "cancelled" $ nl
else
  >ts
  t:.host@ $ ":" $ t:.port@ $ nl
  t:drop
then

localhost:8080

Notes

1. Mint params with Dialog.newFieldDialogParams^, fill title / bodyText / defaultButton and the nested fields object, then Dialog.showFieldDialog^.
2. Int/Float rows stay open with a red error if the text does not parse; fix the field and press Ok again.
3. Same rules as prompts: one dialog at a time; Break cancels.
4. For a plain yes/no with no fields, prefer Simple Prompt Dialogs.

Text and Byte Streams

Streams are sequential sources and sinks: you read or write incrementally (a rune, a line, a byte, a chunk) without loading everything at once. The same programming model applies whether the backing store is a file, an in-memory string or buffer, or the process’s stdin/stdout.

Final splits streams along two axes you already saw in the Features survey:

That gives four role types — the shapes APIs ask for:

You usually open a concrete handle with a class factory on TextReader, TextWriter, ByteReader, or ByteWriter (TextReader.newFromFile^, ByteWriter.newFromBytes^, and so on). Those handles implement the matching role. Other types can too — for example StringBuilder is a TextWrite.

Final does not expose a general “open File, then ask it for a stream” workflow for day-to-day I/O — the stream factories are the entry point. (A small File helper exists for checks like fileExists?; see File Streams.)

Already covered elsewhere

• $ prints to the session’s stdout (Hello Final).
• ByteList is the compact unsigned 8-bit buffer used with byte streams (Numeric Lists).
• Pips inherit stdout/stderr; prefer write* on a TextWrite / ByteWrite for real I/O (Pips).

In this section

• Stream Types — common API shapes, then Text and Byte members
• File Streams — path-based factories and open modes
• String Streams — in-memory String / ByteList / StringBuilder
• stdin/out Streams — session stdin, stdout, stderr

Use list-streams then help TextRead / help TextReader (and the other type names) in the UI for the full member list and stack effects.

Stream Types

This page is the shared API for text and byte streams. TextRead / TextWrite / ByteRead / ByteWrite are the roles; TextReader, TextWriter, ByteReader, and ByteWriter are the usual concrete handles (factories below). Backing-specific openers (file path, in-memory string, ByteList) are illustrated in the following pages; the read / write / close / flush members are the same regardless of how you opened the stream.

Common patterns

Opening: bare vs ?

File-backed factories come in two forms (same convention as casts and File.readBytes / readBytes?):

• bare — must succeed; panics on open failure (( path:s -- stream ))
• ? — modal result for caller-handled failure

Modal shape (same as Writing Clean Final Code):

• success: ( … -- stream true )
• failure: ( … -- err:String false )

"notes.txt" TextReader.newFromFile?^ not if
  $ nl                    // err string
else
  >ts
  // … use t: …
  t:.close^
  t:drop
then

When open must succeed (system / mandatory path):

"notes.txt" TextReader.newFromFile^ >ts

Reading: value plus OK

Text and byte next / line reads use the Final modal apishape:

true means you got a value; false means end of stream (no placeholder value). Chunked readBytes is different: it returns a ByteList (possibly empty) and does not use a flag — empty means no more data (or a non-positive count).

Writing, flush, and close

• Writers buffer; call flush when you need data to reach the backing store before close.
• close releases the backing handle when the provider supports it (files do; many in-memory providers are no-ops). Safe to call when you are done.
• Put the stream on ts (or another aux stack) for a short session of method calls, then t:drop — same style as other objects (Writing Clean Final Code).

Iteration

TextReader is iterable. Put the reader on DS and use foreach … /foreach; i is each Unicode code point as Int. The loop consumes the reader (see foreach).

TextReader

Read Utf-8 text as runes or lines. A TextRead (getNextRune); readLine is on this concrete type.

Factories (class)

Instance methods

"hi" TextReader.newFromString^ drop >ts
t:.getNextRune^ if
  r>s $               // prints h
then
t:.close^
t:drop

TextWriter

Write Utf-8 text (runes, strings, or lines). A TextWrite.

Factories (class)

StringBuilder is a TextWrite: call its writeRune / writeString / writeLine members (same shape as below), then take .toString^. See String Streams.

Instance methods

"out.txt" TextWriter.newFromFileTruncateOrCreate^ >ts
"hello" t:.writeLine^
t:.flush^
t:.close^
t:drop

ByteReader

Read raw bytes. A ByteRead. Values on DS are Int (0…255) for a single byte, or a ByteList for a chunk.

Factories (class)

Instance methods

ByteList.new^ >xs
65 x:.append^
66 x:.append^
x:peek ByteReader.newFromBytes^ drop >ts
t:.getNextByte^ if
  $                       // 65
then
t:.close^
t:drop
x:drop

ByteWriter

Write raw bytes into a file or append into a ByteList. A ByteWrite.

Factories (class)

Instance methods

ByteList.new^ >xs
x:peek ByteWriter.newFromBytes^ drop >ts
65 t:.writeNextByte^
ByteList.new^ >ys
66 y:.append^
67 y:.append^
y:peek t:.writeBytes^
y:drop
t:.flush^
t:.close^
t:drop
x:.len@ $ nl          // 3
x:drop

File Streams

File streams are opened by class factories on TextReader, TextWriter, ByteReader, and ByteWriter. Each file factory has two forms:

• bare — must succeed; panics on open failure (( path:s -- stream ))
• ? — modal result (( path:s -- stream true | err:s false ))

Everyday sequential I/O goes through these factories. File also has whole-file readBytes / writeBytes / readText / writeText (same bare / ? pairing).

Text from a file

"log.txt" TextWriter.newFromFileAppendOrCreate?^ not if
  $ nl
else
  >ts
  "another line" t:.writeLine^
  t:.flush^
  t:.close^
  t:drop
then

: printFileLines ( path:s -- )
  TextReader.newFromFile?^ not if
    $ nl
  else
    >ts
    forever
      t:.readLine^ not if
        break
      then
      $ nl
    /forever
    t:.close^
    t:drop
  then
;
"log.txt" printFileLines

readLine returns the line without the terminating newline. A trailing \r (CRLF files) is stripped. A final line that has no newline is still returned once; the next call returns false.

Bytes from a file

"data.bin" ByteWriter.newFromFileTruncateOrCreate^ >ts
ByteList.new^ >xs
0 x:.append^
255 x:.append^
x:peek t:.writeBytes^
x:drop
t:.flush^
t:.close^
t:drop

"data.bin" ByteReader.newFromFile^ >ts
4 t:.readBytes^ >xs          // up to 4 bytes as ByteList
x:.len@ $ nl
x:drop
t:.close^
t:drop

Choose Text* when the file is Utf-8 text you want as runes or lines. Choose Byte* for opaque binary (images, protocols, hashes). Mixing layers in one handle is not how these APIs are meant to be used — open the unit you need.

Whole-file helpers on File

Bare forms panic on I/O error; ? forms use ( … -- val true | err:s false ) (writes omit val).

File existence

// ( path:s -- b )
"notes.txt" File.fileExists?^ $ nl

Unexpected filesystem errors from fileExists? are treated as faults (they panic), not as a modal false. Missing paths return false.

Security note

File open factories and whole-file read/write are gated by session Security Restrictions (read vs write). Restricted Sessions used for embedding or AI tools may refuse file access. Details: Security Restrictions.

String Streams

In-memory streams let you use the same Text / Byte APIs without touching the filesystem — handy for tests, parsing buffers you already hold, and building text before a single print or send.

Reading a String as text

// ( s:String -- r true | err:s false )
TextReader.newFromString^

: printRunes ( s:String -- )
  TextReader.newFromString^ drop >ts
  t:peek foreach
    i r>s $
  /foreach
  t:.close^
  t:drop
;
"αβ\nγ" printRunes

For line-oriented work, keep the reader on ts and call .readLine^ in a loop (same pattern as File Streams).

Newlines in the source String are ordinary runes (\n, and \r if present). readLine still treats \n as the line terminator and strips a preceding \r.

Writing text in memory: StringBuilder

StringBuilder is a TextWrite — the same write-shaped members as other text writers:

StringBuilder.new^ >ts
"hello" t:.writeString^
32 t:.writeRune^
"world" t:.writeLine^
t:.toString^ $              // hello world\n
t:drop

You already saw this style under Methods. Pretty / indented builders (newWithPretty, nesting helpers) are for structured rendering (for example Json); the plain builder is enough for most stream-like accumulation.

Bytes in memory: ByteList

ByteList is the buffer type for byte streams — a strongly typed list of unsigned 8-bit values (Numeric Lists).

ByteList.new^ >xs
x:peek ByteWriter.newFromBytes^ drop >ts
72 t:.writeNextByte^        // 'H'
105 t:.writeNextByte^       // 'i'
t:.flush^
t:.close^
t:drop

x:peek ByteReader.newFromBytes^ drop >ts
2 t:.readBytes^ >ys
y:.len@ $ nl                // 2
y:drop
t:.close^
t:drop
x:drop

The writer appends to the list you passed in; it does not replace earlier contents. The reader walks from the start of the list with its own offset — it does not remove items from the ByteList.

stdin/out Streams

Every Final Session / run has three text streams bound for you:

You do not open these with the file or in-memory factories. The runtime wires them when the Session starts — process stdio for an interactive TUI or headless REPL, capture buffers when a host embeds Final, or null readers/writers when a worker has no input/output.

Everyday printing: $ and $$

For most programs you never hold the stdout handle yourself. Words you already used write there for you:

> "Hello from Final!\n" $

Hello from Final!

> "warning" $$

Acceptable $ / $$ inputs include String, Int, Uint, Float, Bool, and DateTime. Other objects typically print only their type name — not a full dump. For richer formatting of several values, see Output Formatting (fmt and friends).

Printing a Rune

A Rune is a Unicode code point carried as an Int. Ordinary $ on an Int prints the decimal code point (65 $ → 65), which is rarely what you want for text. Convert first with r>s, then print:

> 65 r>s $ 10 r>s $

A

When you are already building a fmt message, use %c with the Int code point instead — no r>s needed:

> ( 65 ) "char=%c" fmt $ nl

char=A

On a TextWrite handle, call writeRune directly; conversion is only for the $ / $$ path (and any other String sink).

When you care about the handle

• Pips copy the parent’s stdout/stderr into the spawn parameter object by default; process stdout/stderr are safe for concurrent writes. Custom writers you create (files, builders) are not automatically locked — your program owns them. See Pips.
• Worker pips get a null stdin unless you bind an explicit reader; line-oriented REPL input stays on the main pip.
• Prefer TextWrite / ByteWrite write* methods (and fmt) for anything beyond quick $ prints. Do not treat stdout as a general mux for files or network traffic.

Null streams

When no real input or output is bound, reads EOF immediately and writes are discarded. That is normal for some embedded or worker setups — not an error by itself.

File System

Final’s filesystem API covers paths, metadata, directories, and whole-file helpers. Sequential streaming I/O (line/byte readers and writers) lives under File Streams — this page does not repeat open/read/write stream factories.

You already know the pieces these APIs lean on:

• Class methods with ^ — Methods
• Modal ( … -- result true \| err:s false ) — Writing Clean Final Code
• foreach over iterators — Iterators: foreach

Use help File / help Dir / help Path / help FileInfo in the TUI for the full member list.

Path (class-only)

Operands are strings on the data stack. There are no Path instances.

"out" "report.md" Path.join^          // "out/report.md" (host sep)
"a/./b/../c" Path.clean^              // "a/c"
"out/reports/q1.md" Path.basename^    // "q1"
"out/reports/q1.md" Path.extname^     // ".md"
"/var/log/syslog" Path.split^ foreach i $ sp /foreach

FileInfo

Snapshot returned by File.info / Dir.info and by directory iteration. No public new.