From e477ba3b42465864ccf3517bc07ceed7a06359ae Mon Sep 17 00:00:00 2001 From: Andrew Lalis Date: Tue, 2 May 2023 10:28:43 +0200 Subject: [PATCH] Added some more documentation. --- docs/src/guide/itemscript/filters.md | 21 +++++++++++++++++++++ docs/src/guide/movescript/reference.md | 16 ++++++++++++++-- docs/src/guide/movescript/spec.md | 2 +- src/itemscript.lua | 15 ++++++++++++++- src/movescript.lua | 9 +++++++++ 5 files changed, 59 insertions(+), 4 deletions(-) diff --git a/docs/src/guide/itemscript/filters.md b/docs/src/guide/itemscript/filters.md index afe43a8..fa20ebc 100644 --- a/docs/src/guide/itemscript/filters.md +++ b/docs/src/guide/itemscript/filters.md @@ -26,6 +26,27 @@ In the case of strings, a **filter expression string** is a string that can be u The most basic form of an expression string is just an item name, like `"minecraft:dirt"`, or `"create:train_door"`. Most normal items will begin with the `minecraft:` *namespace* prefix. If you don't include such a prefix, and you're not doing a [fuzzy match](#fuzzy-match), itemscript will add `minecraft:` for you. +### Grammar + +Filter expressions can be summarized with a BNF-style grammar description. + +``` +word = %a[%w%-_:]* A whole or substring of an item's name. +number = %d+ +expr = word Matches item stacks whose name matches the given word. + = #word Matches item stacks whose name contains the given word. + = (expr) Grouping of a nested expression. + = !expr Matches item stacks that don't match the given expression. + = expr | expr Matches item stacks that match any of the given expressions (OR). + = expr & expr Matches item stacks that match all of the given expressions (AND). + = expr > number Matches item stacks that match the given expression, and have more than N items. + = expr >= number Matches item stacks that match the given expression, and have more than or equal to N items. + = expr < number Matches item stacks that match the given expression, and have less than N items. + = expr <= number Matches item stacks that match the given expression, and have less than or equal to N items. + = expr = number Matches item stacks that match the given expression, and have exactly N items. + = expr != number Matches item stacks that match the given expression, and do not have exactly N items. +``` + For example, we can count the number of stone items in our inventory like this: ```lua diff --git a/docs/src/guide/movescript/reference.md b/docs/src/guide/movescript/reference.md index 31a2aec..655870c 100644 --- a/docs/src/guide/movescript/reference.md +++ b/docs/src/guide/movescript/reference.md @@ -11,7 +11,11 @@ ms.run("2F") Parses the given `script` string and returns a table containing the parsed instructions to be executed. This is mostly useful for debugging your scripts. -## `run(script, settings)` +## `executeInstruction(instruction, settings, preExecuteHook, postExecuteHook)` + +Executes a single instruction table using the given settings, and if pre- and post-execution hooks are defined, they will be invoked. This is mostly useful for debugging your scripts. + +## `run(script, settings, preExecuteHook, postExecuteHook)` Runs the given `script` string as a movescript, and optionally a `settings` table can be provided. Otherwise, [default settings](settings.md) will be used. @@ -22,7 +26,9 @@ local ms = require("movescript") ms.run("3F2R3B2LUD", {debug=true}) ``` -## `runFile(filename, settings)` +If you provide a non-nil `preExecuteHook` or `postExecuteHook` function, that function will run before or after each instruction in the script, respectively. This could be used to update other systems as to the robot's status, or to make sure items are selected. + +## `runFile(filename, settings, preExecuteHook, postExecuteHook)` Reads content from the given filename and executes it as a script. Just like with `run`, an optional `settings` table can be provided. @@ -37,6 +43,12 @@ local ms = require("movescript") local status, message = ms.validate("not a valid script.") ``` +## `mirror(script)` + +Mirrors the given `script`. That is, this swaps any `R` (turn right) instructions with `L` (turn left), which effectively mirrors the robot's motion relative to its original facing direction. + +Returns the mirrored script which can then be run. + ## `defaultSettings` A table containing the default [settings](./settings.md) for any script executed by the movescript module. \ No newline at end of file diff --git a/docs/src/guide/movescript/spec.md b/docs/src/guide/movescript/spec.md index 5f0a6b4..e0c96bf 100644 --- a/docs/src/guide/movescript/spec.md +++ b/docs/src/guide/movescript/spec.md @@ -81,4 +81,4 @@ The following snippets show a few example scripts, along with a description of w `B2RAd` - Move back, then turn right twice, and then attack downward. - +`4(U2RD)` - 4 times in a row, move up, twice right, and back down. diff --git a/src/itemscript.lua b/src/itemscript.lua index a173660..bd26f71 100644 --- a/src/itemscript.lua +++ b/src/itemscript.lua @@ -310,7 +310,7 @@ function itemscript.selectRandomOrWait(filterExpr) end end --- Selects an empty slot. +-- Selects the first empty slot, if there is one. Returns true if an empty slot could be selected. function itemscript.selectEmpty() for i = 1, 16 do local item = turtle.getItemDetail(i) @@ -322,6 +322,7 @@ function itemscript.selectEmpty() return false end +-- Selects the first empty slot, or prompts the user to remove items so that an empty slot can be selected. function itemscript.selectEmptyOrWait() while not itemscript.selectEmpty() do print("Couldn't find an empty slot. Please remove some items.") @@ -329,6 +330,18 @@ function itemscript.selectEmptyOrWait() end end +-- Gets a list of all inventory slots that match the given filter expression. +function itemscript.findSlots(filterExpr) + local filter = itemscript.filterize(filterExpr) + local slots = {} + for i = 1, 16 do + local item = turtle.getItemDetail(i) + if filter(item) then + table.insert(slots, i) + end + end +end + -- Helper function to drop items in a flexible way, using a drop function and filtering function. local function dropFiltered(dropFunction, filterExpr) local filter = itemscript.filterize(filterExpr) diff --git a/src/movescript.lua b/src/movescript.lua index 5314b57..d7cb1d6 100644 --- a/src/movescript.lua +++ b/src/movescript.lua @@ -461,4 +461,13 @@ function movescript.validate(script, settings) return pcall(function () movescript.parse(script, settings) end) end +-- "Mirrors" a movescript; that is, swaps any "turn right" instructions for "turn left", and vice versa. +-- Note that it does not mirror "equip right" and "equip left" instructions. +function movescript.mirror(script) + local template = string.gsub(script, "L", "__LEFT__") + template = string.gsub(template, "R", "__RIGHT__") + local result = string.gsub(template, "__LEFT__", "R") + return string.gsub(result, "__RIGHT__", "L") +end + return movescript