File        : README.md
Maintainer  : Felix C. Stegerman <flx@obfusk.net>
Date        : 2022-02-12

Copyright   : Copyright (C) 2022  Felix C. Stegerman
Version     : v0.0.2
License     : GPLv3+, LGPLv3+

>>> 1 2 +                     ; postfix notation
3

>>> drop                      ; functions manipulate the stack
>>> ( 3 4 )                   ; literals push a value onto the stack
( 3 4 )

>>> len dup                   ; unquoted identifiers are calls
2
>>> '+                        ; quoted identifiers push themselves
#<multi:2:+>
>>> call                      ; and can then be called explicitly
4

>>> ( 1 2 3 )
( 1 2 3 )
>>> reverse show              ; concatenation is function composition
"( 3 2 1 )"

>>> ( 4 5, 6 )                ; commas are whitespace
( 4 5 6 )

; unless a line starts with a comma, the command-line repl will print
; the top of the stack after evaluating it
>>> , 7 2
>>> -
5

>>> ,s!                       ; show the stack (non-browser repl only)
--- STACK ---
5
( 4 5 6 )
"( 3 2 1 )"
4
---  END  ---
>>> clear-stack!              ; clear the stack (repl only)
*** STACK CLEARED ***

>>> 1 2+
*** ERROR: name 2+ is not defined
>>> (1 2)
*** ERROR: name (1 is not defined

>>> ()                            ; empty list
()
>>> ( nil #t #f )                 ; list containing nil, true & false
( nil #t #f )
>>> ( 1 2 + 4 )                   ; nested expressions are evaluated
( 3 4 )

>>> 32 0x20 0b100000              ; integers
32
>>> 3.14                          ; floating point
3.14

>>> "spam & eggs"                 ; string
"spam & eggs"
>>> :foo                          ; keyword (aka symbol)
:foo

>>> :answer 42 =>                 ; key/value pair
:answer 42 =>
>>> { x: 42, :y 99 1 + => }       ; dict: key/value map
{ :x 42 =>, :y 100 => }

>>> , :Point ( :x :y ) defrecord  ; define record type
>>> Point( 1 -1 )                 ; "list" constructor
Point{ :x 1 =>, :y -1 => }
>>> Point{ y: -1, x: 1 }          ; "dict" constructor
Point{ :x 1 =>, :y -1 => }
>>> .x                            ; field access
1

>>> , 2 7                                 ; push 2 and 7
>>> [ swap - ]                            ; push a block
[ swap - ]
>>> call                                  ; call the block
5
>>> , :swap-and-subtract [ swap - ] def   ; named block
>>> 2 7 swap-and-subtract
5

>>> , :myswap [ x y . 'y 'x ] def         ; named parameters
>>> , 1 2 myswap s!
--- STACK ---
1
2
---  END  ---

>>> 1 2 [ x y . y x ] call                ; remember to quote non-calls
*** ERROR: type int is not callable
>>> [1 +]                                 ; remember to use whitespace
*** ERROR: name [1 is not defined

>>> , :inc [ 1 + ] def          ; naming things
>>> 41 'inc call                ; explicit call
42

>>> 1 2 <                       ; comparison: = not= < <= > >=
#t
>>> [ :less ] [ :not-less ] if  ; conditional
:less

>>> ( 42 ) show                 ; convert to readable str
"( 42 )"
>>> "foo" show
"\"foo\""

>>> , "Hello!" say!             ; print line
Hello!

>>> 1 2 swap drop dup +         ; swap, drop the 1, dup the 2, add
4

>>> , 35 [ 2 + ] [ 7 + ] bi     ; call two functions on 1 value
>>> , s!
--- STACK ---
42
37
---  END  ---

>>> answer: 42                      ; pair w/ single-token value
:answer 42 =>
>>> { x: 1, y: 2 }                  ; dict literal
{ :x 1 =>, :y 2 => }

>>> 1 ( 2 3 ) !cons                 ; field call (field access + call)
( 1 2 3 )

>>> '.x                             ; quoted field access
[ :x __swap__ __call__ ]
>>> '!x                             ; quoted field call
[ :x __swap__ __call__ __call__ ]

>>> '[ 2 * '1 div ]                 ; "curried" block w/ "holes"
[ __1__ . [ 2 * '__1__ div ] ]
>>> 3 swap call                     ; "fill" the hole from the stack
[ 2 * '__1__ div ]
>>> 5 swap call
3

>>> , :fibs ( 0 1 ) [ 'fibs dup rest '+ zip ] lseq def
>>> 'fibs 10 take-first ->list
( 0 1 1 2 3 5 8 13 21 34 )
>>> 'fibs 10 nth
55

>>> "" 0.0 0.0 / show .[ '1 ++ ] 10 times " batman!" ++ say!
NaNNaNNaNNaNNaNNaNNaNNaNNaNNaN batman!

>>> 15 [1-n] [ dup 3 "fizz" 5 "buzz" '[ '1 div? '2 "" ? ] 2bi$ bi
...            ++ 'show 'nip ~seq say! ] each
1
2
fizz
4
buzz
fizz
7
8
fizz
buzz
11
fizz
13
14
fizzbuzz

:mylib defmodule[

; swap top 2 values
;
; >>> :mylib use
; >>> , 1 2 s!
; --- STACK ---
; 2
; 1
; ---  END  ---
; >>> , myswap s!
; --- STACK ---
; 1
; 2
; ---  END  ---

:myswap [ x y . 'y 'x ] def

] ; defmodule

$ cabal v2-build --write-ghc-environment-files=always --enable-tests
$ cabal v2-run koneko                         # Haskell REPL

$ node js\koneko                              # Node.js REPL