Stua's primary raison d'être is simply because it is included in the library stb.h, so it is available with no effort to any application that uses stb.h (which, for its author, is every application). It also in the public domain so no attention need be spent on placing copyright notices anywhere.
Of course this comes at a cost: all applications are bogged down by this implementation of Stua. However, it is not compiled into applications by default, and it uses a fairly small amount of source code (about 1200 lines, or about 15% of stb.h). The implementation is very small because it builds on features available in stb.h (like generic hash tables and lex-like regular-expression support), and because it is extremely inefficient. (Someday a better implementation will be written to the exact same API; so you can use the stb.h Stua implementation until the performance becomes an issue, then drop in the better one.)
// compute the x'th most fibonacci number recursively
func fib(x)
if x < 3 then
1
else
fib(x-1) + fib(x-2)
end
end
/* Note that there is no explicit 'return'; if you do not explicitly
* return a value, then the value of a function is the value of its
* last statement.
*/
var x = print(fib(20))
Numbers: 30-bit integers, 31-bit floats. Defined in code like C.Character constants are specified as in C, but prefixed with the letter c, e.g. c'x' or c'\n'`.
Strings: Defined in code like C, or with single quotes.
Booleans: true and false are special value of their own type
Nil: the value nil is a special 'out of band' value like NULL in C
You can create a dictionary in code in several ways.
x = { foo=17, bar="hello" }
y = { "foo", "bar", x, { a="b", c="d" } }
z = { }
w = { x=x }
In the above code, x will receive a newly-created dictionary which maps the string "foo" to the integer 17 and the string "bar" to the string "hello".
Because the dictionary stored in y does not specify the keys explicitly, the values are assigned increasing integers starting from 0, so y will receive the dictionary with the following mappings:
key = 0; value = "foo"The variable z receives an empty dictionary, and the variable w receives a dictionary mapping the string "x" to the dictionary referenced by the value of x. Note that further assignments to the variable x will not change the dictionaries referenced in y and w, but changes to the dictionary x will be visible.
key = 1; value = "bar"
key = 2; value = x, the dictionary listed above
key = 3; value = the dictionary { <"a", "b">, <"c", "d"> }
Dictionaries can be used for multiple purposes. They can take the place of arrays (simply using integers to index them), they can take the place of structures (storing values with string keys), and they can be used as general purpose hash tables.
Dictionaries are referenced by using array-access notation:
print(y[0]) y[1] = x["foo"] z["bar"] = 1
You can also use a structure field access notation; the last line above could also be represented as z.bar=1.
return [EXPRESSION]
This ends a function prematurely, and produces the optional as the result, or nil if none is provided.
if CONDITION then STATEMENTS [else STATEMENTS] end
The else STATEMENTS part is optional. This computes the obvious thing. The value of the if statement is the value of the chosen branch. If else is omitted the value in the false case is nil.
while CONDITION [update STATEMENTS] do STATEMENTS end
The update STATEMENTS part is optional. This repeatedly tests CONDITION, and if it's true, executes the do STATEMENTS section. After executing the do section, the update section is executed. Then the process repeats. The value computed is the value of the last statement in the do section, or nil if the loop never executes.
break [EXPRESSION]
This terminates a loop prematurely. If the optional expression is included, that value is the result of the loop.
continue
This causes the current iteration of the to stop; the update section is then executed, if present, and then the loop repeats from the beginning.
for VAR [,VAR] in EXPR do STATEMENTS end
The for construction iterates over the keys or <key, value> pairs of a dictionary. Note that if the dictionary changes during the iteration, those changes will not be visible to the iterator. Thus some pairs produced may not actually be in the dictionary.
Results computed, and behavior of continue and break, are like while-`do`. Not implemented yet.
=> LVALUE
The into statement => x takes the value computed by the preceding statement and stores it to the lvalue on the right side. The right side must be an identifier, array-access, or structure-access. The idea here is that you can use an if-then-else or while to compute a value and store it into a variable. You can do this in a more normal way, but this way is possibly clearer (it's an experimental design).
+ - * / arithmetic operators << >> % & | ^ ~ bit operations (ints only) && || ! boolean operations == != equality comparisons >= <= < > inequality comparisons
Stua "fixes" the precedence error in C's "&" and "|" operators; they have higher precedence than comparisons do.
Also available is assignment, which can be written in either of these two ways:
x = a let x = a
The other C assignment operators are not available. Assignments produce values and
The && and || operators are short circuiting. They also produce their arguments as results; for example, in x && y, if x is false then the result is x; if x is true then the result is y. By default only boolean values have boolean meanings, so x must be a boolean (although y need not be); otherwise an error is thrown. However, you can overload the "conditional" operator to introduce other semantics for non-booleans (e.g. everything else being treated as true).
func myfunc(widget, parameter, name="default name")
...
end
Function calls can specify parameters by position or by name:
x = myfunc(a, 2, "my thing") y = myfunc(a, 3, name="thing") z = myfunc(widget=a, 4) w = myfunc(parameter=5, a)
Functions can also be called using dictionaries for their parameters lists, using ":" to call them; for example, the first call above can also be written as:
x = myfunc:{a, 2, "my thing"}
You can perform partial application by using the "+" operator instead of the ":" operator; this applies named arguments to the parameters but doesn't call the function; instead it returns a "new" function. Each of the following is equivalent to the above:
f2 = myfunc+{widget=a, name="my thing"}
x = f2(5)
f3 = myfunc+{widget=a}+{parameter=5}+{name="my thing"}
x = f3()
x = (myfunc+{widget=a, name="mything})(5)
However, there is no way to perform partial application by position; it is only allowed by name.
Similarly, it is possible to introspect the current stack frame by viewing it as a dictionary:
func myfunc(widget, parameter, name="default name")
var x = _frame
print(x.widget)
myotherfunc:x
widget = 1
x["widget"] = 5
print(widget) // not 5!
end
This is useful for creating functions that accept variable number of parameters. The parameters will be listed in _frame by integer values; the leftmost parameter is parameter 0, the next is parameter 1, etc..
Nested functions can refer to lexically scoped variables outside their own definition; closures will be created.
func adder(z)
func(x) z+x end // lexical closure
end
var p = adder(5)
print(p(2)) // prints 7
print(p(3)) // prints 8
func counter(z)
func() z = z + 1 end
end
var c = counter(0) var d = counter(0) print(c()) // prints 1 print(c()) // prints 2 print(c()) // prints 3 print(d()) // prints 1 print(d()) // prints 2 print(d()) // prints 3
44 0x2C c'+' c'A' 1000 0x0003e8 c'\n' c'\t'
Identifiers beginning with _ are reserved for use by the Stua.id _id a_very_long_identifier_52 id2 id_ tHiS_iS_aLsO_lEgItImAtE
Non-basic types are only identical based on reference. (For example, two separately-created dictionaries with identical contents will still be two distinct keys.)
Stua is designed to allow data items to be stored in 32 bits with tags; there are two tag bits so four cases each with 30 bits; one case is ints, so ints are 30 bits; one case is a pointer to all other types (fortunately 4-byte aligned pointers don't use their bottom 2 bits anyway), and the other two cases are both used to represent floating point numbers, which therefore get 31 bits.
(Someday when stb.h is rewritten to support 64-bit compilation, the "pointers" will become indices into a pointer table which already exists.)