wslib

wslib is a library of utilities written in Whitespace, intended to become the standard library for an upcoming compiler.

Modules

• array
• bool
• char
• crypto
• hash
• int
• map
• math
• matrix
• mem
• string
• vm/deadfish
• vm/intcode

Style

Functions are documented with a prose description similarly to godoc, as opposed to Javadoc. Labels prefixed with . are not exported.

Parameters and return values are specified with Forth-style # (x y -- z) comments and preconditions are specified with # Requires comments. These will hopefully become checked by the compiler at every call site.

Using the heap for local variables is avoided when possible until the compiler has sufficient dataflow analysis that can allocate non-conflicting addresses and registerize most heap operations. Until then, and on most interpreters, stack operations are significantly faster than heap operations.

Syntax

wslib uses Whitelips/Nebula instruction names, with extended arguments and shorthands. assemble.sh converts the wslib dialect to a format recognizable by whitespace-rs.

Instruction shorthands

• n -> push n
• ^ -> dup
• ^n -> copy n
• nslide -> slide n
• + -> add
• - -> sub
• * -> mul
• / -> div
• % -> mod

Instruction macros

• 2dup -> ^1 ^1
• 3dup -> ^2 ^2 ^2
• 4dup -> ^3 ^3 ^3 ^3
• 5dup -> ^4 ^4 ^4 ^4 ^4
• 6dup -> ^5 ^5 ^5 ^5 ^5 ^5
• 7dup -> ^6 ^6 ^6 ^6 ^6 ^6 ^6
• 8dup -> ^7 ^7 ^7 ^7 ^7 ^7 ^7 ^7
• 9dup -> ^8 ^8 ^8 ^8 ^8 ^8 ^8 ^8 ^8
• 10dup -> ^9 ^9 ^9 ^9 ^9 ^9 ^9 ^9 ^9 ^9
• 2drop -> drop drop
• 3drop -> drop drop drop
• 4drop -> 3slide drop
• 5drop -> 4slide drop
• 6drop -> 5slide drop
• 7drop -> 6slide drop
• 8drop -> 7slide drop
• 9drop -> 8slide drop
• 10drop -> 9slide drop
• n+ -> n +
• n- -> n -
• n* -> n *
• n/ -> n /
• n% -> n %
• neg -> -1 *
• j= -> - jz
• j< -> - jn
• j> -> swap - jn
• j<= -> 1 + - jn
• j>= -> swap 1 + - jn
• jeof -> jn, jz, or 1 - jn (depending on desired EOF behavior)

Imports

• "module" import - import module
• "module" export - import module under the exporting module's name

Tokens

• # line comments
• 'X' ASCII characters
• '\a' '\b' '\t' '\n' '\v' '\f' '\r' '\e' escapes
• '\xXX' hex escapes
• 0xXX and -0xXX hex numbers

Contributing

If you'd like to help, get in touch by filing an issue, pull request, or sending me an email. There's lots of useful and interesting library APIs to implement!

TODO

• io:

  • prints_quote
  • prints_escape
  • readi_base
  • Unicode codepoint quoting
  • Space-padded integers

• math:

  • gcd
  • extended_gcd
  • modexp
  • crt
  • print_matrix_padded

• cipher:

  • rsa_enc
  • rsa_dec

• ws

  • parse
  • interpret

• Tooling:

  • Test driver that runs tests independently to simplify debugging and check for uncleared stack values

License

This project is made available under the Mozilla Public License, v. 2.0.