Version bump and new GML function docs

7.0/README.md

@@ -0,0 +1,42 @@
+<p align="center"><img src="https://raw.githubusercontent.com/JujuAdams/SNAP/master/LOGO.png" style="display:block; margin:auto; width:300px"></p>
+<h1 align="center">SNAP 7.0</h1>
+
+<p align="center">Data format converters for GameMaker LTS 2022 by <b>@jujuadams</b></p>
+
+<p align="center"><a href="https://github.com/JujuAdams/SNAP/releases/">Download the .yymps</a></p>
+
+&nbsp;
+
+**What platforms does SNAP support?**
+
+Everything apart from HTML5! I've not tested outside of Windows but SNAP relies exclusively on native GameMaker functions so whatever GameMaker supports SNAP should too. You might run into edge cases on other platforms; please [report any bugs](https://github.com/JujuAdams/SNAP/issues) if and when you find them.
+
+&nbsp;
+
+**How is SNAP licensed? Can I use it for commercial projects?**
+
+[SNAP is released under the MIT license](https://github.com/JujuAdams/SNAP/blob/main/LICENSE). This means you can use it for whatever purpose you want, including commercial projects. It'd mean a lot to me if you'd drop my name in the credits (Juju Adams) and/or say thanks, but you're under no obligation to do so.
+
+&nbsp;
+
+**I think you're missing a data format and I'd like you to implement it!**
+
+Great! Please make a [feature request](https://github.com/JujuAdams/SNAP/issues). Feature requests make SNAP a more fun tool to use and gives me something to think about when I'm bored on public transport.
+
+&nbsp;
+
+**I found a bug, and it both scares and mildly annoys me. What is the best way to get the problem solved?**
+
+Please make a [bug report](https://github.com/JujuAdams/SNAP/issues). I check GitHub every day and bug fixes usually go out a couple days after that.
+
+&nbsp;
+
+**Who made SNAP?**
+
+SNAP is built and maintained by [Juju](https://www.jujuadams.com/) who has been working in games for many years. Juju's worked on a lot of [commercial GameMaker games](http://www.jujuadams.com/) in that time and has written, and rewritten, data format converters many times.
+
+&nbsp;
+
+**Can I send you donations? Are you going to start a Patreon?**
+
+Thank you for wanting to show your appreciation - it really does mean a lot to me personally - but I'm fortunate enough to have a stable income from gamedev. I'm not looking to join Patreon as a creator at this moment in time. If you'd like to support my work then drop me a credit in your game and/or give a shout-out on the social media platform of your choice.

7.0/_sidebar.md

@@ -0,0 +1,16 @@
+- [Introduction](README)
+- [JSON](json)
+- [YAML](yaml)
+- [CSV](csv)
+- [NSV](nsv)
+- [Custom Binary](custom-binary)
+- [Messagepack](messagepack)
+- [XML](xml)
+- [INI](ini)
+- [GML](gml)
+- [Grids & 2D Arrays](grids-and-arrays)
+- [Tilemaps](tilemaps)
+- [VDF](vdf)
+- [QML](qml)
+- [Reconstruction](reconstruction)
+- [Utilities](utilities)

7.0/csv.md

@@ -0,0 +1,57 @@
+# CSV
+
+ 
+
+## `SnapToCSV`
+
+*Returns:* String, the CSV data
+
+|Name               |Datatype|Purpose                                                                                |
+|-------------------|--------|---------------------------------------------------------------------------------------|
+|`data`             |2D array|The 2D array to encode                                                                 |
+|`[cellDelimiter]`  |string  |The delimiter to use to split cells from each other. Defaults to `,`                   |
+|`[stringDelimiter]`|string  |The delimiter to use to indicate a cell explicitly contains a string. Defaults to `","`|
+|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false` |
+
+!> Setting `accurateFloats` to `true` will incur a memory and performance penalty.
+
+ 
+
+## `SnapFromCSV`
+
+*Returns:* 2D array
+
+|Name    |Datatype|Purpose                |
+|--------|--------|-----------------------|
+|`string`|string  |The CSV string to parse|
+
+ 
+
+## `SnapBufferWriteCSV`
+
+*Returns:* N/A (`undefined`)
+
+|Name               |Datatype|Purpose                                                                                |
+|-------------------|--------|---------------------------------------------------------------------------------------|
+|`buffer`           |buffer  |The buffer to write the CSV string into                                                |
+|`data`             |2D array|The 2D array to encode                                                                 |
+|`[cellDelimiter]`  |string  |The delimiter to use to split cells from each other. Defaults to `,`                   |
+|`[stringDelimiter]`|string  |The delimiter to use to indicate a cell explicitly contains a string. Defaults to `","`|
+|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false` |
+
+The CSV string will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function.
+
+!> Setting `accurateFloats` to `true` will incur a memory and performance penalty.
+
+ 
+
+## `SnapBufferReadCSV`
+
+*Returns:* 2D array
+
+|Name      |Datatype|Purpose                                                                                                                                        |
+|----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+|`buffer`  |buffer  |The buffer to read the CSV data from                                                                                                           |
+|`[offset]`|integer |The position in the buffer to read the CSV data from, relative to the start of the buffer. If not specified, the buffer's head position is used|
+
+?> If you do **not** specify an offset then SNAP will modify the buffer's "head" position. This allows you to read sequential data more easily.

7.0/custom-binary.md

@@ -0,0 +1,25 @@
+# Custom Binary
+
+ 
+
+## `SnapBufferWriteBinary`
+
+*Returns:* N/A (`undefined`)
+
+|Name    |Datatype    |Purpose                             |
+|--------|------------|------------------------------------|
+|`buffer`|buffer      |Buffer to write the binary data into|
+|`data`  |struct/array|Data to encode                      |
+
+The data will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function.
+
+ 
+
+## `SnapBufferReadBinary`
+
+*Returns:* Struct or array, the data read from the buffer
+
+|Name    |Datatype|Purpose                                                                      |
+|--------|--------|-----------------------------------------------------------------------------|
+|`buffer`|buffer  |Buffer to read the NSV data from                                             |
+|`offset`|integer |Position in the buffer to read data from, relative to the start of the buffer|

7.0/gml.md

@@ -0,0 +1,135 @@
+# GML
+
+ 
+
+## `SnapToGML`
+
+*Returns:* String, the data rewritten as a GML-compatible block of code
+
+|Name                  |Datatype|Purpose                                                             |
+|----------------------|--------|--------------------------------------------------------------------|
+|`data`                |struct  |Data to encode                                                      |
+|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false`|
+
+ 
+
+## `SnapFromGML`
+
+*Returns:* Struct, the resprentation of the input GML code
+
+|Name    |Datatype|Purpose     |
+|--------|--------|------------|
+|`string`|string  |GML to parse|
+
+Parses and executes simple GML code stored in a string. Returns the scope, as given by the `scope` parameter. This GML parser is very stripped back and supports a small subset of GML. The use of this parser should be limited to reading data in keeping with the overall intentions of SNAP as a data-oriented library.
+
+The parser supports:
+- Struct / array literals (JSON)
+- Most GML operators, including ternaries (`condition? valueIfTrue : valueIfFalse`)
+- Executing functions
+- Instantiating constructors (with `new`)
+- Setting global variables
+- Setting scoped variables
+
+The parser does not support:
+- if/else, while, etc. flow control
+- Function and constructor definition
+- Dot notation for variable access in structs/instances
+- Square bracket notation for array value access
+- Anything else that's not explicitly mentioned
+
+Tokens for macros, GML constants, assets etc. can be added by defining them as key-value pairs in the `tokenStruct` parameter. Tokens can be added globally for all executions of `SnapFromGML()` and `SnapBufferReadGML()` by calling `SnapEnvGMLSetToken()` and `SnapEnvGMLSetTokenFunction()`. Please see those functions for more information.
+
+The scope for setting variables is given by by `scope` parameter. By default, variables are set in global scope. You may want to replace this with a struct or an instance depending on your use case.
+
+If you set the `allowAllAssets` parameter to `true` then the GML parser will treat all assets in your project as accessible (effectively this adds all assets in your project as valid tokens). It is not recommended to ship any code with this parameter set to `true` as it may introduce security issues; instead you should explicitly add tokens for assets that you would like to be made accessible.
+
+ 
+
+## `SnapBufferWriteGML`
+
+*Returns:* N/A (`undefined`)
+
+|Name                  |Datatype|Purpose                                                             |
+|----------------------|--------|--------------------------------------------------------------------|
+|`buffer`              |buffer  |Buffer to write the GML code into                                   |
+|`data`                |struct  |Data to encode                                                      |
+|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false`|
+
+The GML string will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function.
+
+ 
+
+## `SnapBufferReadGML`
+
+*Returns:* Struct, the struct/array resprentation of the input GML code
+
+|Name    |Datatype|Purpose                                                                              |
+|--------|--------|-------------------------------------------------------------------------------------|
+|`buffer`|buffer  |Buffer to read the GML code from                                                     |
+|`offset`|integer |Position in the buffer to read the GML code from, relative to the start of the buffer|
+|`size`  |integer |Number of bytes to read                                                              |
+
+Parses and executes simple GML code stored in a buffer as a string. Returns the scope, as given by the `scope` parameter. This GML parser is very stripped back and supports a small subset of GML. The use of this parser should be limited to reading data in keeping with the overall intentions of SNAP as a data-oriented library.
+
+!> The string in the buffer should include the null terminator.
+
+The parser supports:
+- Struct / array literals (JSON)
+- Most GML operators, including ternaries (`condition? valueIfTrue : valueIfFalse`)
+- Executing functions
+- Instantiating constructors (with `new`)
+- Setting global variables
+- Setting scoped variables
+
+The parser does not support:
+- if/else, while, etc. flow control
+- Function and constructor definition
+- Dot notation for variable access in structs/instances
+- Square bracket notation for array value access
+- Anything else that's not explicitly mentioned
+
+Tokens for macros, GML constants, assets etc. can be added by defining them as key-value pairs in the `tokenStruct` parameter. Tokens can be added globally for all executions of `SnapFromGML()` and `SnapBufferReadGML()` by calling `SnapEnvGMLSetToken()` and `SnapEnvGMLSetTokenFunction()`. Please see those functions for more information.
+
+The scope for setting variables is given by by `scope` parameter. By default, variables are set in global scope. You may want to replace this with a struct or an instance depending on your use case.
+
+If you set the `allowAllAssets` parameter to `true` then the GML parser will treat all assets in your project as accessible (effectively this adds all assets in your project as valid tokens). It is not recommended to ship any code with this parameter set to `true` as it may introduce security issues; instead you should explicitly add tokens for assets that you would like to be made accessible.
+
+ 
+
+## `SnapEnvGMLSetToken`
+
+*Returns:* N/A (`undefined`)
+
+|Name       |Datatype|Purpose                   |
+|-----------|--------|--------------------------|
+|`tokenName`|string  |Name of the token to alias|
+|`value`    |any     |Value for the token       |
+
+Adds a token to all future calls to `SnapFromGML()` and `SnapBufferReadGML()`. When evaluated, the token will return the value set by this function. This is useful to carry across constants into the GML parser e.g. the width and height of a tile in your game.
+
+ 
+
+## `SnapEnvGMLSetTokenFunction`
+
+*Returns:* N/A (`undefined`)
+
+|Name        |Datatype|Purpose                                      |
+|------------|--------|---------------------------------------------|
+|`tokenName` |string  |Name of the token to alias                   |
+|`function`  |function|Function to execute when evaluating the token|
+|`[metadata]`|any     |Value for the token                          |
+
+Adds a token to all future calls to `SnapFromGML()` and `SnapBufferReadGML()`. When evaluated, the token will execute the defined function. The return value from that function will be used as the value for the token. This is useful for dynamically updating values (time, mouse position and so on). The `metadata` parameter is passed as the one (and only) parameter for the defined function.
+
+ 
+
+## `SnapEnvGMLSetNativeTokens`
+
+*Returns:* N/A (`undefined`)
+
+|Name|Datatype|Purpose|
+|----|--------|-------|
+|None|        |       |
+
+Adds all (I think!) native GML constants and global variables to the SNAP GML environment. This means that these native values will be available for reading (but not writing) within the SNAP GML parser.

7.0/grids-and-arrays.md

@@ -0,0 +1,84 @@
+# Grids and Arrays
+
+ 
+
+## `SnapBufferWriteGrid`
+
+*Returns:* N/A (`undefined`)
+
+|Name      |Datatype    |Purpose                             |
+|----------|------------|------------------------------------|
+|`buffer`  |buffer      |Buffer to write the data into       |
+|`grid`    |ds_grid     |Data to encode                      |
+|`datatype`|struct/array|Datatype to use to encode each datum|
+
+The grid data will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function.
+
+ 
+
+## `SnapBufferReadGrid`
+
+*Returns:* ds_grid, the data read from the buffer
+
+|Name    |Datatype|Purpose                                                                      |
+|--------|--------|-----------------------------------------------------------------------------|
+|`buffer`|buffer  |Buffer to read the grid data from                                            |
+|`offset`|integer |Position in the buffer to read data from, relative to the start of the buffer|
+
+?> If you do **not** specify an offset then SNAP will modify the buffer's "head" position. This allows you to read sequential data more easily.
+
+ 
+
+## `SnapBufferWrite2DArray`
+
+*Returns:* N/A (`undefined`)
+
+|Name      |Datatype    |Purpose                             |
+|----------|------------|------------------------------------|
+|`buffer`  |buffer      |Buffer to write the data into       |
+|`array`   |array       |Data to encode                      |
+|`datatype`|struct/array|Datatype to use to encode each datum|
+
+The array data will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function.
+
+!> This function will only work on "rectangular" arrays where the length of each child array is the same.
+
+ 
+
+## `SnapBufferRead2DArray`
+
+*Returns:* Array, the data read from the buffer
+
+|Name    |Datatype|Purpose                                                                      |
+|--------|--------|-----------------------------------------------------------------------------|
+|`buffer`|buffer  |Buffer to read the grid data from                                            |
+|`offset`|integer |Position in the buffer to read data from, relative to the start of the buffer|
+
+?> If you do **not** specify an offset then SNAP will modify the buffer's "head" position. This allows you to read sequential data more easily.
+
+ 
+
+## `Snap2DArrayToStructArray`
+
+*Returns:* Array, containing a struct for each row in the CSV
+
+|Name            |Datatype|Purpose                                               |
+|----------------|--------|------------------------------------------------------|
+|`inputArray`    |2D array|Row-major 2D array to convert into an array of structs|
+|`[configStruct]`|struct  |Options that control how data is parsed. See below    |
+
+This function converts a row-major 2D array into an array of structs where each column header defines a variable for each struct and each row defines a struct and its variable values.
+
+Config struct should be in this format:
+
+```gml
+{
+    columnTitle: {
+        ignore: <true> or <false>,
+        numeric: <true> or <false>,
+    },
+    ...
+}
+```
+
+Setting a column's `.ignore` property to `true` will cause that column to not appear as a variable in output structs. Setting a column's `.numeric` property to `true` will cause values in that column to be converted into a number if possible. Not all columns need to be specified in the config struct.