release(0.5.0): add string module, and documentation for Moxlib Exp

moxvallix · moxvallix · commit 826996e1546c · 2023-01-21T03:03:47.000+10:30
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2023-01-21
+Moxlib now has a sister project, [Moxlib Exp](https://github.com/moxvallix/moxlib-exp).
+It enables experimental features. It has its own [Changelog](https://github.com/moxvallix/moxlib-exp/blob/main/CHANGELOG.md).
+
+### Added
+- String module and documentation.
+
+### Changed
+- String to Array has been moved to the string module. Make sure to update your packs, as this is a breaking change.
+- Version info will now display Moxlib Exp version too, if the library is present.
+
+### Fixed
+- The in-game version info hadn't been updated since 0.3.0. Now reports 0.5.0.
+
 ## [0.4.1] - 2023-01-19
 This update only adds one function, and fixes a minor bug, thus has been marked as a patch release.
 
diff --git a/README.md b/README.md
@@ -37,6 +37,9 @@ data that the function will manipulate. Functions will occasionally ask for othe
 Functions, if they output anything, will write to `output`. Optionally, they might also record
 their success to a `success` tag, although not all functions implement this.
 
+Some functions and modules are marked as "experimental". These require [Moxlib Exp](https://github.com/moxvallix/moxlib-exp)
+to function.
+
 ### Modules
 #### Helpers
 [See documentation...](https://github.com/moxvallix/moxlib/blob/main/docs/helpers.md)
@@ -71,4 +74,14 @@ The Math module provides some helpful math functions.
 #### Player
 [See documentation...](https://github.com/moxvallix/moxlib/blob/main/docs/player.md)
 
-The Player module exposes some helpful information about the player.
+The Player module exposes some helpful information about the player.
+
+#### String
+[See documentation...](https://github.com/moxvallix/moxlib/blob/main/docs/string.md)
+
+The String module provides functions to manipulate strings.
+
+#### Dimension
+[See documentation...](https://github.com/moxvallix/moxlib/blob/main/docs/dimension.md)
+
+Moxlib provides a dimension for storing and accessing blocks. (Requires Moxlib Exp)
diff --git a/data/moxlib/functions/api/data/string_to_array.mcfunction b/data/moxlib/functions/api/data/string_to_array.mcfunction
diff --git a/data/moxlib/functions/api/string/reset.mcfunction b/data/moxlib/functions/api/string/reset.mcfunction
@@ -0,0 +1,3 @@
+# Reset data in case of stuck lock
+
+function moxlib:string/common/cleanup
diff --git a/data/moxlib/functions/api/string/to_array.mcfunction b/data/moxlib/functions/api/string/to_array.mcfunction
@@ -0,0 +1 @@
+execute unless data storage moxlib:string/private {lock:true} run function moxlib:string/to_array/init
diff --git a/data/moxlib/functions/data/_objectives.mcfunction b/data/moxlib/functions/data/_objectives.mcfunction
@@ -2,5 +2,4 @@ scoreboard objectives add moxlib.data.get dummy
 scoreboard objectives add moxlib.data.set dummy
 scoreboard objectives add moxlib.data.collect dummy
 scoreboard objectives add moxlib.data.compare dummy
-scoreboard objectives add moxlib.data.paginate dummy
-scoreboard objectives add moxlib.data.string_to_array dummy
+scoreboard objectives add moxlib.data.paginate dummy
diff --git a/data/moxlib/functions/data/string_to_array/init.mcfunction b/data/moxlib/functions/data/string_to_array/init.mcfunction
diff --git a/data/moxlib/functions/data/string_to_array/iterate.mcfunction b/data/moxlib/functions/data/string_to_array/iterate.mcfunction
diff --git a/data/moxlib/functions/load.mcfunction b/data/moxlib/functions/load.mcfunction
@@ -1,6 +1,7 @@
 execute unless data storage moxlib:config {init:true} run function moxlib:init
 
 function moxlib:objectives
+function #moxlib:load
 function moxlib:version
 
-function moxlib:math/_load
+function #moxlib:api/load
diff --git a/data/moxlib/functions/objectives.mcfunction b/data/moxlib/functions/objectives.mcfunction
@@ -3,4 +3,5 @@ function moxlib:data/_objectives
 function moxlib:test/_objectives
 function moxlib:tui/_objectives
 function moxlib:math/_objectives
-function moxlib:player/_objectives
+function moxlib:player/_objectives
+function moxlib:string/_objectives
diff --git a/data/moxlib/functions/string/_objectives.mcfunction b/data/moxlib/functions/string/_objectives.mcfunction
@@ -0,0 +1 @@
+scoreboard objectives add moxlib.string.to_array dummy
diff --git a/data/moxlib/functions/string/common/cleanup.mcfunction b/data/moxlib/functions/string/common/cleanup.mcfunction
@@ -0,0 +1,2 @@
+schedule clear moxlib:api/string/reset
+data modify storage moxlib:string/private lock set value false
diff --git a/data/moxlib/functions/string/common/setup.mcfunction b/data/moxlib/functions/string/common/setup.mcfunction
@@ -0,0 +1,3 @@
+# Lock data, and schedule reset in case of function failure
+data modify storage moxlib:string/private lock set value true
+schedule function moxlib:api/string/reset 1t
diff --git a/data/moxlib/functions/string/to_array/init.mcfunction b/data/moxlib/functions/string/to_array/init.mcfunction
@@ -0,0 +1,7 @@
+function moxlib:string/common/setup
+data remove storage moxlib:api/string/to_array output
+
+function moxlib:string/to_array/iterate
+
+data remove storage moxlib:api/string/to_array target
+function moxlib:string/common/cleanup
diff --git a/data/moxlib/functions/string/to_array/iterate.mcfunction b/data/moxlib/functions/string/to_array/iterate.mcfunction
@@ -0,0 +1,5 @@
+data modify storage moxlib:api/data/to_array output append string storage moxlib:api/data/to_array target 0 1
+data modify storage moxlib:api/data/to_array target set string storage moxlib:api/data/to_array target 1
+
+execute store result score $size moxlib.string.to_array run data get storage moxlib:api/data/to_array target
+execute if score $size moxlib.string.to_array matches 1.. run function moxlib:data/to_array/iterate
diff --git a/data/moxlib/functions/version.mcfunction b/data/moxlib/functions/version.mcfunction
@@ -1,7 +1,7 @@
 data modify storage moxlib:version name set value "Moxlib"
 
 data modify storage moxlib:version major set value 0
-data modify storage moxlib:version minor set value 3
+data modify storage moxlib:version minor set value 5
 data modify storage moxlib:version patch set value 0
 
-tellraw @a {"nbt":"name","storage": "moxlib:version","extra": [{"text": " v","extra":[{"nbt":"major","storage":"moxlib:version","extra":[{"text":"."},{"nbt":"minor","storage":"moxlib:version"},{"text":".","extra":[{"nbt":"patch","storage":"moxlib:version"}]}]}]}]}
+tellraw @a {"nbt":"name","storage":"moxlib:version","extra":[{"text":" v","extra":[{"nbt":"major","storage":"moxlib:version","extra":[{"text":"."},{"nbt":"minor","storage":"moxlib:version"},{"text":".","extra":[{"nbt":"patch","storage":"moxlib:version","extra":[{"nbt":"info","storage":"moxlib:version/experimental","interpret":true}]}]}]}]}]}
diff --git a/data/moxlib/tags/functions/api/load.json b/data/moxlib/tags/functions/api/load.json
@@ -0,0 +1,5 @@
+{
+  "values": [
+    "moxlib:math/_load"
+  ]
+}
diff --git a/data/moxlib/tags/functions/load.json b/data/moxlib/tags/functions/load.json
@@ -0,0 +1,3 @@
+{
+  "values": []
+}
diff --git a/docs/data.md b/docs/data.md
@@ -137,26 +137,6 @@ Example:
 }
 ```
 
-### String to Array
-Turns a given string into an array of characters. Requires snapshot 23w03a+ (1.19.4+).
-
-**Function:** `moxlib:api/data/string_to_array`  
-**Expects:**
-- `target` -- any string
-**Returns:**
-- `output` -- an array of characters in that string, in order
-
-Example:
-```
-/data modify storage moxlib:api/data/string_to_array target set value "Hello, World!"
-/function moxlib:api/data/string_to_array
-/data get storage moxlib:api/data/string_to_array
----
-{
-  output: ["H","e","l","l","o",","," ","W","o","r","l","d","!"]
-}
-```
-
 ### Reset
 Resets the lock, in the unlikely case it gets stuck.
 
diff --git a/docs/dimension.md b/docs/dimension.md
@@ -0,0 +1,26 @@
+# Dimension
+## A void dimension for storing blocks
+
+**Experimental:** Requires [Moxlib Exp](https://github.com/moxvallix/moxlib-exp).
+
+Moxlib provides a void dimension, useful for functions that require manipulation of temporary
+or permanent blocks.
+
+The dimension can be accessed at `moxlib:state`, and the chunk at 0 0 is forceloaded.
+
+## Conventions
+Below Y 32 is reserved for permanent blocks. These are blocks that need to be accessed multiple times,
+outside of a single tick.
+
+Y 32 and above is for temporary blocks, and blocks placed there should be removed promptly after use.
+
+### Table of Reserved Co-ordinates
+If you are using Moxlib, please **do not** use a reserved coordinate, in `moxlib:state`,
+as that could break compatibility with other packs.
+
+If you use Moxlib, and would like to reserve a permanent block coordinate(s) for your pack,
+open an issue or pull request asking for a reservation for the table below.
+
+| Coordinates       | Pack reserving | Used for |
+|-------------------|----------------|----------|
+|`5 0 5` to `5 0 10`| Moxlib         | Internal |
diff --git a/docs/string.md b/docs/string.md
@@ -0,0 +1,64 @@
+# String
+## Functions for working with strings
+
+Moxlib provides a set of functions for working with strings, thanks to the changes made in 23w03a.
+
+As such, these functions require snapshot 23w03a+ (1.19.4+) to function.
+
+## API
+### To Array
+Turns a given string into an array of characters.
+
+**Function:** `moxlib:api/string/to_array`  
+**Expects:**
+- `target` -- any string
+
+**Returns:**
+- `output` -- an array of characters in that string, in order
+
+Example:
+```
+/data modify storage moxlib:api/string/to_array target set value "Hello, World!"
+/function moxlib:api/string/to_array
+/data get storage moxlib:api/string/to_array
+---
+{
+  output: ["H","e","l","l","o",","," ","W","o","r","l","d","!"]
+}
+```
+
+### From Array
+Turns a given array of strings into a single joined string.
+
+**Experimental:** Requires [Moxlib Exp](https://github.com/moxvallix/moxlib-exp).
+
+**Function:** `moxlib:api/string/from_array`  
+**Expects:**
+- `target` -- an array of strings
+
+**Returns:**
+- `output` -- a single string
+
+Unfortunately, due to current limitations, this function cannot run in the same tick
+as it is executed. As such, when it is done, it will call `#moxlib:api/string/from_array/finished`
+to allow you to use the output.
+
+Example:
+```
+/data modify storage moxlib:api/string/from_array target set value ["Hello, ","World!"]
+/function moxlib:api/string/from_array
+
+# After #moxlib:api/string/from_array/finished is called
+/data get storage moxlib:api/string/to_array
+---
+{
+  output: "Hello, World!"
+}
+```
+
+### Reset
+Resets the lock, in the unlikely case it gets stuck.
+
+**Function:** `moxlib:api/string/reset`  
+**Expects:** No value expected  
+**Returns:** No value returned

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Reset data in case of stuck lock`
	`2`	`+`
	`3`	`+function moxlib:string/common/cleanup`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+execute unless data storage moxlib:string/private {lock:true} run function moxlib:string/to_array/init`