From 98917c2ca44a7a4ba160494416e86b013104ac87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Reuh=20Fildadut?= Date: Fri, 5 Jan 2024 01:52:21 +0100 Subject: [PATCH] Update doc --- anselme/ast/Function.lua | 1 + anselme/init.lua | 6 +++--- doc/api.md | 32 ++++++++++++++++---------------- ideas.md | 26 +++++++++++++------------- test/run.lua | 6 +++--- 5 files changed, 36 insertions(+), 35 deletions(-) diff --git a/anselme/ast/Function.lua b/anselme/ast/Function.lua index 7d2fba0..77c3e4d 100644 --- a/anselme/ast/Function.lua +++ b/anselme/ast/Function.lua @@ -124,6 +124,7 @@ Function = Overloadable { -- Note: when serializing and reloading a function, its upvalues will not be linked anymore to their original definition. -- The reloaded function will not be able to affect variables defined outside its body. -- Only the upvalues that explicitely appear in the function body will be saved, so we don't have to keep a copy of the whole environment. + -- TODO: we should also store variables that have been defined in the function scope, even if they are not referred directly in the body _serialize = function(self) return { parameters = self.parameters, expression = self.expression, upvalues = self.upvalues } end, diff --git a/anselme/init.lua b/anselme/init.lua index 1ca0494..ee06797 100644 --- a/anselme/init.lua +++ b/anselme/init.lua @@ -58,10 +58,10 @@ local anselme = { --- Table containing per-category version numbers. Incremented by one for any change that may break compatibility. versions = { - --- Version number for languages and standard library changes. - language = 28, + --- Version number for language and standard library changes. + language = 29, --- Version number for save/AST format changes. - save = 5, + save = 6, --- Version number for Lua API changes. api = 9 }, diff --git a/doc/api.md b/doc/api.md index d28be64..0032663 100644 --- a/doc/api.md +++ b/doc/api.md @@ -17,7 +17,7 @@ state:load_stdlib() -- read an anselme script file local f = assert(io.open("script.ans")) -local script = anselme.parse(f:read("*a"), "script.ans") +local script = anselme.parse(f:read("a"), "script.ans") f:close() -- load the script in a new branch @@ -35,7 +35,7 @@ while run_state:active() do for i, l in ipairs(data) do print(("%s> %s"):format(i, l:format(run_state))) end - local choice = tonumber(io.read("*l")) + local choice = tonumber(io.read("l")) data:choose(choice) elseif e == "return" then run_state:merge() @@ -56,7 +56,7 @@ Anselme expects that `require("anselme.module")` will try loading both `anselme/ Global version string. Follow semver. -_defined at line 57 of [anselme/init.lua](../anselme/init.lua):_ `version = "2.0.0-alpha",` +_defined at line 57 of [anselme/init.lua](../anselme/init.lua):_ `version = "2.0.0-beta",` ### .versions @@ -66,21 +66,21 @@ _defined at line 60 of [anselme/init.lua](../anselme/init.lua):_ `versions = {` #### .language -Version number for languages and standard library changes. +Version number for language and standard library changes. -_defined at line 62 of [anselme/init.lua](../anselme/init.lua):_ `language = 27,` +_defined at line 62 of [anselme/init.lua](../anselme/init.lua):_ `language = 29,` #### .save Version number for save/AST format changes. -_defined at line 64 of [anselme/init.lua](../anselme/init.lua):_ `save = 4,` +_defined at line 64 of [anselme/init.lua](../anselme/init.lua):_ `save = 6,` #### .api Version number for Lua API changes. -_defined at line 66 of [anselme/init.lua](../anselme/init.lua):_ `api = 8` +_defined at line 66 of [anselme/init.lua](../anselme/init.lua):_ `api = 9` ### .parse (code, source) @@ -104,7 +104,7 @@ _defined at line 82 of [anselme/init.lua](../anselme/init.lua):_ `new = function --- -_file generated at 2023-12-31T18:43:08Z_ +_file generated at 2024-01-05T00:44:54Z_ # State @@ -213,7 +213,7 @@ _defined at line 122 of [anselme/state/State.lua](../anselme/state/State.lua):_ Indicate if a script is currently loaded in this branch. -_defined at line 136 of [anselme/state/State.lua](../anselme/state/State.lua):_ `active = function(self)` +_defined at line 137 of [anselme/state/State.lua](../anselme/state/State.lua):_ `active = function(self)` ### :state () @@ -223,7 +223,7 @@ Returns `"active"` if a script is loaded but not currently running (i.e. the scr Returns `"inactive"` if no script is loaded. -_defined at line 144 of [anselme/state/State.lua](../anselme/state/State.lua):_ `state = function(self)` +_defined at line 145 of [anselme/state/State.lua](../anselme/state/State.lua):_ `state = function(self)` ### :run (code, source) @@ -233,7 +233,7 @@ Load a script in this branch. It will become the active script. Note that this will only load the script; execution will only start by using the `:step` method. Will error if a script is already active in this State. -_defined at line 156 of [anselme/state/State.lua](../anselme/state/State.lua):_ `run = function(self, code, source)` +_defined at line 157 of [anselme/state/State.lua](../anselme/state/State.lua):_ `run = function(self, code, source)` ### :step () @@ -243,7 +243,7 @@ Will error if no script is active. Returns `event type string, event data`. -_defined at line 169 of [anselme/state/State.lua](../anselme/state/State.lua):_ `step = function(self)` +_defined at line 171 of [anselme/state/State.lua](../anselme/state/State.lua):_ `step = function(self)` ### :interrupt (code, source) @@ -256,7 +256,7 @@ The new script will then be started on the next `:step` and will preserve the cu If this is called from within a running script, this will raise an `interrupt` event in order to stop the current script execution. -_defined at line 189 of [anselme/state/State.lua](../anselme/state/State.lua):_ `interrupt = function(self, code, source)` +_defined at line 191 of [anselme/state/State.lua](../anselme/state/State.lua):_ `interrupt = function(self, code, source)` ### :eval (code, source) @@ -267,13 +267,13 @@ This can be called from outside a running script, but an error will be triggered * returns AST in case of success. Run `:to_lua(state)` on it to convert to a Lua value. * returns `nil, error message` in case of error. -_defined at line 212 of [anselme/state/State.lua](../anselme/state/State.lua):_ `eval = function(self, code, source)` +_defined at line 215 of [anselme/state/State.lua](../anselme/state/State.lua):_ `eval = function(self, code, source)` ### :eval_local (code, source) Same as `:eval`, but evaluate the expression in the current scope. -_defined at line 219 of [anselme/state/State.lua](../anselme/state/State.lua):_ `eval_local = function(self, code, source)` +_defined at line 222 of [anselme/state/State.lua](../anselme/state/State.lua):_ `eval_local = function(self, code, source)` If you want to perform more advanced manipulation of the resulting AST nodes, look at the `ast` modules. In particular, every Node inherits the methods from [ast.abstract.Node](../ast/abstract/Node.lua). @@ -281,4 +281,4 @@ Otherwise, each Node has its own module file defined in the [ast/](../ast) direc --- -_file generated at 2023-12-31T18:43:08Z_ +_file generated at 2024-01-05T00:44:54Z_ diff --git a/ideas.md b/ideas.md index 877b98e..99802fc 100644 --- a/ideas.md +++ b/ideas.md @@ -2,7 +2,7 @@ Various ideas and things that may or may not be done. It's like GitHub issues, b Loosely ordered by willingness to implement. ---- +# To do or discard before stable release Documentation: * language reference @@ -27,16 +27,6 @@ Standard library. --- -Server API. - -To be able to use Anselme in another language, it would be nice to be able to access it over some form of IPC. - -No need to bother with networking I think. Just do some stdin/stdout handling, maybe use something like JSON-RPC: https://www.jsonrpc.org/specification (reminder: will need to add some metadata to specify content length, not aware of any streaming json lib in pure Lua - here's a rxi seal of quality library btw: https://github.com/rxi/json.lua). Or just make our own protocol around JSON. -Issue: how to represent Anselme values? they will probably contain cycles, needs to access their methods, etc. -Probably wise to look into how other do it. LSP: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/ - ---- - Default arguments and initial variables values should pass the type check associated with the variable / parameter. Issue: dispatch is decided before evaluating default values. @@ -50,13 +40,23 @@ Syntax modifications: :a, :b = 5, 6 a, b = list!($(l) l[3], l[6]) - Easy by interpreting the left operand as a List. + Easy by interpreting the left operand as a List. And also make this work for for loops. - regular operator assignments: Could interpret the left operand as a string when it is an identifier, like how _._ works. Would feel good to have less nodes. But because we can doesn't mean we should. Also Assignment is reused in a few other places. - - remove operators if possible, i'd like to avoid the code looking like a bunch of sigils. Could be replaced by functions: _|>_, _::_ +* remove operators if possible, i'd like to avoid the code looking like a bunch of sigils. Could be replaced by functions: _|>_, _::_ + +# Can be done later + +Server API. + +To be able to use Anselme in another language, it would be nice to be able to access it over some form of IPC. + +No need to bother with networking I think. Just do some stdin/stdout handling, maybe use something like JSON-RPC: https://www.jsonrpc.org/specification (reminder: will need to add some metadata to specify content length, not aware of any streaming json lib in pure Lua - here's a rxi seal of quality library btw: https://github.com/rxi/json.lua). Or just make our own protocol around JSON. +Issue: how to represent Anselme values? they will probably contain cycles, needs to access their methods, etc. +Probably wise to look into how other do it. LSP: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/ --- diff --git a/test/run.lua b/test/run.lua index c65fc1c..a9a3b9e 100644 --- a/test/run.lua +++ b/test/run.lua @@ -1,6 +1,5 @@ --- Require LuaFileSystem: luarocks install luafilesystem - -local lfs = require("lfs") +-- Require LuaFileSystem for running test suite: luarocks install luafilesystem +-- Not needed for running a single script in interactive mode. package.path = "./?/init.lua;./?.lua;" .. package.path local anselme = require("anselme") @@ -144,6 +143,7 @@ if not arg[1] or arg[1] == "update" then } -- list tests + local lfs = require("lfs") local tests = {} for test in lfs.dir("test/tests/") do if test:match("%.ans$") then