wasp-0.3.1 is not a library.

Wasp 🐝

a Lisp programming language for extremely performant and concise web assembly modules

warning: this compiler is very alpha and error messages aren't the best, but it works and language is simple!

// main.w
extern console_log(message)
pub fn main(){
  (console_log "Hello World!")
}

Features

encourages immutability
immutable c-strings, memory manipulation, global variables, imported functions, 1st class functions
optional standard library runtime
functions with inline web assembly
test framework support
easy project dependency management
self hosting
code pruning and inlining
type inference

Quickstart

Wasp depends on git and rust. Make sure you have them installed before beginning.

cargo install wasp
wasp init myproject
cd myproject
wasp build
python3 -m http.server

Open up http://localhost:8000 and look in console. At this point we will have a web assembly module that has access to the standard libraries functions. More to come in this area!

If you don't have need for the standard library (or want to write your own!). This is also an option.

wasp init myproject --no-std

At this point we will have a web assembly module with a single exported main function and nothing else.

If you think your standard library is out of date, just run wasp vendor

Lisp like its 1959

Wasp is an extremely basic language and standard library. It's primary goal right now is to be a MINIMAL Lisp that can be self hosted. Specifically:

emphasis on recursion
functions can be passed around as arguments
symbols
immutable cons data structure

(cons 42 none) ; returns the memory location of cons

(head (cons 42 none) ; return the head value 42

(tail (cons 42 none) ; returns the memory location of tail

(cons 1 (cons 2 (cons 3 none)) ; returns a linked list

(# cons 1 2 3) ; short hand for (cons 1 (cons 2 (cons 3 none))

Other major features that are Lispy may be added in the future.

Drawing

Using wasm-module we can easily draw something to screen. Loops in wasp work differently than other languages, bbserve how this example uses recursion to rebind variables.

extern global_getWindow()
extern Window_get_document(window)
extern Document_querySelector(document query)
extern HTMLCanvasElement_getContext(element context)
extern CanvasRenderingContext2D_set_fillStyle(canvas color)
extern CanvasRenderingContext2D_fillRect(canvas x y w h)

static colors = ("black" "grey" "red")

pub fn main(){
  (let [window (global_getWindow)
        document (Window_get_document window)
        canvas (Document_querySelector document "#screen")
        ctx (HTMLCanvasElement_getContext canvas "2d")]
        (loop [x 0]
               (if (< x 3)
                   (do (CanvasRenderingContext2D_set_fillStyle ctx (mem32 (+ colors (* 4 x))))
                       (CanvasRenderingContext2D_fillRect ctx (* x 10) (* x 10) 50 50 )
                       (recur [x (+ x 1)])))))
}

See it working here

Mutable Global Data

It's often important for a web assembly modules to have some sort of global data that can be changed. For instance in a game we might have a high score.

static high_score = 0

fn run_my_game() {
  ...
  (mem32 high_score (+ (mem32 high_score) 100)  
  ...
}

Project Management

warning: this may change but it works Code dependencies are kept in a special folder called vendor which is populated by specific checkouts of git repositories.

For example a project.wasp containing:

bar git@github.com:richardanaya/bar.git@specific-bar

would result in these commands (roughly)

rm -rf vendor
mkdir vendor
git clone git@github.com:richardanaya/bar.git@specific-bar vendor/bar

when wasp vendor is called

Now, when wasp compiles your code, it does a few things.

In order specified by your project.wasp, one folder at a time all files ending in .w are loaded from each vendor/<dependency-name> and its subfolders.
all files in the current directory and sub directories not in vendor are loaded
then everything is compiled in order

Please try to use non conflicting names in meantime while this is fleshed out for 0.2.0

Advanced

When necessary, low level web assembly can be directly inlined

#[wasm]
fn memswap(i32) -> i32 {
  [i32]  // int tmp = 0;
  // tmp = a
  LOCAL_GET   0
  LOCAL_SET   2
  // a = b
  LOCAL_GET   1
  LOCAL_SET   0
  // b = tmp
  LOCAL_GET   2
  LOCAL_SET   1
  END
}

pub fn main() {
  ...
  (memswap 10, 20) )
  ...
}

Technical Details

Types

integer - a 32-bit integer (e.g -1, 0, 42)
string - a 32-bit pointer to a location in memory of the start of of a c-string (e.g. "hello world!")
symbol - a 32-bit pointer to a location in memory of the start of of a c-string (e.g. ":hello_world")
bool - a 32-bit number representing boolean values. True is 1, false is 0. (e.g. true false)
none - a 32-bit pointer to value that represents nothingness
data - a global only type this is a a 32-bit pointer to sequence of 32-bit values in memory (e.g. (1 true :hey (:more-data none). Use this for embedding raw data into your application memory on startup.

Functions

pub fn { ... } - create a function that executes a list of expressions returning the result of the last one. Optionally provide an export symbol to make visible to host.
(function_name ...) - call a function with arguments
(mem x:integer) - get 8-bit value from memory location x
(mem x:integer y) - set 8-bit value at memory location x to value y
(mem32 x:integer) - get 32-bit value from memory location x
(mem32 x:integer y) - set 32-bit value at memory location x to value y
(if x y) - if x is true return expression y otherwise return none
(if x y z) - if x is true return expression y otherwise return expression z
(do ... ) - executes a list of expressions and returns the value of the last. useful putting complicated expressions in places that expect one expression.
(let [x0:identifier y0:expression x1:identifier y1:expression ... ] ... ) - bind pairs of values to identifiers. Then run a sequence of expressions that can use those values by their identifier. Returns the value of the last expression in sequence. bindings specified in let shadow those at higher scopes.
(loop [x0:identifier y0:expression x1:identifier y1:expression ... ] ... x ) - bind pairs of values to identifiers. Then run a sequence of expressions that can use those values by their identifier. Returns the value of the last expression in sequence. bindings specified in loop shadow those at higher scopes.
(recur [x0:identifier y0:expression x1:identifier y1:expression ... ] ... x ) - rebinds pairs of values to identifiers and restarts the innermost loop.
(fnsig [x0 x1 .. ] y) - gets the value of a function signature with inputs x0, x1, etc and output y
(call x f y0 y1 ...) call a function with signature x and function handle f with parameters y0, y1, ...
(# function_name e1 e2 e3 ...) recursively call a chain of functions ( e1 ( e2 ( e3 none)). I call this the nest operator. This function works differently the more parameters your fn takes.

Common Operators

These oprators work pretty much how you'd expect if you've used C

(+ ...) - sums a list of values and returns result
(- ...) - subtracts a list of values and returns result
(* ...) - multiplies a list of values and returns result
(/ ...) - divides a list of values and returns result
(% ...) - modulos a list of values and returns result
(== x y) - returns true if values are equal, false if otherwise
(!= x ) - returns true if values are not equal, false if otherwise
(< x y) - returns true if x is less than y, false if otherwise
(> x y) - returns true if x is greater than y, false if otherwise
(<= x y) - returns true if x is less than or equal y, false if otherwise
(>= x y) - returns true if x is greater than or equal y, false if otherwise
(and x y) - returns true if x and y are true, false if otherwise
(or x y) - returns true if x or y are true, false if otherwise
(& x y) - returns bitwise and of x and y
(| x y) - returns bitwise or of x and y
(! x ) - returns true if zero and false if not zero
(^ x ) - bitwise exclusive or of x
(~ x ) - bitwise complement of x
(<< x y) - shift x left by y bits
(>> x y) - shift x right by y bits

Testing

(deftest x0 x1) - executes expression x0 then x1 etc. and stops when it first encounters a value and return the value otherwise if all expressions return none, none is returned. Test names will be exported by default as "test_"+name when compiled in debug and removed when built with wasp build --release. The function is comes from the standard library.

#[test]
addition[
  (is (= 4 (+ 2 2)) "2 + 2 should be 4")
  (is (= 7 (+ 3 4)) "3 + 4 should be 7")
]