GS2 documentation

What is GS2?

GS2 is a stack-based, concatenative programming language with functional influences, inspired by GolfScript and J. Its primary purpose is doing well at code golf contests; it achieves this by supplying many built-in commands and syntactical shortcuts that are each only one byte long.

Programming in GS2 is conceptually similar to programming in GolfScript or similar languages: the stack initially contains a string representing standard input, and its contents are printed to standard output when the program is finished.

The original author (@nooodl/@maurisvh) is no longer maintaining this language.

Values

GS2 values are integers, blocks, or lists. Blocks contain unevaluated code, representing "functions", like in GolfScript. There is no dedicated string type: strings are just lists of integers.

Tokens

Throughout this document mnemonics are listed next to some token names; these are compatible with the included gs2c utility.

Special tokens are:

Token | Meaning ----- | ------- $01 $xx | Push unsigned byte $xx to stack. $02 $yy $xx | Push signed short $xxyy to stack. $03 $zz $yy $xx $ww | Push signed short $wwxxyyzz to stack. $04 ss* $zz | Push string(s) to stack. ss is separated by $07; the action performed is decided by the string end byte $zz, see below. $07 $cc | Push single-character string "\xcc" to stack. $08 | Opens a block. $09 | Closes a block. %111xxyyy (hex values $e0 through $fb) | Wraps last y + 1 values into a block. x is the final token (what do we do with this block?): 0=nop, 1=map ($34), 2=filter ($35), 3=apply on both of top 2 elements ($38) $xx $fc (dm1, dump-map1) | Map single token inside lists. Short for $08 $90 $xx $09 $34. $xx $fd (df1, dump-filter1) | Filter single token inside lists. Short for $08 $90 $xx $09 $35. $fe (m:) | Open rest-of-program map block. $ff (f:) | Open rest-of-program filter block.

The end bytes for $04 mean the following:

End byte | Meaning -------- | ------- $05 | push strings to stack, sequentially $06 | push strings to stack in array $9b | sprintf (pops format from ss, pops fitting number of items from stack, pushes formatted string) $9c | regex match (pops regex from ss, pops string from stack, pushes 1 on match, else 0) $9d | regex replace (pops replacement string from ss, pops regex from ss, pops string from stack and pushes re.sub result) $9e | regex find (like $9c, but calls re.findall) $9f | regex split (like $9c, but calls re.split)

The regexes used by these operations may be prefixed by special characters to set a special variable c: by default it is 0, prefixing the regex by $5D sets it to 1, prefixing it by $7D $xx sets it to $xx. c affects the operations as follows:

• $9c: match whole string if c > 0
• $9d: perform at most c substitutions (unlimited if c = 0)
• $9e: find first matching substring only if c > 0 (else array of matching substrings)
• $9f: perform at most c splits (unlimited if c = 0) Furthermore, if the first character of a program is $04, it may be omitted; an unmatched string closing token will automatically be paired up. (gs2c will automatically perform this optimization.)

The following single-byte tokens have special meaning at the start of a program:

Mode | Meaning ---- | ------- $30 (line-mode) | Line mode: [program] -> [lines, map program, unlines] $31 (word-mode) | Word mode: [program] -> [words, map program, unwords] $32 (line-mode-skip-first) | Like $30, but ignore first line.

All other tokens are simple operations that pop values from the stack and push results back.

Constants

The following single-byte tokens push constants to the stack:

Byte | Constant ---- | -------- $0a (new-line) | [$0a] $0b (empty-list) | [] $0c (empty-block) | {} $0d (space) | [$20] $10 - $1a | 0 - 10 $1b | 100 $1c | 1000 $1d | 16 $1e | 64 $1f | 256

Functions

Opcode | Meaning ------ | ------- $0e (make-array, extract-array) | Pop number n, then pop n elements and push them back into an array; pop array and push each element. $20 (negate, reverse, eval) | Negate numbers; reverse lists; evaluate blocks. $21 (bnot, head) | Bitwise-negates numbers; extract first element from lists. $22 (not, tail) | Boolean negation for numbers; drop first element from lists. $23 (abs, init) | Absolute value for numbers; drop last element from lists. $24 (digits, last) | Push array of base 10 digits for numbers; extract last element from lists. $25 (random) | Push random.randint(0, x-1) for numbers x; choose random element for lists. $26 (dec, left-uncons) | Subtract 1 from numbers; pushes tail and then head for lists. $27 (inc, right-uncons) | Add 1 to numbers; pushes init and then last for lists. $28 (sign, min) | Push sign for numbers; minimum for lists. $29 (thousand, max) | Multiply numbers by 1000; maximum for lists. $2a (double, lines) | Multiply numbers by 2; split list into lines. $2b (half, unlines) | Divide numbers by 2; join with newlines for lists. $2c (square, words) | Square numbers; split list into words. $2d (sqrt, unwords) | Integer square root for numbers, join with space for lists. $2e (range, length) | Push [0..n-1] for numbers n, length for lists. $2f (range1, sort) | Push [1..n] for numbers n; sorts lists; sortBy for blocks. $30 (add, cat, +) | Add numbers, catenate lists/blocks. $31 (sub, diff, -) | Subtract numbers, set difference for lists. $32 (mul, join, times, fold, \*) | Multiply numbers; repeats a list n times; join list of lists with another; fold block over list. $33 (div, chunks, split, each, /) | Divide numbers; splits a list in chunks of size n; split two lists; call block with each element of list. $34 (mod, step, clean-split, map, %) | Modulo numbers; each nth element for list+number; split two lists removing empty lists; maps block over list. $35 (and, get, when, filter, &) | Bitwise and numbers; index list; eval block only when number on top of stack is non-zero, filter list by block. Et cetera. You can see the full list of mnemonics in gs2.py and play around with them to get a feel for what they do.

Example usage and gs2c

The included gs2c.py script is an "assembler" that compiles a more readable representation of gs2 opcodes and constants. It reads mnemonics for gs2 functions from the source code of gs2.py itself! Let's write a simple program, compile it using gs2c.py, and run it.

A very simple golf challenge is the following: given a positive integer n on standard input, print a triangle of asterisks of size n:

*
**
***
****
*****

We read the number, then map a block over [1..n], turning each number into asterisks followed by a newline:

read-num range1 m: "*" times new-line

Then gs2c can compile this, and gs2 can run the resulting file:

$ python gs2c.py < stars > compiled && echo 7 | python gs2.py compiled
*
**
***
****
*****
******
*******

Our solution is 7 bytes long: 56 2f fe 07 2a 32 0a. This is pretty good compared to GolfScript's 11.