Add modules documentation

Author: ProggerX

docs/index.md

@@ -1,3 +1,15 @@
 # lapse-hs
 
 Hello, this is official [Lapse](https://github.com/ProggerX/lapse-hs) documentation. Lapse is my LISP dialect that was created in educational purposes only.
+
+## Why use it?
+Lapse is really small language but it has some [modules](modules/index.md) for different use-cases.
+
+## Installation guide
+- Go to [this page](https://github.com/ProggerX/lapse-hs/actions/workflows/build.yml)
+- Click on latest successful action run from master (or run from specific commit)
+- Find an "Artifacts" section and download version for your OS. (If you can't see download button, log in to your github account)
+- Unzip this artifact and you will get an executable of Lapse interpreter
+- To run some code, write this code in ".lp" file (in fact, extension does not matter) and run `<path-to-lapse-interpreter> <path-to-file>` command in command line
+- (You can find example files [here](https://github.com/ProggerX/lapse-hs/blob/master/example/))
+- Also, Lapse provides a clean REPL by `<path-to-lapse-interpreter>` command

docs/modules/colors.md

@@ -0,0 +1,27 @@
+# ANSI terminal colors
+
+### Description
+Small module that allows you to type thing like `(blue "hello")` and produces string with that color (e.g. `"\e[0;34mhello\e[0m"`).
+
+### Import
+```
+(import "colors")
+```
+
+### Usage
+```
+(print $ blue "Hello, user!")
+```
+
+### Reference
+- `(black <string>)` -- produces black string.
+- `(red <string>)` -- produces red string.
+- `(green <string>)`  -- produces green string.
+- `(yellow <string>)` -- produces yellow string.
+- `(blue <string>)` -- produces blue string.
+- `(purple <string>)` -- produces purple string.
+- `(cyan <string>)` -- produces cyan string.
+- `(white <string>)`  -- produces white string.
+
+### Source
+[Source](https://github.com/ProggerX/lapse-hs/blob/master/modules/colors.lp)

docs/modules/fs.md

@@ -0,0 +1,25 @@
+# Filesystem
+
+### Description
+Module that allows you to interact with files.
+
+### Import
+```
+(import "fs")
+```
+
+### Usage
+```
+(print $ readF "text.txt")
+```
+
+### Reference
+- `(readF <string:filename>)` -- reads file as string and returns its text.
+- `(writeF <string:filename> <string:contents>)` -- writes contents to file.
+- `(appendF <string:filename> <string:contents>)` -- appends contents to file.
+- `(lsdir)` -- returns list of strings -- files in CWD.
+- `(lsdir <string:path>)` -- returns list of strings -- files in `path`.
+- `(chdir <string:path>)` -- changes CWD to `path`.
+
+### Source
+[Source](https://github.com/ProggerX/lapse-hs/blob/master/src/Lapse/Modules/FS.hs)

docs/modules/gcode.md

@@ -0,0 +1,41 @@
+# G-code generator
+
+### Description
+Module that allows you to generate G-code from human-readable LISP code and prints it to stdout.
+
+### Import
+```
+(import "gcode")
+```
+
+### Usage
+```
+(import "gcode")
+
+(init "plra4")
+(base)
+(go 5 50)
+(delta 5 -40)
+(down)
+(left 5)
+(right 20)
+(forward 50)
+(right 20)
+(backward 15)
+(base)
+(end)
+```
+
+### Reference
+- `(init <string:name>)` -- init G-code for machine with name `name` (runs `init_func` of machine).
+- `(machine <string:name> <function:init_func> <function:end_func>)` -- creates custom machine with name `name`, init `init_func` and end `end_func`.
+- `(end)` -- end of G-code (runs `end_func` of machine).
+- `(base)` -- go to base (`G0Z10`; `G0X0Y0`; disable cutting).
+- `(down)` -- enable cutting and run `G1Z<material-z>F<speed>`.
+- `(up)` -- disable cutting and run `G0Z10`.
+- `(go x y)` -- go to x, y (`G0X<x>Y<y>` or `G1X<x>Y<y>F<speed>`).
+- `(delta x y)` -- same as go, but relative to current position.
+- `left, right, forward, backward` -- extra functions on top of delta.
+
+### Source
+[Source](https://github.com/ProggerX/lapse-hs/blob/master/modules/gcode.lp)

docs/modules/index.md

@@ -0,0 +1,9 @@
+# Modules
+
+Lapse includes different modules:
+
+- [ANSI terminal colors](colors.md)
+- [G-code generator](gcode.md)
+- [Filesystem](fs.md)
+- [JSON](json.md)
+- [Web server and client](web.md)

docs/modules/json.md

@@ -0,0 +1,21 @@
+# JSON
+
+### Description
+Module that allows you to encode and decode JSON.
+
+### Import
+```
+(import "json")
+```
+
+### Usage
+```
+(print $ decode $ encode 5)
+```
+
+### Reference
+- `(encode <value:data>)` -- encodes `data` to JSON (Of course, it cannot store functions and macroses) and returns string.
+- `(decode <string:json-data>)` -- decodes JSON and returns value (All numbers become floats!)
+
+### Source
+[Source](https://github.com/ProggerX/lapse-hs/blob/master/src/Lapse/Modules/Json.hs)

docs/modules/web.md

@@ -0,0 +1,77 @@
+# Web (server and client)
+
+### Description
+Module that allows you to make small web servers and clients.
+
+### Import
+```
+(import "web")
+```
+
+### Usage
+#### Server
+```lisp
+-- Built for web client from examples
+
+(import "std" "web" "json")
+
+(defn greet (fn ln) (concat "Hello, " fn " " ln "!"))
+
+- Create a handler
+(defn f (fn ln) (encode $ dict
+  (first_name fn)
+  (last_name ln)
+  (greeting $ greet fn ln)))
+
+(defn fpost (txt fn ln) (concat txt " " fn " " ln))
+
+(defn echo (body) body)
+
+- Build + serve
+(serve
+  $ routeGET "/greet" (list "fname" "lname") f
+  $ routePOST "/post" (list "fname" "lname") fpost
+  $ routePOST "/echo" () echo
+  $ server 2025)
+```
+#### Client
+```lisp
+-- Uses web server from examples
+
+(import "web" "std" "io" "json")
+
+- Build request
+(set rget $ send
+  $ withParam "fname" "John"
+  $ withParam "lname" "Black"
+  $ get "http://localhost:2025/greet")
+
+- Print response
+(print $ concat "Got response: " $ show rget)
+(print "Body:")
+(print $ resBody rget)
+
+- Decode JSON and get a greeting
+(set gr $ lookup greeting $ fst $ decode $ resBody rget)
+
+(print "Greeting:")
+(print gr)
+```
+
+### Reference
+#### Server
+- `(server <number:port>)` -- creates a web server on port `port`.
+- `(routeGET <string:path> <list of strings:params> <function(params -> string):handler> <server>)` -- adds GET route to `server`.
+- `(routePOST <string:path> <list of strings:params> <function(body, params -> string):handler> <server>)` -- adds POST route to `server`.
+- `(serve <server>)` -- serves a server.
+#### Client
+- `(get <string:url>)` -- creates a GET request to `url`.
+- `(post <string:url>)` -- creates a POST request to `url`.
+- `(withParam <string:name> <string or list of strings:value(s)>)` -- adds param to request.
+- `(withBody <string:body>)` -- adds body to request.
+- `(send <request>)` -- sends `request` and returns response.
+- `(resStatus <response>)` -- returns statusCode of `response`.
+- `(resBody <response>)` -- returns body of `response`.
+
+### Source
+[Source](https://github.com/ProggerX/lapse-hs/tree/master/src/Lapse/Modules/Web)

example/gcode.lp

@@ -1,4 +1,4 @@
-(import "std" "io" "gcode")
+(import "gcode")
 
 (init "plra4")
 (base)

mkdocs.yml

@@ -1,4 +1,11 @@
 site_name: Lapse Docs
 nav:
   - Lapse: index.md
+  - Modules:
+    - Index: modules/index.md
+    - Colors: modules/colors.md
+    - G-code: modules/gcode.md
+    - FS: modules/fs.md
+    - JSON: modules/json.md
+    - Web: modules/web.md
 theme: readthedocs