flisp/spec.md

fLisp

• S-expressions: (<function> [arg0 ... argN])
  Will call function with optional args arg0-argN
  ([*]<variable> [arg | *arg] [arg2])
  If arg is given, it will assign arg to variable, then return variable
  If assigning to a vector or string :

  • If * is specified before variable, it will replace the vector
  • Otherwise, if only arg is given, it will return the element at position
    arg of variable. If arg2 is given, it will set the element at position arg of variable to arg2.
    Examples:

  fLisp : (let:vec:int a 5)
  C : int a[5];
  fLisp : (a 0 69)
  C : a[0] = 69;
  fLisp : (let:int x)(x (a 0))
  C : int x = a[0];
  

  For vectors and strings, it's a shallow copy (data is the same) unless a *
  is specified before [arg]

• Compiled to bytecode

In this document :

• <...> : Mandatory argument
• [...] : Optional argument
• | : Or

Core types

• null : Represents a null value - always evaluates to false
• int : 32 bit signed integer, evaluates to false if zero and true otherwise
• fix : 16:16 bit fixed point signed integer, same evaluation rules as ints
• float : 32bit IEEE floating point value, same evaluation as ints (within
  FL_ESPILOǸ̀)
• str: ASCII character string - always evaluates to false
• fn: Function, function "variables" are inherently of type fn - handle with care !
• vec : Vectors of any type,

Core functions

• (var[:type] <name> [size]) : Declares a global variable of optional type type and name name
  if type is of format :vec:<type>, the variable will be a vector of type type, and optional size size (otherwise size 0) (if type isn't specified it is inferred)

• (let[:type] <name>): Same as var, but variable is of local scope (recommended)

• (if <cond> [expressions]): If cond evaluates to true, will execute optional expressions

• (else [expressions]): Must follow a if, will execute if the if's cond evaluates to false

• (while <cond> [expressions]): while cond evalutates to true, will execute optional expressions

• (fn (<name> [arg0[:type] ... argN[:type]]) [expressions]) : Declares a function of name name, optional args arg0-argN with optional
  types (recommended to explicit them), that executes optional expressions
  The name cannot be a variable

• (import <lib0> [... libN]) : Import the functions and variables from lib0-libN

For the following numerical functions, values must be scalars (except + and =, where they may be strings), and of the same type

• (+ <a> <b>): Returns a+b, if they are both strings they will be concatenated

• (- <a> <b>): Returns a-b

• (* <a> <b>): Returns a×b

• (/ <a> <b>): Returns a/b

• (% <a> <b>): Returns a%b

• (< <a> <b>): Returns 1 if a < b, else 0

• ̀(<= <a> <b>): Returns 1 if a <= b, else 0

• (= <a> <b>)̀̀: Returns 1 if a == b, else 0

• (>= <a> <b>): Returns 1 if a >= b, else 0

• (> <a> <b>): Returns 1 if a > b, else 0

console functions

• (input): Will try to get input from the user, returns it as a string
• (write <var>): Will try to cast var to string then print it to the console
• (newline): Will print a newline to the console (newline characters aren't escaped with write)

gint functions

TODO

Bytecode

• 8 byte Value : 2 bytes tag, 6 bytes value itself
• 4 byte bytecode ops: 1 byte op, 3 byte args (named 1-3)

Bytecode types

• T_Null̀̀ -> null
• T_Int -> int
• T_Fix -> fix
• T_Float -> float
• T_Str -> string :
  • If shorter than 4 chars (+ \0), is a "compact string"
  • Otherwise, gets converted to a vector, inherently of chars
• T_Fn -> fn / function

Bytecode operations :

if just 1, 2 or 3, means the value at pos 1,2,3 of the stack if #1,#2,#3, the immediate value of 1,2,3 if 1:2 / 1:2:3, means stitching 1,2,3 together as a 2 or 3 byte value

• add : 1+2 -> stack
• sub : 1-2 -> stack
• mul : 1×2 -> stack
• div : 1/2 -> stack
• mod : 1%2 -> stack
• call : calls 1
• ret : returns to caller
• mov : 1 -> 2
• copy : deepcopy of 1 -> 2
• get : value at pos 2 of vector 1 -> stack
• set : set value at pos 2 of vector 1 to 3
• gt : 1>2 -> stack
• ge : 1>=2 -> stack
• eq : 1==2 -> stack
• jmp : Jumps to bytecode at relative 2:3
• brt : Jumps to bytecode at relative 2:3 if 1
• cast : Casts 1 to the type of 2 -> 1
• fcast : Casts 1 to the type of 2:3 -> 1
• init : value of type 2:3 and size 1 -> stack
• fcall : calls function of hash 1:2:3
• pop : pop value 1
• popl : pops the last #2 values on stack, starting from #1
• cst0 : 2:3 -> LSW of 3
• cst1 : 2:3 -> MSW of 3
• iter : Iterates on vector 1, keeping track with int value at 2, and sets int value at 3 to 1 when done to 1