Welcome to hana! Hana is a dynamically-typed interpreted language, built upon minimalist philosophy, it's inspired by Pascal, Ruby and Javascript, and it's fairly fast and lightweight. Enjoy your stay in Hana!

For documentation on the module, see docs.rs.

This is alpha software! Things may break at any moment, please send bug report and stack trace to Issues!

Syntax

Statements

All statements are separated by newlines. For statements that are composed of a statement (X) which is preceded by then, if the statement X is a block statement, the then keyword can be omitted, for example you can write:

if 1+1 == 2 begin
    print("math is correct")
end

Instead of

if 1+1 == 2 then begin
    print("math is correct")
end

Expression

Syntax:

[expression]

Evaluates [expression].

If

Syntax (else line is optional):

if [expression] then [statement]
else [else statement]

The statement evaluates [statement] if [expression] is true, else if [else statement] is specified then it will be evaluated.

For

Syntax:

for [var]=[from] [to/downto] [dest] step [step] then [statement]

The statement sets [var] to [from], and loops to (or down to) [dest] (exclusive) stepping [step] each iteration. With each iteration, it executes [statement].

step [step] is optional, if not specified, and the to keyword is used, [step] will be 1, otherwise if downto is used, then [step] will be -1.

For-in

Syntax:

for [var] in [object] then [statement]

The statement evaluates [object].

If [object] is an array, it will continuously set the variable [var] to every value in the array and evaluate [statement].
If [object] is a string, it will continuously set the variable [var] to every character in the string and evaluate [statement].
If [object] is an iterator, it will continuously evaluate the record's next function until the record has a stopped key set.
Otherwise, the interpreter will panic.

An iterator is simply a record with a next function, and is not initialized with a stopped key.

While

Syntax:

while [expression] then [statement]

The statement evaluates [expression], if it true then continuously evaluate [statement] until [expression] is false.

Try statements

Syntax:

try
    [body]
case [type] as [e]
    [catch]
    ...
case [type2]
    ...
end

The statement tries to execute statements in [body], if an exception is raised, it will lookup the raised value's type in the case statements, once it finds a match, it will execute the statements after the matching case statement.

Use as [e] in a case statement to capture the raised value into the variable [e].

Raise statement

Syntax:

raise [value]

Blocks

Syntax:

begin
[statements]
end

The statement evaluates all of [statements] sequentially.

Function

(see Types#Functions)

Scoping rules

A scope is a container which stores local variables. Every time a function is called, a new scope is setup. Scopes can be nested, meaning functions (A) inside of functions (B) can get its parent's variables (B), but not the other way around. Scopes can't set its parent scope's variables, doing so will create a new local variable with the same name.

Example:

function a() begin
    x = 1
    function b() begin
        y = 2
        print(y," ", x,"\n") // => 2 1
        x = 3
        print(x,"\n") // => 3
    end
    print(x,"\n") // => 1
    b()
    print(x,"\n") // => 1
end

a()

Local variables inside of scopes can be used inside of functions that escapes the scope (through returns, global variables or through dictionary/array keys). These are called closures. Hana implements this by copying the current scope's local variables (whenever the function is declared) into the function's hidden variable container.

function adder(n) begin
    return function(x) begin
        return x + n
    end
end

x = adder(5)
y = x(10) // => 15

Functions can do recursion, calling itself in its scopes:

function call_1000_times(n) begin
    print(n, "\n")
    if n == 1000 return
    return call_1000_times(n+1)
end
call_1000_times(0)

Return statements

The return statement exits the called function, and returns its result. If no result is given or no return statement is specified in the function, the function will yield nil.

Syntax:

return [expr]

Return statements are only possible in function bodies.

Record

(see Types#Records)

Record bodies only accept function, assignment and record statements.

Use

(see #Imports)

Expressions

The following sections describe expressions in hana in order of operator precedence.

Assignment operators

Assignment operators assign the value of its right operand to its left operand. The left operand may be a function call (for function definitions), a variable or a member expression.

List of assignment operators:

Shorthand operator	Meaning
`x = 10`	Sets variable `x` to `10`.
`x += 10`	Sets variable `x` to `x + 10`.
`x -= 10`	Sets variable `x` to `x - 10`.
`x *= 10`	Sets variable `x` to `x * 10`.
`x /= 10`	Sets variable `x` to `x / 10`.

Conditional operator

Hana uses the ternary operator to denote condition expressions:

condition ? then : otherwise

Bitwise operators

&, |, xor: Takes in two integer operands and performs a bitwise and, or, xor respectively.

Logical operators

and, or: Casts the two values into booleans then does the equivalent short-circuited boolean operation.

not casts the value into a boolean then does a boolean NOT (true becomes false and vice-versa).

Equality operators

Compares 2 values to see if they are the same (==) or not the same (!=).

Integer-integer and float-float pairs will be compared value-wise.

If an integer is compared with a float, the float will be compared to a float-casted value of the integer.

If a string is compared with another string, the byte values of the two strings will be compared.

If an array is compared with another array, or a record is compared with another record, they will only be the same when they are of the same memory address.

Otherwise, the two values will not be the same.

Comparison operators

Compares 2 values to see if they are greater than (>), greater than or equal to (>=), lesser than (<), lesser than or equal to (<=).

Numeric values will be compared value-wise.

String values will be compared based on their Unicode character points.

Otherwise comparison will always evaluate to false.

Arithmetic operators

Division (/)

Divides right value from left value.

Type table:

Left value	Right value	Result
Integer	Integer	Float
Integer	Float	Float
Float	Integer	Float

Multiplication (*)

Multiplies 2 values together.

Type table:

Left value	Right value	Result
Integer	Integer	Integer
Integer	Float	Float
Float	Integer	Float
String	Integer	String (repeats string by n times)
Array	Integer	Array (repeats array by n times)

Modulo (mod)

Gets the modulo or the remainder when the left value is divided by the right value.

Left value	Right value	Result
Integer	Integer	Integer

Addition (+)

Adds 2 values together.

Type table:

Left value	Right value	Result
Integer	Integer	Integer
Integer	Float	Float
Float	Integer	Float
String	String	String (concatenation)

Subtraction (-)

Subtracts right value from left value.

Type table:

Left value	Right value	Result
Integer	Integer	Integer
Integer	Float	Float
Float	Integer	Float

Call expressions

Call expressions are used to call functions or records:

a() // calls function a with no arguments
a(1,2) // calls function a with 2 arguments

When a record is called, its constructor function is invoked, and depending on the member expression's operator it will also pass a new dictionary in:

record Namespace
    record Example
        function constructor(self, num) begin
            self.num = num
            return self
        end
    end
end

Namespace.Example(10) // => calls constructor with arguments
                      // containing a new record and 10
Namespace::Example() // => calls constructor with arguments
                     // containing the Namespace record

Member expressions

Member expressions are used to access a key of a record, an array or a string:

a.b // => access "b" key of record "a"
a["b"] // => access "b" key of record "a"
v = [3,5]
v[0] //  => access 0th index (value 3) of array "v"
s = "abcd"
s[3] // => "d" access 3rd element of string s

Calling a member expression will pass the left hand side as an argument to the called method, to call a value's method without passing itself, use the :: operator:

record Test
    function constructor(self) begin
        print(self)
    end
end
Test::constructor("Hello") // => Hello

Values

Basic types include:

String: UTF-8 encoded string
Int: 64-bit signed integer
Float: 64-bit double precision floating point
Function: function
Record: records
Array: array

Int, Float values are primitives, they are passed by copies into (arguments) and out of (return) functions.

Function, String, Record and Array values are passed by reference. Those values are only deleted whenever the last variable containing the value is deleted or set to another value.

Primitive types have an immutable prototype key which provides its methods: String for string literals, Int for integers, Float for floating points, Array for arrays. Records by default do not have any prototype key.

By convention, type names are title-cased.

Identifiers

All strings of alphabetical characters, followed by alphanumeric characters or the characters $, _, ?, ! are considered an identifier.

Identifiers starting with $ denotes an identifier in the global scope:

a = 1
f() = $a = 20
f() // sets the global variable a to 20
a // => 20

Otherwise identifiers will follow scoping rules.

Note that the $ identifier will just refer to the $ identifier.

Functions

You can define a function like this:

function fib(n) begin
    if n <= 1 return n
    return fib(n-1) + fib(n-2)
end
function price(X) return X*0.5

or use a short hand form:

fib(n) = n <= 1 ? n : fib(n-1)+fib(n-2)

or use the expression form:

price = function(X) begin
    return X*0.5
end

or the Ruby style closure form (you should only use this for callbacks!):

price = |X| { return X*0.5 }

You can then call it like this:

fib(30) // => 1346269

Each function creates a scope (a separate variable environment). Variables that don't exist in the upper scope will be declared locally, while existing variables will set accordingly. (see #Scoping rules)

If a return statement is issued within the function, and the expression within the return statement is a call, then the interpreter will tail-call optimise it by pushing the call expression's arguments onto the stack frame and jumping into the function.

Strings

Strings are mutable UTF-8 strings. Characters in hana are Unicode grapheme clusters (actual characters) rather than bytes.

name = "Alice"
greeting = "Hello " + name // => "Hello Alice"
kaos_says = "ab"*3 + "a" // => "abababa"
multiline = "

    multi
    line
    string

"

Strings can be indexed using the brackets ([]) operator, however it is a O(n) operation so you shouldn't do it too much! (store its characters into an array and access it)

Methods:

"abc".bytesize() // => 3 (number of bytes in string)
"abc".length() // => 3 (number of characters in string)
"abc".chars() // => ["a", "b", "c"] (characters in string into array)
"abc".delete(1,2) // => "a" (copies and deletes 2 characters starting from index 1)
"abc".delete(1,-1) // => "a" (copies and deletes remaining characters starting from index 1)
"abc".delete!(1,2) // => "a" (deletes in place 2 characters starting from index 1)
"abc".delete!(1,-1) // => "a" (deletes in place remaining starting from index 1)
"abc".copy(1, 2) // => "bc" (copies 2 characters starting from index 1)
"abc".copy(1, -1) // => "bc" (copies remaining characters starting from index 1)
"abc".index("bc") // => 1 (index of the string "bc" in "abc")
"abc".insert!(1, "bc") // => "abcbc" (inserts in place "bc" to "abc" in index 1)
"a b c".split(" ") // => ["a", "b", "c"] (splits string with delimeter ' ' into array)
"a".ord() // => 97 (turn first character of string into a number)

Numbers

Numbers are either 64-bit ints or 64-bit double precision floats.

Numbers can be decimal or hexadecimal (prefixed by 0x).

Methods:

97.chr() // => (int only) converts 97 to equivalent unicode character ('a')

Records

Hana is has a prototype-based object system, like JS. Every value is a record (a key-value mapping), which keys can be accessed by using the dot (.key) operator or the brackets (["key"]) operator. A record (say record A), can inherit another record (record B), by setting its prototype key (A.prototype) to the parent record (B).

Once set, keys from record B can be used or called from record A. Record A's keys will of course override record B's keys if they are set. There's no distinction between records and instances of records.

You can define a record through a statement like this:

record Person
    species = "Human"
    function constructor(self, name, age) begin
        self.name = name
        self.age = age
    end
    function talk(self) begin
        print("*", self.species, " noises*\n")
    end
end

Or through an expression:

Person = record
    species = "Human"
    // ...
end

Then use it by doing this:

bob = Person("Bob", 20) // => record with keys name="Bob" and age="20"
bob.name // => "Bob"
bob.species // => "Human"
bob.talk() // => *Human noises*

Each time you call a record, the record's constructor function gets called instead, and will pass the record in addition to your arguments. I recommend using self to denote the argument containing the record. You must return the record (self) manually in the constructor.

Accessing a key can be done through member expressions. Accessing a non-existant key will throw an error.

Methods:

a = Record() // => creates a new record
a["key"] = "value" // => sets a key
Record::keys(a) // => ["key"] (gets all keys in record)

Records can embed a custom native_field containing pointers to user defined data. The native fields can not be accessed from the hana language, it can only be accessed through using native functions.

Arrays

Arrays in Hana are dynamic arrays. You can declare arrays like this:

[] // => empty array
[1,2] // => array with elements 1, 2
array(1, 2) // => same
[1,2,3]*3 // => [1, 2, 3, 1, 2, 3, 1, 2, 3] (repeats all elements in [1,2,3] 3 times)

Methods:

[1,2,3].length() // => 3 (number of elements in array)
[].empty?() // => true (is array empty?)
[1,2,3].delete!(1,2) // => [1] (deletes 2 elements starting from index 1)
[1,2,3].copy(1, 2) // => [2,3] (copies 2 elements starting from index 1)
[1,2,3].index(2) // => 1 (index of the element 1 in array)
[1,2,3].insert(1, 1) // => [1,1,2,3] (inserts 1 to [1,2,3] in index 1)
a = [4,6,7,3,1]
a.sort() // => [1, 3, 4, 6, 7] (sorts array without changing the array)
a.sort!() // => [1, 3, 4, 6, 7] (sorts array in place)
a.map(f(x) = x*2) // => [8, 12, 14, 6, 2] (maps each element with result of function)
a.filter(f(x) = x > 5) // => [6,7] (filters based on the truthiness of the function)
a.reduce(f(prev, curr) = prev+curr, 0) // => 21
// reduce executes a function on each member of the array's element
// then returns a single output

Comments

Comments can either be single line:

// a single line comment

or multiple lines:

/*
 multline comment
*/

Libraries

Standard library

Hana's standard library is called hanayo! The library is imported by default upon running.

Special constants

nil // => (nil)
true // => 1
false // => 0
inf // => infinity
nan // => not a number

Types

(see #Types)

IO

print("Hello World") // => prints string "Hello World" onto stdout
input() // => gets a string from stdin

Files

f = File("/tmp/a", "r") // => opens the file /tmp/a with the read flag
f.read_up_to(10) // => read first 10 bytes of file as string
f.read() // => read all of file as string

f = File("/tmp/a", "w") // => opens the file /tmp/a with the writer flag
f.write("Hello World\n") // => overwrites the file with the string "Hello World\n"

Environment variables

Env::get("x") // gets the environment variable x as a string
Env::set("x", "y") // sets the environment variable x to y
Env::vars() // gets a record of environment variables

Commands

c = Cmd("echo Hello World") // creates a process with the shell command "echo Hello World"
c = Cmd(["echo", "Hello World"]) // creates a process with args "echo", "Hello World"
c.out() // => "Hello World\n" (spawns the process and gets its stdout)
c.err() // => "" (spawns the process and gets its stderr)
c.outputs() // => ["Hello World\n", ""] (spawns the process and gets an array of stdout/stderr outputs)
Cmd("cat -").in("hi").out() // => "" (spawns the process with "Hi" passed to its stdin and gets its stdout)
c.spawn() // => Process record (spawns and detaches the process)

Process

p = Cmd(["echo", "Hello World"]).spawn()
p.out() // => "Hello World\n" (waits for the process to terminate and gets its stdout)
p.err() // => "" (waits for the process to terminate and gets its stderr)
p.outputs() // => ["Hello World\n", ""] (spawns the process and gets an array of stdout/stderr outputs)
p.in('hello') // => sends the string 'hello' into the process' stdin

Optional libraries

In addition to the standard library, Hana also comes included with some optional libraries that must be imported to use.

JSON

JSON::parse('{"a": true}') // => record of a key = 1
(record
    a = JSON::true
end).to_json() // => {"a": true}

C FFI

The implementation provides a native set of utilities for interfacing with C functions.

To enable it install the interpreter through cargo with the cffi feature. This requires libffi be installed in your system.

// calling getuid(), a native libc function from the ffi
getuid = Cffi::Function("getuid", [], Cffi.Int64)
print(getuid.call([]), "\n")

// returning a unicode string from c ffi
strchr = Cffi::Function("strchr", [Cffi.String, Cffi.Int64], Cffi.String)
print(strchr.call(["Hello World", "r".ord()]), "\n")

// importing sin from libm and using it:
libm = Cffi::Library("/lib/libm.so.6")
sin = Cffi::Function(libm.sym("sin"), [Cffi.Float64], Cffi.Float64)
print(sin.call([0.4]), '\n')

// creating a garbage collected pointer
// free will automatically be called whenever
// it goes out of scope on garbage collection
malloc = Cffi::Function("malloc", [Cffi.UInt64], Cffi.Pointer)
free = Cffi::Function("free", [Cffi.UInt64], Cffi.Pointer)
print(Cffi::GcPointer(malloc.call([10]), free))

FFI Types

Stored in Cffi:

UInt8,
Int8,
UInt16,
Int16,
UInt32,
Int32,
UInt64,
Int64,
Float32,
Float64,
Pointer,
String,
Void

Imports

You can import files using the use statement:

use [module]

Where [module] is a string,

If the module name starts with a ./, it will lookup and import the file relative to the script's local directory.
If the module name starts with a /, it will lookup and import the file relative to the root filesystem directory.
Otherwise, it will lookup and import the file in the path specified by HANA_PATH environment variable.

Circular dependency is undefined behavior. The interpreter may break if you do this.

Virtual machine

Hana has a stack-based virtual machine written in C. Code passed on to the interpreter will be parsed into an abstract syntax tree then translated into bytecodes which the virtual machine can understand.

Memory management

Hana uses garbage collection to manage memory. All values that are not referenced in the value stack or are not referenced by any of the global objects will be automatically collected and free'd by the garbage collector.

For values on the native stack, the interpreter uses reference counting to track references. All heap-allocated values that have a reference count of more than 0 will be considered a GC root (its childrens will not be marked as unreachable). Otherwise the garbage collector will handle it as normal.

Upon exit the virtual machine will release all memory that is managed by the garbage collector.

Note: all objects allocated by the virtual machine through vm.malloc() lasts as long as the virtual machine.

Do not use these GC-allocated outside of the virtual machine's lifetime!

Native functions

Native functions callable from the virtual machine must have the following signature:

void native_function(struct vm *vm, uint16_t nargs);

Arguments are passed on the virtual machine's stack, and the native function is called with a pointer to the virtual machine and the number of arguments (16-bits).

The native function must return a value by pushing it on the stack. If you don't have anything to return, push nil to the stack.

You should be using the hana_function macro in the module haru-decorator if you're making an exportable Rust function.

Files

DOCUMENTATION.md

Latest commit

History

DOCUMENTATION.md

File metadata and controls

Syntax

Statements

Expression

If

For

For-in

While

Try statements

Raise statement

Blocks

Function

Scoping rules

Return statements

Record

Use

Expressions

Assignment operators

Conditional operator

Bitwise operators

Logical operators

Equality operators

Comparison operators

Arithmetic operators

Division (/)

Multiplication (*)

Modulo (mod)

Addition (+)

Subtraction (-)

Call expressions

Member expressions

Values

Identifiers

Functions

Strings

Numbers

Records

Arrays

Comments

Libraries

Standard library

Special constants

Types

IO

Files

Environment variables

Commands

Process

Optional libraries

JSON

C FFI

FFI Types

Imports

Virtual machine

Memory management

Native functions