koneko

File : README.md
Maintainer : Felix C. Stegerman
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.**

$3

* 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

$3

* 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

$3

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

$3

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

$3

`koneko
>>> 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
#
>>> 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.

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

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

$3

NB: all data types are immutable.

`koneko
>>> () ; 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.

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

$3

`koneko
>>> , 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.

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

$3

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

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

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

#### Combinators

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

$3

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

$3

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

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

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

$3

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

`koneko
: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:

`bash
$ 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

$3

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

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

$3

`
$ 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.

$3

`bash
$ 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

`bash
$ make cabal_build test_haskell # Haskell
$ make test_node # JavaScript
`

TODO: haddock

Vim Syntax Highlighting

`bash
$ 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

$3

![GPLv3+](https://www.gnu.org/licenses/gpl-3.0.html)

$3

(i.e. lib/*.knk`)