Stof Language
Stof language reference sheet.
Stof is designed to be very easy to use. It is not a general-purpose language; it only exists as a scalable, secure, and portable interface to data and remote systems (APIs).
In general, Stof should be considered a document rather than a program. One of its main goals is to be a medium for different data types to come together (data unification). The language is only one of these data types, acting as a controlled interface to the others.
Types
See Primitive Types and Units for more information on types in Stof.
obj
Object
null
Null value
str
String
int
Integer (i64)
float
Floating point number (f64)
Units (m, km, s, ms, etc.)
Units are f64 variant types
bool
Boolean (true or false)
map
Maps keys to values (ordered)
set
Set of values (ordered)
blob
Binary array of values (Uint8Array or Vec<u8>)
vec
Vector/Array of values
fn
Function type
unknown
Unknown type (used to accept many types)
void
Allowed on functions that don't return a value
Comments
Line Comment
Block Comment
Fields
For declaring fields, Stof is a superset of JSON, valid JSON will always be valid Stof.
Given this syntax, the above "message" field could be written as any one of the following:
If the value were an object, the field could be written as:
Value Expressions
Fields get parsed from the top of the document downwards, executing each value expression as they are seen.
If we reversed the order of the function declaration and field declaration in this example, the document would fail to parse, resulting in an error.
However, if a function is parsed that references a field that has not yet been parsed, this is fine as long as it isn't called until after the document is parsed (or all fields/functions it references).
This functionality can help improve the readability of your documents as well:
Block Expressions
Stof also has block expressions, which can be used when defining fields (or within functions of course).
Objects
Objects are defined as fields, but start a new scope that can contain additional fields, functions, and types (along with other data if you choose).
See Objects for more information on objects in Stof.
Arrays
Array fields are defined in a familiar way.
Functions
See Functions for more information on functions in Stof. This is merely a syntax reference.
Functions in Stof should feel pretty familiar, following the general syntax:
Parameters
Parameters are optional, consisting of a name, type, and an optional default value.
Return Type
Attributes
Statements
Statements are used in functions and code blocks to manipulate the document, perform transformations, and execute custom logic.
Variable Declaration
A variable is declared in Stof using the "let" keyword. Variables are not fields, but field values can be loaded into variables for mutation.
Assignment
Assignment is special in Stof as variables can be assigned to, sure, but fields in the document can be set this way also.
Fields are not references, as seen in this example. This makes Stof much easier to use in real life, where undoing field manipulations on errors, etc. can be quite difficult or impossible.
It also improves the readability and maintainability of Stof, knowing exactly when and where fields are being set vs variables.
In some scenarios (like pushing to an array that is a field), this can be annoying. However, it's worth the minor inconvenience of another assignment.
Addition Assignment
Assignments to fields are allowed in all explicit assignment statements.
Subtraction Assignment
Multiplication Assignment
Division Assignment
Modulo Assignment
Drop
The "drop" statement does exactly what it sounds like, frees variables. It can also delete fields, functions, and objects from the document entirely.
If Statement
An "if" block is required, followed by optional "else if" blocks, and finally, an optional "else" block.
Switch Statement
Switch statements evaluate an expression, matching the resulting value to a specified "case", or the "default" case if one is defined and a matching "case" was not found.
Cases in a switch statement do not fall through to the next case in Stof (like other languages) if a break or return is not found. Instead, Stof offers the "or" keyword to match multiple cases to a singular block of statements.
Try-Catch
Try-catch blocks are pretty simple in Stof, consisting of a singular try block and a singular catch block (no finally). Catch blocks are not required to, but can optionally catch the error type and message.
See Error Handling for more information on handling errors in Stof.
Return
While Loop
Just like in other programming languages, both the "break" and "continue" statements only apply to the most immediate loop (including for-loops).
For Loop
In real life, there's a range expression for constructing arrays of this nature:
<start (inclusive)>..<end (exclusive)>|<step>?.
The above "res" array could be defined with the expression: 0..5
.
For-in Loop
The for-in loop is the easiest and most common way to iterate over collections and objects in Stof. Any value that implements a "len" and "at" function can be iterated over using a for-in loop. This includes most of the value types in Stof by default: vectors, sets, maps, objects, tuples, blobs, numbers, and strings. Take a look at each library, the "at" function will tell you what type of value to expect.
Each for-in loop defines 3 variables (in a separate scope) that commonly come in handy while iterating:
first - true if inside the first iteration of the loop, false otherwise
last - true if inside the last iteration of the loop, false otherwise
index - the index of the current value
Custom Object Iteration
Expressions
In this section, we'll highlight some of the most handy and used expressions Stof has - this is not a complete list of expressions available.
Function Calls
Tuple Construction
Array/Vector Construction
Index/At
Range Constructor
Type Of
Stof's "typeof" expression is handy for determining the type of a value programmatically, especially for "unknown" types and fields. It will always return the base type, one of: str, bool, obj, fn, blob, int, float, null, vec, map, set, or Box<type>. Numbers that are a unit type will result in float.
Type Name
Stof's "typename" expression is similar to "typeof", however, will never return a box type ("Box<type>") and will always give the more complex type if present. For objects, this would be the custom type given to it, or "obj". For numbers that have units, the unit will be returned.
Arrow Function
See Functions for more information on functions in Stof.
Format String
Object Constructor
This is how one programmatically creates new objects in the document. Objects created will have the function's scope as its parent.
This does not create a field in the document pointing to the new object. If you don't want to lose your object, create a field for it with an assignment statement (shown below)!
Unless a field is explicitly created for newly created objects, they will not be exported via the standard formats.
Newly created objects are not dropped or reference counted automatically, so keep this in mind, especially for loops, and clean up your document responsibly. For most practical situations, this is not an issue.
Data on the other hand keeps track of the objects it is attached to, so dropping an object will remove data from the document only if that data isn't also referenced elsewhere.
Logical And & Or
Logical operations get executed from left to right, with parenthesis taking precedence.
Ternary Expression
The ternary expression in Stof is slightly modified from other programming languages, starting with an "if" keyword. If the conditional expression is evaluated to have a truthy value, the first expression after the "?" is executed and returned, otherwise, the expression after the colon ":" is returned.
Comparison Operations
Last updated
Was this helpful?