koneko: a concatenative not-quite-lisp for kittens

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+

koneko - a concatenative not-quite-lisp for kittens

→ Description, → Whirlwind Tour, → Language Reference, → More Examples, → Doctests;
→ Installing, → Running, → (Build) Requirements, → Specs & Docs, → Vim Syntax Highlighting;
→ TODO, → License

Description

NB: work in progress.

Koneko (子猫 -- "kitten" in Japanese) is a simple functional concatenative stack-based programming language with Lisp (& Haskell) influences. It is intended to combine the elegance of the (point-free) "concatenation is composition" model with the elegance of Lisp-like languages.

→ Try koneko in your browser with the JavaScript REPL.

Properties

• concatenative
  • point-free
  • juxtaposition of expressions denotes function composition
• stack-oriented
  • postfix (reverse polish) notation
  • functions consume arguments from the stack
  • functions produce return values on the stack
• Lisp-like
  • homoiconic
  • blocks (anonymous functions, similar to lambdas)
  • named parameters/points (lexically scoped)
• functional
  • only immutable data structures
  • does have side effects (I/O)
  • (mostly) strict evaluation
• dynamically, strongly typed

Features

• primitive (built-in):
  • primitive data types: nil, bool, int, float, str, kwd
  • composite data types: pair, list, dict
  • multi(method)s (similar to multiple dispatch & type classes)
  • records (similar to algebraic data types)
  • modules
  • regexes (mostly Perl-compatible and thus not actually "regular" expressions)
  • concurrency (& parallelism)
  • exception handling
  • thunks
• prelude (standard library):
  • stack shuffling
  • combinators (stack-oriented higher-order functions)
  • arithmetic
  • string operations
  • ranges, lazy sequences & sequence operations
  • slicing & associative structure operations
  • looping & basic I/O
  • either, functor, monad
• nil punning
• syntactic sugar (on top of a minimal "core language")

Whirlwind Tour

Hello World

$ koneko -e '"Hello, World!" say!'
hello, World!

REPL

$ koneko
>>> "Hello, World!" say!
Hello, World!
>>> ^D

The Weird (& Wonderful)

>>> 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 ***

NB: use whitespace to separate tokens since "special" characters like + and ( are not delimiters but valid parts of identifiers.

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

Details: → Language Features, → Ident(ifiers) & Quoting

Data Types

NB: all data types are immutable.

>>> ()                            ; 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 => }

NB: nil and #f are falsy, everything else is truthy.

>>> , :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

Details: → Primitive Data Types, → Pairs, Lists & Dicts, → Records

Functions

>>> , 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

NB: since purely concatenative programs contain no free variables, almost any "subexpression" can be "factored out" simply by giving it a name.

>>> , :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

Details: → Functions, → Multi(method)s

Primitives & Prelude

Details: → Primitives, Builtins & Prelude, → Prelude: Syntax Highlighted Source, → Prelude: Function Index

>>> , :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!

Stack Shuffling

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

Combinators

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

Syntactic Sugar

>>> 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

Details: → Syntactic Sugar

Examples

>>> , :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

Language Reference

→ 01: Language Features,
→ 02: Ident(ifiers) & Quoting,
→ 03: Primitive Data Types,
→ 04: Pairs, Lists & Dicts,
→ 05: Functions,
→ 06: Multi(method)s,
→ 07: Records,
→ 08: Syntactic Sugar,
→ 09: Primitives, Builtins & Prelude,
→ 10: Standard Library,
→ 11: Possible Future Extensions

Prelude

→ Syntax Highlighted Source, → Function Index

More Examples

→ More Examples

Doctests

Like Python (& Haskell), koneko supports "doctests": executable pieces of documentation that look like interactive REPL sessions. Doctests make it easy to write user tutorials, documentation, and regression tests at the same time and confirm that examples in documentation are correct and up to date.

NB: this README, the Language Reference, and koneko's Prelude & Standard Library are full of doctests.

Lets look at an example, mylib.knk:

: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

We run koneko with the --doctest option (in this case also with -v for verbosity) to execute the tests in a koneko -- or markdown -- file:

$ KONEKOPATH=. koneko --doctest -v mylib.knk
=== Testing mylib.knk (koneko) ===
Trying:
  :mylib use
Expecting:
ok
Trying:
  , 1 2 s!
Expecting:
  --- STACK ---
  2
  1
  ---  END  ---
ok
Trying:
  , myswap s!
Expecting:
  --- STACK ---
  1
  2
  ---  END  ---
ok
Total: 3, Tried: 3, Passed: 3, Failed: 0.
=== Summary ===
Total: 3, Tried: 3, Passed: 3, Failed: 0.
Test passed.

=== Summary ===
Files: 1.
Total: 3, Tried: 3, Passed: 3, Failed: 0.
Test passed.

NB: for :mylib use to be able to load the mylib.knk file we need to add the current directory to KONEKOPATH.

Installing

See (Build) Requirements.

... TODO ...

Running

Linux (& Probably macOS and *BSD)

$ make cabal_build                            # Haskell Build
$ ./scripts/repl_hs                           # Haskell REPL

$ ./scripts/repl_js                           # Node.js REPL
$ make repl_browser                           # Browser REPL

Windows (Untested)

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

$ node js\koneko                              # Node.js REPL

... TODO ...

(Build) Requirements

The Haskell implementation requires the Haskell Platform (and a few additional libraries that the Cabal build system provided with the Platform can install); see koneko.cabal for the dependencies.

The JavaScript implementation requires Node.js.

Debian

$ apt install haskell-platform libghc-aeson-dev \
  libghc-cmdargs-dev libghc-doctest-dev libghc-hashtables-dev \
  libghc-megaparsec-dev libghc-regex-pcre-dev \
  libghc-safe-dev libghc-silently-dev         # Haskell version
$ apt install nodejs                          # Node.js version
$ apt install rlwrap                          # (readline support)

Specs & Docs

$ make cabal_build test_haskell               # Haskell
$ make test_node                              # JavaScript

TODO: haddock

Vim Syntax Highlighting

$ make link_vim_syntax    # symlinks misc/vim/ files from ~/.vim
$ make copy_vim_syntax    # copies   misc/vim/ files to   ~/.vim

TODO

• finish design
• finish documentation
• finish implementation
• ???
• profit!

License

Interpreter(s)

Standard Library

(i.e. lib/*.knk)