From 589575ef2d43351bb53e6f64cb675fecbe8dd07b Mon Sep 17 00:00:00 2001 From: Hybrid Dog Date: Thu, 24 Aug 2017 18:05:34 +0200 Subject: [PATCH] Update documentation of instructions and change tostring and tonumber behaviour --- README.md | 165 +++++++++++++------------------ standardbefehlssatz.lua | 4 +- util/standartbefehlssatz_doc.lua | 98 ++++++++++-------- 3 files changed, 123 insertions(+), 144 deletions(-) diff --git a/README.md b/README.md index 362fe44..1d15bfb 100644 --- a/README.md +++ b/README.md @@ -2,112 +2,78 @@ commands are read line by line ```[:] [ [[,]``` -arguments can be either variables, labels or immediates, -labels are replaced with immediates which have the line numbers of the labels as their values -true/false: boolean (immediate) -12.6: number (immediate) -$hello nwae: string (immediate) -nodolla: either a label is called so (immediate) or it's a variable -If you want to use : in a string, you need to put it at the beginning of the line to not treat the left part as label - -``` -Types: - -e anything -v any variable -ve any set variable -s string -vs string variable -n number -vn number variable -ui unsigned integer number -b bool -vn bool variable +arguments can be either variables, labels or immediates,
+labels are replaced with immediates which have the line numbers of the labels as +their values
+true/false: boolean (immediate)
+12.6: number (immediate)
+$hello nwae: string (immediate)
+nodolla: either a label is called so (immediate) or it's a variable
+If you want to use : in a string, you need to put it at the beginning of the +line to not treat the left part as label -Instructions: -mov , - Copies from into to. +### Types -getvar [, ] - Sets varname to the current variable called if it's set. If exists is passed, it's set to a bool indicating whether the variable was set. +Name | Description +----|------------- +e| anything defined +v| any variable +ve| any defined variable +s| string +vs| string variable +n| number +vn| number variable +ui| unsigned integer number +b| bool +vb| bool variable -add , - to += from -add , - to = to and from +### Instructions -add , - to = to .. from +Name | Parameters | Description +-----|------------|------------ +mov | `, ` | `to <= from`; Copies from into to. +xchg | `, ` | `a,b <= b,a`; Switches a with b. +getvar | `[, ]` | Sets varname to the current variable called if it's set. If exists is passed, it's set to a bool indicating whether the variable was set. +copytable | `, ` | Copies ${origin}.* to ${target}.*. +add | `, ` | `to <= to + from` +add | `[, [, […]]]` | `to <= to ∨ ba ∨ bb ∨ …`; logical or: *to* indicates whether at least one of the arguments is true +add | `, ` | `to <= to .. from`; string concatenation +sub | `, ` | `num <= num - tosub` +sub | `, [, ]` | `str <= str:sub(start, end)`; substring +mul | `, ` | `to <= to * from`; multiplication +mul | `[, [, […]]]` | `to <= to ∧ ba ∧ bb ∧ …`; logical and: *to* indicates whether all of the arguments are true +mul | `, ` | `str <= str:rep(cnt)`; repeating a string cnt times +div | `, ` | `num <= num / todiv`; division +inc | `` | `num <= num + 1` +dec | `` | `num <= num - 1` +neg | `` | `num <= -num`; negation +neg | `` | `var <= ¬var`; logical not +neg | `` | `str <= str:rev()`; reverts a string +inv | `` | `num <= 1 / num` +mod | `, ` | `num <= num mod dv`; modulo +jmp | `[, ]` | jump; If *cond* is not *false*, the instruction pointer is set to *target*. To disallow infinite loops, the program is interrupted after changing it, mods may have different heuristics about restarting it then. +call | `[, ]` | same as pushing the current instruction pointer and then jumping (see jmp); used to execute subroutines +ret | no arguments | pop some unsigned integer, then jump there; used to exit subroutines +push | `[, [, […]]]` | put values onto the stack; from left to right +pop | `[, [, […]]]` | takes values from the stack and sets the passed variables to them; the last variable must be a defined one; from left to right +equal | `, ` | `a <= (a = b)`; equality +less | `, ` | `a <= (a < b)`; after executing, a is a bool +less | `, ` | `a <= (a < b)`; less also works for strings, it compares characters from left to right, see man ASCII for the order +greater | `, ` | executes less b,a +usleep | `` | aborts the program for at least ⌊max{0, t}⌋ microseconds +sleep | `` | executes usleep with t * 1000000 as argument +get_us_time | `` | stores current time in microsecond precision into *to*; can be used to measure time differences +tostring | `` | Sets *var* to a string representing its value; if it's not defined, it's set to `$nil`, if it's a boolean, it's set to `$true` or `$false` +tonumber | `` | Sets *var* to a number representing its value +toboolean | `` | If *var* is `false` or not defined, it's set to `false`, else it's set to `true`. +print | `[, [, […]]]` | adds variables to the log, seperated by \t (tab), \n (newline) is added at the end +flush | no arguments | Output the log, what exactly happens should vary for every mod. -mul , - to *= from +Note to Developers: Do not edit the instructions manually here in the Readme, do changes in util/standartbefehlssatz_doc.lua and execute it. -mul , - to = to or from - -mul , - str = str:rep(from) - -neg - num = -num - -neg - var = not var - -neg - str = str:rev() - -inv - num = 1 / num - -mod , - num = num % dv - -jmp [, ] - If c is not false, the instruction pointer is set to p. To disallow infinite loops, the program is interrupted after changing the ip, the mod should then consider restarting it. - -call - push the ip, then jmp p; used to execute subroutines - -ret - pop something, then jmp there; used to exit subroutines - -push [, [, […]]] - put values onto the stack; from left to right - -pop [, [, […]]] - takes values from the stack and sets the passed variables to them; from left to right - -equal , - a = a == b - -less , - a = a < b; after executing, a is a bool - -less , - a = a < b; less also works for strings - -usleep - aborts the program for at least floor(max(0, t)) ms - -sleep - executes usleep with t * 1000000 as argument - -get_us_time - stores minetest.get_us_time() into to; can be used to measure time differences - -tostring - var = tostring(var) - -print [, [, […]]] - adds variables to the log, seperated by \t, \n is added at the end - -flush - Output the log, this should vary for every mod. -``` @@ -144,6 +110,7 @@ end ``` -TODO: +TODO: * add string. instructions -* metatable +* security: test table copy functions +* update README diff --git a/standardbefehlssatz.lua b/standardbefehlssatz.lua index 663ea20..c6a775b 100644 --- a/standardbefehlssatz.lua +++ b/standardbefehlssatz.lua @@ -298,11 +298,11 @@ s = { end, tostring = function(params) - return true, params[1] and tostring(params[1]) or nil + return true, tostring(params[1]) end, tonumber = function(params) - return true, params[1] and tonumber(params[1]) + return true, tonumber(params[1]) end, toboolean = function(params) diff --git a/util/standartbefehlssatz_doc.lua b/util/standartbefehlssatz_doc.lua index b54b4de..7d3b20c 100644 --- a/util/standartbefehlssatz_doc.lua +++ b/util/standartbefehlssatz_doc.lua @@ -1,54 +1,54 @@ local types = { - {"e", "anything"}, + {"e", "anything defined"}, {"v", "any variable"}, - {"ve", "any set variable"}, + {"ve", "any defined variable"}, {"s", "string"}, {"vs", "string variable"}, {"n", "number"}, {"vn", "number variable"}, {"ui", "unsigned integer number"}, {"b", "bool"}, - {"vn", "bool variable"} + {"vb", "bool variable"} } local instr = { - {"mov", ", ", "Copies from into to."}, - {"xchg", ", ", "Switches a with b."}, + {"mov", ", ", "`to <= from`; Copies from into to."}, + {"xchg", ", ", "`a,b <= b,a`; Switches a with b."}, {"getvar", "[, ]", "Sets varname to the current variable called if it's set. If exists is passed, it's set to a bool indicating whether the variable was set."}, {"copytable", ", ", "Copies ${origin}.* to ${target}.*."}, - {"add", ", ", "to += from"}, - {"add", "[, [, […]]]", "to indicates whether at least one of the arguments is true"}, - {"add", ", ", "to = to .. from"}, - {"sub", ", ", "num -= tosub"}, - {"sub", ", [, ]", "str = str:sub(start, end)"}, - {"mul", ", ", "to *= from"}, - {"mul", "[, [, […]]]", "to indicates whether all of the arguments are true"}, - {"mul", ", ", "str = str:rep(from)"}, - {"div", ", ", "num /= todiv"}, - {"inc", "", "++num"}, - {"dec", "", "--num"}, - {"neg", "", "num = -num"}, - {"neg", "", "var = not var"}, - {"neg", "", "str = str:rev()"}, - {"inv", "", "num = 1 / num"}, - {"mod", ", ", "num = num mod dv"}, - {"jmp", "[, ]", "If c is not false, the instruction pointer is set to p. To disallow infinite loops, the program is interrupted after changing the ip, the mod should then consider restarting it."}, - {"call", "[, ]", "push the ip, then jmp p; used to execute subroutines"}, - {"ret", "", "pop something, then jmp there; used to exit subroutines"}, + {"add", ", ", "`to <= to + from`"}, + {"add", "[, [, […]]]", "`to <= to ∨ ba ∨ bb ∨ …`; logical or: *to* indicates whether at least one of the arguments is true"}, + {"add", ", ", "`to <= to .. from`; string concatenation"}, + {"sub", ", ", "`num <= num - tosub`"}, + {"sub", ", [, ]", "`str <= str:sub(start, end)`; substring"}, + {"mul", ", ", "`to <= to * from`; multiplication"}, + {"mul", "[, [, […]]]", "`to <= to ∧ ba ∧ bb ∧ …`; logical and: *to* indicates whether all of the arguments are true"}, + {"mul", ", ", "`str <= str:rep(cnt)`; repeating a string cnt times"}, + {"div", ", ", "`num <= num / todiv`; division"}, + {"inc", "", "`num <= num + 1`"}, + {"dec", "", "`num <= num - 1`"}, + {"neg", "", "`num <= -num`; negation"}, + {"neg", "", "`var <= ¬var`; logical not"}, + {"neg", "", "`str <= str:rev()`; reverts a string"}, + {"inv", "", "`num <= 1 / num`"}, + {"mod", ", ", "`num <= num mod dv`; modulo"}, + {"jmp", "[, ]", "jump; If *cond* is not *false*, the instruction pointer is set to *target*. To disallow infinite loops, the program is interrupted after changing it, mods may have different heuristics about restarting it then."}, + {"call", "[, ]", "same as pushing the current instruction pointer and then jumping (see jmp); used to execute subroutines"}, + {"ret", "", "pop some unsigned integer, then jump there; used to exit subroutines"}, {"push", "[, [, […]]]", "put values onto the stack; from left to right"}, - {"pop", "[, [, […]]]", "takes values from the stack and sets the passed variables to them; from left to right"}, - {"equal", ", ", "a = a == b"}, - {"less", ", ", "a = a < b; after executing, a is a bool"}, - {"less", ", ", "a = a < b; less also works for strings"}, + {"pop", "[, [, […]]]", "takes values from the stack and sets the passed variables to them; the last variable must be a defined one; from left to right"}, + {"equal", ", ", "`a <= (a = b)`; equality"}, + {"less", ", ", "`a <= (a < b)`; after executing, a is a bool"}, + {"less", ", ", "`a <= (a < b)`; less also works for strings, it compares characters from left to right, see man ASCII for the order"}, {"greater", ", ", "executes less b,a"}, - {"usleep", "", "aborts the program for at least floor(max(0, t)) ms"}, + {"usleep", "", "aborts the program for at least ⌊max{0, t}⌋ microseconds"}, {"sleep", "", "executes usleep with t * 1000000 as argument"}, - {"get_us_time", "", "stores minetest.get_us_time() into to; can be used to measure time differences"}, - {"tostring", "", "var = tostring(var)"}, - {"tonumber", "", "var = tonumber(var)"}, - {"toboolean", "", "var = var and true or false"}, - {"print", "[, [, […]]]", "adds variables to the log, seperated by \\t, \\n is added at the end"}, - {"flush", "", "Output the log, this should vary for every mod."}, + {"get_us_time", "", "stores current time in microsecond precision into *to*; can be used to measure time differences"}, + {"tostring", "", "Sets *var* to a string representing its value; if it's not defined, it's set to `$nil`, if it's a boolean, it's set to `$true` or `$false`"}, + {"tonumber", "", "Sets *var* to a number representing its value"}, + {"toboolean", "", "If *var* is `false` or not defined, it's set to `false`, else it's set to `true`."}, + {"print", "[, [, […]]]", "adds variables to the log, seperated by \\t (tab), \\n (newline) is added at the end"}, + {"flush", "", "Output the log, what exactly happens should vary for every mod."}, } --[[ @@ -60,19 +60,31 @@ for i = 1,#instr do mal = math.max(#bef[2], mal) end--]] -local mtl = 2 - -local o = "Types:\n\n" +local o = "### Types\n\n" .. + "Name | Description\n" .. + "----|-------------\n" for i = 1,#types do local t = types[i] - o = o .. t[1] .. (" "):rep(mtl - #t[1] + 2) .. t[2] .. "\n" + o = o .. t[1] .. (" "):rep(1 - #t[1]) .. "| " .. t[2] .. "\n" end -o = o .. "\n\nInstructions:\n\n" +o = o .. "\n\n### Instructions\n\n" .. + "Name | Parameters | Description\n" .. + "-----|------------|------------\n" for i = 1,#instr do i = instr[i] - o = o .. i[1] .. " " .. i[2] .. "\n" - .. " " .. i[3] .. "\n\n" -- TODO: max 80 letters each line + if i[2] ~= "" then + i[2] = "`" .. i[2] .. "`" + else + i[2] = "no arguments" + end + o = o .. i[1] .. " | " .. i[2] .. " | " .. i[3] .. "\n" end -print(o) +o = o .. + "\nNote to Developers: Do not edit the instructions manually " .. + "here in the Readme, do changes in util/standartbefehlssatz_doc.lua and " .. + "execute it.\n" + +io.write(o) +io.flush()