Reuh/anselme
1
0
Fork 0
mirror of https://github.com/Reuh/anselme.git synced 2025-10-27 16:49:31 +00:00
Code Releases Activity

Update docs

Browse source
This commit is contained in:
Étienne Fildadut 2023-12-28 17:42:14 +01:00
parent 809613ef8b
commit 9acde377c2
3 changed files with 44 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

54
doc/api.md
View file

@ -49,31 +49,31 @@ end
Global version string. Follow semver.
_defined at line 52 of [anselme.lua](../anselme.lua):_ `version = "2.0.0-alpha",`
_defined at line 57 of [anselme.lua](../anselme.lua):_ `version = "2.0.0-alpha",`
### .versions
Table containing per-category version numbers. Incremented by one for any change that may break compatibility.
_defined at line 55 of [anselme.lua](../anselme.lua):_ `versions = {`
_defined at line 60 of [anselme.lua](../anselme.lua):_ `versions = {`
#### .language
Version number for languages and standard library changes.
_defined at line 57 of [anselme.lua](../anselme.lua):_ `language = 27,`
_defined at line 62 of [anselme.lua](../anselme.lua):_ `language = 27,`
#### .save
Version number for save/AST format changes.
_defined at line 59 of [anselme.lua](../anselme.lua):_ `save = 4,`
_defined at line 64 of [anselme.lua](../anselme.lua):_ `save = 4,`
#### .api
Version number for Lua API changes.
_defined at line 61 of [anselme.lua](../anselme.lua):_ `api = 8`
_defined at line 66 of [anselme.lua](../anselme.lua):_ `api = 8`
### .parse (code, source)
@ -87,17 +87,17 @@ local ast = anselme.parse("1 + 2", "test")
ast:eval()
```
_defined at line 73 of [anselme.lua](../anselme.lua):_ `parse = function(code, source)`
_defined at line 78 of [anselme.lua](../anselme.lua):_ `parse = function(code, source)`
### .new ()
Return a new [State](#state).
_defined at line 77 of [anselme.lua](../anselme.lua):_ `new = function()`
_defined at line 82 of [anselme.lua](../anselme.lua):_ `new = function()`
---
_file generated at 2023-12-21T20:56:31Z_
_file generated at 2023-12-28T16:41:42Z_
# State
@ -109,7 +109,7 @@ Each State can run a single script at a time, and variable changes are isolated
Load standard library.
You will probably want to call this on every State right after creation.
_defined at line 40 of [state/State.lua](../state/State.lua):_ `load_stdlib = function(self)`
_defined at line 41 of [state/State.lua](../state/State.lua):_ `load_stdlib = function(self)`
## Branching and merging
@ -117,13 +117,13 @@ _defined at line 40 of [state/State.lua](../state/State.lua):_ `load_stdlib = fu
Name of the branch associated to this State.
_defined at line 47 of [state/State.lua](../state/State.lua):_ `branch_id = "main",`
_defined at line 48 of [state/State.lua](../state/State.lua):_ `branch_id = "main",`
### .source_branch_id
Name of the branch this State was branched from.
_defined at line 49 of [state/State.lua](../state/State.lua):_ `source_branch_id = "main",`
_defined at line 50 of [state/State.lua](../state/State.lua):_ `source_branch_id = "main",`
### :branch ()
@ -132,7 +132,7 @@ Return a new branch of this State.
Branches act as indepent copies of this State where any change will not be reflected in the source State until it is merged back into the source branch.
Note: probably makes the most sense to create branches from the main State only.
_defined at line 55 of [state/State.lua](../state/State.lua):_ `branch = function(self)`
_defined at line 56 of [state/State.lua](../state/State.lua):_ `branch = function(self)`
### :merge ()
@ -142,7 +142,7 @@ Recommendation: only merge if you know that the state of the variables is consis
If your script errored or was interrupted at an unknown point in the script, you might be in the middle of a calculation and variables won't contain
values you want to merge.
_defined at line 64 of [state/State.lua](../state/State.lua):_ `merge = function(self)`
_defined at line 65 of [state/State.lua](../state/State.lua):_ `merge = function(self)`
## Variable definition
@ -159,13 +159,13 @@ Define a value in the global scope, converting it from Lua to Anselme if needed.
If `raw_mode` is true, no anselme-to/from-lua conversion will be performed in the function.
The function will receive the state followed by AST nodes as arguments, and is expected to return an AST node.
_defined at line 82 of [state/State.lua](../state/State.lua):_ `define = function(self, name, value, func, raw_mode)`
_defined at line 83 of [state/State.lua](../state/State.lua):_ `define = function(self, name, value, func, raw_mode)`
### :define_local (name, value, func, raw_mode)
Same as `:define`, but define the expression in the current scope.
_defined at line 88 of [state/State.lua](../state/State.lua):_ `define_local = function(self, name, value, func, raw_mode)`
_defined at line 89 of [state/State.lua](../state/State.lua):_ `define_local = function(self, name, value, func, raw_mode)`
For anything more advanced, you can directly access the current scope stack stored in `state.scope`.
See [state/ScopeStack.lua](../state/ScopeStack.lua) for details; the documentation is not as polished as this file but you should still be able to find your way around.
@ -174,19 +174,19 @@ See [state/ScopeStack.lua](../state/ScopeStack.lua) for details; the documentati
### :save ()
Return a serialized (string) representation of all global persistent variables in this State.
Return a serialized (string) representation of all persistent variables in this State.
This can be loaded back later using `:load`.
_defined at line 100 of [state/State.lua](../state/State.lua):_ `save = function(self)`
_defined at line 101 of [state/State.lua](../state/State.lua):_ `save = function(self)`
### :load (save)
Load a string generated by `:save`.
Variables that do not exist currently in the global scope will be defined, those that do will be overwritten with the loaded data.
Variables that already exist will be overwritten with the loaded data.
_defined at line 107 of [state/State.lua](../state/State.lua):_ `load = function(self, save)`
_defined at line 108 of [state/State.lua](../state/State.lua):_ `load = function(self, save)`
## Current script state
@ -194,7 +194,7 @@ _defined at line 107 of [state/State.lua](../state/State.lua):_ `load = function
Indicate if a script is currently loaded in this branch.
_defined at line 127 of [state/State.lua](../state/State.lua):_ `active = function(self)`
_defined at line 122 of [state/State.lua](../state/State.lua):_ `active = function(self)`
### :state ()
@ -204,7 +204,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 135 of [state/State.lua](../state/State.lua):_ `state = function(self)`
_defined at line 130 of [state/State.lua](../state/State.lua):_ `state = function(self)`
### :run (code, source)
@ -214,7 +214,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 147 of [state/State.lua](../state/State.lua):_ `run = function(self, code, source)`
_defined at line 142 of [state/State.lua](../state/State.lua):_ `run = function(self, code, source)`
### :step ()
@ -224,7 +224,7 @@ Will error if no script is active.
Returns `event type string, event data`.
_defined at line 160 of [state/State.lua](../state/State.lua):_ `step = function(self)`
_defined at line 155 of [state/State.lua](../state/State.lua):_ `step = function(self)`
### :interrupt (code, source)
@ -235,7 +235,7 @@ Will error if no script is active.
If `code` is given, the script will not be disabled but instead will be immediately replaced with this new script.
The new script will then be started on the next `:step` and will preserve the current scope. This can be used to trigger an exit function or similar in the active script.
_defined at line 178 of [state/State.lua](../state/State.lua):_ `interrupt = function(self, code, source)`
_defined at line 173 of [state/State.lua](../state/State.lua):_ `interrupt = function(self, code, source)`
### :eval (code, source)
@ -246,13 +246,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 199 of [state/State.lua](../state/State.lua):_ `eval = function(self, code, source)`
_defined at line 194 of [state/State.lua](../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 206 of [state/State.lua](../state/State.lua):_ `eval_local = function(self, code, source)`
_defined at line 201 of [state/State.lua](../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).
@ -260,4 +260,4 @@ Otherwise, each Node has its own module file defined in the [ast/](../ast) direc
---
_file generated at 2023-12-21T20:56:31Z_
_file generated at 2023-12-28T16:41:42Z_