Added some more documentation.

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

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.

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.

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)

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