From ffffde405001cedd5a90131df0ddca096125ec52 Mon Sep 17 00:00:00 2001 From: Juju Adams Date: Sun, 18 Aug 2024 15:16:01 +0100 Subject: [PATCH] Version bump and new GML function docs --- 7.0/README.md | 42 +++++++++ 7.0/_sidebar.md | 16 ++++ 7.0/csv.md | 57 +++++++++++ 7.0/custom-binary.md | 25 +++++ 7.0/gml.md | 135 ++++++++++++++++++++++++++ 7.0/grids-and-arrays.md | 84 +++++++++++++++++ 7.0/ini.md | 44 +++++++++ 7.0/json.md | 65 +++++++++++++ 7.0/messagepack.md | 29 ++++++ 7.0/nsv.md | 37 ++++++++ 7.0/qml.md | 153 ++++++++++++++++++++++++++++++ 7.0/reconstruction.md | 69 ++++++++++++++ 7.0/tilemaps.md | 53 +++++++++++ 7.0/utilities.md | 204 ++++++++++++++++++++++++++++++++++++++++ 7.0/vdf.md | 59 ++++++++++++ 7.0/xml.md | 46 +++++++++ 7.0/yaml.md | 54 +++++++++++ config.js | 4 +- 18 files changed, 1174 insertions(+), 2 deletions(-) create mode 100644 7.0/README.md create mode 100644 7.0/_sidebar.md create mode 100644 7.0/csv.md create mode 100644 7.0/custom-binary.md create mode 100644 7.0/gml.md create mode 100644 7.0/grids-and-arrays.md create mode 100644 7.0/ini.md create mode 100644 7.0/json.md create mode 100644 7.0/messagepack.md create mode 100644 7.0/nsv.md create mode 100644 7.0/qml.md create mode 100644 7.0/reconstruction.md create mode 100644 7.0/tilemaps.md create mode 100644 7.0/utilities.md create mode 100644 7.0/vdf.md create mode 100644 7.0/xml.md create mode 100644 7.0/yaml.md diff --git a/7.0/README.md b/7.0/README.md new file mode 100644 index 0000000..58cae7f --- /dev/null +++ b/7.0/README.md @@ -0,0 +1,42 @@ +

+

SNAP 7.0

+ +

Data format converters for GameMaker LTS 2022 by @jujuadams

+ +

Download the .yymps

+ +  + +**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. + +  + +**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. + +  + +**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. + +  + +**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. + +  + +**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. + +  + +**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/7.0/_sidebar.md b/7.0/_sidebar.md new file mode 100644 index 0000000..bbbdeb5 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/7.0/csv.md b/7.0/csv.md new file mode 100644 index 0000000..1ba9703 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/7.0/custom-binary.md b/7.0/custom-binary.md new file mode 100644 index 0000000..89e1d8f --- /dev/null +++ b/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| \ No newline at end of file diff --git a/7.0/gml.md b/7.0/gml.md new file mode 100644 index 0000000..9594e30 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/7.0/grids-and-arrays.md b/7.0/grids-and-arrays.md new file mode 100644 index 0000000..a44d6ba --- /dev/null +++ b/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: or , + numeric: or , + }, + ... +} +``` + +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. \ No newline at end of file diff --git a/7.0/ini.md b/7.0/ini.md new file mode 100644 index 0000000..9c4a113 --- /dev/null +++ b/7.0/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. + +  + +## `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. + +  + +## `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. + +  + +## `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. \ No newline at end of file diff --git a/7.0/json.md b/7.0/json.md new file mode 100644 index 0000000..9e74e49 --- /dev/null +++ b/7.0/json.md @@ -0,0 +1,65 @@ +# JSON + +[JavaScript Object Notation](https://www.json.org/json-en.html), otherwise known as JSON, is a commonly-used data format on the web. It is a text-based format insofar that JSON is expressed as a human-readable string of symbols, letters, and numbers. Its use has grown over the years such that it is frequently used through software engineering. JSON hits the sweet spot of simple, human-readable, and general enough to express nested datasets. JSON does have its limits however: it is not memory-efficient, it can be slow to parse (load), it is hard to write by hand, and JSON cannot express cylical self-reference. In reality, JSON is more than adequate for most data storage in GameMaker and you'll find yourself using it a lot for everything from savedata, to REST APIs, to item databases. + +JSON in GameMaker used to be handled by the nested ds_list and ds_map constructions. Old-style GameMaker JSON could be converted from lists/maps to a string and back again using `json_encode()` and `json_decode()`. As of GameMaker 2.3, the preference these days is to represent JSON data as arrays and structs rather than lists and maps, and the functions `json_stringify()` and `json_parse()` should be used instead. These functions aren't perfect, however, and there is room for improvement. + +SNAP's JSON stringification functions (`SnapToJSON()` and `SnapBufferWriteJSON()`) allow you to customise the accuracy of floating point numbers and the appearance of the resulting JSON string. The former option works around a flaw in `json_stringify()` where only two decimal places are stored for a decimal number, and the later makes JSON output much easier to read. Both behaviours incur a performance and memory penalty but they are often useful, if only during development. + +The JSON parser (`SnapFromJSON()` and `SnapBufferReadJSON()`) functions cover basic JSON reading as well as allowing for in-line and block comments. This isn't strictly part of the JSON specification, but being able to comment out sections of JSON is a useful feature. SNAP's JSON parser also allows for hanging commas at the end of arrays and objects which is convenient when writing JSON by hand. + +  + +## `SnapToJSON` + +*Returns:* String, the JSON-encoded data + +|Name |Datatype |Purpose | +|----------------------|------------|-----------------------------------------------------------------------------------------------------------| +|`data` |struct/array|The nested array/struct data to encode | +|`[pretty]` |boolean |Whether to output a "pretty" JSON string, one that uses indentation for easier reading. Defaults to `false`| +|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false` | +|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false` | + +!> Setting any of the optional arguments to `true` will incur a memory and performance penalty. You will generally only want to turn the optional features on during development. + +  + +## `SnapFromJSON` + +*Returns:* Array or struct, the root node of the JSON data + +|Name |Datatype|Purpose | +|--------|--------|------------------------| +|`string`|string |The JSON string to parse| + +  + +## `SnapBufferWriteJSON` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|----------------------|------------|-----------------------------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to write the JSON string into | +|`data` |struct/array|The nested array/struct data to encode | +|`[pretty]` |boolean |Whether to output a "pretty" JSON string, one that uses indentation for easier reading. Defaults to `false`| +|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false` | +|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false` | + +The JSON string will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function. + +!> Setting any of the optional arguments to `true` will incur a memory and performance penalty. You will generally only want to turn the optional features on during development. + +  + +## `SnapBufferReadJSON` + +*Returns:* Array or struct, the root node of the JSON data + +|Name |Datatype|Purpose | +|----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to read the JSON string from | +|`[offset]`|integer |The position in the buffer to read the JSON string 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. \ No newline at end of file diff --git a/7.0/messagepack.md b/7.0/messagepack.md new file mode 100644 index 0000000..0739e92 --- /dev/null +++ b/7.0/messagepack.md @@ -0,0 +1,29 @@ +# MessagePack + +[MessagePack](https://msgpack.org/index.html) is a binary format that is an alternative to JSON. It is both smaller and faster to parse with libraries for parsing available in many languages. MessagePack is especially useful for communicating with servers written in other languages. + +?> If you're looking for a faster alternative to JSON but aren't concerned about the interoperability benefits of MessagePack, take a look at SNAP's [custom binary format](custom-binary). + +  + +## `SnapBufferWriteMessagePack` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|--------|------------|------------------------------------| +|`buffer`|buffer |Buffer to write the binary data into| +|`data` |struct/array|Data to encode | + +The MessagePack data will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function. + +  + +## `SnapBufferReadMessagePack` + +*Returns:* Struct or array, the data read from the buffer + +|Name |Datatype|Purpose | +|--------|--------|-----------------------------------------------------------------------------| +|`buffer`|buffer |Buffer to read the MessagePack data from | +|`offset`|integer |Position in the buffer to read data from, relative to the start of the buffer| \ No newline at end of file diff --git a/7.0/nsv.md b/7.0/nsv.md new file mode 100644 index 0000000..4f0da2d --- /dev/null +++ b/7.0/nsv.md @@ -0,0 +1,37 @@ +# NSV + +Null-Separated Value fules, or NSVs, are a custom data format designed for GameMaker that replicates the behaviour of CSVs but allowing for much faster ingestion in GameMaker than would be possible with standard CSVs. You will find NSVs especially helpful when handling large quantities of tabulated data, such as an item database or localisation strings. + +NSVs can only be written and read using buffers as their use of null characters interferes with a string representation of the data. NSVs should only be used to store and retrieve 2D arrays that contain numbers or strings. If you're looking to store more complex data structures in whilst optimising performance, please use the [Custom Binary](custom-binary) functions. + +!> NSVs only work on "rectangular" data where the length of each child array is the same. + +  + +## `SnapBufferWriteNSV` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|------------------|--------|--------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to write the NSV data into | +|`data` |2D array|The 2D array to encode | +|`[width]` |integer |The length of each child array. If not provided, SNAP will find the maximum length | +|`[accurateFloats]`|boolean |Whether to output floats using a greater number of decimal points. Defaults to `false`| + +The NSV data 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. + +  + +## `SnapBufferReadNSV` + +*Returns:* 2D array + +|Name |Datatype|Purpose | +|----------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to read the NSV data from | +|`[offset]`|integer |The position in the buffer to read the NSV 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. \ No newline at end of file diff --git a/7.0/qml.md b/7.0/qml.md new file mode 100644 index 0000000..860a73b --- /dev/null +++ b/7.0/qml.md @@ -0,0 +1,153 @@ +# QML + +[QML](https://en.wikipedia.org/wiki/QML) (Qt Modeling Language) is a markup language originally designed for describing user interface layouts. It was created for [Qt](https://en.wikipedia.org/wiki/Qt_(software)), a cross-platform GUI framework. + +SNAP's implementation of QML is incomplete as a complete QML implementation necessarily involves writing a whole user interface system (an exercise for the reader, perhaps). The design of QML has many benefits if used beyond the scope of UI layouts, primarily the fact that it is possible to give structs a "type", thereby allowing SNAP to call a constructor when deserializing QML. + +Consider this short QML segment: +```qml +Tree { + x: 678 + y: 426 + leaves: "willow" +} +``` + +In a manner similar to JSON, QML allows us to describe a struct (delineated by curly brackets `{}`) and the variable for that struct. The key difference is the label `Tree` however, which indicates that the struct that follows should use whatever constructor is tied to the label of `"Tree"`. + +We might want to deserialize the above QML using the following GML code: +```gml +//Define a constructor for trees decoded from QML +function ConstructorTree() constructor +{ + x = 0; + y = 0; + leaves = "default"; + children = []; //Required for use with SNAP's QML parser +} + +//Define a struct ("dictionary") that maps QML labels to GML constructors +var _instanceofDict = { + "Tree": ConstructorTree +}; + +treeStruct = SnapFromQML(QMLstring, _instanceofDict); +``` + +In this situation, when the QML parser sees a new struct labelled `Tree` in the QML string, it will will construct a new instance of `ConstructorTree()` and then assign variables to it as required. + +Structs created from QML can have children. As noted above in the `ConstructorTree()` function, all QML constructors must contain a variable called `children` that is initialized to be an empty array. When deserializing QML, children of a particular struct are stored in this `children` array. For example, the following QML string... +```qml +Copse { + x1: 578 + y1: 326 + x2: 778 + y2: 526 + + Tree { + x: 678 + y: 426 + leaves: "willow" + } + + Tree { + x: 601 + y: 350 + leaves: "pine" + } +} +``` + +...would be deserialized as the following data (written here as GML literals): + +```gml +root = { //instanceof = "ConstructorField" + x1: 578, + y1: 326, + x2: 778, + y2: 526, + children: [ + { //instanceof = "ConstructorTree" + x: 678 + y: 426 + leaves: "willow" + }, + { //instanceof = "ConstructorTree" + x: 601, + y: 350, + leaves: "pine", + } + ] +} +``` + +If you enable relaxed mode when calling a SNAP QML function, you need not define 100% of the constructors that you're using. Instead, SNAP will recognise the literal names of the constructor functions as valid QML labels. + +!> "Relaxed mode" is convenient during development but is a significant security hole in your program if you expose relaxed QML parsing to your users. + +As mentioned above, SNAP's QML parser is not a complete implementation: + +1. QML allows for JavaScript to be used to declaratively define properties relative to other properties. This sort of behaviour is far *far* beyond the scope of SNAP. SNAP instead parses in-line JavaScript as a string literal. +2. QML allows for structs to be created "on" properties; effectively this assigns a struct to a variable on the parent (rather than the child struct being in the `children` array). SNAP's parser doesn't support this but can do in the future if [someone asks for it](https://github.com/JujuAdams/SNAP/issues). +3. QML allows for new properties to be defined in the QML file itself, with an associated type. SNAP does not support this syntax, or type safety for that matter, but you can freely define new variables on generated structs without limitation. +4. QML allows for variables to be set on nested structs (e.g. `font.pixelSize: 42`). SNAP will interpret the variable name as literally `"font.pixelSize"` rather than trying to find a variable called `font` that holds a struct with a member variable `pixelSize`. + +  + +## `SnapToQML` + +*Returns:* String, the data encoded as QML + +|Name |Datatype |Purpose | +|----------------------|------------|--------------------------------------------------------------------------------------| +|`data` |struct/array|The nested array/struct data to encode | +|`instanceofDict` |struct |A struct that maps QML type names to GML constructors. See above for more information | +|`[relaxed]` |boolean |Whether to run in "relaxed mode", see above. Defaults to `false` | +|`[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. + +  + +## `SnapFromQML` + +*Returns:* Array or struct, the root node of the QML data + +|Name |Datatype|Purpose | +|----------------|--------|-------------------------------------------------------------------------------------| +|`string` |string |The QML string to parse | +|`instanceofDict`|struct |A struct that maps QML type names to GML constructors. See above for more information| +|`[relaxed]` |boolean |Whether to run in "relaxed mode", see above. Defaults to `false` | + +  + +## `SnapBufferWriteQML` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|------------------|------------|--------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to write the QML string into | +|`data` |struct/array|The nested array/struct data to encode | +|`instanceofDict` |struct |A struct that maps QML type names to GML constructors. See above for more information | +|`[relaxed]` |boolean |Whether to run in "relaxed mode", see above. Defaults to `false` | +|`[accurateFloats]`|boolean |Whether to output floats using a greater number of decimal points. Defaults to `false`| + +The QML 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. + +  + +## `SnapBufferReadQML` + +*Returns:* Array or struct, the root node of the "loose JSON" data + +|Name |Datatype|Purpose | +|----------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to read the QML string from | +|`instanceofDict`|struct |A struct that maps QML type names to GML constructors. See above for more information | +|`[relaxed]` |boolean |Whether to run in "relaxed mode", see above. Defaults to `false` | +|`[offset]` |integer |The position in the buffer to read the QML string 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. \ No newline at end of file diff --git a/7.0/reconstruction.md b/7.0/reconstruction.md new file mode 100644 index 0000000..6e0417e --- /dev/null +++ b/7.0/reconstruction.md @@ -0,0 +1,69 @@ +# Reconstruction + +  + +## `SnapReconstructionPack` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|--------------------------|------------|--------------------------------------------------------------------------------------------------------------| +|`value` |string/array|The nested array/struct data to process | +|`[instanceofVariableName]`|string |Name of the special variable to store `instanceof()` data in. If not specified, defaults to `"__instanceof__"`| +|`[unsetConstructor]` |boolean |Whether to unset constructors for structs. If not specified, defaults to `false` | + +Recursively navigates over a nested struct/array and writes the `instanceof()` value for structs into a special value in the struct itself. This value can then be serialized with the rest of the struct's non-static variables using a SNAP function or `json_stringify()` etc. When deserializing data, either using a SNAP function or `json_parse()`, you should reconstruct the constructor for structs by calling `SnapReconstructionUnpack()`. + +If `unsetConstructor` is set to `true`, the constructor for structs is also cleared which is handy to work around current (2023.8, 2023-10-21) bugs in `json_stringify()`. You will need to restore the `instanceof()` value using `SnapReconstructionUnpack()` if you intend to keep using static variables/methods in these structs. + +!> There are significant limitations to what constructors can be serialized. This is mostly to avoid unpleasant situations where it's not possible to deserialize. You cannot use anonymous and/or non-global constructors with `SnapReconstructionPack()` as these cannot be reliably resolved later on when using `SnapReconstructionUnpack()`. + +Intended use is: + +``` +//On save +SnapReconstructionPack(jsonToSave); +SnapStringToFile(SnapToJSON(jsonToSave, "filename.txt")); +SnapReconstructionCleanUp(jsonToSave); + +//On load +loadedJson = SnapFromJSON(SnapStringFromFile("filename.txt")); +SnapReconstructionCleanUp(loadedJson); +``` + +!> This function is only available in versions of GameMaker with the native functions `static_get()` and `static_set()`. + +  + +## `SnapReconstructionUnpack` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|--------------------------|------------|--------------------------------------------------------------------------------------------------------------| +|`value` |string/array|The nested array/struct data to process | +|`[instanceofVariableName]`|string |Name of the special variable to store `instanceof()` data in. If not specified, defaults to `"__instanceof__"`| +|`[cleanUp]` |boolean |Whether to unset constructors for structs. If not specified, defaults to `false` | + +Recursively navigates over a nested struct/array and restores `instanceof()` values for structs based on the value of a special variable in each struct. These special variables are set by the companion function `SnapReconstructionPack()`. + +If `unsetConstructor` is set to `false`, the special variable used to store the `instanceof()` value for each struct will be maintained rather than deleted. + +!> You cannot use anonymous and/or non-global constructors with `SnapReconstructionPack()` as these cannot be reliably resolved. + +!> This function is only available in versions of GameMaker with the native functions `static_get()` and `static_set()`. + +  + +## `SnapReconstructionCleanUp` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|--------------------------|------------|--------------------------------------------------------------------------------------------------------------| +|`value` |string/array|The nested array/struct data to process | +|`[instanceofVariableName]`|string |Name of the special variable to store `instanceof()` data in. If not specified, defaults to `"__instanceof__"`| + +Cleans up special variables inserted into structs by `SnapReconstructionPack()`. + +!> This function is only available in versions of GameMaker with the native functions `static_get()` and `static_set()`. \ No newline at end of file diff --git a/7.0/tilemaps.md b/7.0/tilemaps.md new file mode 100644 index 0000000..af72661 --- /dev/null +++ b/7.0/tilemaps.md @@ -0,0 +1,53 @@ +# Tilemaps + +  + +## `SnapBufferWriteTilemap` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|---------|--------|-----------------------------| +|`buffer` |buffer |Buffer to write the data into| +|`tilemap`|tilemap |Tilemap to serialize | + +Stores the contents of a tilemap in a buffer, starting at the buffer's current head position. + +!> The name of the tileset to use is embedded in the tilemap data so any renamed or deleted tilesets will fail to read. + +  + +## `SnapBufferReadTilemapNew` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|--------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------| +|`buffer`|buffer |Buffer to write the data into | +|`offset`|integer |The position in the buffer to read the tilemap from, relative to the start of the buffer. If set to `undefined`, the buffer's head position is used| +|`layer` |string |Name of room layer to create the tilemap on | + +Creates a new tilemap on the given layer. The tilemap's dimensions and position will be set to whatever is in the data found in the buffer. + +!> The name of the tileset to use is embedded in the tilemap data (see above) so any renamed or deleted tilesets will fail to read. + +?> 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. + +  + +## `SnapBufferReadTilemapOverwrite` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|----------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------| +|`buffer` |buffer |Buffer to write the data into | +|`offset` |integer |The position in the buffer to read the tilemap from, relative to the start of the buffer. If set to `undefined`, the buffer's head position is used| +|`tilemap` |tilemap |Tilemap whose contents this function should overwrite | +|`[readPosition]`|boolean |Whether to set the position of the tilemap based on the coordinates in the tilemap data. Defaults to `false` if not specified | + +Overwrites the contents of an already existing tilemap based on data serialized by `SnapBufferWriteTilemap()`. If the width or height of the incoming tilemap is larger than the current tilemap, extra tiles will not be created. If the width or height is smaller than the current tilemap, the empty space will be set to `0` (no tile). + +!> The name of the tileset to use is embedded in the tilemap data (see above) so any renamed or deleted tilesets will fail to read. + +?> 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. \ No newline at end of file diff --git a/7.0/utilities.md b/7.0/utilities.md new file mode 100644 index 0000000..f9c32e7 --- /dev/null +++ b/7.0/utilities.md @@ -0,0 +1,204 @@ +# Utilities + +SNAP has a handful of utility scripts that you might find useful when working with datasets made out of nested arrays and structs. + +  + +## `SnapVisualize` + +*Returns:* String, a human-readable "ASCII art" diagram showing the structure of the input struct/array. + +|Name |Datatype |Purpose | +|---------|------------|------------------------------------------------------------------------------| +|`value` |struct/array|Value to process for display | +|`[ascii]`|boolean |Whether to use ASCII compatibility mode. If not specified, defaults to `false`| + +  + +## `SnapForeach` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|----------|---------------|-------------------------------------------------------------------| +|`data` |struct/array/ds|Data to operate on. See below | +|`method` |method |Method to execute for each member of the data structure | +|`[dsType]`|`ds_type_*` |Data structure type. Not used when iterating over a struct or array| + +Executes a method call for each element of the given struct/array/data structure. This iterator is shallow and will not also iterate over nested structs/arrays (though you can of course call `SnapForeach()` inside the specified method). + +This function can also iterate over all members of a ds_map, ds_list, or ds_grid. You will need to specify a value for `[dsType]` to iterate over a data structure. + +The specified method is passed the following parameters: + +|Argument |Purpose | +|-------------|---------------------------------------------------------------------------------------------------------------------| +|`argument0` |Value found in the given struct/array/ds | +|`argument1` |0-indexed index of the value e.g. `0` for the first element, `1` for the second element etc. | +|`[argument2]`|When iterating over structs or map, the name of the variable/key that contains the given value; otherwise `undefined`| + +The order that values are sent into `method` is guaranteed for arrays and ds_lists (starting at index `0` and ascending), but is not guaranteed for structs or maps due to the behaviour of GameMaker's internal hashmap. + +  + +## `SnapDeepCopy` + +*Returns:* Struct or array, a deep copy of the input data respecting constructors + +|Name |Datatype |Purpose | +|----------|------------|------------| +|`data` |struct/array|Data to copy| + +!> This function is only available in versions of GameMaker with the native functions `static_get()` and `static_set()`. + +  + +## `SnapDeepCopyLegacy` + +*Returns:* Struct or array, a deep copy of the input data ignoring constructors + +|Name |Datatype |Purpose | +|----------|------------|------------| +|`data` |struct/array|Data to copy| + +  + +## `SnapDeepForeachStruct` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|--------|------------|-----------------------------------------------------------------------------| +|`data` |struct/array|Data to operate on. See below | +|`method`|method |Method to call for each element of each struct in the given root struct/array| + +Executes a method call for each element of every struct found recursively by iterating over an input struct/array assembly. This iterator is deep and will also iterate over nested structs/arrays. + +The specified method is passed the following parameters: + +|Argument |Purpose | +|-----------|--------------------------------------------------------------------------------------------| +|`argument0`|Value found in the given struct/array | +|`argument1`|0-indexed index of the value e.g. `0` for the first element, `1` for the second element etc.| +|`argument2`|The name of the variable that contains the given value; otherwise `undefined` | + +The order that values are sent into `method` is not guaranteed due to the behaviour of GameMaker's internal hashmap. + +  + +## `SnapDeepAdd` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|--------------------|------------|------------| +|`source` |struct/array| | +|`destination` |struct/array| | +|`[ignoreNonNumbers]`|boolean | | + +  + +## `SnapMerge` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|-------------------|------------|--------------------------------------------------------------------------------------------------------------------------------| +|`source` |struct/array|Source struct/array to copy from | +|`destination` |struct/array|Destination struct/array to copy to | +|`[resolveToSource]`|boolean |Whether to prefer the source or the destination if there is a datatype conflict. Defaults to `false`, preferring the destination| + +This function is designed to merge one simple tree-like structures into another. Values from the source tree are copied into the destination tree recursively. Values from the source will overwrite values in the destination, but any values that are present in the destination but not the source will be maintained. In situations where there is a datatype conflict, the `resolveToSource` argument will determine which way data is copied. + +!> Structs and arrays are copied by reference. If you wish to ensure that structs and arrays copied to the destination are fresh copies, first use `SnapDeepCopy()` on the source. + +  + +## `SnapShallowAdd` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|--------------------|------------|------------| +|`source` |struct/array| | +|`destination` |struct/array| | +|`[ignoreNonNumbers]`|boolean | | + +  + +## `SnapStringify` + +*Returns:* String + +|Name |Datatype|Purpose | +|-------|--------|------------| +|`value`|any | | + +  + +## `SnapNumberToString` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|-------|--------|------------| +|`value`|any | | + +  + +# Files + +The following functions relate to file operations, specifically embedding or removing the UTF-8 byte order mark (BOM). This is often needed to get programs to recognise that the data in a file is encoded as UTF-8 and is helpful in avoiding communication issues. + +## `SnapStringFromFile` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|-------------|--------|---------------------------------------------------------------------------------------| +|`filename` |string |Filename to read from | +|`[removeBOM]`|boolean |Whether to remove the BOM from the start of the file (if it exists). Defaults to `true`| + +  + +## `SnapStringToFile` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|----------|--------|--------------------------------------------------------------------| +|`string` |string |String to write to the file | +|`filename`|string |Filename to write to | +|`[addBOM]`|boolean |Whether to add the BOM to the start of the file. Defaults to `false`| + +  + +## `SnapBufferWriteBOM` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|--------|--------|--------------------------| +|`buffer`|buffer |Buffer to write the BOM to| + +  + +## `SnapBufferReadBOM` + +*Returns:* Boolean, whether a UTF-8 byte order mark was found + +|Name |Datatype|Purpose | +|--------|--------|-----------------| +|`buffer`|buffer |Buffer to process| + +  + +## `SnapMD5` + +*Returns:* Hexadecimal string, the MD5 hash of the given struct/array + +|Name |Datatype|Purpose | +|-------|--------|-----------------| +|`value`|any |The value to hash| + +This function can also be used on non-struct/array data, though the hash may not line up with other MD5 implementations. \ No newline at end of file diff --git a/7.0/vdf.md b/7.0/vdf.md new file mode 100644 index 0000000..5e516a3 --- /dev/null +++ b/7.0/vdf.md @@ -0,0 +1,59 @@ +# VDF + +Valve's [KeyValue format](https://developer.valvesoftware.com/wiki/KeyValues), more commonly known as the "Valve Data Format" or VDF, is a simple struct-based data format used for several Source Engine titles. The format curiously doesn't support arrays and all values must be strings, but its simplicity makes it attractive for human-readable configuration files and the like. + +!> SNAP's VDF parser does not support the use of `#include` or `#base`. + +  + +## `SnapToVDF` + +*Returns:* String, the VDF-encoded data + +|Name |Datatype |Purpose | +|----------------------|------------|--------------------------------------------------------------------------------------| +|`data` |struct/array|The nested struct data to encode | +|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false` | +|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false`| + +!> Setting any of the optional arguments to `true` will incur a memory and performance penalty. You will generally only want to turn the optional features on during development. + +  + +## `SnapFromVDF` + +*Returns:* Struct, the root node of the VDF data + +|Name |Datatype|Purpose | +|--------|--------|-----------------------| +|`string`|string |The VDF string to parse| + +  + +## `SnapBufferWriteVDF` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|----------------------|------------|--------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to write the VDF string into | +|`data` |struct/array|The nested array/struct data to encode | +|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false` | +|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false`| + +The VDF string will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function. + +!> Setting any of the optional arguments to `true` will incur a memory and performance penalty. You will generally only want to turn the optional features on during development. + +  + +## `SnapBufferReadVDF` + +*Returns:* Struct, the root node of the JSON data + +|Name |Datatype|Purpose | +|----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------| +|`buffer` |buffer |The buffer to read the VDF string from | +|`[offset]`|integer |The position in the buffer to read the VDF string 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/7.0/xml.md b/7.0/xml.md new file mode 100644 index 0000000..839539c --- /dev/null +++ b/7.0/xml.md @@ -0,0 +1,46 @@ +# XML + +  + +## `SnapToXML` + +*Returns:* String, the CSV data + +|Name |Datatype|Purpose | +|------|--------|--------------| +|`data`|struct |Data to encode| + +  + +## `SnapFromXML` + +*Returns:* Struct, the struct/array resprentation of the input XML data + +|Name |Datatype|Purpose | +|--------|--------|-----------------------------------------| +|`string`|string |XML data, presented as a string, to parse| + +  + +## `SnapBufferWriteYAML` + +*Returns:* N/A (`undefined`) + +|Name |Datatype|Purpose | +|--------|--------|---------------------------------| +|`buffer`|buffer |Buffer to write the XML data into| +|`data` |struct |Data to encode | + +The XML string will be inserted into the buffer at the current "head" position, as determined by GameMaker's native `buffer_tell()` function. + +  + +## `SnapBufferReadYAML` + +*Returns:* Struct, the struct/array resprentation of the input XML data + +|Name |Datatype|Purpose | +|--------|--------|-------------------------------------------------------------------------------------| +|`buffer`|buffer |Buffer to read the CSV data from | +|`offset`|integer |Position in the buffer to read the CSV data from, relative to the start of the buffer| +|`size` |integer |Number of bytes to read | \ No newline at end of file diff --git a/7.0/yaml.md b/7.0/yaml.md new file mode 100644 index 0000000..d8a9fa3 --- /dev/null +++ b/7.0/yaml.md @@ -0,0 +1,54 @@ +# YAML + +  + +## `SnapToYAML` + +*Returns:* String, the YAML data + +|Name |Datatype |Purpose | +|----------------------|------------|--------------------------------------------------------------------------------------| +|`data` |struct/array|Data to encode | +|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false` | +|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false`| + +!> Setting either of the optional arguments to `true` will incur a memory and performance penalty. You will generally only want to turn the optional features on during development. + +  + +## `SnapFromYAML` + +*Returns:* Struct or array, the struct/array resprentation of the input YAML data + +|Name |Datatype|Purpose | +|--------|--------|------------------| +|`string`|string |YAML data to parse| + +  + +## `SnapBufferWriteYAML` + +*Returns:* N/A (`undefined`) + +|Name |Datatype |Purpose | +|----------------------|------------|--------------------------------------------------------------------------------------| +|`buffer` |buffer |Buffer to write the YAML data into | +|`data` |struct/array|Data to encode | +|`[alphabetizeStructs]`|boolean |Whether to alphabetize structs by variable name. Defaults to `false` | +|`[accurateFloats]` |boolean |Whether to output floats using a greater number of decimal points. Defaults to `false`| + +!> Setting either of the optional arguments to `true` will incur a memory and performance penalty. You will generally only want to turn the optional features on during development. + +  + +## `SnapBufferReadYAML` + +*Returns:* Struct or array, the struct/array resprentation of the input YAML data + +|Name |Datatype|Purpose | +|-------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +|`buffer` |buffer |Buffer to read the YAML data from | +|`offset` |integer |Offset in the buffer to read data from | +|`[replaceKeywords]`|boolean |Whether to replace keyword strings (`"true"`, `"false"`, `"null"`) with their equivalents. Defaults to `true` | +|`[trackFieldOrder]`|boolean |Whether to track the order of struct fields as they appear in the YAML string (stored in `__snapFieldOrder` field on each GML struct). Default to `false`| +|`[tabSize=2]` |integer |Size of tabs, measured in "number of spaces". This is used to calculate indentation | \ No newline at end of file diff --git a/config.js b/config.js index 6f45e8b..8dd9de6 100644 --- a/config.js +++ b/config.js @@ -22,8 +22,8 @@ const config = { name: 'SNAP', description: 'Data format conversion for GameMaker LTS 2022', - latestVersion: '6.1', - otherVersions: ['6.0','5.9', '5.8', '5.7', '5.6', '5.5', '5.4', '5.3', '5.2', '5.1', '5.0'], + latestVersion: '7.0', + otherVersions: ['6.1', '6.0','5.9', '5.8', '5.7', '5.6', '5.5', '5.4', '5.3', '5.2', '5.1', '5.0'], favicon: 'assets/favicon.ico', themeColor: '#4f98ff', };