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. 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) 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 diff --git a/docs/lib/language.md b/docs/lib/language.md new file mode 100644 index 00000000..581da36b --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/lib/math.md b/docs/lib/math.md new file mode 100644 index 00000000..783b514e --- /dev/null +++ b/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 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 +(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/peer.md b/docs/lib/peer.md new file mode 100644 index 00000000..e9f24133 --- /dev/null +++ b/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` + + + + + +--- +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 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)