Reference Manual

Gaiman Programming Language Reference Manual

Commands

Commands are like functions without parentheses, they do the most important interactions with the terminal:

example:

echo "hello"
echo* "hello, world!", 100

Normal commands

• echo - print argument on a terminal
• ask - print prefix and get input from the user
• get - send GET HTTP request and return JSON, HTML, XML or Text depending on content-type of the response
• post - send POST HTTP request similar to get
• config - configure the terminal
• prompt - change the prompt (prefix that can be changed by using backspace)
• input - enter text into a command like if user type it
• sleep - pause the interpreter with given milliseconds
• rpc - command that return an object which methods send JSON-RPC request to given url
• store - save and return value from localStorage
• clear - clear the terminal
• mask - mask the input so you can enter for instance a password (it set or return current mask depending if you use argument or not)
• import - imports JavaScript variable into Gaiman namespace (e.g. import firebase will import firebase) or UMD module (e.g. import i18n from "https://cdn.jsdelivr.net/npm/...") or import the module (e.g. import "https://cdn.jsdelivr.net/npm/...").

Extra Commands

with an asterisk that works a little bit different than the normal version:

• sleep* - pause the interpreter but don't hide the cursor prompt
• input* - type into the command line with animation
• ask* - get input from a user, the prefix is printed with typing animation
• echo* - prints anything on the terminal with typing animation
• prompt* - change the prompt with typing animation

ask command

ask command works a little bit different since it has a validator as the last argument. The validator is a function that should return true or false. If the function returns false, the command will ask the user again. You can print an error when the validator fails.

example:

let name = ask "name ", lambda(name)
  let valid = name != ""
  if not valid then
    echo "<red>You need to specify the name</red>"
  end
  return valid
end

Standard library (very small to be extended)

• ord() - return codepoint of a single-character string (need to be one Unicode codepoint),
• chr() - return character from codepoint,
• range() - like in python return array of numbers,
• cookie - special object with key-value pairs of cookies saved by the server, if you set properties of this object they are saved as cookies,
• `location - JavaScript location object,
• JSON - JavaScript JSON object with parse and stringify methods,
• console - JavaScript console object,
• shuffle() - randomize an array,
• sprintf() - format strings like in C,
• cols() - returns a number of columns (characters per line),
• rows() - returns a number of terminal rows,
• to_base64() - encodes string to base64,
• from_base64() - decodes base64 encoded string,
• delay() - pause the code for n muliseconds.

Math functions and constants:

• abs
• acos
• acosh
• asin
• asinh
• atan
• atanh
• atan2
• ceil
• cbrt
• expm1
• clz32
• cos
• cosh
• exp
• floor
• fround
• hypot
• imul
• log
• log1p
• log2
• log10
• max
• min
• pow
• random
• round
• sign
• sin
• sinh
• sqrt
• tan
• tanh
• trunc
• E
• LN10
• LN2
• LOG10E
• LOG2E
• PI
• SQRT1_2
• SQRT2

Operator precedence

Operator	Description
[]	array and object access
()	parentheses grouping
=~	regex match
* / %	multiplication, division, modulo
+ -	addition (or concatenation), subtraction
< > <= >=	boolean compare
== !=	equal, not equal
not	Boolean not
and	Boolean and
or	Boolean or

Functions

# named function
def square(x)
   return x * x
end

# anonymous function expression
let square = lambda(x)
   return x * x
end

Functions supports splat operator:

def sum(*args)
   let result = 0
   for i in args do
       result += i
   end
   return result
end

echo sum(1,2,3,4,5)
echo sum(*[1,2,3,4])

Variables

let x = 10
let y = "hello, world"

Numbers

Gaiman supports standard form of numbers:

• integers
• hexadecimal 0x100
• octal 0777
• binary 0b11000111010101
• floating-point numbers 0.1e-2 or 0.1e10

Arrays

let x = [1,2,3,4]

it supports methods like in JavaScript map/reduce/filter/forEach/some/every/find/sort.

let x = [1,2,3,4]

while x.length do
    echo x.pop()
end

Dictionaries

let x = {"foo" => "Hello", "bar" => "world"}

Strings

Strings allow for variable interpolation. Strings only support double quotes.

let name = "John"
echo "Hello $name"

string methods have methods like in JavaScript e.g. replace/search/toLowerCase/toUpperCase

here docs

let x = <<<MSG
Hello
this
is
string
MSG

if statements

Parentheses around conditional are optional:

let name = ask "? "
if name == "foo" then
  echo "this is FOO"
end

let name = ask "? "
if name == "foo" then
   echo "is foo"
else if name == bar then
   echo "is bar"
else
   echo "is something else"
end

if name == "foo" then
  echo "this is FOO"
end

Regular expressions

let x = /foo|bar/g

Regex match

let cmd = ask "? "
if cmd =~ /echo (.+)/ then
    echo $1
end

Each group in regex has $ variable defined.

Loops

for loop

Over array:

for i in [1, 2, 3, 4] do
   echo i
end

Over key, value pair (array with index or dictionary)

let array = ["hello", "world"]
for key, value in array do
   echo "$index => $value"
end

let dict = {"foo" => "hello", "bar" => "world"}
for key, value in dict do
   echo "$key => $value"
end

while loop

Parentheses around conditional are optional:

while true do
  let cmd = ask ">>> "
  echo cmd
end

If you don't put an async command like ask inside while true loop, you may create an infinite loop. But if something like this happens the application will detect that and stop the program.

You can use config command to change the guard infinite loop. To turn of the infinite loop protection use:

config {"loop_threshold" => infinity, "loop_timeout" => infinity}

You can also turn off the echo newline at the end of the text, and make it explicit:

config {"newline" => false}
echo "this"
echo " is"
echo " the"
echo " text\n"

This will print "this is the text" in a single line.

do blocks

normal do block that only encapsulates the variables:

do
  let x = 10
end
# x is undefined hereh

async block. That executes code asynchronously (which means that the output JavaScript code will not use await that is implicit for every function).

async do
    let text = get "https://terminal.jcubic.pl"
    if text =~ /<title>(.+)<\/title>/ then
        echo $1
    end
end
echo "this is it"

animate block, that can be used to pause the terminal so it doesn't accept any input while the animation is running.

animate do
   echo* "some command", 50   
   exec* "this is command", 50
end

Text color

With Gaiman you can make the text you echo in a different color. You can use XML like syntax:

echo "<green>hello world</green>"

Each CSS color has it's own XML tag. You can also echo HTML images with <img src="<URL>" alt="<ALT TEXT>"/> and links <a href="<URL">text</a>.