Merge branch 'dev'

JujuAdams · Jun 24, 2020 · af5560f · af5560f
2 parents 00de606 + 25d59aa
commit af5560f
Show file tree

Hide file tree

Showing 20 changed files with 1,088 additions and 43 deletions.
diff --git a/README.md b/README.md
@@ -1,21 +1,20 @@
-<h1 align="center">SNAP: Struct N' Array Parser 3.0.0</h1>
+<h1 align="center">SNAP: Struct N' Array Parsing 3.2.0</h1>
 
-<p align="center">Replacement for ds_map/ds_list-based encoding/decoding</p>
+<p align="center">Easy struct/array saving and loading</p>
 
 <p align="center"><a href="https://github.com/JujuAdams/SNAP/releases/tag/3.0.0">Download the .yymps here</a></p>
 
 &nbsp;
 
-Functions included are:
+Functions included can:
 
-1. `foreach(struct/array, method, [dsType])`
-2. `snap_deep_copy(struct/array)`
-3. `snap_to_json(struct/array, [pretty], [alphabetizeStructs])`
-4. `snap_from_json(string)`
-5. `snap_to_binary(struct/array)`
-6. `snap_from_binary(buffer, [offset], [size], [destroyBuffer])`
-7. `snap_from_xml(string)`
-8. `snap_to_xml(struct/array, [alphabetizeStructs])`
+1. Iterate over all elements of a struct/array and execute a function: `foreach()`
+2. Make a deep copy of a struct/array: `snap_deep_copy(struct/array)`
+3. Encode/decode JSON
+4. Encode/decode binary
+5. Encode/decode [messagepack](https://msgpack.org/index.html)
+6. Encode/decode XML
+7. Decode INI
 
 -----
 
@@ -44,7 +43,7 @@ Returns a copy of the given `struct/array`, including a copy of any nested struc
 
 ### snap_to_json(struct/array, [pretty], [alphabetizeStructs]) ###
 
-Turns struct and array nested data into a JSON string. The root data type 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.
+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.
 
 &nbsp;
 
@@ -56,13 +55,25 @@ Decodes a JSON string into nested struct/array data. This function will happily
 
 ### snap_to_binary(struct/array) ###
 
-Returns a buffer that holds binary encoded struct and array nested data. The root data type can be either a struct or an array. This is substantially faster than `snap_to_json()`.
+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()`.
 
 &nbsp;
 
-### snap_from_binary(buffer, [offset], [size], [destroyBuffer]) ###
+### snap_from_binary(buffer, [offset], [destroyBuffer]) ###
 
-Unpacks binary encoded struct/array data. An `[offset]` and total `[size]` for the data within the buffer can be specified which is helpful for working with composite buffers. Set `[size]` to `-1` to use the entire size of the buffer. 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()`.
+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()`.
+
+&nbsp;
+
+### snap_to_messagepack(struct/array) ###
+
+Returns a buffer that holds a binary representation of struct and array nested data according to the [messagepack](https://msgpack.org/index.html) specification. The root datatype can any datatype. This function is slower then the proprietary `snap_to_binary()`, but the [messagepack](https://msgpack.org/index.html) format is widely used and tends to output slightly smaller buffers.
+
+&nbsp;
+
+### snap_from_messagepack(buffer, [offset], [destroyBuffer]) ###
+
+Unpacks [messagepack](https://msgpack.org/index.html) 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()`.
 
 &nbsp;
 
@@ -115,3 +126,18 @@ This is a bit wordy, so here's an example. The following XML and struct/array li
 ### snap_to_xml(struct/array, [alphabetizeStructs]) ###
 
 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.
+
+&nbsp;
+
+### snap_from_ini_string(string, [tryReal]) ###
+
+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)._
+
+&nbsp;
+
+### snap_from_ini_file(filename, [tryReal]) ###
+
+Convenience function that loads an .ini file from disk and passes it into `snap_from_ini_string()`.
+
diff --git a/objects/oTestBinary/Create_0.gml b/objects/oTestBinary/Create_0.gml
@@ -25,4 +25,6 @@ struct = {
     url : "https://www.jujuadams.com/"
 };
 
-show_debug_message(snap_to_json(snap_from_binary(snap_to_binary(struct)), true, true));
+buffer = snap_to_binary(struct);
+show_debug_message(buffer_base64_encode(buffer, 0, -1));
+show_debug_message(snap_to_json(snap_from_binary(buffer), true, true));
diff --git a/objects/oTestBinary/oTestMessagepack.yy b/objects/oTestBinary/oTestMessagepack.yy
@@ -0,0 +1,33 @@
+{
+  "spriteId": null,
+  "solid": false,
+  "visible": true,
+  "spriteMaskId": null,
+  "persistent": false,
+  "parentObjectId": null,
+  "physicsObject": false,
+  "physicsSensor": false,
+  "physicsShape": 1,
+  "physicsGroup": 1,
+  "physicsDensity": 0.5,
+  "physicsRestitution": 0.1,
+  "physicsLinearDamping": 0.1,
+  "physicsAngularDamping": 0.1,
+  "physicsFriction": 0.2,
+  "physicsStartAwake": true,
+  "physicsKinematic": false,
+  "physicsShapePoints": [],
+  "eventList": [
+    {"isDnD":false,"eventNum":0,"eventType":0,"collisionObjectId":null,"parent":{"name":"oTestMessagepack","path":"objects/oTestMessagepack/oTestMessagepack.yy",},"resourceVersion":"1.0","name":null,"tags":[],"resourceType":"GMEvent",},
+  ],
+  "properties": [],
+  "overriddenProperties": [],
+  "parent": {
+    "name": "snap",
+    "path": "snap.yyp",
+  },
+  "resourceVersion": "1.0",
+  "name": "oTestMessagepack",
+  "tags": [],
+  "resourceType": "GMObject",
+}
diff --git a/objects/oTestINI/Create_0.gml b/objects/oTestINI/Create_0.gml
@@ -0,0 +1,22 @@
+var _text = @'[Section 1]
+; comment
+Option 1 = value 1                     ; option "Option 1" has value "value 1"
+oPtion 1    =  \ value 2\ \ \          ; option "oPtion 1" has value " value 2   ", "oPtion 1" and "Option 1" are different
+
+[Numbers]
+num = "-1285"
+num_bin = 0b01101001
+num_hex = 0x12ae
+num_oct = 01754
+
+float1 = -124.45667356
+float2 = +4.1234565E+45
+float3 = 412.34565e45
+float4 = -1.1245864E-6
+
+[Other]
+bool1 = 1
+bool2 = on
+bool3=f';
+
+show_debug_message(snap_to_json(snap_from_ini_string(_text, false), true, true));
diff --git a/objects/oTestINI/oTestINI.yy b/objects/oTestINI/oTestINI.yy
@@ -0,0 +1,33 @@
+{
+  "spriteId": null,
+  "solid": false,
+  "visible": true,
+  "spriteMaskId": null,
+  "persistent": false,
+  "parentObjectId": null,
+  "physicsObject": false,
+  "physicsSensor": false,
+  "physicsShape": 1,
+  "physicsGroup": 1,
+  "physicsDensity": 0.5,
+  "physicsRestitution": 0.1,
+  "physicsLinearDamping": 0.1,
+  "physicsAngularDamping": 0.1,
+  "physicsFriction": 0.2,
+  "physicsStartAwake": true,
+  "physicsKinematic": false,
+  "physicsShapePoints": [],
+  "eventList": [
+    {"isDnD":false,"eventNum":0,"eventType":0,"collisionObjectId":null,"parent":{"name":"oTestINI","path":"objects/oTestINI/oTestINI.yy",},"resourceVersion":"1.0","name":null,"tags":[],"resourceType":"GMEvent",},
+  ],
+  "properties": [],
+  "overriddenProperties": [],
+  "parent": {
+    "name": "snap",
+    "path": "snap.yyp",
+  },
+  "resourceVersion": "1.0",
+  "name": "oTestINI",
+  "tags": [],
+  "resourceType": "GMObject",
+}
diff --git a/objects/oTestMessagepack/Create_0.gml b/objects/oTestMessagepack/Create_0.gml
@@ -0,0 +1,30 @@
+struct = {
+    a : true,
+    b : false,
+    c : undefined,
+    d : 1/9,
+    e : 15/100,
+    array : [
+        5,
+        6,
+        7,
+        {
+            struct : "struct!",
+            nested : {
+                nested : "nested!",
+                array : [
+                    "more",
+                    "MORE",
+                    "M O R E"
+                ]
+            }
+        }
+    ],
+    test : "text!",
+    test2 : "\"Hello world!\"",
+    url : "https://www.jujuadams.com/"
+};
+
+buffer = snap_to_messagepack(struct);
+show_debug_message(buffer_base64_encode(buffer, 0, -1));
+show_debug_message(snap_to_json(snap_from_messagepack(buffer), true, true));
diff --git a/objects/oTestMessagepack/oTestMessagepack.yy b/objects/oTestMessagepack/oTestMessagepack.yy
@@ -0,0 +1,33 @@
+{
+  "spriteId": null,
+  "solid": false,
+  "visible": true,
+  "spriteMaskId": null,
+  "persistent": false,
+  "parentObjectId": null,
+  "physicsObject": false,
+  "physicsSensor": false,
+  "physicsShape": 1,
+  "physicsGroup": 1,
+  "physicsDensity": 0.5,
+  "physicsRestitution": 0.1,
+  "physicsLinearDamping": 0.1,
+  "physicsAngularDamping": 0.1,
+  "physicsFriction": 0.2,
+  "physicsStartAwake": true,
+  "physicsKinematic": false,
+  "physicsShapePoints": [],
+  "eventList": [
+    {"isDnD":false,"eventNum":0,"eventType":0,"collisionObjectId":null,"parent":{"name":"oTestMessagepack","path":"objects/oTestMessagepack/oTestMessagepack.yy",},"resourceVersion":"1.0","name":null,"tags":[],"resourceType":"GMEvent",},
+  ],
+  "properties": [],
+  "overriddenProperties": [],
+  "parent": {
+    "name": "snap",
+    "path": "snap.yyp",
+  },
+  "resourceVersion": "1.0",
+  "name": "oTestMessagepack",
+  "tags": [],
+  "resourceType": "GMObject",
+}
diff --git a/rooms/rMain/rMain.yy b/rooms/rMain/rMain.yy
@@ -14,15 +14,15 @@
   ],
   "layers": [
     {"instances":[
-        {"properties":[],"isDnd":false,"objectId":{"name":"oTestBinary","path":"objects/oTestBinary/oTestBinary.yy",},"inheritCode":false,"hasCreationCode":false,"colour":4294967295,"rotation":0.0,"scaleX":1.0,"scaleY":1.0,"imageIndex":0,"imageSpeed":1.0,"inheritedItemId":null,"frozen":false,"ignore":false,"inheritItemSettings":false,"x":64.0,"y":32.0,"resourceVersion":"1.0","name":"inst_721877E5","tags":[],"resourceType":"GMRInstance",},
+        {"properties":[],"isDnd":false,"objectId":{"name":"oTestBinary","path":"objects/oTestBinary/oTestBinary.yy",},"inheritCode":false,"hasCreationCode":false,"colour":4294967295,"rotation":0.0,"scaleX":1.0,"scaleY":1.0,"imageIndex":0,"imageSpeed":1.0,"inheritedItemId":null,"frozen":false,"ignore":false,"inheritItemSettings":false,"x":32.0,"y":32.0,"resourceVersion":"1.0","name":"inst_6380F5B5","tags":[],"resourceType":"GMRInstance",},
       ],"visible":true,"depth":0,"userdefinedDepth":false,"inheritLayerDepth":false,"inheritLayerSettings":false,"gridX":32,"gridY":32,"layers":[],"hierarchyFrozen":false,"resourceVersion":"1.0","name":"Instances","tags":[],"resourceType":"GMRInstanceLayer",},
     {"spriteId":null,"colour":4278190080,"x":0,"y":0,"htiled":false,"vtiled":false,"hspeed":0.0,"vspeed":0.0,"stretch":false,"animationFPS":15.0,"animationSpeedType":0,"userdefinedAnimFPS":false,"visible":true,"depth":100,"userdefinedDepth":false,"inheritLayerDepth":false,"inheritLayerSettings":false,"gridX":32,"gridY":32,"layers":[],"hierarchyFrozen":false,"resourceVersion":"1.0","name":"Background","tags":[],"resourceType":"GMRBackgroundLayer",},
   ],
   "inheritLayers": false,
   "creationCodeFile": "",
   "inheritCode": false,
   "instanceCreationOrder": [
-    {"name":"inst_721877E5","path":"rooms/rMain/rMain.yy",},
+    {"name":"inst_6380F5B5","path":"rooms/rMain/rMain.yy",},
   ],
   "inheritCreationOrder": false,
   "sequenceId": null,

diff --git a/scripts/snap_deep_copy/snap_deep_copy.gml b/scripts/snap_deep_copy/snap_deep_copy.gml
@@ -2,7 +2,7 @@
 /// 
 /// @param struct/array   The struct/array to be copied
 /// 
-/// @jujuadams 2020-06-16
+/// @jujuadams 2020-06-24
 
 function snap_deep_copy(_value)
 {
@@ -28,11 +28,11 @@ function __snap_deep_copy(_value) constructor
 
             if (is_struct(_value))
             {
-                _value = copy_struct(_source);
+                _value = copy_struct(_value);
             }
             else if (is_array(_value))
             {
-                _value = copy_array(_source);
+                _value = copy_array(_value);
             }
 
             variable_struct_set(_copy, _name, _value);
@@ -57,11 +57,11 @@ function __snap_deep_copy(_value) constructor
 
             if (is_struct(_value))
             {
-                _value = copy_struct(_source);
+                _value = copy_struct(_value);
             }
             else if (is_array(_value))
             {
-                _value = copy_array(_source);
+                _value = copy_array(_value);
             }
 
             _copy[@ _i] = _value;

diff --git a/scripts/snap_from_binary/snap_from_binary.gml b/scripts/snap_from_binary/snap_from_binary.gml
@@ -1,11 +1,10 @@
-/// @return Nested struct/array data decoded from the buffer
+/// @return Nested struct/array data encoded from the buffer, using a proprietary format
 /// 
-/// @param buffer           Binary data to be decoded, created by sna_to_binary()
+/// @param buffer           Binary data to be decoded, created by snap_to_binary()
 /// @param [offset]         Start position for binary decoding in the buffer. Defaults to 0, the start of the buffer
-/// @param [size]           Number of bytes of data to be decoded. Set to -1 to use the entire size of the buffer. Defaults to -1
 /// @param [destroyBuffer]  Set to <true> to destroy the input buffer. Defaults to <false>
 /// 
-/// @jujuadams 2020-05-02
+/// @jujuadams 2020-06-20
 
 /*
     0x00  -  terminator
@@ -24,33 +23,28 @@ function snap_from_binary()
 {
     var _buffer         = argument[0];
     var _offset         = ((argument_count > 1) && (argument[1] != undefined))? argument[1] : 0;
-    var _size           = ((argument_count > 2) && (argument[2] != undefined))? argument[2] : -1;
-    var _destroy_buffer = ((argument_count > 3) && (argument[3] != undefined))? argument[3] : false;
-
-    if (_size < 0) _size = buffer_get_size(_buffer) - _offset;
+    var _destroy_buffer = ((argument_count > 2) && (argument[2] != undefined))? argument[2] : false;
 
     var _old_tell = buffer_tell(_buffer);
     buffer_seek(_buffer, buffer_seek_start, _offset);
-    var _result = (new __snap_from_binary_parser(_buffer, _size)).root;
+    var _result = (new __snap_from_binary_parser(_buffer)).root;
     buffer_seek(_buffer, buffer_seek_start, _old_tell);
 
     if (_destroy_buffer) buffer_delete(_buffer);
 
     return _result;
 }
 
-function __snap_from_binary_parser(_buffer, _buffer_size) constructor
+function __snap_from_binary_parser(_buffer) constructor
 {
     buffer          = _buffer;
-    buffer_size     = _buffer_size;
-
     root            = undefined;
     root_is_struct  = false;
     root_array_size = 0;
     in_key          = false;
     key             = undefined;
 
-    while(buffer_tell(buffer) < buffer_size)
+    while(true)
     {
         if (in_key)
         {
@@ -102,7 +96,7 @@ function __snap_from_binary_parser(_buffer, _buffer_size) constructor
                     case 0x01: //Struct
                     case 0x02: //Array
                         buffer_seek(buffer, buffer_seek_relative, -1);
-                        value = (new __snap_from_binary_parser(_buffer, _buffer_size)).root;
+                        value = (new __snap_from_binary_parser(_buffer)).root;
                     break;
 
                     case 0x03: //String