diff --git a/docs/src/.vuepress/config.js b/docs/src/.vuepress/config.js index 7c96c4f..dae83da 100755 --- a/docs/src/.vuepress/config.js +++ b/docs/src/.vuepress/config.js @@ -18,7 +18,7 @@ module.exports = { * ref:https://v1.vuepress.vuejs.org/config/#head */ head: [ - ['meta', { name: 'theme-color', content: '#3eaf7c' }], + ['meta', { name: 'theme-color', content: '#de9502' }], ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }], ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }] ], @@ -60,6 +60,17 @@ module.exports = { 'reference' ] } + ], + '/guide/itemscript/': [ + { + title: 'Itemscript Module', + collapsable: false, + children: [ + '', + 'filters', + 'reference' + ] + } ] } }, diff --git a/docs/src/.vuepress/styles/palette.styl b/docs/src/.vuepress/styles/palette.styl index 6490cb3..47cd36a 100755 --- a/docs/src/.vuepress/styles/palette.styl +++ b/docs/src/.vuepress/styles/palette.styl @@ -4,7 +4,7 @@ * ref:https://v1.vuepress.vuejs.org/zh/config/#palette-styl */ -$accentColor = #3eaf7c +$accentColor = #de9502 $textColor = #2c3e50 $borderColor = #eaecef -$codeBgColor = #282c34 +$codeBgColor = #233536 diff --git a/docs/src/guide/itemscript/README.md b/docs/src/guide/itemscript/README.md index ded1c7f..153e48d 100644 --- a/docs/src/guide/itemscript/README.md +++ b/docs/src/guide/itemscript/README.md @@ -1,3 +1,18 @@ # Getting Started -> This page is a work-in-progress. \ No newline at end of file +The Itemscript module provides a flexible, powerful interface for managing a turtle's inventory, and any connected inventories. + +## Installing + +To install this module, run the following command from your turtle's console: + +```shell +wget https://raw.githubusercontent.com/andrewlalis/movescript/main/min/itemscript.lua +``` + +And then use it in a script: + +```lua +local is = require("itemscript") +print("Non-log items: " .. is.totalCount("!log")) +``` diff --git a/docs/src/guide/itemscript/filters.md b/docs/src/guide/itemscript/filters.md new file mode 100644 index 0000000..afe43a8 --- /dev/null +++ b/docs/src/guide/itemscript/filters.md @@ -0,0 +1,66 @@ +# Filters + +Most of the functions provided by Itemscript make use of *filter expressions*. You'll often see it denoted in function parameters as `filterExpr`. A filter expression can be one of several things: + +- A function that takes an `item` (as obtained from `getItemDetail`) and returns a boolean `true` if the item matches, or `false` if it doesn't. +- A string or list of strings (see [filter expression strings](#filter-expression-strings)). + +## Filter Functions + +Filter functions **must** follow these rules to avoid errors or undefined behavior: + +- The function accepts a single `item` parameter, which may be `nil`, or a table like `{ name = "item_name", count = 32 }`. +- The function returns `true` if the given item should pass the filter or `false` if not. + +Below is a simple example of a filter function that only allows item stacks with more than 10 items. + +```lua +function myFilterFunction(item) + return item ~= nil and item.count > 10 +end +``` + +## Filter Expression Strings + +In the case of strings, a **filter expression string** is a string that can be used to match against an item with some advanced options. + +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. + +For example, we can count the number of stone items in our inventory like this: + +```lua +local is = require("itemscript") +print(is.totalCount("minecraft:stone")) +print(is.totalCount("stone")) -- "minecraft:" is added for us. +``` + +### Negation + +If `!` is added to the beginning of the string, only items that **don't** match will pass the filter. + +For example, suppose we want to drop everything except for oak planks: + +```lua +local is = require("itemscript") +is.dropAll("!oak_planks") +``` + +### Fuzzy Match + +If `#` is added to the beginning of the string, a *fuzzy* match will be performed, instead of a normal one. That is, instead of looking for an item whose name exactly matches, we look for the first item whose name we can find a given pattern in. In other words, normally when matching we check if `item.name == your_text`, and in a fuzzy match, we check if `string.find(item.name, your_text)` is not `nil`. + +For example, suppose we want to count the total number of logs of any type. This would be quite tedious to do normally, but with fuzzy matching, it's trivial: + +```lua +local is = require("itemscript") +print(is.totalCount("#log")) +``` + +Because a fuzzy match is nothing more than passing your text to Lua's `string.find` function, you can also take advantage of the more advanced *character classes* to define matching patterns. [Read about Lua's pattern matching documentation here.](https://www.lua.org/pil/20.2.html) + +In the example below, we filter to all items that begin with the text `minecraft:red_` by using the special `^` character. + +```lua +local is = require("itemscript") +print(is.totalCount("#^minecraft:red_")) +``` \ No newline at end of file diff --git a/docs/src/guide/itemscript/reference.md b/docs/src/guide/itemscript/reference.md new file mode 100644 index 0000000..0a1e0cb --- /dev/null +++ b/docs/src/guide/itemscript/reference.md @@ -0,0 +1,28 @@ +# Module Reference + +The following is a complete reference of the **itemscript** module. All symbols defined here belong to the `itemscript` module, and can be accessed via an instance of that module. For example: + +```lua +local is = require("itemscript") +is.dropAll("stone") +``` + +## `totalCount(filterExpr)` + +Computes the total number of items matching the given [filter expression](./filters.md). + +## `select(filterExpr)` + +Selects the first inventory slot containing an item that matches the given [filter expression](./filters.md). Returns `true` if a slot was selected successfully, or `false` if no matching item could be found. + +## `dropAll(filterExpr)` + +Drops all items from the turtle's inventory matching the given [filter expression](./filters.md). + +## `dropAllDown(filterExpr)` + +Variant of [dropAll](#dropall-filterexpr) which drops items downward. + +## `dropAllUp(filterExpr)` + +Variant of [dropAll](#dropall-filterexpr) which drops items upward. \ No newline at end of file diff --git a/docs/src/guide/movescript/README.md b/docs/src/guide/movescript/README.md index 68957d3..560fce4 100644 --- a/docs/src/guide/movescript/README.md +++ b/docs/src/guide/movescript/README.md @@ -7,7 +7,7 @@ The Movescript module provides a simple interface for executing *movescript sour To install this module, run the following command from your turtle's console: ```shell -wget https://raw.githubusercontent.com/andrewlalis/movescript/main/min/movescript.lua movescript.lua +wget https://raw.githubusercontent.com/andrewlalis/movescript/main/min/movescript.lua ``` And then use it in a script: diff --git a/docs/src/guide/movescript/reference.md b/docs/src/guide/movescript/reference.md index dbca63e..4fccbd8 100644 --- a/docs/src/guide/movescript/reference.md +++ b/docs/src/guide/movescript/reference.md @@ -7,18 +7,14 @@ local ms = require("movescript") ms.run("2F") ``` -## Functions - -### `run(script, settings)` +## `run(script, settings)` Runs the given `script` string as a movescript, and optionally a `settings` table can be provided. Otherwise, [default settings](settings.md) will be used. -### `runFile(filename, settings)` +## `runFile(filename, settings)` Reads content from the given filename and executes it as a script. Just like with `run`, an optional `settings` table can be provided. -## Variables - -### `defaultSettings` +## `defaultSettings` A table containing the default settings for any script executed by the movescript module. \ No newline at end of file