mcfstd/README.md

# Standard library for mcfunction
Make development of Minecraft datapacks in mcfunction easier with variables, arithmetic, and relational (comparison) operators.

```mcfunction
# Set variable 'my_variable' to 10
function var:set { k: my_variable, v: 10 }

# Add 5 to 'my_variable'
function math:add { k: my_variable, v: 5 }

# Put the result of the calculation back into 'my_variable'
function var:put { k: my_variable }

# if 'my_variable' == 15
function comp:eq { k: my_variable, v: 15 }

# then
execute if std:out run return run function my_function

# else
execute unless std:out run return fail
```

**See the [function reference](#functions) for a full list of available functions**

# Installation
Download the datapack as a zip from [the releases page](/vlw/mcfstd/releases) for the version that you require. Place the zip file directly into the `datapacks/` directory of your Minecraft world save directory.

Enable this library in Minecraft by typing the following two commands
```mcfunction
reload

datapack enable "file/mcfstd-X-X-X.zip" # Where X-X-X would be the version of the datapack
```

# The standard output
This library contains a standard output that is used as an intermediary for arithmetic and comparison operations.

# Arithmetics
When performing arithmetic and comparisons on variables, the result of the operation is not stored back into the variable immediately. When a function, for example `std:add` is performed on a varaible, the result is stored in an internal register called the "A" register. This allows for simple equations to be constructed without needing to create temporary or mutating existing variables.

```mcfunction
function var:set { k: addend, v: 10 }
function var:set { k: sum, v: 0 }

# Add 10 to the variable 'addend' and store the result in 'sum'
function math:add { k: addend, v: 10 }
function var:put { k: sum }
```
Note that the variable `addend` is still 10 and the variable `sum` contains the sum of the calculation.

# Comparisons
The result of comparing variable values is not returned immediately from the comparison functions. This is mainly due to a limitation in mcfunction which does not permit function arguments to be passed after an `execute (if|unless)` statement. To work around this, we store the result of the last comparison in a standard output function `std:out`. This function will return nothing (pass) if the last comparison was truthy, and return 0 (fail) if the comparison was falsy.

```mcfunction
function var:set { k: x, v: 20 }
function var:set { k: y, v: 10 }

# x != y, so std:out will be false
function comp:eq { a: x, b: y }
execute if std:out run return run function my_function

# x > y, so std:out will be TRUE and this function will return with my_function
function comp:gt { a: x, b: y }
execute if std:out run return run function my_function
```

# Functions
> [!Note]
> The functions under the `z_:` namespace are used internally by mcfstd and are not meant to be called directly unless you know what you are doing.

<table>
	<tr>
		<th>Function</th>
		<th>Arguments</th>
		<th>Description</th>
	</tr>
	<tr>
		<th colspan="4">Variables</th>
	</tr>
	<!-- var:set -->
	<tr>
		<td rowspan="2"><code>var:set</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td rowspan="2">Set the value of a variable</td>
	</tr>
	<tr>
		<td><code>v</code> Value of the variable (int)</td>
	</tr>
	<!-- var:unset -->
	<tr>
		<td><code>var:unset</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td>Remove a varialbe</td>
	</tr>
	<!-- var:mv -->
	<tr>
		<td rowspan="2"><code>var:mv</code></td>
		<td><code>k</code> Old variable name (string)</td>
		<td rowspan="2">Rename a variable</td>
	</tr>
	<tr>
		<td><code>v</code> New variable name (string)</td>
	</tr>
	<!-- var:inc -->
	<tr>
		<td><code>var:inc</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td>Increment the value of a variable</td>
	</tr>
	<!-- var:dec -->
	<tr>
		<td><code>var:dec</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td>Decrement the value of a variable</td>
	</tr>
	<!-- var:put -->
	<tr>
		<td><code>var:put</code></td>
		<td>-</td>
		<td>Put the current value of A into this variable</td>
	</tr>
	<tr>
		<th colspan="4">Arithmetic</th>
	</tr>
	<!-- math:add -->
	<tr>
		<td rowspan="2"><code>math:add</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td rowspan="2">Add a number to the current value of a variable and store the result in A</td>
	</tr>
	<tr>
		<td><code>v</code> Number to add (int)</td>
	</tr>
	<!-- math:sub -->
	<tr>
		<td rowspan="2"><code>math:sub</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td rowspan="2">Subtract a number to the current value of a variable and store the result in A</td>
	</tr>
	<tr>
		<td><code>v</code> Number to subtract (int)</td>
	</tr>
	<!-- math:mul -->
	<tr>
		<td rowspan="2"><code>math:mul</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td rowspan="2">Multiply a number with the current value of a variable and store the result in A</td>
	</tr>
	<tr>
		<td><code>v</code> Number to multiply (int)</td>
	</tr>
	<!-- math:div -->
	<tr>
		<td rowspan="2"><code>math:div</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td rowspan="2">Divide a number with the current value of a variable and store the result in A</td>
	</tr>
	<tr>
		<td><code>v</code> Number to divide (int)</td>
	</tr>
	<!-- math:mod -->
	<tr>
		<td rowspan="2"><code>math:mod</code></td>
		<td><code>k</code> Name of the variable (string)</td>
		<td rowspan="2">Modulo a number with the current value of a variable and store the result in A</td>
	</tr>
	<tr>
		<td><code>v</code> Number to modulo (int)</td>
	</tr>
	<tr>
		<th colspan="4">Relation / Compare</th>
	</tr>
	<!-- comp:eq -->
	<tr>
		<td rowspan="2"><code>comp:eq</code></td>
		<td><code>a</code> Name of the first variable (string)</td>
		<td rowspan="2">Check if <code>a = b</code> and store the result in <a href="#the-standard-output">the standard output</a></td>
	</tr>
	<tr>
		<td><code>b</code> Name of the second variable (string)</td>
	</tr>
	<!-- comp:gt -->
	<tr>
		<td rowspan="2"><code>comp:gt</code></td>
		<td><code>a</code> Name of the first variable (string)</td>
		<td rowspan="2">Check if <code>a > b</code> and store the result in <a href="#the-standard-output">the standard output</a></td>
	</tr>
	<tr>
		<td><code>b</code> Name of the second variable (string)</td>
	</tr>
	<!-- comp:gteq -->
	<tr>
		<td rowspan="2"><code>comp:gteq</code></td>
		<td><code>a</code> Name of the first variable (string)</td>
		<td rowspan="2">Check if <code>a >= b</code> and store the result in <a href="#the-standard-output">the standard output</a></td>
	</tr>
	<tr>
		<td><code>b</code> Name of the second variable (string)</td>
	</tr>
	<!-- comp:lt -->
	<tr>
		<td rowspan="2"><code>comp:lt</code></td>
		<td><code>a</code> Name of the first variable (string)</td>
		<td rowspan="2">Check if <code>a < b</code> and store the result in <a href="#the-standard-output">the standard output</a></td>
	</tr>
	<tr>
		<td><code>b</code> Name of the second variable (string)</td>
	</tr>
	<!-- comp:lteq -->
	<tr>
		<td rowspan="2"><code>comp:lteq</code></td>
		<td><code>a</code> Name of the first variable (string)</td>
		<td rowspan="2">Check if <code>a <= b</code> and store the resulteq in <a href="#the-standard-output">the standard output</a></td>
	</tr>
	<tr>
		<td><code>b</code> Name of the second variable (string)</td>
	</tr>
	<tr>
		<th colspan="4">Built-in operations</th>
	</tr>
	<!-- std:out -->
	<tr>
		<td><code>std:out</code></td>
		<td>-</td>
		<td>Will return nothing if the value of <a href="#the-standard-output">the standard output</a> is not <code>fail</code>. Else this function will also <code>fail</code></td>
	</tr>
</table>