Version bump

JujuAdams · Oct 21, 2023 · 11bd242 · 11bd242
1 parent 4d4ee75
commit 11bd242
Show file tree

Hide file tree

Showing 17 changed files with 1,015 additions and 2 deletions.
diff --git a/5.7/README.md b/5.7/README.md
@@ -0,0 +1,43 @@
+<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 5.6</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>
+<p align="center">Chat about SNAP on the <a href="https://discord.gg/8krYCqr">Discord server</a></p>
+
+&nbsp;
+
+**What platforms does SNAP support?**
+
+In principle, everything! 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. You can also grab me on the [Discord server](https://discord.gg/8krYCqr), but that's not a replacement for a nice clear bug report.
+
+&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.
diff --git a/5.7/_sidebar.md b/5.7/_sidebar.md
@@ -0,0 +1,15 @@
+- [Introduction](README)
+- [JSON](json)
+- [Loose JSON](loose-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)
+- [VDF](vdf)
+- [QML](qml)
+- [Utilities](utilities)
diff --git a/5.7/csv.md b/5.7/csv.md
@@ -0,0 +1,57 @@
+# CSV
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `SnapFromCSV`
+
+*Returns:* 2D array
+
+|Name    |Datatype|Purpose                |
+|--------|--------|-----------------------|
+|`string`|string  |The CSV string to parse|
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `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.
diff --git a/5.7/custom-binary.md b/5.7/custom-binary.md
@@ -0,0 +1,25 @@
+# Custom Binary
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `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|
diff --git a/5.7/gml.md b/5.7/gml.md
@@ -0,0 +1,48 @@
+# GML
+
+&nbsp;
+
+## `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`|
+
+&nbsp;
+
+## `SnapFromGML`
+
+*Returns:* Struct, the resprentation of the input GML code
+
+|Name    |Datatype|Purpose     |
+|--------|--------|------------|
+|`string`|string  |GML to parse|
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `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                                                              |
diff --git a/5.7/grids-and-arrays.md b/5.7/grids-and-arrays.md
@@ -0,0 +1,84 @@
+# Grids and Arrays
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `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.
+
+&nbsp;
+
+## `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.
diff --git a/5.7/ini.md b/5.7/ini.md
@@ -0,0 +1,44 @@
+# INI
+
+!> I hate INI files, it is a nasty little format, and I strongly encourage you to move to other data storage formats. YAML is especially useful for config files, and JSON is otherwise generally applicable.
+
+&nbsp;
+
+## `SnapFromINIString`
+
+*Returns:* Struct, the data found inside the INI string
+
+|Name       |Datatype|Purpose                                                                      |
+|-----------|--------|-----------------------------------------------------------------------------|
+|`string`   |string  |INI data to parse, represented as a string                                   |
+|`[tryReal]`|boolean |Whether try to convert strings to real values if possible. Defaults to `true`|
+
+!> Setting `tryReal` to `true` will incur a performance penalty.
+
+&nbsp;
+
+## `SnapFromINIFile`
+
+*Returns:* Struct, the data found inside the INI file
+
+|Name       |Datatype|Purpose                                                                      |
+|-----------|--------|-----------------------------------------------------------------------------|
+|`filename` |string  |INI file to parse                                                            |
+|`[tryReal]`|boolean |Whether try to convert strings to real values if possible. Defaults to `true`|
+
+!> Setting `tryReal` to `true` will incur a performance penalty.
+
+&nbsp;
+
+## `SnapBufferReadINI`
+
+*Returns:* Struct, the data found inside the buffer
+
+|Name       |Datatype|Purpose                                                                              |
+|-----------|--------|-------------------------------------------------------------------------------------|
+|`buffer`   |buffer  |Buffer to read the INI data from                                                     |
+|`offset`   |integer |Position in the buffer to read the INI data from, relative to the start of the buffer|
+|`size`     |integer |Number of bytes to read                                                              |
+|`[tryReal]`|boolean |Whether try to convert strings to real values if possible. Defaults to `true`        |
+
+!> Setting `tryReal` to `true` will incur a performance penalty.