From e136adc89a75aad4b5c8d0bfb1d23ac78c741414 Mon Sep 17 00:00:00 2001 From: Jack Frain Date: Tue, 29 Oct 2024 10:06:11 -0400 Subject: [PATCH] feat(aos): add ldocs to process lua --- .github/workflows/ci.yml | 16 + config.ld | 6 + package.json | 1 + process/ao.lua | 116 +++- process/assignment.lua | 47 +- process/boot.lua | 12 +- process/chance.lua | 39 +- process/docs/index.html | 112 ++++ process/docs/ldoc.css | 304 +++++++++ process/docs/modules/ao.html | 627 +++++++++++++++++++ process/docs/modules/assignment.html | 154 +++++ process/docs/modules/boot.html | 117 ++++ process/docs/modules/chance.html | 210 +++++++ process/docs/modules/eval.html | 123 ++++ process/docs/modules/handlers-utils.html | 296 +++++++++ process/docs/modules/handlers.html | 482 +++++++++++++++ process/docs/modules/pretty.html | 156 +++++ process/docs/modules/process.html | 351 +++++++++++ process/docs/modules/stringify.html | 194 ++++++ process/docs/modules/utils.html | 744 +++++++++++++++++++++++ process/eval.lua | 18 +- process/handlers-utils.lua | 39 +- process/handlers.lua | 82 ++- process/pretty.lua | 16 +- process/process.lua | 69 ++- process/stringify.lua | 18 + process/utils.lua | 154 ++++- 27 files changed, 4415 insertions(+), 88 deletions(-) create mode 100644 config.ld create mode 100644 process/docs/index.html create mode 100644 process/docs/ldoc.css create mode 100644 process/docs/modules/ao.html create mode 100644 process/docs/modules/assignment.html create mode 100644 process/docs/modules/boot.html create mode 100644 process/docs/modules/chance.html create mode 100644 process/docs/modules/eval.html create mode 100644 process/docs/modules/handlers-utils.html create mode 100644 process/docs/modules/handlers.html create mode 100644 process/docs/modules/pretty.html create mode 100644 process/docs/modules/process.html create mode 100644 process/docs/modules/stringify.html create mode 100644 process/docs/modules/utils.html diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 88e81ca2..03a095f7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -195,6 +195,22 @@ jobs: path: ${{ steps.aos_llama_module.outputs.aos_module_path }} retention-days: 10 + # Set up Lua + - name: 🔧 Set up Lua + uses: leafo/gh-actions-lua@v10 + with: + luaVersion: 5.3 + + # Install LDoc + - name: 📦 Install LDoc + run: | + luarocks install ldoc + + # Build process docs + - name: 📄 Build Process Docs + run: | + yarn build-docs + # TODO: update manifests with new version and txids # - name: ⬆️ Push diff --git a/config.ld b/config.ld new file mode 100644 index 00000000..bc27481f --- /dev/null +++ b/config.ld @@ -0,0 +1,6 @@ +file = {"./process", exclude = {"./process/node_modules", "./process/crypto", "./process/test", "./process/dump.lua", "./process/base64.lua", "./process/bint.lua" } } +project = "AOS" +dir = "process/docs/" +description = [[ + AOS is your personal operating system for the ao computer. +]] \ No newline at end of file diff --git a/package.json b/package.json index 7220b34e..3dfa0046 100644 --- a/package.json +++ b/package.json @@ -10,6 +10,7 @@ "scripts": { "start": "node src/index.js", "test": "node --test test", + "build-docs": "rm -rf process/docs && ldoc .", "generate-wallet": "node -e \"require('arweave').init({}).wallets.generate().then(JSON.stringify).then(console.log.bind(console))\" > wallet.json", "deploy": "npx -y ardrive-cli@2.0.4 upload-file --turbo --local-path=./$(npm pack) -w ~/.wallet.json -F 0d009773-ce2c-4539-8e0d-c331db9ab348 | jq .created[0].dataTxId" }, diff --git a/process/ao.lua b/process/ao.lua index faa61053..efa964d6 100644 --- a/process/ao.lua +++ b/process/ao.lua @@ -1,4 +1,29 @@ +--- The AO module provides functionality for managing the AO environment and handling messages. Returns the ao table. +-- @module ao + local oldao = ao or {} + +--- The AO module +-- @table ao +-- @field _version The version number of the ao module +-- @field _module The module id of the process +-- @field id The id of the process +-- @field authorities A table of authorities of the process +-- @field reference The reference number of the process +-- @field outbox The outbox of the process +-- @field nonExtractableTags The non-extractable tags +-- @field nonForwardableTags The non-forwardable tags +-- @field clone The clone function +-- @field normalize The normalize function +-- @field sanitize The sanitize function +-- @field init The init function +-- @field log The log function +-- @field clearOutbox The clearOutbox function +-- @field send The send function +-- @field spawn The spawn function +-- @field assign The assign function +-- @field isTrusted The isTrusted function +-- @field result The result function local ao = { _version = "0.0.6", id = oldao.id or "", @@ -20,6 +45,10 @@ local ao = { } } +--- Checks if a key exists in a list. +-- @lfunction _includes +-- @tparam {table} list The list to check against +-- @treturn {function} A function that takes a key and returns true if the key exists in the list local function _includes(list) return function(key) local exists = false @@ -34,6 +63,10 @@ local function _includes(list) end end +--- Checks if a table is an array. +-- @lfunction isArray +-- @tparam {table} table The table to check +-- @treturn {boolean} True if the table is an array, false otherwise local function isArray(table) if type(table) == "table" then local maxIndex = 0 @@ -49,8 +82,17 @@ local function isArray(table) return false end +--- Pads a number with leading zeros to 32 digits. +-- @lfunction padZero32 +-- @tparam {number} num The number to pad +-- @treturn {string} The padded number as a string local function padZero32(num) return string.format("%032d", num) end +--- Clones a table recursively. +-- @function clone +-- @tparam {any} obj The object to clone +-- @tparam {table} seen The table of seen objects (default is nil) +-- @treturn {any} The cloned object function ao.clone(obj, seen) -- Handle non-tables and previously-seen tables. if type(obj) ~= 'table' then return obj end @@ -64,6 +106,10 @@ function ao.clone(obj, seen) return setmetatable(res, getmetatable(obj)) end +--- Normalizes a message by extracting tags. +-- @function normalize +-- @tparam {table} msg The message to normalize +-- @treturn {table} The normalized message function ao.normalize(msg) for _, o in ipairs(msg.Tags) do if not _includes(ao.nonExtractableTags)(o.name) then @@ -73,6 +119,10 @@ function ao.normalize(msg) return msg end +--- Sanitizes a message by removing non-forwardable tags. +-- @function sanitize +-- @tparam {table} msg The message to sanitize +-- @treturn {table} The sanitized message function ao.sanitize(msg) local newMsg = ao.clone(msg) @@ -83,6 +133,9 @@ function ao.sanitize(msg) return newMsg end +--- Initializes the AO environment, including ID, module, authorities, outbox, and environment. +-- @function init +-- @tparam {table} env The environment object function ao.init(env) if ao.id == "" then ao.id = env.Process.Id end @@ -105,6 +158,9 @@ function ao.init(env) end +--- Logs a message to the output. +-- @function log +-- @tparam {string} txt The message to log function ao.log(txt) if type(ao.outbox.Output) == 'string' then ao.outbox.Output = {ao.outbox.Output} @@ -112,11 +168,15 @@ function ao.log(txt) table.insert(ao.outbox.Output, txt) end --- clears outbox +--- Clears the outbox. +-- @function clearOutbox function ao.clearOutbox() ao.outbox = {Output = {}, Messages = {}, Spawns = {}, Assignments = {}} end +--- Sends a message. +-- @function send +-- @tparam {table} msg The message to send function ao.send(msg) assert(type(msg) == 'table', 'msg should be a table') ao.reference = ao.reference + 1 @@ -191,6 +251,10 @@ function ao.send(msg) return message end +--- Spawns a process. +-- @function spawn +-- @tparam {string} module The module source id +-- @tparam {table} msg The message to send function ao.spawn(module, msg) assert(type(module) == "string", "Module source id is required!") assert(type(msg) == 'table', 'Message must be a table') @@ -263,6 +327,9 @@ function ao.spawn(module, msg) return spawn end +--- Assigns a message to a process. +-- @function assign +-- @tparam {table} assignment The assignment to assign function ao.assign(assignment) assert(type(assignment) == 'table', 'assignment should be a table') assert(type(assignment.Processes) == 'table', 'Processes should be a table') @@ -270,8 +337,11 @@ function ao.assign(assignment) table.insert(ao.outbox.Assignments, assignment) end --- The default security model of AOS processes: Trust all and *only* those --- on the ao.authorities list. +--- Checks if a message is trusted. +-- The default security model of AOS processes: Trust all and *only* those on the ao.authorities list. +-- @function isTrusted +-- @tparam {table} msg The message to check +-- @treturn {boolean} True if the message is trusted, false otherwise function ao.isTrusted(msg) for _, authority in ipairs(ao.authorities) do if msg.From == authority then return true end @@ -280,6 +350,10 @@ function ao.isTrusted(msg) return false end +--- Returns the result of the process. +-- @function result +-- @tparam {table} result The result of the process +-- @treturn {table} The result of the process, including Output, Messages, Spawns, and Assignments function ao.result(result) -- if error then only send the Error to CU if ao.outbox.Error or result.Error then @@ -293,4 +367,40 @@ function ao.result(result) } end + +--- Add the MatchSpec to the ao.assignables table. A optional name may be provided. +-- This implies that ao.assignables may have both number and string indices. +-- Added in the assignment module. +-- @function addAssignable +-- @tparam ?string|number|any nameOrMatchSpec The name of the MatchSpec +-- to be added to ao.assignables. if a MatchSpec is provided, then +-- no name is included +-- @tparam ?any matchSpec The MatchSpec to be added to ao.assignables. Only provided +-- if its name is passed as the first parameter +-- @treturn ?string|number name The name of the MatchSpec, either as provided +-- as an argument or as incremented +-- @see assignment + +--- Remove the MatchSpec, either by name or by index +-- If the name is not found, or if the index does not exist, then do nothing. +-- Added in the assignment module. +-- @function removeAssignable +-- @tparam {string|number} name The name or index of the MatchSpec to be removed +-- @see assignment + +--- Return whether the msg is an assignment or not. This can be determined by simply check whether the msg's Target is this process' id +-- Added in the assignment module. +-- @function isAssignment +-- @param msg The msg to be checked +-- @treturn boolean isAssignment +-- @see assignment + +--- Check whether the msg matches any assignable MatchSpec. +-- If not assignables are configured, the msg is deemed not assignable, by default. +-- Added in the assignment module. +-- @function isAssignable +-- @param msg The msg to be checked +-- @treturn boolean isAssignable +-- @see assignment + return ao diff --git a/process/assignment.lua b/process/assignment.lua index 5ba30f0c..eb7d3bb0 100644 --- a/process/assignment.lua +++ b/process/assignment.lua @@ -1,9 +1,28 @@ +--- The Assignment module provides functionality for handling assignments. Returns the Assignment table. +-- @module assignment +--- The Assignment module +-- @table Assignment +-- @field _version The version number of the assignment module +-- @field init The init function local Assignment = { _version = "0.1.0" } local utils = require('.utils') --- Implement assignable polyfills on _ao +--- Implement assignable polyfills on ao. +-- Creates addAssignable, removeAssignable, isAssignment, and isAssignable fields on ao. +-- @function init +-- @tparam {table} ao The ao environment object +-- @see ao.addAssignable +-- @see ao.removeAssignable +-- @see ao.isAssignment +-- @see ao.isAssignable function Assignment.init (ao) + -- Find the index of an object in an array by a given property + -- @lfunction findIndexByProp + -- @tparam {table} array The array to search + -- @tparam {string} prop The property to search by + -- @tparam {any} value The value to search for + -- @treturn {number|nil} The index of the object, or nil if not found local function findIndexByProp(array, prop, value) for index, object in ipairs(array) do if object[prop] == value then return index end @@ -14,16 +33,6 @@ function Assignment.init (ao) ao.assignables = ao.assignables or {} - -- Add the MatchSpec to the ao.assignables table. A optional name may be provided. - -- This implies that ao.assignables may have both number and string indices. - -- - -- @tparam ?string|number|any nameOrMatchSpec The name of the MatchSpec - -- to be added to ao.assignables. if a MatchSpec is provided, then - -- no name is included - -- @tparam ?any matchSpec The MatchSpec to be added to ao.assignables. Only provided - -- if its name is passed as the first parameter - -- @treturn ?string|number name The name of the MatchSpec, either as provided - -- as an argument or as incremented ao.addAssignable = ao.addAssignable or function (...) local name = nil local matchSpec = nil @@ -50,11 +59,6 @@ function Assignment.init (ao) end end - -- Remove the MatchSpec, either by name or by index - -- If the name is not found, or if the index does not exist, then do nothing. - -- - -- @tparam string|number name The name or index of the MatchSpec to be removed - -- @treturn nil nil ao.removeAssignable = ao.removeAssignable or function (name) local idx = nil @@ -69,19 +73,8 @@ function Assignment.init (ao) table.remove(ao.assignables, idx) end - -- Return whether the msg is an assignment or not. This - -- can be determined by simply check whether the msg's Target is - -- This process' id - -- - -- @param msg The msg to be checked - -- @treturn boolean isAssignment ao.isAssignment = ao.isAssignment or function (msg) return msg.Target ~= ao.id end - -- Check whether the msg matches any assignable MatchSpec. - -- If not assignables are configured, the msg is deemed not assignable, by default. - -- - -- @param msg The msg to be checked - -- @treturn boolean isAssignable ao.isAssignable = ao.isAssignable or function (msg) for _, assignable in pairs(ao.assignables) do if utils.matchesSpec(msg, assignable.pattern) then return true end diff --git a/process/boot.lua b/process/boot.lua index 34a81853..23375c6c 100644 --- a/process/boot.lua +++ b/process/boot.lua @@ -1,3 +1,6 @@ +--- The Boot module provides functionality for booting the process. Returns the boot function. +-- @module boot + -- This is for aop6 Boot Loader -- See: https://github.com/permaweb/aos/issues/342 -- For the Process as the first Message, if On-Boot @@ -18,6 +21,13 @@ function drive.getData(txId) return contents end +--- The boot function. +-- If the message has no On-Boot tag, do nothing. +-- If the message has an On-Boot tag with the value 'Data', then evaluate the message. +-- If the message has an On-Boot tag with a tx id, then download and evaluate the tx data. +-- @function boot +-- @param ao The ao environment object +-- @see eval return function (ao) local eval = require(".eval")(ao) return function (msg) @@ -30,5 +40,5 @@ return function (ao) local loadedVal = drive.getData(msg.Tags['On-Boot']) eval({ Data = loadedVal }) end - end + end end \ No newline at end of file diff --git a/process/chance.lua b/process/chance.lua index c6f576a0..7c84f8d9 100644 --- a/process/chance.lua +++ b/process/chance.lua @@ -1,10 +1,16 @@ +--- The Chance module provides utilities for generating random numbers and values. Returns the chance table. +-- @module chance + local N = 624 local M = 397 local MATRIX_A = 0x9908b0df local UPPER_MASK = 0x80000000 local LOWER_MASK = 0x7fffffff --- initializes mt[N] with a seed +--- Initializes mt[N] with a seed +-- @lfunction init_genrand +-- @tparam {table} o The table to initialize +-- @tparam {number} s The seed local function init_genrand(o, s) o.mt[0] = s & 0xffffffff for i = 1, N - 1 do @@ -19,7 +25,10 @@ local function init_genrand(o, s) o.mti = N end --- generates a random number on [0,0xffffffff]-interval +--- Generates a random number on [0,0xffffffff]-interval +-- @lfunction genrand_int32 +-- @tparam {table} o The table to generate the random number from +-- @treturn {number} The random number local function genrand_int32(o) local y local mag01 = {} -- mag01[x] = x * MATRIX_A for x=0,1 @@ -60,24 +69,34 @@ MersenneTwister.mt = {} MersenneTwister.mti = N + 1 +--- The Random table +-- @table Random +-- @field seed The seed function +-- @field random The random function +-- @field integer The integer function local Random = {} --- set new random seed +--- Sets a new random table given a seed. +-- @function seed +-- @tparam {number} seed The seed function Random.seed(seed) init_genrand(MersenneTwister, seed) end --- generates a random number on [0,1)-real-interval +--- Generates a random number on [0,1)-real-interval. +-- @function random +-- @treturn {number} The random number function Random.random() return genrand_int32(MersenneTwister) * (1.0 / 4294967296.0) end ---[[ -return a random integer -NOTE the min and max are INCLUDED in the range. -the max integer in lua is math.maxinteger -the min is math.mininteger -]] +--- Returns a random integer. The min and max are INCLUDED in the range. +-- The max integer in lua is math.maxinteger +-- The min is math.mininteger +-- @function Random.integer +-- @tparam {number} min The minimum value +-- @tparam {number} max The maximum value +-- @treturn {number} The random integer function Random.integer(min, max) assert(max >= min, "max must bigger than min") return math.floor(Random.random() * (max - min + 1) + min) diff --git a/process/docs/index.html b/process/docs/index.html new file mode 100644 index 00000000..751fd622 --- /dev/null +++ b/process/docs/index.html @@ -0,0 +1,112 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ + +

AOS is your personal operating system for the ao computer. +

+ +

Modules

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
aoThe AO module provides functionality for managing the AO environment and handling messages.
assignmentThe Assignment module provides functionality for handling assignments.
bootThe Boot module provides functionality for booting the process.
chanceThe Chance module provides utilities for generating random numbers and values.
evalThe Eval module provides a handler for evaluating Lua expressions.
handlers-utilsThe Handler Utils module is a lightweight Lua utility library designed to provide common functionalities for handling and processing messages within the AOS computer system.
handlersThe Handlers library provides a flexible way to manage and execute a series of handlers based on patterns.
prettyThe Pretty module provides a utility for printing Lua tables in a more readable format.
processThe Process library provides an environment for managing and executing processes on the AO network.
stringifyThe Stringify module provides utilities for formatting and displaying Lua tables in a more readable manner.
utilsThe Utils module provides a collection of utility functions for functional programming in Lua.
+ +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/ldoc.css b/process/docs/ldoc.css new file mode 100644 index 00000000..f945ae70 --- /dev/null +++ b/process/docs/ldoc.css @@ -0,0 +1,304 @@ +/* BEGIN RESET + +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 2.8.2r1 +*/ +html { + color: #000; + background: #FFF; +} +body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td { + margin: 0; + padding: 0; +} +table { + border-collapse: collapse; + border-spacing: 0; +} +fieldset,img { + border: 0; +} +address,caption,cite,code,dfn,em,strong,th,var,optgroup { + font-style: inherit; + font-weight: inherit; +} +del,ins { + text-decoration: none; +} +li { + margin-left: 20px; +} +caption,th { + text-align: left; +} +h1,h2,h3,h4,h5,h6 { + font-size: 100%; + font-weight: bold; +} +q:before,q:after { + content: ''; +} +abbr,acronym { + border: 0; + font-variant: normal; +} +sup { + vertical-align: baseline; +} +sub { + vertical-align: baseline; +} +legend { + color: #000; +} +input,button,textarea,select,optgroup,option { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; +} +input,button,textarea,select {*font-size:100%; +} +/* END RESET */ + +body { + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color: #ffffff; margin: 0px; +} + +code, tt { font-family: monospace; font-size: 1.1em; } +span.parameter { font-family:monospace; } +span.parameter:after { content:":"; } +span.types:before { content:"("; } +span.types:after { content:")"; } +.type { font-weight: bold; font-style:italic } + +body, p, td, th { font-size: .95em; line-height: 1.2em;} + +p, ul { margin: 10px 0 0 0px;} + +strong { font-weight: bold;} + +em { font-style: italic;} + +h1 { + font-size: 1.5em; + margin: 20px 0 20px 0; +} +h2, h3, h4 { margin: 15px 0 10px 0; } +h2 { font-size: 1.25em; } +h3 { font-size: 1.15em; } +h4 { font-size: 1.06em; } + +a:link { font-weight: bold; color: #004080; text-decoration: none; } +a:visited { font-weight: bold; color: #006699; text-decoration: none; } +a:link:hover { text-decoration: underline; } + +hr { + color:#cccccc; + background: #00007f; + height: 1px; +} + +blockquote { margin-left: 3em; } + +ul { list-style-type: disc; } + +p.name { + font-family: "Andale Mono", monospace; + padding-top: 1em; +} + +pre { + background-color: rgb(245, 245, 245); + border: 1px solid #C0C0C0; /* silver */ + padding: 10px; + margin: 10px 0 10px 0; + overflow: auto; + font-family: "Andale Mono", monospace; +} + +pre.example { + font-size: .85em; +} + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } + +#container { + margin-left: 1em; + margin-right: 1em; + background-color: #f0f0f0; +} + +#product { + text-align: center; + border-bottom: 1px solid #cccccc; + background-color: #ffffff; +} + +#product big { + font-size: 2em; +} + +#main { + background-color: #f0f0f0; + border-left: 2px solid #cccccc; +} + +#navigation { + float: left; + width: 14em; + vertical-align: top; + background-color: #f0f0f0; + overflow: visible; +} + +#navigation h2 { + background-color:#e7e7e7; + font-size:1.1em; + color:#000000; + text-align: left; + padding:0.2em; + border-top:1px solid #dddddd; + border-bottom:1px solid #dddddd; +} + +#navigation ul +{ + font-size:1em; + list-style-type: none; + margin: 1px 1px 10px 1px; +} + +#navigation li { + text-indent: -1em; + display: block; + margin: 3px 0px 0px 22px; +} + +#navigation li li a { + margin: 0px 3px 0px -1em; +} + +#content { + margin-left: 14em; + padding: 1em; + width: 700px; + border-left: 2px solid #cccccc; + border-right: 2px solid #cccccc; + background-color: #ffffff; +} + +#about { + clear: both; + padding: 5px; + border-top: 2px solid #cccccc; + background-color: #ffffff; +} + +@media print { + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight: bold; color: #004080; text-decoration: underline; } + + #main { + background-color: #ffffff; + border-left: 0px; + } + + #container { + margin-left: 2%; + margin-right: 2%; + background-color: #ffffff; + } + + #content { + padding: 1em; + background-color: #ffffff; + } + + #navigation { + display: none; + } + pre.example { + font-family: "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.module_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.module_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.module_list td.summary { width: 100%; } + + +table.function_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.function_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.function_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.function_list td.summary { width: 100%; } + +ul.nowrap { + overflow:auto; + white-space:nowrap; +} + +dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} +dl.table h3, dl.function h3 {font-size: .95em;} + +/* stop sublists from having initial vertical space */ +ul ul { margin-top: 0px; } +ol ul { margin-top: 0px; } +ol ol { margin-top: 0px; } +ul ol { margin-top: 0px; } + +/* make the target distinct; helps when we're navigating to a function */ +a:target + * { + background-color: #FF9; +} + + +/* styles for prettification of source */ +pre .comment { color: #558817; } +pre .constant { color: #a8660d; } +pre .escape { color: #844631; } +pre .keyword { color: #aa5050; font-weight: bold; } +pre .library { color: #0e7c6b; } +pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; } +pre .string { color: #8080ff; } +pre .number { color: #f8660d; } +pre .function-name { color: #60447f; } +pre .operator { color: #2239a8; font-weight: bold; } +pre .preprocessor, pre .prepro { color: #a33243; } +pre .global { color: #800080; } +pre .user-keyword { color: #800080; } +pre .prompt { color: #558817; } +pre .url { color: #272fc2; text-decoration: underline; } + diff --git a/process/docs/modules/ao.html b/process/docs/modules/ao.html new file mode 100644 index 00000000..1ed0d344 --- /dev/null +++ b/process/docs/modules/ao.html @@ -0,0 +1,627 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module ao

+

The AO module provides functionality for managing the AO environment and handling messages.

+

Returns the ao table.

+ + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
clone (obj, seen)Clones a table recursively.
normalize (msg)Normalizes a message by extracting tags.
sanitize (msg)Sanitizes a message by removing non-forwardable tags.
init (env)Initializes the AO environment, including ID, module, authorities, outbox, and environment.
log (txt)Logs a message to the output.
clearOutbox ()Clears the outbox.
send (msg)Sends a message.
spawn (module, msg)Spawns a process.
assign (assignment)Assigns a message to a process.
isTrusted (msg)Checks if a message is trusted.
result (result)Returns the result of the process.
addAssignable (nameOrMatchSpec, matchSpec)Add the MatchSpec to the ao.assignables table.
removeAssignable (name)Remove the MatchSpec, either by name or by index + If the name is not found, or if the index does not exist, then do nothing.
isAssignment (msg)Return whether the msg is an assignment or not.
isAssignable (msg)Check whether the msg matches any assignable MatchSpec.
+

Tables

+ + + + + +
aoThe AO module
+ +
+
+ + +

Functions

+ +
+
+ + clone (obj, seen) +
+
+ Clones a table recursively. + + +

Parameters:

+
    +
  • obj + {any} + The object to clone +
    • +
  • seen + {table} + The table of seen objects (default is nil) +
    • +
+ +

Returns:

+
    + + {any} + The cloned object +
+ + + + +
+
+ + normalize (msg) +
+
+ Normalizes a message by extracting tags. + + +

Parameters:

+
    +
  • msg + {table} + The message to normalize +
    • +
+ +

Returns:

+
    + + {table} + The normalized message +
+ + + + +
+
+ + sanitize (msg) +
+
+ Sanitizes a message by removing non-forwardable tags. + + +

Parameters:

+
    +
  • msg + {table} + The message to sanitize +
    • +
+ +

Returns:

+
    + + {table} + The sanitized message +
+ + + + +
+
+ + init (env) +
+
+ Initializes the AO environment, including ID, module, authorities, outbox, and environment. + + +

Parameters:

+
    +
  • env + {table} + The environment object +
    • +
+ + + + + +
+
+ + log (txt) +
+
+ Logs a message to the output. + + +

Parameters:

+
    +
  • txt + {string} + The message to log +
    • +
+ + + + + +
+
+ + clearOutbox () +
+
+ Clears the outbox. + + + + + + + +
+
+ + send (msg) +
+
+ Sends a message. + + +

Parameters:

+
    +
  • msg + {table} + The message to send +
    • +
+ + + + + +
+
+ + spawn (module, msg) +
+
+ Spawns a process. + + +

Parameters:

+
    +
  • module + {string} + The module source id +
    • +
  • msg + {table} + The message to send +
    • +
+ + + + + +
+
+ + assign (assignment) +
+
+ Assigns a message to a process. + + +

Parameters:

+
    +
  • assignment + {table} + The assignment to assign +
    • +
+ + + + + +
+
+ + isTrusted (msg) +
+
+ Checks if a message is trusted. + The default security model of AOS processes: Trust all and *only* those on the ao.authorities list. + + +

Parameters:

+
    +
  • msg + {table} + The message to check +
    • +
+ +

Returns:

+
    + + {boolean} + True if the message is trusted, false otherwise +
+ + + + +
+
+ + result (result) +
+
+ Returns the result of the process. + + +

Parameters:

+
    +
  • result + {table} + The result of the process +
    • +
+ +

Returns:

+
    + + {table} + The result of the process, including Output, Messages, Spawns, and Assignments +
+ + + + +
+
+ + addAssignable (nameOrMatchSpec, matchSpec) +
+
+ Add the MatchSpec to the ao.assignables table. A optional name may be provided. + This implies that ao.assignables may have both number and string indices. + Added in the assignment module. + + +

Parameters:

+
    +
  • nameOrMatchSpec + string, number or any + The name of the MatchSpec + to be added to ao.assignables. if a MatchSpec is provided, then + no name is included +
    • +
  • matchSpec + optional any + The MatchSpec to be added to ao.assignables. Only provided + if its name is passed as the first parameter +
    • +
+ +

Returns:

+
    + + string or number + name The name of the MatchSpec, either as provided + as an argument or as incremented +
+ + +

See also:

+ + + +
+
+ + removeAssignable (name) +
+
+ Remove the MatchSpec, either by name or by index + If the name is not found, or if the index does not exist, then do nothing. + Added in the assignment module. + + +

Parameters:

+
    +
  • name + {string or number} + The name or index of the MatchSpec to be removed +
    • +
+ + + +

See also:

+ + + +
+
+ + isAssignment (msg) +
+
+ Return whether the msg is an assignment or not. This can be determined by simply check whether the msg's Target is this process' id + Added in the assignment module. + + +

Parameters:

+
    +
  • msg + The msg to be checked +
    • +
+ +

Returns:

+
    + + boolean + isAssignment +
+ + +

See also:

+ + + +
+
+ + isAssignable (msg) +
+
+ Check whether the msg matches any assignable MatchSpec. + If not assignables are configured, the msg is deemed not assignable, by default. + Added in the assignment module. + + +

Parameters:

+
    +
  • msg + The msg to be checked +
    • +
+ +

Returns:

+
    + + boolean + isAssignable +
+ + +

See also:

+ + + +
+
+

Tables

+ +
+
+ + ao +
+
+ The AO module + + +

Fields:

+
    +
  • _version + The version number of the ao module +
    • +
  • _module + The module id of the process +
    • +
  • id + The id of the process +
    • +
  • authorities + A table of authorities of the process +
    • +
  • reference + The reference number of the process +
    • +
  • outbox + The outbox of the process +
    • +
  • nonExtractableTags + The non-extractable tags +
    • +
  • nonForwardableTags + The non-forwardable tags +
    • +
  • clone + The clone function +
    • +
  • normalize + The normalize function +
    • +
  • sanitize + The sanitize function +
    • +
  • init + The init function +
    • +
  • log + The log function +
    • +
  • clearOutbox + The clearOutbox function +
    • +
  • send + The send function +
    • +
  • spawn + The spawn function +
    • +
  • assign + The assign function +
    • +
  • isTrusted + The isTrusted function +
    • +
  • result + The result function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/assignment.html b/process/docs/modules/assignment.html new file mode 100644 index 00000000..95a24cc3 --- /dev/null +++ b/process/docs/modules/assignment.html @@ -0,0 +1,154 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module assignment

+

The Assignment module provides functionality for handling assignments.

+

Returns the Assignment table.

+ + +

Functions

+ + + + + +
init (ao)Implement assignable polyfills on ao.
+

Tables

+ + + + + +
AssignmentThe Assignment module
+ +
+
+ + +

Functions

+ +
+
+ + init (ao) +
+
+ Implement assignable polyfills on ao. + Creates addAssignable, removeAssignable, isAssignment, and isAssignable fields on ao. + + +

Parameters:

+
    +
  • ao + {table} + The ao environment object +
    • +
+ + + +

See also:

+ + + +
+
+

Tables

+ +
+
+ + Assignment +
+
+ The Assignment module + + +

Fields:

+
    +
  • _version + The version number of the assignment module +
    • +
  • init + The init function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/boot.html b/process/docs/modules/boot.html new file mode 100644 index 00000000..e4d292f4 --- /dev/null +++ b/process/docs/modules/boot.html @@ -0,0 +1,117 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module boot

+

The Boot module provides functionality for booting the process.

+

Returns the boot function.

+ + +

Functions

+ + + + + +
boot (ao)The boot function.
+ +
+
+ + +

Functions

+ +
+
+ + boot (ao) +
+
+ The boot function. + If the message has no On-Boot tag, do nothing. + If the message has an On-Boot tag with the value 'Data', then evaluate the message. + If the message has an On-Boot tag with a tx id, then download and evaluate the tx data. + + +

Parameters:

+
    +
  • ao + The ao environment object +
    • +
+ + + +

See also:

+ + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/chance.html b/process/docs/modules/chance.html new file mode 100644 index 00000000..1edf38e9 --- /dev/null +++ b/process/docs/modules/chance.html @@ -0,0 +1,210 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module chance

+

The Chance module provides utilities for generating random numbers and values.

+

Returns the chance table.

+ + +

Functions

+ + + + + + + + + + + + + +
seed (seed)Sets a new random table given a seed.
random ()Generates a random number on [0,1)-real-interval.
Random.integer (min, max)Returns a random integer.
+

Tables

+ + + + + +
RandomThe Random table
+ +
+
+ + +

Functions

+ +
+
+ + seed (seed) +
+
+ Sets a new random table given a seed. + + +

Parameters:

+
    +
  • seed + {number} + The seed +
    • +
+ + + + + +
+
+ + random () +
+
+ Generates a random number on [0,1)-real-interval. + + + +

Returns:

+
    + + {number} + The random number +
+ + + + +
+
+ + Random.integer (min, max) +
+
+ Returns a random integer. The min and max are INCLUDED in the range. + The max integer in lua is math.maxinteger + The min is math.mininteger + + +

Parameters:

+
    +
  • min + {number} + The minimum value +
    • +
  • max + {number} + The maximum value +
    • +
+ +

Returns:

+
    + + {number} + The random integer +
+ + + + +
+
+

Tables

+ +
+
+ + Random +
+
+ The Random table + + +

Fields:

+
    +
  • seed + The seed function +
    • +
  • random + The random function +
    • +
  • integer + The integer function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/eval.html b/process/docs/modules/eval.html new file mode 100644 index 00000000..d5a78534 --- /dev/null +++ b/process/docs/modules/eval.html @@ -0,0 +1,123 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module eval

+

The Eval module provides a handler for evaluating Lua expressions.

+

Returns the eval function.

+ + +

Functions

+ + + + + +
eval (ao)The eval function.
+ +
+
+ + +

Functions

+ +
+
+ + eval (ao) +
+
+ The eval function. + Handler for executing and evaluating Lua expressions. + After execution, the result is stringified and placed in ao.outbox.Output. + + +

Parameters:

+
    +
  • ao + {table} + The ao environment object +
    • +
+ +

Returns:

+
    + + {function} + The handler function, which takes a message as an argument. +
+ + +

See also:

+ + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/handlers-utils.html b/process/docs/modules/handlers-utils.html new file mode 100644 index 00000000..4be16470 --- /dev/null +++ b/process/docs/modules/handlers-utils.html @@ -0,0 +1,296 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module handlers-utils

+

The Handler Utils module is a lightweight Lua utility library designed to provide common functionalities for handling and processing messages within the AOS computer system.

+

It offers a set of functions to check message attributes and send replies, simplifying the development of more complex scripts and modules. This document will guide you through the module's functionalities, installation, and usage. Returns the _utils table.

+ + +

Functions

+ + + + + + + + + + + + + + + + + + + + + +
hasMatchingTag (name, value)Checks if a given message has a tag that matches the specified name and value.
hasMatchingTagOf (name, values)Checks if a given message has a tag that matches the specified name and one of the specified values.
hasMatchingData (value)Checks if a given message has data that matches the specified value.
reply (string)Given an input, returns a function that takes a message and replies to it.
continue (function)Inverts the provided pattern's result if it matches, so that it continues execution with the next matching handler.
+

Tables

+ + + + + +
_utilsThe _utils table
+ +
+
+ + +

Functions

+ +
+
+ + hasMatchingTag (name, value) +
+
+ Checks if a given message has a tag that matches the specified name and value. + + +

Parameters:

+
    +
  • name + {string} + The tag name to check +
    • +
  • value + {string} + The value to match for in the tag +
    • +
+ +

Returns:

+
    + + {function} + A function that takes a message and returns whether there is a tag match (-1 if matches, 0 otherwise) +
+ + + + +
+
+ + hasMatchingTagOf (name, values) +
+
+ Checks if a given message has a tag that matches the specified name and one of the specified values. + + +

Parameters:

+
    +
  • name + {string} + The tag name to check +
    • +
  • values + {string[]} + The list of values of which one should match +
    • +
+ +

Returns:

+
    + + {function} + A function that takes a message and returns whether there is a tag match (-1 if matches, 0 otherwise) +
+ + + + +
+
+ + hasMatchingData (value) +
+
+ Checks if a given message has data that matches the specified value. + + +

Parameters:

+
    +
  • value + {string} + The value to match against the message data +
    • +
+ +

Returns:

+
    + + {function} + A function that takes a message and returns whether the data matches the value (-1 if matches, 0 otherwise) +
+ + + + +
+
+ + reply (string) +
+
+ Given an input, returns a function that takes a message and replies to it. + + +

Parameters:

+
    +
  • string + {table + } input The content to send back. If a string, it sends it as data. If a table, it assumes a structure with `Tags`. +
    • +
+ +

Returns:

+
    + + {function} + A function that takes a message and replies to it +
+ + + + +
+
+ + continue (function) +
+
+ Inverts the provided pattern's result if it matches, so that it continues execution with the next matching handler. + + +

Parameters:

+
    +
  • function + {table + } pattern The pattern to check for in the message +
    • +
+ +

Returns:

+
    + + {function} + Function that executes the pattern matching function and returns `1` (continue), so that the execution of handlers continues. +
+ + + + +
+
+

Tables

+ +
+
+ + _utils +
+
+ The _utils table + + +

Fields:

+
    +
  • _version + The version number of the _utils module +
    • +
  • hasMatchingTag + The hasMatchingTag function +
    • +
  • hasMatchingTagOf + The hasMatchingTagOf function +
    • +
  • hasMatchingData + The hasMatchingData function +
    • +
  • reply + The reply function +
    • +
  • continue + The continue function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/handlers.html b/process/docs/modules/handlers.html new file mode 100644 index 00000000..2da443d1 --- /dev/null +++ b/process/docs/modules/handlers.html @@ -0,0 +1,482 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module handlers

+

The Handlers library provides a flexible way to manage and execute a series of handlers based on patterns.

+

Each handler consists of a pattern function, a handle function, and a name. This library is suitable for scenarios where different actions need to be taken based on varying input criteria. Returns the handlers table.

+ + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
generateResolver (function)Given a resolver specification, returns a resolver function.
receive (function)Given a pattern, returns the next message that matches the pattern.
once (name, function, handle)Given a name, a pattern, and a handle, adds a handler to the list.
add (name, function, handle, string)Given a name, a pattern, and a handle, adds a handler to the list.
append (name, function, handle, string)Appends a new handler to the end of the handlers list.
prepend (name, function, handle, string)Prepends a new handler to the beginning of the handlers list.
before (handleName)Returns an object that allows adding a new handler before a specified handler.
after (handleName)Returns an object that allows adding a new handler after a specified handler.
remove (name)Removes a handler from the handlers list by name.
evaluate (msg, env)Evaluates each handler against a given message and environment.
+

Tables

+ + + + + +
handlersThe handlers table
+ +
+
+ + +

Functions

+ +
+
+ + generateResolver (function) +
+
+ Given a resolver specification, returns a resolver function. + + +

Parameters:

+
    +
  • function + {table + } resolveSpec The resolver specification +
    • +
+ +

Returns:

+
    + + {function} + A resolver function +
+ + + + +
+
+ + receive (function) +
+
+ Given a pattern, returns the next message that matches the pattern. + This function uses Lua's coroutines under-the-hood to add a handler, pause, + and then resume the current coroutine. This allows us to effectively block + processing of one message until another is received that matches the pattern. + + +

Parameters:

+
    +
  • function + {table + } pattern The pattern to check for in the message +
    • +
+ + + + + +
+
+ + once (name, function, handle) +
+
+ Given a name, a pattern, and a handle, adds a handler to the list. + If name is not provided, "_once_" prefix plus onceNonce will be used as the name. + Adds handler with maxRuns of 1 such that it will only be called once then removed from the list. + + +

Parameters:

+
    +
  • name + {string} + The name of the handler +
    • +
  • function + {table + | string} pattern The pattern to check for in the message +
    • +
  • handle + {function} + The function to call if the pattern matches +
    • +
+ + + + + +
+
+ + add (name, function, handle, string) +
+
+ Given a name, a pattern, and a handle, adds a handler to the list. + + +

Parameters:

+
    +
  • name + {string} + The name of the handler +
    • +
  • function + {table + | string} pattern The pattern to check for in the message +
    • +
  • handle + {function} + The function to call if the pattern matches +
    • +
  • string + {number + | nil} maxRuns The maximum number of times the handler should run, or nil if there is no limit +
    • +
+ + + + + +
+
+ + append (name, function, handle, string) +
+
+ Appends a new handler to the end of the handlers list. + + +

Parameters:

+
    +
  • name + {string} + The name of the handler +
    • +
  • function + {table + | string} pattern The pattern to check for in the message +
    • +
  • handle + {function} + The function to call if the pattern matches +
    • +
  • string + {number + | nil} maxRuns The maximum number of times the handler should run, or nil if there is no limit +
    • +
+ + + + + +
+
+ + prepend (name, function, handle, string) +
+
+ Prepends a new handler to the beginning of the handlers list. + + +

Parameters:

+
    +
  • name + {string} + The name of the handler +
    • +
  • function + {table + | string} pattern The pattern to check for in the message +
    • +
  • handle + {function} + The function to call if the pattern matches +
    • +
  • string + {number + | nil} maxRuns The maximum number of times the handler should run, or nil if there is no limit +
    • +
+ + + + + +
+
+ + before (handleName) +
+
+ Returns an object that allows adding a new handler before a specified handler. + + +

Parameters:

+
    +
  • handleName + {string} + The name of the handler before which the new handler will be added +
    • +
+ +

Returns:

+
    + + {table} + An object with an `add` method to insert the new handler +
+ + + + +
+
+ + after (handleName) +
+
+ Returns an object that allows adding a new handler after a specified handler. + + +

Parameters:

+
    +
  • handleName + {string} + The name of the handler after which the new handler will be added +
    • +
+ +

Returns:

+
    + + {table} + An object with an `add` method to insert the new handler +
+ + + + +
+
+ + remove (name) +
+
+ Removes a handler from the handlers list by name. + + +

Parameters:

+
    +
  • name + {string} + The name of the handler to be removed +
    • +
+ + + + + +
+
+ + evaluate (msg, env) +
+
+ Evaluates each handler against a given message and environment. Handlers are called in the order they appear in the handlers list. + Return 0 to not call handler, -1 to break after handler is called, 1 to continue + + +

Parameters:

+
    +
  • msg + {table} + The message to be processed by the handlers. +
    • +
  • env + {table} + The environment in which the handlers are executed. +
    • +
+ +

Returns:

+
    + + The + response from the handler(s). Returns a default message if no handler matches. +
+ + + + +
+
+

Tables

+ +
+
+ + handlers +
+
+ The handlers table + + +

Fields:

+
    +
  • _version + The version number of the handlers module +
    • +
  • list + The list of handlers +
    • +
  • coroutines + The coroutines of the handlers +
    • +
  • onceNonce + The nonce for the once handlers +
    • +
  • utils + The handlers-utils module +
    • +
  • generateResolver + The generateResolver function +
    • +
  • receive + The receive function +
    • +
  • once + The once function +
    • +
  • add + The add function +
    • +
  • append + The append function +
    • +
  • prepend + The prepend function +
    • +
  • remove + The remove function +
    • +
  • evaluate + The evaluate function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/pretty.html b/process/docs/modules/pretty.html new file mode 100644 index 00000000..3de8d1ca --- /dev/null +++ b/process/docs/modules/pretty.html @@ -0,0 +1,156 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module pretty

+

The Pretty module provides a utility for printing Lua tables in a more readable format.

+

+ + +

Functions

+ + + + + +
tprint (tbl, indent)Prints a table with indentation for better readability.
+

Tables

+ + + + + +
prettyThe pretty module
+ +
+
+ + +

Functions

+ +
+
+ + tprint (tbl, indent) +
+
+ Prints a table with indentation for better readability. + + +

Parameters:

+
    +
  • tbl + {table} + The table to print +
    • +
  • indent + {number} + The indentation level (default is 0) +
    • +
+ +

Returns:

+
    + + {string} + A string representation of the table with indentation +
+ + + + +
+
+

Tables

+ +
+
+ + pretty +
+
+ The pretty module + + +

Fields:

+
    +
  • _version + The version number of the pretty module +
    • +
  • tprint + The tprint function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/process.html b/process/docs/modules/process.html new file mode 100644 index 00000000..2aca53da --- /dev/null +++ b/process/docs/modules/process.html @@ -0,0 +1,351 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module process

+

The Process library provides an environment for managing and executing processes on the AO network.

+

It includes capabilities for handling messages, spawning processes, and customizing the environment with programmable logic and handlers. Returns the process table.

+ + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Tab (msg)Convert a message's tags to a table of key-value pairs
Prompt ()Generate a prompt string for the current process
print (a)Print a value, formatting tables and converting non-string types
Send (msg)Send a message to a target process
Spawn (args)Spawn a new process
Receive (match)Calls Handlers.receive with the provided pattern criteria, awaiting a message that matches the criteria.
Assign (assignment)Assigns based on the assignment passed.
Version ()Prints the version of the process
handle (msg, _)Main handler for processing incoming messages.
+

Tables

+ + + + + +
processThe process table
+ +
+
+ + +

Functions

+ +
+
+ + Tab (msg) +
+
+ Convert a message's tags to a table of key-value pairs + + +

Parameters:

+
    +
  • msg + {table} + The message containing tags +
    • +
+ +

Returns:

+
    + + {table} + A table with tag names as keys and their values +
+ + + + +
+
+ + Prompt () +
+
+ Generate a prompt string for the current process + + + +

Returns:

+
    + + {string} + The custom command prompt string +
+ + + + +
+
+ + print (a) +
+
+ Print a value, formatting tables and converting non-string types + + +

Parameters:

+
    +
  • a + {any} + The value to print +
    • +
+ + + + + +
+
+ + Send (msg) +
+
+ Send a message to a target process + + +

Parameters:

+
    +
  • msg + {table} + The message to send +
    • +
+ + + + + +
+
+ + Spawn (args) +
+
+ Spawn a new process + + +

Parameters:

+
    +
  • args + {...any} + The arguments to pass to the spawn function +
    • +
+ + + + + +
+
+ + Receive (match) +
+
+ Calls Handlers.receive with the provided pattern criteria, awaiting a message that matches the criteria. + + +

Parameters:

+
    +
  • match + {table} + The pattern criteria for the message +
    • +
+ +

Returns:

+
    + + {any} + The result of the message handling +
+ + + + +
+
+ + Assign (assignment) +
+
+ Assigns based on the assignment passed. + + +

Parameters:

+
    +
  • assignment + {table} + The assignment to be made +
    • +
+ + + + + +
+
+ + Version () +
+
+ Prints the version of the process + + + + + + + +
+
+ + handle (msg, _) +
+
+ Main handler for processing incoming messages. It initializes the state, processes commands, and handles message evaluation and inbox management. + + +

Parameters:

+
    +
  • msg + {table} + The message to handle +
    • +
  • _ + {table} + The environment to handle the message in +
    • +
+ + + + + +
+
+

Tables

+ +
+
+ + process +
+
+ The process table + + +

Fields:

+
    +
  • _version + The version number of the process +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/stringify.html b/process/docs/modules/stringify.html new file mode 100644 index 00000000..261f8e3a --- /dev/null +++ b/process/docs/modules/stringify.html @@ -0,0 +1,194 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module stringify

+

The Stringify module provides utilities for formatting and displaying Lua tables in a more readable manner.

+

Returns the stringify table.

+ + +

Functions

+ + + + + + + + + +
isSimpleArray (tbl)Checks if a table is a simple array (i.e., an array with consecutive numeric keys starting from 1).
format (tbl, indent, visited)Formats a table for display, handling circular references and formatting strings and tables recursively.
+

Tables

+ + + + + +
stringifyThe stringify table
+ +
+
+ + +

Functions

+ +
+
+ + isSimpleArray (tbl) +
+
+ Checks if a table is a simple array (i.e., an array with consecutive numeric keys starting from 1). + + +

Parameters:

+
    +
  • tbl + {table} + The table to check +
    • +
+ +

Returns:

+
    + + {boolean} + Whether the table is a simple array +
+ + + + +
+
+ + format (tbl, indent, visited) +
+
+ Formats a table for display, handling circular references and formatting strings and tables recursively. + + +

Parameters:

+
    +
  • tbl + {table} + The table to format +
    • +
  • indent + {number} + The indentation level (default is 0) +
    • +
  • visited + {table} + A table to track visited tables and detect circular references (optional) +
    • +
+ +

Returns:

+
    + + {string} + A string representation of the table +
+ + + + +
+
+

Tables

+ +
+
+ + stringify +
+
+ The stringify table + + +

Fields:

+
    +
  • _version + The version number of the stringify module +
    • +
  • isSimpleArray + The isSimpleArray function +
    • +
  • format + The format function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/docs/modules/utils.html b/process/docs/modules/utils.html new file mode 100644 index 00000000..ba511573 --- /dev/null +++ b/process/docs/modules/utils.html @@ -0,0 +1,744 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module utils

+

The Utils module provides a collection of utility functions for functional programming in Lua.

+

It includes functions for array manipulation such as concatenation, mapping, reduction, filtering, and finding elements, as well as a property equality checker.

+ + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
matchesPattern (pattern, value, msg)Given a pattern, a value, and a message, returns whether there is a pattern match.
matchesSpec (msg, spec)Given a message and a spec, returns whether there is a spec match.
curry (fn, arity)Curries a function.
concat (a, b)Concat two Array Tables
reduce (fn, initial, t)Applies a function to each element of a table, reducing it to a single value.
map (fn, data)Applies a function to each element of an array table, mapping it to a new value.
filter (fn, data)Filters an array table based on a predicate function.
find (fn, t)Finds the first element in an array table that satisfies a predicate function.
propEq (propName, value, object)Checks if a property of an object is equal to a value.
reverse (data)Reverses an array table.
compose (...)Composes a series of functions into a single function.
prop (propName, object)Returns the value of a property of an object.
includes (val, t)Checks if an array table includes a value.
keys (t)Returns the keys of a table.
values (t)Returns the values of a table.
+

Tables

+ + + + + +
utilsThe utils table
+ +
+
+ + +

Functions

+ +
+
+ + matchesPattern (pattern, value, msg) +
+
+ Given a pattern, a value, and a message, returns whether there is a pattern match. + + +

Parameters:

+
    +
  • pattern + The pattern to match +
    • +
  • value + The value to check for in the pattern +
    • +
  • msg + The message to check for the pattern +
    • +
+ +

Returns:

+
    + + {boolean} + Whether there is a pattern match +
+ + + +

Usage:

+
    + 
    utils.matchesPattern(pattern, value, msg)
    +
+ +
+
+ + matchesSpec (msg, spec) +
+
+ Given a message and a spec, returns whether there is a spec match. + + +

Parameters:

+
    +
  • msg + The message to check for the spec +
    • +
  • spec + The spec to check for in the message +
    • +
+ +

Returns:

+
    + + {boolean} + Whether there is a spec match +
+ + + +

Usage:

+
    + 
    utils.matchesSpec(msg, spec)
    +
+ +
+
+ + curry (fn, arity) +
+
+ Curries a function. + + +

Parameters:

+
    +
  • fn + {function} + The function to curry +
    • +
  • arity + {number} + The arity of the function +
    • +
+ +

Returns:

+
    + + {function} + The curried function +
+ + + + +
+
+ + concat (a, b) +
+
+ Concat two Array Tables + + +

Parameters:

+
    +
  • a + {table} + The first array +
    • +
  • b + {table} + The second array +
    • +
+ +

Returns:

+
    + + {table} + The concatenated array +
+ + + +

Usage:

+
    + 
  • utils.concat(a)(b)
    • + 
  • utils.concat({1, 2})({3, 4}) --> {1, 2, 3, 4}
    • +
+ +
+
+ + reduce (fn, initial, t) +
+
+ Applies a function to each element of a table, reducing it to a single value. + + +

Parameters:

+
    +
  • fn + {function} + The function to apply +
    • +
  • initial + The initial value +
    • +
  • t + {table} + The table to reduce +
    • +
+ +

Returns:

+
    + + The reduced value +
+ + + +

Usage:

+
    + 
  • utils.reduce(fn)(initial)(t)
    • + 
  • utils.reduce(function(acc, x) return acc + x end)(0)({1, 2, 3}) --> 6
    • +
+ +
+
+ + map (fn, data) +
+
+ Applies a function to each element of an array table, mapping it to a new value. + + +

Parameters:

+
    +
  • fn + {function} + The function to apply to each element +
    • +
  • data + {table} + The table to map over +
    • +
+ +

Returns:

+
    + + {table} + The mapped table +
+ + + +

Usage:

+
    + 
  • utils.map(fn)(t)
    • + 
  • utils.map(function(x) return x * 2 end)({1, 2, 3}) --> {2, 4, 6}
    • +
+ +
+
+ + filter (fn, data) +
+
+ Filters an array table based on a predicate function. + + +

Parameters:

+
    +
  • fn + {function} + The predicate function to determine if an element should be included. +
    • +
  • data + {table} + The array to filter +
    • +
+ +

Returns:

+
    + + {table} + The filtered table +
+ + + +

Usage:

+
    + 
  • utils.filter(fn)(t)
    • + 
  • utils.filter(function(x) return x > 1 end)({1, 2, 3}) --> {2,3}
    • +
+ +
+
+ + find (fn, t) +
+
+ Finds the first element in an array table that satisfies a predicate function. + + +

Parameters:

+
    +
  • fn + {function} + The predicate function to determine if an element should be included. +
    • +
  • t + {table} + The array table to search +
    • +
+ +

Returns:

+
    + + The + first element that satisfies the predicate function +
+ + + +

Usage:

+
    + 
  • utils.find(fn)(t)
    • + 
  • utils.find(function(x) return x > 1 end)({1, 2, 3}) --> 2
    • +
+ +
+
+ + propEq (propName, value, object) +
+
+ Checks if a property of an object is equal to a value. + + +

Parameters:

+
    +
  • propName + {string} + The property name to check +
    • +
  • value + {string} + The value to check against +
    • +
  • object + {table} + The object to check +
    • +
+ +

Returns:

+
    + + {boolean} + Whether the property is equal to the value +
+ + + +

Usage:

+
    + 
  • utils.propEq(propName)(value)(object)
    • + 
  • utils.propEq("name")("Lua")({name = "Lua"}) --> true
    • +
+ +
+
+ + reverse (data) +
+
+ Reverses an array table. + + +

Parameters:

+
    +
  • data + {table} + The array table to reverse +
    • +
+ +

Returns:

+
    + + {table} + The reversed array table +
+ + + +

Usage:

+
    + 
  • utils.reverse(data)
    • + 
  • utils.reverse({1, 2, 3}) --> {3, 2, 1}
    • +
+ +
+
+ + compose (...) +
+
+ Composes a series of functions into a single function. + + +

Parameters:

+
    +
  • ... + {function} + The functions to compose +
    • +
+ +

Returns:

+
    + + {function} + The composed function +
+ + + +

Usage:

+
    + 
  • utils.compose(fn1)(fn2)(fn3)(v)
    • + 
  • utils.compose(function(x) return x + 1 end)(function(x) return x * 2 end)(3) --> 7
    • +
+ +
+
+ + prop (propName, object) +
+
+ Returns the value of a property of an object. + + +

Parameters:

+
    +
  • propName + {string} + The property name to get +
    • +
  • object + {table} + The object to get the property from +
    • +
+ +

Returns:

+
    + + The + value of the property +
+ + + +

Usage:

+
    + 
  • utils.prop(propName)(object)
    • + 
  • utils.prop("name")({name = "Lua"}) --> "Lua"
    • +
+ +
+
+ + includes (val, t) +
+
+ Checks if an array table includes a value. + + +

Parameters:

+
    +
  • val + The value to check for +
    • +
  • t + {table} + The array table to check +
    • +
+ +

Returns:

+
    + + {boolean} + Whether the value is in the array table +
+ + + +

Usage:

+
    + 
  • utils.includes(val)(t)
    • + 
  • utils.includes(2)({1, 2, 3}) --> true
    • +
+ +
+
+ + keys (t) +
+
+ Returns the keys of a table. + + +

Parameters:

+
    +
  • t + {table} + The table to get the keys from +
    • +
+ +

Returns:

+
    + + {table} + The keys of the table +
+ + + +

Usage:

+
    + 
  • utils.keys(t)
    • + 
  • utils.keys({name = "Lua", age = 25}) --> {"name", "age"}
    • +
+ +
+
+ + values (t) +
+
+ Returns the values of a table. + + +

Parameters:

+
    +
  • t + {table} + The table to get the values from +
    • +
+ +

Returns:

+
    + + {table} + The values of the table +
+ + + +

Usage:

+
    + 
  • utils.values(t)
    • + 
  • utils.values({name = "Lua", age = 25}) --> {"Lua", 25}
    • +
+ +
+
+

Tables

+ +
+
+ + utils +
+
+ The utils table + + +

Fields:

+
    +
  • _version + The version number of the utils module +
    • +
  • matchesPattern + The matchesPattern function +
    • +
  • matchesSpec + The matchesSpec function +
    • +
  • curry + The curry function +
    • +
  • concat + The concat function +
    • +
  • reduce + The reduce function +
    • +
  • map + The map function +
    • +
  • filter + The filter function +
    • +
  • find + The find function +
    • +
  • propEq + The propEq function +
    • +
  • reverse + The reverse function +
    • +
  • compose + The compose function +
    • +
  • prop + The prop function +
    • +
  • includes + The includes function +
    • +
  • keys + The keys function +
    • +
  • values + The values function +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-10-29 14:41:25 +
+
+ + diff --git a/process/eval.lua b/process/eval.lua index da3c6291..957f3e45 100644 --- a/process/eval.lua +++ b/process/eval.lua @@ -1,5 +1,15 @@ +--- The Eval module provides a handler for evaluating Lua expressions. Returns the eval function. +-- @module eval + local stringify = require(".stringify") --- handler for eval + +--- The eval function. +-- Handler for executing and evaluating Lua expressions. +-- After execution, the result is stringified and placed in ao.outbox.Output. +-- @function eval +-- @tparam {table} ao The ao environment object +-- @treturn {function} The handler function, which takes a message as an argument. +-- @see stringify return function (ao) return function (msg) -- exec expression @@ -22,7 +32,7 @@ return function (ao) end if HANDLER_PRINT_LOGS and output then table.insert(HANDLER_PRINT_LOGS, type(output) == "table" and stringify.format(output) or tostring(output)) - else + else -- set result in outbox.Output (Left for backwards compatibility) ao.outbox.Output = { json = type(output) == "table" and pcall(function () return json.encode(output) end) and output or "undefined", @@ -30,9 +40,9 @@ return function (ao) output = type(output) == "table" and stringify.format(output) or output, prompt = Prompt() }, - prompt = Prompt() + prompt = Prompt() } end - end + end end diff --git a/process/handlers-utils.lua b/process/handlers-utils.lua index 93c15984..3f4b89c5 100644 --- a/process/handlers-utils.lua +++ b/process/handlers-utils.lua @@ -1,16 +1,37 @@ +--- The Handler Utils module is a lightweight Lua utility library designed to provide common functionalities for handling and processing messages within the AOS computer system. It offers a set of functions to check message attributes and send replies, simplifying the development of more complex scripts and modules. This document will guide you through the module's functionalities, installation, and usage. Returns the _utils table. +-- @module handlers-utils + +--- The _utils table +-- @table _utils +-- @field _version The version number of the _utils module +-- @field hasMatchingTag The hasMatchingTag function +-- @field hasMatchingTagOf The hasMatchingTagOf function +-- @field hasMatchingData The hasMatchingData function +-- @field reply The reply function +-- @field continue The continue function local _utils = { _version = "0.0.2" } local _ = require('.utils') local ao = require(".ao") +--- Checks if a given message has a tag that matches the specified name and value. +-- @function hasMatchingTag +-- @tparam {string} name The tag name to check +-- @tparam {string} value The value to match for in the tag +-- @treturn {function} A function that takes a message and returns whether there is a tag match (-1 if matches, 0 otherwise) function _utils.hasMatchingTag(name, value) assert(type(name) == 'string' and type(value) == 'string', 'invalid arguments: (name : string, value : string)') - return function (msg) - return msg.Tags[name] == value + return function (msg) + return msg.Tags[name] == value end end +--- Checks if a given message has a tag that matches the specified name and one of the specified values. +-- @function hasMatchingTagOf +-- @tparam {string} name The tag name to check +-- @tparam {string[]} values The list of values of which one should match +-- @treturn {function} A function that takes a message and returns whether there is a tag match (-1 if matches, 0 otherwise) function _utils.hasMatchingTagOf(name, values) assert(type(name) == 'string' and type(values) == 'table', 'invalid arguments: (name : string, values : string[])') return function (msg) @@ -26,6 +47,10 @@ function _utils.hasMatchingTagOf(name, values) end end +--- Checks if a given message has data that matches the specified value. +-- @function hasMatchingData +-- @tparam {string} value The value to match against the message data +-- @treturn {function} A function that takes a message and returns whether the data matches the value (-1 if matches, 0 otherwise) function _utils.hasMatchingData(value) assert(type(value) == 'string', 'invalid arguments: (value : string)') return function (msg) @@ -33,17 +58,25 @@ function _utils.hasMatchingData(value) end end +--- Given an input, returns a function that takes a message and replies to it. +-- @function reply +-- @tparam {table | string} input The content to send back. If a string, it sends it as data. If a table, it assumes a structure with `Tags`. +-- @treturn {function} A function that takes a message and replies to it function _utils.reply(input) assert(type(input) == 'table' or type(input) == 'string', 'invalid arguments: (input : table or string)') return function (msg) if type(input) == 'string' then - msg.reply({ Data = input}) + msg.reply({ Data = input }) return end msg.reply(input) end end +--- Inverts the provided pattern's result if it matches, so that it continues execution with the next matching handler. +-- @function continue +-- @tparam {table | function} pattern The pattern to check for in the message +-- @treturn {function} Function that executes the pattern matching function and returns `1` (continue), so that the execution of handlers continues. function _utils.continue(pattern) return function (msg) local match = _.matchesSpec(msg, pattern) diff --git a/process/handlers.lua b/process/handlers.lua index 2ac36c3f..81fb3d8b 100644 --- a/process/handlers.lua +++ b/process/handlers.lua @@ -1,3 +1,21 @@ +--- The Handlers library provides a flexible way to manage and execute a series of handlers based on patterns. Each handler consists of a pattern function, a handle function, and a name. This library is suitable for scenarios where different actions need to be taken based on varying input criteria. Returns the handlers table. +-- @module handlers + +--- The handlers table +-- @table handlers +-- @field _version The version number of the handlers module +-- @field list The list of handlers +-- @field coroutines The coroutines of the handlers +-- @field onceNonce The nonce for the once handlers +-- @field utils The handlers-utils module +-- @field generateResolver The generateResolver function +-- @field receive The receive function +-- @field once The once function +-- @field add The add function +-- @field append The append function +-- @field prepend The prepend function +-- @field remove The remove function +-- @field evaluate The evaluate function local handlers = { _version = "0.0.5" } local coroutine = require('coroutine') local utils = require('.utils') @@ -14,7 +32,12 @@ else end handlers.onceNonce = 0 - +--- Given an array, a property name, and a value, returns the index of the object in the array that has the property with the value. +-- @lfunction findIndexByProp +-- @tparam {table[]} array The array to search through +-- @tparam {string} prop The property name to check +-- @tparam {any} value The value to check for in the property +-- @treturn {number | nil} The index of the object in the array that has the property with the value, or nil if no such object is found local function findIndexByProp(array, prop, value) for index, object in ipairs(array) do if object[prop] == value then @@ -24,6 +47,12 @@ local function findIndexByProp(array, prop, value) return nil end +--- Given a name, a pattern, and a handle, asserts that the arguments are valid. +-- @lfunction assertAddArgs +-- @tparam {string} name The name of the handler +-- @tparam {table | function | string} pattern The pattern to check for in the message +-- @tparam {function} handle The function to call if the pattern matches +-- @tparam {number | string | nil} maxRuns The maximum number of times the handler should run, or nil if there is no limit local function assertAddArgs(name, pattern, handle, maxRuns) assert( type(name) == 'string' and @@ -36,6 +65,10 @@ local function assertAddArgs(name, pattern, handle, maxRuns) '\tMaxRuns? : number | "inf" | nil') end +--- Given a resolver specification, returns a resolver function. +-- @function generateResolver +-- @tparam {table | function} resolveSpec The resolver specification +-- @treturn {function} A resolver function function handlers.generateResolver(resolveSpec) return function(msg) -- If the resolver is a single function, call it. @@ -52,10 +85,12 @@ function handlers.generateResolver(resolveSpec) end end --- Returns the next message that matches the pattern +--- Given a pattern, returns the next message that matches the pattern. -- This function uses Lua's coroutines under-the-hood to add a handler, pause, -- and then resume the current coroutine. This allows us to effectively block -- processing of one message until another is received that matches the pattern. +-- @function receive +-- @tparam {table | function} pattern The pattern to check for in the message function handlers.receive(pattern) local self = coroutine.running() handlers.once(pattern, function (msg) @@ -68,6 +103,13 @@ function handlers.receive(pattern) return coroutine.yield(pattern) end +--- Given a name, a pattern, and a handle, adds a handler to the list. +-- If name is not provided, "_once_" prefix plus onceNonce will be used as the name. +-- Adds handler with maxRuns of 1 such that it will only be called once then removed from the list. +-- @function once +-- @tparam {string} name The name of the handler +-- @tparam {table | function | string} pattern The pattern to check for in the message +-- @tparam {function} handle The function to call if the pattern matches function handlers.once(...) local name, pattern, handle if select("#", ...) == 3 then @@ -83,6 +125,12 @@ function handlers.once(...) handlers.prepend(name, pattern, handle, 1) end +--- Given a name, a pattern, and a handle, adds a handler to the list. +-- @function add +-- @tparam {string} name The name of the handler +-- @tparam {table | function | string} pattern The pattern to check for in the message +-- @tparam {function} handle The function to call if the pattern matches +-- @tparam {number | string | nil} maxRuns The maximum number of times the handler should run, or nil if there is no limit function handlers.add(...) local name, pattern, handle, maxRuns local args = select("#", ...) @@ -121,6 +169,12 @@ function handlers.add(...) return #handlers.list end +--- Appends a new handler to the end of the handlers list. +-- @function append +-- @tparam {string} name The name of the handler +-- @tparam {table | function | string} pattern The pattern to check for in the message +-- @tparam {function} handle The function to call if the pattern matches +-- @tparam {number | string | nil} maxRuns The maximum number of times the handler should run, or nil if there is no limit function handlers.append(...) local name, pattern, handle, maxRuns local args = select("#", ...) @@ -158,6 +212,12 @@ function handlers.append(...) end +--- Prepends a new handler to the beginning of the handlers list. +-- @function prepend +-- @tparam {string} name The name of the handler +-- @tparam {table | function | string} pattern The pattern to check for in the message +-- @tparam {function} handle The function to call if the pattern matches +-- @tparam {number | string | nil} maxRuns The maximum number of times the handler should run, or nil if there is no limit function handlers.prepend(...) local name, pattern, handle, maxRuns local args = select("#", ...) @@ -195,6 +255,10 @@ function handlers.prepend(...) end +--- Returns an object that allows adding a new handler before a specified handler. +-- @function before +-- @tparam {string} handleName The name of the handler before which the new handler will be added +-- @treturn {table} An object with an `add` method to insert the new handler function handlers.before(handleName) assert(type(handleName) == 'string', 'Handler name MUST be a string') @@ -213,6 +277,10 @@ function handlers.before(handleName) } end +--- Returns an object that allows adding a new handler after a specified handler. +-- @function after +-- @tparam {string} handleName The name of the handler after which the new handler will be added +-- @treturn {table} An object with an `add` method to insert the new handler function handlers.after(handleName) assert(type(handleName) == 'string', 'Handler name MUST be a string') local idx = findIndexByProp(handlers.list, "name", handleName) @@ -231,6 +299,9 @@ function handlers.after(handleName) end +--- Removes a handler from the handlers list by name. +-- @function remove +-- @tparam {string} name The name of the handler to be removed function handlers.remove(name) assert(type(name) == 'string', 'name MUST be string') if #handlers.list == 1 and handlers.list[1].name == name then @@ -245,7 +316,12 @@ function handlers.remove(name) end ---- return 0 to not call handler, -1 to break after handler is called, 1 to continue +--- Evaluates each handler against a given message and environment. Handlers are called in the order they appear in the handlers list. +-- Return 0 to not call handler, -1 to break after handler is called, 1 to continue +-- @function evaluate +-- @tparam {table} msg The message to be processed by the handlers. +-- @tparam {table} env The environment in which the handlers are executed. +-- @treturn The response from the handler(s). Returns a default message if no handler matches. function handlers.evaluate(msg, env) local handled = false assert(type(msg) == 'table', 'msg is not valid') diff --git a/process/pretty.lua b/process/pretty.lua index 89ea8dc2..57cbee74 100644 --- a/process/pretty.lua +++ b/process/pretty.lua @@ -1,6 +1,18 @@ -local pretty = { _version = "0.0.1"} +--- The Pretty module provides a utility for printing Lua tables in a more readable format. +-- @module pretty -function pretty.tprint (tbl, indent) +--- The pretty module +-- @table pretty +-- @field _version The version number of the pretty module +-- @field tprint The tprint function +local pretty = { _version = "0.0.1" } + +--- Prints a table with indentation for better readability. +-- @function tprint +-- @tparam {table} tbl The table to print +-- @tparam {number} indent The indentation level (default is 0) +-- @treturn {string} A string representation of the table with indentation +pretty.tprint = function (tbl, indent) if not indent then indent = 0 end local output = "" for k, v in pairs(tbl) do diff --git a/process/process.lua b/process/process.lua index d756713d..1366f379 100644 --- a/process/process.lua +++ b/process/process.lua @@ -1,3 +1,7 @@ +--- The Process library provides an environment for managing and executing processes on the AO network. It includes capabilities for handling messages, spawning processes, and customizing the environment with programmable logic and handlers. Returns the process table. +-- @module process + +-- @dependencies local pretty = require('.pretty') local base64 = require('.base64') local json = require('json') @@ -31,12 +35,18 @@ end -- Implement assignable polyfills on _ao assignment.init(ao) +--- The process table +-- @table process +-- @field _version The version number of the process + local process = { _version = "2.0.1" } +-- The maximum number of messages to store in the inbox local maxInboxCount = 10000 -- wrap ao.send and ao.spawn for magic table -local aosend = ao.send +local aosend = ao.send local aospawn = ao.spawn + ao.send = function (msg) if msg.Data and type(msg.Data) == 'table' then msg['Content-Type'] = 'application/json' @@ -52,6 +62,10 @@ ao.spawn = function (module, msg) return aospawn(module, msg) end +--- Remove the last three lines from a string +-- @lfunction removeLastThreeLines +-- @tparam {string} input The string to remove the last three lines from +-- @treturn {string} The string with the last three lines removed local function removeLastThreeLines(input) local lines = {} for line in input:gmatch("([^\n]*)\n?") do @@ -67,17 +81,24 @@ local function removeLastThreeLines(input) return table.concat(lines, "\n") end - +--- Insert a message into the inbox and manage overflow +-- @lfunction insertInbox +-- @tparam {table} msg The message to insert into the inbox local function insertInbox(msg) table.insert(Inbox, msg) if #Inbox > maxInboxCount then - local overflow = #Inbox - maxInboxCount + local overflow = #Inbox - maxInboxCount for i = 1,overflow do table.remove(Inbox, 1) end - end + end end +--- Find an object in an array by a given key and value +-- @lfunction findObject +-- @tparam {table} array The array to search through +-- @tparam {string} key The key to search for +-- @tparam {any} value The value to search for local function findObject(array, key, value) for i, object in ipairs(array) do if object[key] == value then @@ -87,6 +108,10 @@ local function findObject(array, key, value) return nil end +--- Convert a message's tags to a table of key-value pairs +-- @function Tab +-- @tparam {table} msg The message containing tags +-- @treturn {table} A table with tag names as keys and their values function Tab(msg) local inputs = {} for _, o in ipairs(msg.Tags) do @@ -97,6 +122,9 @@ function Tab(msg) return inputs end +--- Generate a prompt string for the current process +-- @function Prompt +-- @treturn {string} The custom command prompt string function Prompt() return Colors.green .. Name .. Colors.gray .. "@" .. Colors.blue .. "aos-" .. process._version .. Colors.gray @@ -104,6 +132,9 @@ function Prompt() .. "]" .. Colors.reset .. "> " end +--- Print a value, formatting tables and converting non-string types +-- @function print +-- @tparam {any} a The value to print function print(a) if type(a) == "table" then a = stringify.format(a) @@ -136,6 +167,9 @@ In order to print non string types we need to convert to string return tostring(a) end +--- Send a message to a target process +-- @function Send +-- @tparam {table} msg The message to send function Send(msg) if not msg.Target then print("WARN: No target specified for message. Data will be stored, but no process will receive it.") @@ -148,6 +182,9 @@ function Send(msg) } end +--- Spawn a new process +-- @function Spawn +-- @tparam {...any} args The arguments to pass to the spawn function function Spawn(...) local module, spawnMsg @@ -167,13 +204,20 @@ function Spawn(...) output = "Spawn process request added to outbox", after = result.after, receive = result.receive - } + } end +--- Calls Handlers.receive with the provided pattern criteria, awaiting a message that matches the criteria. +-- @function Receive +-- @tparam {table} match The pattern criteria for the message +-- @treturn {any} The result of the message handling function Receive(match) return Handlers.receive(match) end +--- Assigns based on the assignment passed. +-- @function Assign +-- @tparam {table} assignment The assignment to be made function Assign(assignment) if not ao.assign then print("Assign is not implemented.") @@ -186,6 +230,10 @@ end Seeded = Seeded or false +--- Converts a string to a seed value +-- @lfunction stringToSeed +-- @tparam {string} s The string to convert to a seed +-- @treturn {number} The seed value -- this is a temporary approach... local function stringToSeed(s) local seed = 0 @@ -196,9 +244,12 @@ local function stringToSeed(s) return seed end +--- Initializes or updates the state of the process based on the incoming message and environment. +-- @lfunction initializeState +-- @tparam {table} msg The message to initialize the state with +-- @tparam {table} env The environment to initialize the state with local function initializeState(msg, env) if not Seeded then - --math.randomseed(1234) chance.seed(tonumber(msg['Block-Height'] .. stringToSeed(msg.Owner .. msg.Module .. msg.Id))) math.random = function (...) local args = {...} @@ -240,10 +291,16 @@ local function initializeState(msg, env) end +--- Prints the version of the process +-- @function Version function Version() print("version: " .. process._version) end +--- Main handler for processing incoming messages. It initializes the state, processes commands, and handles message evaluation and inbox management. +-- @function handle +-- @tparam {table} msg The message to handle +-- @tparam {table} _ The environment to handle the message in function process.handle(msg, _) local env = nil if _.Process then diff --git a/process/stringify.lua b/process/stringify.lua index a828e3ac..e3c46fbd 100644 --- a/process/stringify.lua +++ b/process/stringify.lua @@ -1,3 +1,11 @@ +--- The Stringify module provides utilities for formatting and displaying Lua tables in a more readable manner. Returns the stringify table. +-- @module stringify + +--- The stringify table +-- @table stringify +-- @field _version The version number of the stringify module +-- @field isSimpleArray The isSimpleArray function +-- @field format The format function local stringify = { _version = "0.0.1" } -- ANSI color codes @@ -8,6 +16,10 @@ local colors = { reset = "\27[0m" } +--- Checks if a table is a simple array (i.e., an array with consecutive numeric keys starting from 1). +-- @function isSimpleArray +-- @tparam {table} tbl The table to check +-- @treturn {boolean} Whether the table is a simple array function stringify.isSimpleArray(tbl) local arrayIndex = 1 for k, v in pairs(tbl) do @@ -19,6 +31,12 @@ function stringify.isSimpleArray(tbl) return true end +--- Formats a table for display, handling circular references and formatting strings and tables recursively. +-- @function format +-- @tparam {table} tbl The table to format +-- @tparam {number} indent The indentation level (default is 0) +-- @tparam {table} visited A table to track visited tables and detect circular references (optional) +-- @treturn {string} A string representation of the table function stringify.format(tbl, indent, visited) indent = indent or 0 local toIndent = string.rep(" ", indent) diff --git a/process/utils.lua b/process/utils.lua index 8f30cde6..14990942 100644 --- a/process/utils.lua +++ b/process/utils.lua @@ -1,8 +1,35 @@ +--- The Utils module provides a collection of utility functions for functional programming in Lua. It includes functions for array manipulation such as concatenation, mapping, reduction, filtering, and finding elements, as well as a property equality checker. +-- @module utils + +--- The utils table +-- @table utils +-- @field _version The version number of the utils module +-- @field matchesPattern The matchesPattern function +-- @field matchesSpec The matchesSpec function +-- @field curry The curry function +-- @field concat The concat function +-- @field reduce The reduce function +-- @field map The map function +-- @field filter The filter function +-- @field find The find function +-- @field propEq The propEq function +-- @field reverse The reverse function +-- @field compose The compose function +-- @field prop The prop function +-- @field includes The includes function +-- @field keys The keys function +-- @field values The values function local utils = { _version = "0.0.5" } +--- Given a pattern, a value, and a message, returns whether there is a pattern match. +-- @usage utils.matchesPattern(pattern, value, msg) +-- @param pattern The pattern to match +-- @param value The value to check for in the pattern +-- @param msg The message to check for the pattern +-- @treturn {boolean} Whether there is a pattern match function utils.matchesPattern(pattern, value, msg) -- If the key is not in the message, then it does not match - if(not pattern) then + if (not pattern) then return false end -- if the patternMatchSpec is a wildcard, then it always matches @@ -44,6 +71,11 @@ function utils.matchesPattern(pattern, value, msg) return false end +--- Given a message and a spec, returns whether there is a spec match. +-- @usage utils.matchesSpec(msg, spec) +-- @param msg The message to check for the spec +-- @param spec The spec to check for in the message +-- @treturn {boolean} Whether there is a spec match function utils.matchesSpec(msg, spec) if type(spec) == 'function' then return spec(msg) @@ -72,6 +104,12 @@ function utils.matchesSpec(msg, spec) return false end +--- Given a table, returns whether it is an array. +-- An 'array' is defined as a table with integer keys starting from 1 and +-- having no gaps between the keys. +-- @lfunction isArray +-- @param table The table to check +-- @treturn {boolean} Whether the table is an array local function isArray(table) if type(table) == "table" then local maxIndex = 0 @@ -87,8 +125,10 @@ local function isArray(table) return false end --- @param {function} fn --- @param {number} arity +--- Curries a function. +-- @tparam {function} fn The function to curry +-- @tparam {number} arity The arity of the function +-- @treturn {function} The curried function utils.curry = function (fn, arity) assert(type(fn) == "function", "function is required as first argument") arity = arity or debug.getinfo(fn, "u").nparams @@ -107,9 +147,13 @@ utils.curry = function (fn, arity) end end ---- Concat two Array Tables. --- @param {table} a --- @param {table} b +--- Concat two Array Tables +-- @function concat +-- @usage utils.concat(a)(b) +-- @usage utils.concat({1, 2})({3, 4}) --> {1, 2, 3, 4} +-- @tparam {table} a The first array +-- @tparam {table} b The second array +-- @treturn {table} The concatenated array utils.concat = utils.curry(function (a, b) assert(type(a) == "table", "first argument should be a table that is an array") assert(type(b) == "table", "second argument should be a table that is an array") @@ -124,13 +168,16 @@ utils.concat = utils.curry(function (a, b) result[#result + 1] = b[i] end return result - --return table.concat(a,b) end, 2) ---- reduce applies a function to a table --- @param {function} fn --- @param {any} initial --- @param {table} t +--- Applies a function to each element of a table, reducing it to a single value. +-- @function utils.reduce +-- @usage utils.reduce(fn)(initial)(t) +-- @usage utils.reduce(function(acc, x) return acc + x end)(0)({1, 2, 3}) --> 6 +-- @tparam {function} fn The function to apply +-- @param initial The initial value +-- @tparam {table} t The table to reduce +-- @return The reduced value utils.reduce = utils.curry(function (fn, initial, t) assert(type(fn) == "function", "first argument should be a function that accepts (result, value, key)") assert(type(t) == "table" and isArray(t), "third argument should be a table that is an array") @@ -145,8 +192,13 @@ utils.reduce = utils.curry(function (fn, initial, t) return result end, 3) --- @param {function} fn --- @param {table} data +--- Applies a function to each element of an array table, mapping it to a new value. +-- @function utils.map +-- @usage utils.map(fn)(t) +-- @usage utils.map(function(x) return x * 2 end)({1, 2, 3}) --> {2, 4, 6} +-- @tparam {function} fn The function to apply to each element +-- @tparam {table} data The table to map over +-- @treturn {table} The mapped table utils.map = utils.curry(function (fn, data) assert(type(fn) == "function", "first argument should be a unary function") assert(type(data) == "table" and isArray(data), "second argument should be an Array") @@ -159,8 +211,13 @@ utils.map = utils.curry(function (fn, data) return utils.reduce(map, {}, data) end, 2) --- @param {function} fn --- @param {table} data +--- Filters an array table based on a predicate function. +-- @function utils.filter +-- @usage utils.filter(fn)(t) +-- @usage utils.filter(function(x) return x > 1 end)({1, 2, 3}) --> {2,3} +-- @tparam {function} fn The predicate function to determine if an element should be included. +-- @tparam {table} data The array to filter +-- @treturn {table} The filtered table utils.filter = utils.curry(function (fn, data) assert(type(fn) == "function", "first argument should be a unary function") assert(type(data) == "table" and isArray(data), "second argument should be an Array") @@ -175,8 +232,13 @@ utils.filter = utils.curry(function (fn, data) return utils.reduce(filter,{}, data) end, 2) --- @param {function} fn --- @param {table} t +--- Finds the first element in an array table that satisfies a predicate function. +-- @function utils.find +-- @usage utils.find(fn)(t) +-- @usage utils.find(function(x) return x > 1 end)({1, 2, 3}) --> 2 +-- @tparam {function} fn The predicate function to determine if an element should be included. +-- @tparam {table} t The array table to search +-- @treturn The first element that satisfies the predicate function utils.find = utils.curry(function (fn, t) assert(type(fn) == "function", "first argument should be a unary function") assert(type(t) == "table", "second argument should be a table that is an array") @@ -187,18 +249,28 @@ utils.find = utils.curry(function (fn, t) end end, 2) --- @param {string} propName --- @param {string} value --- @param {table} object +--- Checks if a property of an object is equal to a value. +-- @function utils.propEq +-- @usage utils.propEq(propName)(value)(object) +-- @usage utils.propEq("name")("Lua")({name = "Lua"}) --> true +-- @tparam {string} propName The property name to check +-- @tparam {string} value The value to check against +-- @tparam {table} object The object to check +-- @treturn {boolean} Whether the property is equal to the value utils.propEq = utils.curry(function (propName, value, object) assert(type(propName) == "string", "first argument should be a string") - -- assert(type(value) == "string", "second argument should be a string") + assert(type(value) == "string", "second argument should be a string") assert(type(object) == "table", "third argument should be a table") return object[propName] == value end, 3) --- @param {table} data +--- Reverses an array table. +-- @function utils.reverse +-- @usage utils.reverse(data) +-- @usage utils.reverse({1, 2, 3}) --> {3, 2, 1} +-- @tparam {table} data The array table to reverse +-- @treturn {table} The reversed array table utils.reverse = function (data) assert(type(data) == "table", "argument needs to be a table that is an array") return utils.reduce( @@ -211,7 +283,12 @@ utils.reverse = function (data) ) end --- @param {function} ... +--- Composes a series of functions into a single function. +-- @function utils.compose +-- @usage utils.compose(fn1)(fn2)(fn3)(v) +-- @usage utils.compose(function(x) return x + 1 end)(function(x) return x * 2 end)(3) --> 7 +-- @tparam {function} ... The functions to compose +-- @treturn {function} The composed function utils.compose = utils.curry(function (...) local mutations = utils.reverse({...}) @@ -225,20 +302,35 @@ utils.compose = utils.curry(function (...) end end, 2) --- @param {string} propName --- @param {table} object +--- Returns the value of a property of an object. +-- @function utils.prop +-- @usage utils.prop(propName)(object) +-- @usage utils.prop("name")({name = "Lua"}) --> "Lua" +-- @tparam {string} propName The property name to get +-- @tparam {table} object The object to get the property from +-- @treturn The value of the property utils.prop = utils.curry(function (propName, object) return object[propName] end, 2) --- @param {any} val --- @param {table} t +--- Checks if an array table includes a value. +-- @function utils.includes +-- @usage utils.includes(val)(t) +-- @usage utils.includes(2)({1, 2, 3}) --> true +-- @param val The value to check for +-- @tparam {table} t The array table to check +-- @treturn {boolean} Whether the value is in the array table utils.includes = utils.curry(function (val, t) assert(type(t) == "table", "argument needs to be a table") + assert(isArray(t), "argument should be a table that is an array") return utils.find(function (v) return v == val end, t) ~= nil end, 2) --- @param {table} t +--- Returns the keys of a table. +-- @usage utils.keys(t) +-- @usage utils.keys({name = "Lua", age = 25}) --> {"name", "age"} +-- @tparam {table} t The table to get the keys from +-- @treturn {table} The keys of the table utils.keys = function (t) assert(type(t) == "table", "argument needs to be a table") local keys = {} @@ -248,7 +340,11 @@ utils.keys = function (t) return keys end --- @param {table} t +--- Returns the values of a table. +-- @usage utils.values(t) +-- @usage utils.values({name = "Lua", age = 25}) --> {"Lua", 25} +-- @tparam {table} t The table to get the values from +-- @treturn {table} The values of the table utils.values = function (t) assert(type(t) == "table", "argument needs to be a table") local values = {}