Document library!

docs/code.md

@@ -20,6 +20,13 @@
        other people wrote
 5. `lib`
     1. Tcl/Folk libraries that we wrote, as well as the C FFI and the C trie
+        - [`/lib/environment.tcl`](./lib/environment.md)
+        - [`/lib/language.tcl`](./lib/language.md)
+        - [`/lib/math.tcl`](./lib/math.md)
+        - [`/lib/peer.tcl`](./lib/peer.md)
+        - [`/lib/process.tcl`](./lib/process.md)
+        - [`/lib/trie.tcl`](./lib/trie.md)
+
 6. `virtual-programs`
     1. Our own high-level Folk programs
     2. They could be printed out... Perhaps, should be.

docs/lib/c.md

@@ -0,0 +1,28 @@
+# C FFI Library
+
+<details>
+    <summary>Allowed type for arguments:</summary>
+
+- `int`: signed integers
+- `double`: high-precision floating point number
+- `bool`: boolean value
+- `int32_t`: 32 bit signed integer
+- `char`: 1 character
+- `size_t`: unsigned integer type used to represent the size of objects in bytes
+- `intptr_t`: an integer value that is safe to convert to a pointer
+- `uint16_t`: unsigned 16 bit integer
+- `uint32_t`: unsigned 32 bit integer
+- `uint64_t`: unsigned 64 bit integer
+- `char*`: string (i.e. a null terminated array of characters, starting at a pointer to a char)
+- `Tcl_Obj*`: a pointer to a Tcl object
+- `<above>*`: pointers to anything above
+
+</details>
+
+## C namespace
+
+- `create {}`: creates and returns a new C FFI interface
+
+---
+CC-BY-SA 2023 Arcade Wise
+(We can change the license if y'all want, I just wanted to avoid copyright issues)

docs/lib/environment.md

@@ -0,0 +1,10 @@
+# Environment
+
+## functions
+
+- `serializeEnvironment`: Get all variables and serialize them, to fake lexical scope
+- `runInSerializedEnvironment {lambda env}`: run the lambda `lambda` in the serialized environment `env`
+
+---
+CC-BY-SA 2023 Arcade Wise
+(We can change the license if y'all want, I just wanted to avoid copyright issues)

docs/lib/language.md

@@ -0,0 +1,32 @@
+# Tcl extensions
+
+'Language' utilities that extend and customize base Tcl.
+
+## Language features
+
+- `fn {name args body}`: creates a lexically scoped function in folk
+    Example:
+
+    ```tcl
+    fn text {coords text angle} {
+        Display::text [lindex $coords 0] [lindex $coords 1] 2 $text $angle
+    }
+    ```
+
+- `forever { ... }`: Works like `while true { ... }`, but yiels to the event loop, so it's safe to use in the context of folk
+- `assert { condition }`: if condition evaluates to not true, it will error out and return the error code
+
+## Functions
+
+- `python3 { ... }`: evaluate the body in python3
+- `lenumerate { list }`: enumarate over a list, that is, return each of the elements in the list in the form `{ index element }`
+- `ltrim { list }`: remove empty items at the beginning and the end of the list
+- `undent { msg }`: trims the indentation from msg, as long as it is made of spaces
+
+## Imports
+
+`language.tcl` brings all of `::tcl::mathop` and `::tcl::mathfunc` into the global namespace.
+
+---
+CC-BY-SA 2023 Arcade Wise
+(We can change the license if y'all want, I just wanted to avoid copyright issues)

docs/lib/math.md

@@ -0,0 +1,72 @@
+# Math library
+
+Utility functions for math objects.  
+
+## functions
+
+- `rectanglesOverlap {P1 P2 Q1 Q2 strict}` determine if the rectangles defined by the corner points `P1 P2` and `Q1 Q2`. Strict is a bool that indicates if the answer is strictly determined. (From: Cormen, Leiserson, and Rivests' "Algorithms", page 889)
+- `regionToBbox {r}`: converts a region `r` to its bounding box, returns a list of `{minimum_x minimum_y maximum_x maximum_y}`
+- `boxCentroid {box}`: returns the centroid of the box `box`
+- `boxWidth {box}`: returns the width of the box `box`
+- `boxHeight {box}`: returns the height of the box `box`
+
+## namespaces
+
+### `vec2`
+
+A `vec2` is a 2d vector, i.e. a structure that stores 2 number, and can preform operations upon it. In Tcl they are represented by a list of 2 numbers.
+
+- `add {a b}`: adds the respective pairs of x and y values together
+- `sub {a b}`: subracts the respective pairs of Xb and Yb from Xa and Ya
+- `scale {a args}`: if args is 1 value, scale both values by it, if it's 2 values, scale Xa by Xargs and Ya by Yargs
+- `rotate {a theta}`: rotate the values in a by theta
+- `distance {a b}`: calculates the euclidean distance (the length of a line segment between the two points)
+- `normalize {a}`: normalizes the vector by dividing each value by the magnitude of the vector
+- `dot {a b}`: calculate the dot product of the two vectors, basically, calculates how much two vectors point in the same direction.
+- `distanceToLineSegment {a v w}`: returns the distance to the line segment defined by v and w
+- `midpoint {a b}`: returns the midpoint of the line segment defined by `a b`.
+
+### `region`
+
+A region is an arbitrary oriented chunk of a plane. The
+archetypal region is the region of a program/page, which is the
+quadrilateral area of space that is covered by that page. A
+region is defined by a set of vertices and a set of edges among
+those vertices.
+
+- `create {vertices edges {angle 0}}`: create a region with the given vertices and edges, and optional angle.
+- `vertices {r}`: return the vertices of the region `r`
+- `edges {r}`: return the edges of the region `r`
+- `angle {r}`: return the angle of the region `r`
+- `width {r}`: return the width of the region `r` in screen space, acounting for rotation.
+- `height {r}`: return the height of the region `r` in screen space, acounting for rotation.
+- `top {r}`: return the vec2 point at the top of the region `r`
+- `left {r}`: return the vec2 point to the left of the region `r`
+- `right {r}`: return the vec2 point to the right of the region `r`
+- `bottom {r}`: return the vec2 point at the bottom of the region `r`
+- `bottomleft {r}`: return the vec2 point at the bottom left of the region `r`
+- `bottomright {r}`: return the vec2 point at the bottom right of the region `r`
+- `topleft {r}`: return the vec2 point at the top left of the region `r`
+- `topright {r}`: return the vec2 point at the top right of the region `r`
+- `mapVertices {varname r body}`: apply the body for each vector `varname` in region `r`
+- `distance {r1 r2}`: calculate the distance between regions `r1` and `r2`
+- `contains {r p}`: check if the region `r` contains the point `p`
+- `intersects {r1 r2}`: check if region `r1` intersects with region `r2`
+- `centroid {r}`: only works for rectangular regions! returns the point that is the centroid of the region `r`
+- `rotate {r angle}`: returns a region `r'` that has been rotated by `angle`
+- `scale {r args}`: Accepts values in `px`, `%`, and unmarked. If 1 arg, scale all by that arg, otherwise accepts `X<unit> width Y<unit> height`
+- `move {r args}`: Moves the region left/right/up/down on the x and y axies of the region, not the global x and y. Args in the format `<AMMOUNT><UNIT> <DIRECTION>` where unit is one of the units that scale supports, and direction is left/right/up/down.
+
+## TODO:
+
+- [ ] Rewrite in C
+- [ ] Triangulate a region
+- [ ] Average the centroids of all triangles in a region
+- [ ] Rename `regionToBbox`
+- [ ] Assert that `box` is actually a box
+- [ ] Optimize `scale`
+- [ ] Allow areas in regions to be filled/unfilled
+
+---
+CC-BY-SA 2023 Arcade Wise
+(We can change the license if y'all want, I just wanted to avoid copyright issues)

docs/lib/peer.md

@@ -0,0 +1,35 @@
+# peer
+
+Adds "./vendor" to the `auto_path` variable.
+
+Creates a `peersBlacklist` dict.
+
+## functions
+
+- `::peer {process {dieOnDisconnect false}}`: creates a namespace `::Peers::$process` with the following functions:
+  - `share {statements}`: share the statements `statements` to the given peer
+  - `recieve`: recieve from the given peer
+  - `init {n shouldDieOnDisconnect}`: set `process` to `n`, set dieOnDisconnect, and connect through `Mailbox`
+
+<!-- 
+OLD DOCS
+## functions
+
+- `::peer {process {dieOnDisconnect false}}`: creates a namespace `::Peers::$process` with the following functions:
+
+  - `log {s}`: Log the process name and the string `s`
+  - `setupSock`: try and setup the websocket connection
+  - `handleWs {chan type msg}`: depending on the type, handle a websocket message or error out
+    - type "connect": log connected, and establish a peering in reverse direction, which will implicitly run in a `::Peers::X` namespace
+    - type "disconnect": log disconnected, and if `dieOnDisconnect` is true, exit with code 0. Otherwise set `connected` to false and run `setupSock` after 2s
+    - type "error": log the error message `msg` and run `setupSock` after 2s
+    - type "text": evaluate `msg`
+    - type "ping" or "pong": do nothing
+  - `run {msg}`: send the message `msg` over the websocket channel, telling the remote instance to evaluate `msg`
+  - `init {n shouldDieOnDisconnect}`: set `process` to `n`, then setup the socket, set dieOnDisconnect value, and wait till `connected` becomes true -->
+
+
+
+---
+CC-BY-SA 2023 Arcade Wise
+(We can change the license if y'all want, I just wanted to avoid copyright issues)

docs/lib/process.md

@@ -0,0 +1,20 @@
+# Processes Library
+
+## functions
+
+- `On-process {name body}`: run `body` in a new process, setting up all the peering and lexical environment code
+
+## namespacs
+
+### Zygote
+
+The zygote is a process that's forked off during Folk
+startup. It can fork itself to create subprocesses on demand.
+
+- `init {}`: fork Folk to create a zygote process, setting the current state as the startup state for the subprocesses
+- `zygote {}`: the Zygote's main loop
+- `spawn {code}`: puts the pipe and `code`
+
+---
+CC-BY-SA 2023 Arcade Wise
+(We can change the license if y'all want, I just wanted to avoid copyright issues)

docs/lib/trie.md

@@ -0,0 +1,71 @@
+# Trie library
+
+Implements the statement trie datatype and operations. This data
+structure has 2 differences from the average trie you might have
+seen before.
+
+1. Its nodes are _entire tokens_, not characters.
+
+   `someone -> wishes -> 30 -> is -> labelled -> Hello World`
+
+   not
+
+   `s -> o -> m -> e -> o -> n -> e -> SPACE -> w -> i -> ...`
+
+   In other words, its alphabet is dynamic -- the set of all
+   tokens that programs are using in statements -- not 26
+   characters or whatever.
+
+2. Both search patterns and nodes can contain 'wildcards'.
+
+   This bidirectional matching is useful for incremental update.
+
+## namespaces
+
+### ctrie
+
+Implementation of the trie in c, using `lib/c.tcl`.
+
+#### Structs (in C)
+
+- `trie_t`: has a `key` which is a pointer to a `Tcl_Obj`, a bool for whether it has a value, a 64 bit field for either a pointer (for example, to a reaction thunk) or a generational handle (for example, for a statement), a list of branches and the size of said list
+
+#### Procs (in C)
+
+- `create {}`: creates a trie and returns it
+- `scanVariableC {Tcl_Obj* wordobj char* outVarName size_t sizeOutVarName}`: checks if the string in `wordobj` is viable??? (Not sure on this one)
+
+These functions operate on the Tcl string representation of a
+value _without_ coercing the value into a pure string first, so
+they avoid shimmering / are more efficient than using Tcl
+builtin functions like `regexp` and `string index`.
+
+- `scanVariable {Tcl_Obj* wordobj}`: same as `scanVariable`, but just Tcl code
+- `startsWithDollarSign {wordobj}`: returns whether `wordobj` starts with a '$'
+- `addImpl {trie_t** trie int wordc Tcl_Obj** wordv uint64_t value}`: add the implementation `wordv[1..]` to `wordv[0]`, growing the trie if necessary
+- `add {Tcl_Interp* interp trie_t** trie Tcl_Obj* clause uint64_t value}`: not sure, does something with adding an impl, and a tcl interpreter...
+- `addWithVar {Tcl_Interp* interp Tcl_Obj* trieVar Tcl_Obj* clause uint64_t value}`: same as above, but with a var?
+- `removeImpl {trie_t* trie int wordc Tcl_Obj** wordv}`: remove the implementation of `wordv[0]`
+- `remove {Tcl_Interp* interp trie_t* trie Tcl_Obj* clause}`: basically the same code as `add`, but with `removeImpl`
+- `removeWithVar {Tcl_Interp* interp Tcl_Obj* trieVar Tcl_Obj* clause}`: same as `addWithVar` but with `removeImpl`
+- `lookupImpl {Tcl_Interp* interp uint64_t* results int* resultsidx size_t maxresults trie_t* trie int wordc Tcl_Obj** wordv}`: lookup the implementation of `wordv[0]`, storing a pointer in `results`
+- `lookup {Tcl_Interp* interp uint64_t* results size_t maxresults trie_t* trie Tcl_Obj* pattern}`: same as `lookupImpl`, but returns the count and is safer?
+- `lookupTclObjs {Tcl_Interp* interp trie_t* trie Tcl_Obj* pattern}`: looks up a Tcl object based on `pattern`, and return a Tcl list of the objects
+- `tclify {trie_t* trie}`: returns a Tcl list based on `trie`
+
+#### Proc
+
+- `dot {trie}`: generate a dot graph of the trie
+
+### trie
+
+Compatibility with test/trie and old Tcl impl of trie.
+
+Includes all of `ctrie`.
+Renames `add` to `add_` and renames `addWithVar` to `add`.
+Renames `remove` to `remove_` and renames `removeWithVar` to `remove`.
+Renames `lookup` to `lookup_` and renames `lookupTclObjs` to `lookup`.
+
+---
+CC-BY-SA 2023 Arcade Wise
+(We can change the license if y'all want, I just wanted to avoid copyright issues)