From ce3cde5918f08afcc496d1836df14a63cfafb2cc Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Mon, 14 Aug 2023 15:07:24 -0400 Subject: [PATCH 01/11] Initial lib/math.tcl docs --- docs/lib/math.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/lib/math.md diff --git a/docs/lib/math.md b/docs/lib/math.md new file mode 100644 index 00000000..ae70e70e --- /dev/null +++ b/docs/lib/math.md @@ -0,0 +1,22 @@ +# Math library + +## 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`. + + +--- +CC-BY-SA 2023 Arcade Wise +(We can change the license if y'all want, I just wanted to avoid copyright issues) \ No newline at end of file From ba222b45bc5e0a98bd4197bbd1cc9ef88b0e9980 Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Tue, 15 Aug 2023 15:30:02 -0400 Subject: [PATCH 02/11] language.tcl docs --- docs/lib/language.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/lib/language.md diff --git a/docs/lib/language.md b/docs/lib/language.md new file mode 100644 index 00000000..e5fcfcbd --- /dev/null +++ b/docs/lib/language.md @@ -0,0 +1,28 @@ +# 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. From ed30796ac5664ba3da6b76633634f86fb7410d61 Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Wed, 16 Aug 2023 09:07:02 -0400 Subject: [PATCH 03/11] finish math.tcl --- docs/lib/math.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/docs/lib/math.md b/docs/lib/math.md index ae70e70e..1a427977 100644 --- a/docs/lib/math.md +++ b/docs/lib/math.md @@ -1,5 +1,15 @@ # 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` @@ -14,8 +24,44 @@ A `vec2` is a 2d vector, i.e. a structure that stores 2 number, and can preform - `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`. +- `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` +- `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 width Y 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 ` ` 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 From 6de3ae4bf611d8f2ce9d8dfae4a8a36ae2d985cc Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Wed, 16 Aug 2023 10:27:35 -0400 Subject: [PATCH 04/11] Document environment.tcl --- docs/lib/environment.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/lib/environment.md diff --git a/docs/lib/environment.md b/docs/lib/environment.md new file mode 100644 index 00000000..515c4b71 --- /dev/null +++ b/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) \ No newline at end of file From 5af8e2b3504c0b7ea3698cf604dc158ec85c4a14 Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Wed, 16 Aug 2023 13:23:37 -0400 Subject: [PATCH 05/11] Document peer.tcl --- docs/lib/peer.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 docs/lib/peer.md diff --git a/docs/lib/peer.md b/docs/lib/peer.md new file mode 100644 index 00000000..ecb78c2c --- /dev/null +++ b/docs/lib/peer.md @@ -0,0 +1,24 @@ +# 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: + + - `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) \ No newline at end of file From 2d03b5d2b7814934173ccfeb3a0dff457bf6fb0b Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Wed, 16 Aug 2023 13:30:55 -0400 Subject: [PATCH 06/11] Fix peer.md --- docs/lib/peer.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/lib/peer.md b/docs/lib/peer.md index ecb78c2c..e9f24133 100644 --- a/docs/lib/peer.md +++ b/docs/lib/peer.md @@ -6,6 +6,15 @@ 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` + + + + --- CC-BY-SA 2023 Arcade Wise From d8ff17ab8dd4e111d493bb6d349d7d5009d41ef6 Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Mon, 28 Aug 2023 15:11:48 -0400 Subject: [PATCH 07/11] document lib/process.tcl --- docs/lib/language.md | 4 ++++ docs/lib/process.md | 20 ++++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 docs/lib/process.md diff --git a/docs/lib/language.md b/docs/lib/language.md index e5fcfcbd..581da36b 100644 --- a/docs/lib/language.md +++ b/docs/lib/language.md @@ -26,3 +26,7 @@ ## 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) \ No newline at end of file diff --git a/docs/lib/process.md b/docs/lib/process.md new file mode 100644 index 00000000..081bc2e3 --- /dev/null +++ b/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) \ No newline at end of file From a809c690e853c4440cd0dd1a2b19937bc3bb896b Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Tue, 29 Aug 2023 10:12:34 -0400 Subject: [PATCH 08/11] Update `lib/math.md` --- docs/lib/math.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/lib/math.md b/docs/lib/math.md index 1a427977..783b514e 100644 --- a/docs/lib/math.md +++ b/docs/lib/math.md @@ -44,6 +44,10 @@ those vertices. - `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` From 9cd7077b4d015cd1b65a74ed924e89586c587276 Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Wed, 30 Aug 2023 09:59:57 -0400 Subject: [PATCH 09/11] semi-incomplete documenation of `lib/trie.tcl` --- docs/lib/trie.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/lib/trie.md diff --git a/docs/lib/trie.md b/docs/lib/trie.md new file mode 100644 index 00000000..a8e4a45b --- /dev/null +++ b/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) From 8948562a6fb29acc017e9a3b5cf1fcce6d1fa31f Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Wed, 30 Aug 2023 10:03:31 -0400 Subject: [PATCH 10/11] Add links from the code.md file --- docs/code.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/code.md b/docs/code.md index cffd554e..34276d19 100644 --- a/docs/code.md +++ b/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. From c5e5879ddd54c68c2d13afc0e6052eb5bda1b939 Mon Sep 17 00:00:00 2001 From: Arcade Wise Date: Wed, 6 Sep 2023 14:09:48 -0400 Subject: [PATCH 11/11] start on c --- docs/lib/c.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/lib/c.md diff --git a/docs/lib/c.md b/docs/lib/c.md new file mode 100644 index 00000000..21068f23 --- /dev/null +++ b/docs/lib/c.md @@ -0,0 +1,28 @@ +# C FFI Library + +
+ Allowed type for arguments: + +- `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 +- `*`: pointers to anything above + +
+ +## 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)