Easy struct/array saving and loading
Chat about SNAP on the Discord server
Functions included can:
- Iterate over all elements of a struct/array and execute a function:
foreach() - Make a deep copy of a struct/array:
snap_deep_copy(struct/array) - Encode/decode JSON
- Encode/decode CSV
- Encode/decode YAML
- Encode/decode a custom binary format
- Encode/decode messagepack
- Encode/decode XML
- Encode/decode GML
- Decode INI
Executes a function call for each element of the given struct/array. This iterator is shallow and will not also iterate over nested structs/arrays (though you can of course call foreach 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.
function is passed the following parameters:
arg0 - Value found in the given struct/array
arg1 - 0-indexed index of the value e.g. =0 for the first element, =1 for the second element etc.
arg2 - When iterating over structs, the name of the variable that contains the given value; otherwise <undefined>The order that values are sent into method is guaranteed for arrays (starting at index 0 and ascending), but is not guaranteed for structs due to the behaviour of GameMaker's internal hashmap.
Convenience function that returns a string that contains all the data in the given file.
Returns a copy of the given struct/array, including a copy of any nested structs and arrays.
Turns struct and array nested data into a JSON string. The root datatype can be either a struct or an array. Setting [pretty] to true will format the JSON string in a more pleasing human-readable way, whereas setting [alphabetizeStructs] to true will output the struct variables in ascending alphabetical order. Using pretty and/or alphabetized output does incur a performance penalty.
Decodes a JSON string into nested struct/array data. This function will happily ignore formatting whitespace and handles \\, \", \n, \r, and \t escaped characters. Also supports true, false, and null values.
Turns a 2D array into a CSV string. The 2D array must not contain further nested structs or arrays. The cell and string delimiters can be specified for compatibility with various different languages.
N.B. This function expects the input array to be column-major i.e. array[column][row] / array[y][x]
Decodes a CSV string into a 2D array. All values unpacked from the CSV string will be stored as strings - unfortunately, issues with try...catch in GMS2.3.0 runtime 23.1.1.146 prevent automatic detection of numeric values. As above, the cell and string delimiters can be defined, though they are limited to the first 127 ASCII characters.
N.B. The 2D array that this function creates is column-major i.e. array[column][row] / array[y][x]
Turns struct and array nested data into a YAML string. The root datatype can be either a struct or an array. Setting [alphabetizeStructs] to true will output the struct variables in ascending alphabetical order. Using alphabetized output does incur a performance penalty.
Decodes a YAML string into nested struct/array data. If [replaceKeywords] is set to true (the default) then the following keywords will be turned into their associated numeric values: true, false, undefined. snap_from_json() is not a full implementation of the YAML spec and doesn't try to be. This parser doesn't support:
- Single quote
'delimited strings (you must use double quotes") - Block scalars using
|and>prefixes - Anchors, documents, directives, nodes... all the weird extra stuff.
Returns a buffer that holds binary encoded struct and array nested data. The root datatype can be either a struct or an array. This is substantially faster than snap_to_json().
Unpacks binary encoded struct/array data. An [offset] for the data within the buffer can be specified which is helpful for working with composite buffers. If [destroyBuffer] is set to true then the input buffer will be destroyed once the function has finished executing. This function is a lot faster than snap_from_json_string().
Returns a buffer that holds a binary representation of struct and array nested data according to the messagepack specification. The root datatype can any datatype. This function is slower then the proprietary snap_to_binary(), but the messagepack format is widely used and tends to output slightly smaller buffers.
Unpacks messagepack binary data into a struct/array data. An [offset] for the data within the buffer can be specified which is helpful for working with composite buffers. If [destroyBuffer] is set to true then the input buffer will be destroyed once the function has finished executing. snap_from_messagepack() is a little slower than snap_from_binary().
Decodes a XML string into nested struct/array data. Each XML element is struct. Element attributes are stored inside a sub-struct called _attr. Child elements are stored using their name as the member variable name in the parent. If more than one element with the same name exists then they are put into an array. If an element's content is a string then it is stored under the member variable _text. If an element has neither attributes nor children nor content then it is stored as an empty struct. The XML prolog is stored in a struct in the root struct under the member variable _prolog.
This is a bit wordy, so here's an example. The following XML and struct/array literal are interchangable:
<root halign="left" valign="top">
<text>Hello World!</text>
<button url="http://www.jujuadams.com/">Click me!</button>
<button url="http://www.spiderlili.com/">Or me!</button>
<empty_tag></empty_tag>
</root>{
root : {
_attr : {
halign : "left",
valign : "top",
},
text : {
_text : "Hello World!"
},
button : [
{
_attr : {
url : "http://www.jujuadams.com/
},
_text : "Click me!"
},
{
_attr : {
url : "http://www.spiderlili.com/
},
text : "Or me!"
}
],
empty_tag : {}
}
}
Turns struct and array nested data into a XML string. The data must be structured as above in GML example for snap_from_xml(). Setting [alphabetizeStructs] to true will output child element in ascending alphabetical order. Using an alphabetized output incurs a performance penalty.
Turns a struct into a GML struct defintion, exported as a string. The root element must be a struct (not an array), but otherwise structs and arrays can be nested inside each other. Setting [alphabetizeStructs] to true will output variables in ascending alphabetical order, albeit at a performance penalty.
Decodes a GML struct defintion (stored as a string) into nested struct/array data. This function will always return a struct as the root element. snap_from_gml() will happily ignore formatting whitespace and handles \\, \", \n, \r, and \t escaped characters. Also supports true, false, and undefined values.
Parses a string representation of an .ini file into nested structs: sections are stored as nested structs inside the root struct. Setting [tryReal] to true (the default value) will instruct the function to attempt to turn any values into real numbers if possible.
N.B. This script is only intended to read the .ini files and strings that GM generates using the native ini_close() function. This is not a full implementation of an .ini specification (not that an official one really exists).
Convenience function that loads an .ini file from disk and passes it into snap_from_ini_string().