docs revamp

This commit is contained in:
2025-12-17 02:53:01 -06:00
parent 3211b59408
commit 363ca1c3c1
33 changed files with 2308 additions and 1439 deletions

10
docs/library/.pages Normal file
View File

@@ -0,0 +1,10 @@
nav:
- text.md
- number.md
- array.md
- object.md
- blob.md
- time.md
- math.md
- json.md
- random.md

151
docs/library/array.md Normal file
View File

@@ -0,0 +1,151 @@
# array
The `array` function and its methods handle array creation and manipulation.
## Creation
### array(number)
Create an array of specified size, filled with `null`.
```javascript
array(3) // [null, null, null]
```
### array(number, initial)
Create an array with initial values.
```javascript
array(3, 0) // [0, 0, 0]
array(3, i => i * 2) // [0, 2, 4]
```
### array(array)
Copy an array.
```javascript
var copy = array(original)
```
### array(array, from, to)
Slice an array.
```javascript
array([1, 2, 3, 4, 5], 1, 4) // [2, 3, 4]
array([1, 2, 3], -2) // [2, 3]
```
### array(array, another)
Concatenate arrays.
```javascript
array([1, 2], [3, 4]) // [1, 2, 3, 4]
```
### array(object)
Get keys of an object.
```javascript
array({a: 1, b: 2}) // ["a", "b"]
```
### array(text)
Split text into grapheme clusters.
```javascript
array("hello") // ["h", "e", "l", "l", "o"]
array("👨‍👩‍👧") // ["👨‍👩‍👧"]
```
### array(text, separator)
Split text by separator.
```javascript
array("a,b,c", ",") // ["a", "b", "c"]
```
### array(text, length)
Split text into chunks.
```javascript
array("abcdef", 2) // ["ab", "cd", "ef"]
```
## Methods
### array.for(arr, fn, reverse, exit)
Iterate over elements.
```javascript
array.for([1, 2, 3], function(el, i) {
log.console(i, el)
})
// With early exit
array.for([1, 2, 3, 4], function(el) {
if (el > 2) return true
log.console(el)
}, false, true) // prints 1, 2
```
### array.find(arr, fn, reverse, from)
Find element index.
```javascript
array.find([1, 2, 3], 2) // 1
array.find([1, 2, 3], x => x > 1) // 1
array.find([1, 2, 3], x => x > 1, true) // 2 (from end)
```
### array.filter(arr, fn)
Filter elements.
```javascript
array.filter([1, 2, 3, 4], x => x % 2 == 0) // [2, 4]
```
### array.reduce(arr, fn, initial, reverse)
Reduce to single value.
```javascript
array.reduce([1, 2, 3, 4], (a, b) => a + b) // 10
array.reduce([1, 2, 3, 4], (a, b) => a + b, 10) // 20
```
### array.sort(arr, select)
Sort array (returns new array).
```javascript
array.sort([3, 1, 4, 1, 5]) // [1, 1, 3, 4, 5]
// Sort by field
array.sort([{n: 3}, {n: 1}], "n") // [{n: 1}, {n: 3}]
// Sort by index
array.sort([[3, "c"], [1, "a"]], 0) // [[1, "a"], [3, "c"]]
```
## Map with array()
The `array(arr, fn)` form maps over elements:
```javascript
array([1, 2, 3], x => x * 2) // [2, 4, 6]
array([1, 2, 3], function(el, i) {
return el + i
}) // [1, 3, 5]
```

182
docs/library/blob.md Normal file
View File

@@ -0,0 +1,182 @@
# blob
Blobs are binary large objects — containers of bits (not bytes). They're used for encoding data, messages, images, network payloads, and more.
## States
A blob exists in one of two states:
- **antestone** (mutable) — write operations allowed
- **stone** (immutable) — read operations allowed
```javascript
var blob = use('blob')
var b = blob.make() // antestone
blob.write_bit(b, 1)
blob.write_fit(b, 42, 8)
stone(b) // now stone, readable
```
## Creation
### blob.make()
Create an empty blob.
```javascript
var b = blob.make()
```
### blob.make(capacity)
Create with initial capacity (bits).
```javascript
var b = blob.make(1024) // 1024 bits capacity
```
### blob.make(length, logical)
Create filled with zeros or ones.
```javascript
blob.make(64, false) // 64 zero bits
blob.make(64, true) // 64 one bits
```
### blob.make(blob, from, to)
Copy a range from another blob.
```javascript
var slice = blob.make(original, 0, 32) // first 32 bits
```
## Writing (antestone only)
### blob.write_bit(b, logical)
Append a single bit.
```javascript
blob.write_bit(b, true) // append 1
blob.write_bit(b, false) // append 0
```
### blob.write_fit(b, value, length)
Append a fixed-width integer.
```javascript
blob.write_fit(b, 255, 8) // 8-bit value
blob.write_fit(b, 1000, 16) // 16-bit value
```
### blob.write_blob(b, other)
Append another blob's contents.
```javascript
blob.write_blob(b, other_blob)
```
### blob.write_dec64(b, number)
Append a 64-bit DEC64 number.
```javascript
blob.write_dec64(b, 3.14159)
```
### blob.write_text(b, text)
Append text (kim-encoded length + characters).
```javascript
blob.write_text(b, "hello")
```
### blob.write_pad(b, block_size)
Pad to block boundary (1 bit + zeros).
```javascript
blob.write_pad(b, 8) // pad to byte boundary
```
## Reading (stone only)
### blob.read_logical(b, from)
Read a single bit.
```javascript
var bit = blob.read_logical(b, 0) // first bit
```
### blob.read_fit(b, from, length)
Read a fixed-width integer.
```javascript
var value = blob.read_fit(b, 0, 8) // read 8 bits from position 0
```
### blob.read_blob(b, from, to)
Extract a range as new blob.
```javascript
var slice = blob.read_blob(b, 8, 24) // bits 8-23
```
### blob.read_dec64(b, from)
Read a 64-bit DEC64 number.
```javascript
var num = blob.read_dec64(b, 0)
```
### blob.read_text(b, from)
Read kim-encoded text.
```javascript
var str = blob.read_text(b, 0)
```
### blob.pad?(b, from, block_size)
Check if padding is valid.
```javascript
if (blob["pad?"](b, pos, 8)) {
// valid byte-aligned padding
}
```
## Length
```javascript
length(b) // returns bit count
```
## Example
```javascript
var blob = use('blob')
// Encode a simple message
var msg = blob.make()
blob.write_fit(msg, 1, 8) // message type
blob.write_fit(msg, 42, 32) // payload
blob.write_text(msg, "hello") // text data
stone(msg)
// Decode
var type = blob.read_fit(msg, 0, 8)
var payload = blob.read_fit(msg, 8, 32)
var txt = blob.read_text(msg, 40)
```

90
docs/library/json.md Normal file
View File

@@ -0,0 +1,90 @@
# json
JSON encoding and decoding.
```javascript
var json = use('json')
```
## Encoding
### json.encode(value, space, replacer, whitelist)
Convert a value to JSON text.
```javascript
json.encode({a: 1, b: 2})
// '{"a":1,"b":2}'
// Pretty print with 2-space indent
json.encode({a: 1, b: 2}, 2)
// '{
// "a": 1,
// "b": 2
// }'
```
**Parameters:**
- **value** — the value to encode
- **space** — indentation (number of spaces or string)
- **replacer** — function to transform values
- **whitelist** — array of keys to include
```javascript
// With replacer
json.encode({a: 1, b: 2}, null, function(key, value) {
if (key == "b") return value * 10
return value
})
// '{"a":1,"b":20}'
// With whitelist
json.encode({a: 1, b: 2, c: 3}, null, null, ["a", "c"])
// '{"a":1,"c":3}'
```
## Decoding
### json.decode(text, reviver)
Parse JSON text to a value.
```javascript
json.decode('{"a":1,"b":2}')
// {a: 1, b: 2}
json.decode('[1, 2, 3]')
// [1, 2, 3]
```
**Parameters:**
- **text** — JSON string to parse
- **reviver** — function to transform parsed values
```javascript
// With reviver
json.decode('{"date":"2024-01-15"}', function(key, value) {
if (key == "date") return parse_date(value)
return value
})
```
## Example
```javascript
var json = use('json')
// Save configuration
var config = {
debug: true,
maxRetries: 3,
endpoints: ["api.example.com"]
}
var config_text = json.encode(config, 2)
// Load configuration
var loaded = json.decode(config_text)
log.console(loaded.debug) // true
```

153
docs/library/math.md Normal file
View File

@@ -0,0 +1,153 @@
# math
Cell provides three math modules with identical functions but different angle representations:
```javascript
var math = use('math/radians') // angles in radians
var math = use('math/degrees') // angles in degrees
var math = use('math/cycles') // angles in cycles (0-1)
```
## Trigonometry
### sine(angle)
```javascript
math.sine(math.pi / 2) // 1 (radians)
math.sine(90) // 1 (degrees)
math.sine(0.25) // 1 (cycles)
```
### cosine(angle)
```javascript
math.cosine(0) // 1
```
### tangent(angle)
```javascript
math.tangent(math.pi / 4) // 1 (radians)
```
### arc_sine(n)
Inverse sine.
```javascript
math.arc_sine(1) // π/2 (radians)
```
### arc_cosine(n)
Inverse cosine.
```javascript
math.arc_cosine(0) // π/2 (radians)
```
### arc_tangent(n, denominator)
Inverse tangent. With two arguments, computes atan2.
```javascript
math.arc_tangent(1) // π/4 (radians)
math.arc_tangent(1, 1) // π/4 (radians)
math.arc_tangent(-1, -1) // -3π/4 (radians)
```
## Exponentials and Logarithms
### e(power)
Euler's number raised to a power. Default power is 1.
```javascript
math.e() // 2.718281828...
math.e(2) // e²
```
### ln(n)
Natural logarithm (base e).
```javascript
math.ln(math.e()) // 1
```
### log(n)
Base 10 logarithm.
```javascript
math.log(100) // 2
```
### log2(n)
Base 2 logarithm.
```javascript
math.log2(8) // 3
```
## Powers and Roots
### power(base, exponent)
```javascript
math.power(2, 10) // 1024
```
### sqrt(n)
Square root.
```javascript
math.sqrt(16) // 4
```
### root(radicand, n)
Nth root.
```javascript
math.root(27, 3) // 3 (cube root)
```
## Constants
Available in the radians module:
```javascript
math.pi // 3.14159...
math.e() // 2.71828...
```
## Example
```javascript
var math = use('math/radians')
// Distance between two points
function distance(x1, y1, x2, y2) {
var dx = x2 - x1
var dy = y2 - y1
return math.sqrt(dx * dx + dy * dy)
}
// Angle between two points
function angle(x1, y1, x2, y2) {
return math.arc_tangent(y2 - y1, x2 - x1)
}
// Rotate a point
function rotate(x, y, angle) {
var c = math.cosine(angle)
var s = math.sine(angle)
return {
x: x * c - y * s,
y: x * s + y * c
}
}
```

143
docs/library/number.md Normal file
View File

@@ -0,0 +1,143 @@
# number
The `number` function and its methods handle numeric conversion and operations.
## Conversion
### number(logical)
Convert boolean to number.
```javascript
number(true) // 1
number(false) // 0
```
### number(text, radix)
Parse text to number. Radix is 2-36 (default: 10).
```javascript
number("42") // 42
number("ff", 16) // 255
number("1010", 2) // 10
```
### number(text, format)
Parse formatted numbers.
| Format | Description |
|--------|-------------|
| `""` | Standard decimal |
| `"u"` | Underbar separator (1_000) |
| `"d"` | Comma separator (1,000) |
| `"s"` | Space separator (1 000) |
| `"v"` | European (1.000,50) |
| `"b"` | Binary |
| `"o"` | Octal |
| `"h"` | Hexadecimal |
| `"j"` | JavaScript style (0x, 0o, 0b prefixes) |
```javascript
number("1,000", "d") // 1000
number("0xff", "j") // 255
```
## Methods
### number.abs(n)
Absolute value.
```javascript
number.abs(-5) // 5
number.abs(5) // 5
```
### number.sign(n)
Returns -1, 0, or 1.
```javascript
number.sign(-5) // -1
number.sign(0) // 0
number.sign(5) // 1
```
### number.floor(n, place)
Round down.
```javascript
number.floor(4.9) // 4
number.floor(4.567, 2) // 4.56
```
### number.ceiling(n, place)
Round up.
```javascript
number.ceiling(4.1) // 5
number.ceiling(4.123, 2) // 4.13
```
### number.round(n, place)
Round to nearest.
```javascript
number.round(4.5) // 5
number.round(4.567, 2) // 4.57
```
### number.trunc(n, place)
Truncate toward zero.
```javascript
number.trunc(4.9) // 4
number.trunc(-4.9) // -4
```
### number.whole(n)
Get the integer part.
```javascript
number.whole(4.9) // 4
number.whole(-4.9) // -4
```
### number.fraction(n)
Get the fractional part.
```javascript
number.fraction(4.75) // 0.75
```
### number.min(...values)
Return the smallest value.
```javascript
number.min(3, 1, 4, 1, 5) // 1
```
### number.max(...values)
Return the largest value.
```javascript
number.max(3, 1, 4, 1, 5) // 5
```
### number.remainder(dividend, divisor)
Compute remainder.
```javascript
number.remainder(17, 5) // 2
```

112
docs/library/object.md Normal file
View File

@@ -0,0 +1,112 @@
# object
The `object` function and related utilities handle object creation and manipulation.
## Creation
### object(obj)
Shallow copy an object.
```javascript
var copy = object(original)
```
### object(obj, another)
Combine two objects.
```javascript
object({a: 1}, {b: 2}) // {a: 1, b: 2}
object({a: 1}, {a: 2}) // {a: 2}
```
### object(obj, keys)
Select specific keys.
```javascript
object({a: 1, b: 2, c: 3}, ["a", "c"]) // {a: 1, c: 3}
```
### object(keys)
Create object from keys (values are `true`).
```javascript
object(["a", "b", "c"]) // {a: true, b: true, c: true}
```
### object(keys, value)
Create object from keys with specified value.
```javascript
object(["a", "b"], 0) // {a: 0, b: 0}
```
### object(keys, fn)
Create object from keys with computed values.
```javascript
object(["a", "b", "c"], (k, i) => i) // {a: 0, b: 1, c: 2}
```
## Prototypes
### meme(prototype)
Create a new object with the given prototype.
```javascript
var animal = {speak: function() { log.console("...") }}
var dog = meme(animal)
dog.speak = function() { log.console("woof") }
```
### proto(obj)
Get an object's prototype.
```javascript
var p = proto(dog) // animal
```
### isa(obj, prototype)
Check if prototype is in the chain.
```javascript
isa(dog, animal) // true
```
## Serialization
### splat(obj)
Flatten an object's prototype chain into a plain object. Only includes primitive types (numbers, text, booleans, arrays, objects).
```javascript
var base = {x: 1}
var derived = meme(base)
derived.y = 2
splat(derived) // {x: 1, y: 2}
```
When sending objects between actors with `$send`, they are automatically splatted.
## Key Iteration
```javascript
var obj = {a: 1, b: 2, c: 3}
// Get all keys
var keys = array(obj) // ["a", "b", "c"]
// Iterate
for (var key in obj) {
log.console(key, obj[key])
}
```

71
docs/library/random.md Normal file
View File

@@ -0,0 +1,71 @@
# random
Random number generation.
```javascript
var random = use('random')
```
## Functions
### random.random()
Returns a number between 0 (inclusive) and 1 (exclusive).
```javascript
random.random() // e.g., 0.7234...
```
### random.random_fit()
Returns a random 56-bit integer in the range -36028797018963968 to 36028797018963967.
```javascript
random.random_fit() // e.g., 12345678901234
```
### random.random_whole(max)
Returns a whole number from 0 (inclusive) to max (exclusive).
```javascript
random.random_whole(10) // 0-9
random.random_whole(100) // 0-99
random.random_whole(6) + 1 // dice roll: 1-6
```
## Examples
```javascript
var random = use('random')
// Random boolean
var coin_flip = random.random() < 0.5
// Random element from array
function pick(arr) {
return arr[random.random_whole(length(arr))]
}
var colors = ["red", "green", "blue"]
var color = pick(colors)
// Shuffle array
function shuffle(arr) {
var result = array(arr) // copy
for (var i = length(result) - 1; i > 0; i--) {
var j = random.random_whole(i + 1)
var temp = result[i]
result[i] = result[j]
result[j] = temp
}
return result
}
// Random in range
function random_range(min, max) {
return min + random.random() * (max - min)
}
var x = random_range(-10, 10) // -10 to 10
```

123
docs/library/text.md Normal file
View File

@@ -0,0 +1,123 @@
# text
The `text` function and its methods handle string conversion and manipulation.
## Conversion
### text(array, separator)
Convert an array to text, joining elements with a separator (default: space).
```javascript
text([1, 2, 3]) // "1 2 3"
text([1, 2, 3], ", ") // "1, 2, 3"
text(["a", "b"], "-") // "a-b"
```
### text(number, radix)
Convert a number to text. Radix is 2-36 (default: 10).
```javascript
text(255) // "255"
text(255, 16) // "ff"
text(255, 2) // "11111111"
```
### text(text, from, to)
Extract a substring from index `from` to `to`.
```javascript
text("hello world", 0, 5) // "hello"
text("hello world", 6) // "world"
```
## Methods
### text.lower(text)
Convert to lowercase.
```javascript
text.lower("HELLO") // "hello"
```
### text.upper(text)
Convert to uppercase.
```javascript
text.upper("hello") // "HELLO"
```
### text.trim(text, reject)
Remove characters from both ends. Default removes whitespace.
```javascript
text.trim(" hello ") // "hello"
text.trim("xxhelloxx", "x") // "hello"
```
### text.search(text, target, from)
Find the position of `target` in `text`. Returns `null` if not found.
```javascript
text.search("hello world", "world") // 6
text.search("hello world", "xyz") // null
text.search("hello hello", "hello", 1) // 6
```
### text.replace(text, target, replacement, limit)
Replace occurrences of `target` with `replacement`.
```javascript
text.replace("hello", "l", "L") // "heLLo"
text.replace("hello", "l", "L", 1) // "heLlo"
// With function
text.replace("hello", "l", function(match, pos) {
return pos == 2 ? "L" : match
}) // "heLlo"
```
### text.format(text, collection, transformer)
Substitute `{key}` placeholders with values from a collection.
```javascript
text.format("Hello, {name}!", {name: "World"})
// "Hello, World!"
text.format("{0} + {1} = {2}", [1, 2, 3])
// "1 + 2 = 3"
```
### text.normalize(text)
Unicode normalize the text (NFC form).
```javascript
text.normalize("café") // normalized form
```
### text.codepoint(text)
Get the Unicode codepoint of the first character.
```javascript
text.codepoint("A") // 65
text.codepoint("😀") // 128512
```
### text.extract(text, pattern, from, to)
Match a pattern and extract named groups.
```javascript
text.extract("2024-01-15", /(\d+)-(\d+)-(\d+)/)
// Returns match info
```

116
docs/library/time.md Normal file
View File

@@ -0,0 +1,116 @@
# time
The time module provides time constants and conversion functions.
```javascript
var time = use('time')
```
## Constants
| Constant | Value | Description |
|----------|-------|-------------|
| `time.second` | 1 | Seconds in a second |
| `time.minute` | 60 | Seconds in a minute |
| `time.hour` | 3600 | Seconds in an hour |
| `time.day` | 86400 | Seconds in a day |
| `time.week` | 604800 | Seconds in a week |
| `time.month` | 2629746 | Seconds in a month (30.44 days) |
| `time.year` | 31556952 | Seconds in a year (365.24 days) |
## Getting Current Time
### time.number()
Get current time as seconds since epoch.
```javascript
var now = time.number() // e.g., 1702656000
```
### time.record()
Get current time as a record.
```javascript
var now = time.record()
// {year: 2024, month: 1, day: 15, hour: 10, minute: 30, second: 45, nanosecond: 123456789}
```
### time.text(format)
Get current time as formatted text.
```javascript
time.text() // default format
time.text("yyyy-MM-dd HH:mm:ss.SSS") // custom format
```
## Converting Time
### time.number(text, format, zone)
Parse text to timestamp.
```javascript
time.number("2024-01-15", "yyyy-MM-dd")
```
### time.number(record)
Convert record to timestamp.
```javascript
time.number({year: 2024, month: 1, day: 15})
```
### time.text(number, format, zone)
Format timestamp as text.
```javascript
time.text(1702656000, "yyyy-MM-dd") // "2024-01-15"
```
### time.record(number)
Convert timestamp to record.
```javascript
time.record(1702656000)
// {year: 2024, month: 1, day: 15, ...}
```
## Time Arithmetic
```javascript
var now = time.number()
// Tomorrow at this time
var tomorrow = now + time.day
// One week ago
var last_week = now - time.week
// In 2 hours
var later = now + (2 * time.hour)
// Format future time
log.console(time.text(tomorrow))
```
## Example
```javascript
var time = use('time')
// Measure execution time
var start = time.number()
// ... do work ...
var elapsed = time.number() - start
log.console(`Took ${elapsed} seconds`)
// Schedule for tomorrow
var tomorrow = time.number() + time.day
log.console(`Tomorrow: ${time.text(tomorrow, "yyyy-MM-dd")}`)
```