From 154ef61e3bcb74c98fb4dbe46fc0a375b54d789a Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:12:21 -0400 Subject: [PATCH 01/17] Rename README.txt to README.rst --- README.txt => README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename README.txt => README.rst (99%) diff --git a/README.txt b/README.rst similarity index 99% rename from README.txt rename to README.rst index 3f537ba..4701459 100644 --- a/README.txt +++ b/README.rst @@ -88,7 +88,7 @@ JSON. The detailed help info for the four functions can be found below: Nedialko Krouchev: http://www.mathworks.com/matlabcentral/fileexchange/25713 created on 2009/11/02 - Fran�ois Glineur: http://www.mathworks.com/matlabcentral/fileexchange/23393 + François Glineur: http://www.mathworks.com/matlabcentral/fileexchange/23393 created on 2009/03/22 Joel Feenstra: http://www.mathworks.com/matlabcentral/fileexchange/20565 From ab23b5163f4041289d54cebb6eef1096db027768 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:14:58 -0400 Subject: [PATCH 02/17] Update README.rst --- README.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index 4701459..1a7645d 100644 --- a/README.rst +++ b/README.rst @@ -1,13 +1,12 @@ -=============================================================================== -= JSONLab = -= An open-source MATLAB/Octave JSON encoder and decoder = -=============================================================================== +############################################################################## + JSONLab + An open-source MATLAB/Octave JSON encoder and decoder +############################################################################## *Copyright (C) 2011-2017 Qianqian Fang *License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt *Version: 1.5 (Nominus - alpha) -------------------------------------------------------------------------------- Table of Content: @@ -17,9 +16,9 @@ III.Using JSONLab IV. Known Issues and TODOs V. Contribution and feedback -------------------------------------------------------------------------------- - -I. Introduction +============ +Introduction +============ JSON ([http://www.json.org/ JavaScript Object Notation]) is a highly portable, human-readable and "[http://en.wikipedia.org/wiki/JSON fat-free]" text format @@ -50,9 +49,9 @@ JSON/UBJSON formatted strings, or to decode a JSON/UBJSON file into MATLAB data structure. JSONLab supports both MATLAB and [http://www.gnu.org/software/octave/ GNU Octave] (a free MATLAB clone). -------------------------------------------------------------------------------- - +================ II. Installation +================ The installation of JSONLab is no different than any other simple MATLAB toolbox. You only need to download/unzip the JSONLab package @@ -66,9 +65,10 @@ browse to the jsonlab root folder and add to the list, then click "Save". Then, run "rehash" in MATLAB, and type "which loadjson", if you see an output, that means JSONLab is installed for MATLAB/Octave. -------------------------------------------------------------------------------- -III.Using JSONLab +================ +Using JSONLab +================ JSONLab provides two functions, loadjson.m -- a MATLAB->JSON decoder, and savejson.m -- a MATLAB->JSON encoder, for the text-based JSON, and @@ -368,9 +368,9 @@ and loadubjson functions for various matlab data structures. Please run these examples and understand how JSONLab works before you use it to process your data. -------------------------------------------------------------------------------- - -IV. Known Issues and TODOs +======================= +Known Issues and TODOs +======================= JSONLab has several known limitations. We are striving to make it more general and robust. Hopefully in a few future releases, the limitations become less. @@ -389,9 +389,9 @@ possibility of making it upstream # loadubjson can not parse all UBJSON Specification (Draft 9) compliant \ files, however, it can parse all UBJSON files produced by saveubjson. -------------------------------------------------------------------------------- - -V. Contribution and feedback +========================== +Contribution and feedback +========================== JSONLab is an open-source project. This means you can not only use it and modify it as you wish, but also you can contribute your changes back to JSONLab so From 604a553a45e256b96599b52bbad8fcdc9dbfa860 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:15:30 -0400 Subject: [PATCH 03/17] Update README.rst --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 1a7645d..7704098 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,7 @@ -############################################################################## - JSONLab - An open-source MATLAB/Octave JSON encoder and decoder -############################################################################## +.. ############################################################################## +.. JSONLab +.. An open-source MATLAB/Octave JSON encoder and decoder +.. ############################################################################## *Copyright (C) 2011-2017 Qianqian Fang *License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt From d887deedc52351a8b495238029d66113143dc429 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:16:24 -0400 Subject: [PATCH 04/17] Update README.rst --- README.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 7704098..d020921 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,6 @@ -.. ############################################################################## -.. JSONLab -.. An open-source MATLAB/Octave JSON encoder and decoder -.. ############################################################################## +############################################################################## + JSONLab: An open-source MATLAB/Octave JSON encoder and decoder +############################################################################## *Copyright (C) 2011-2017 Qianqian Fang *License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt From f84371cf2ce2197686c1d4e018518b40e3b3d3d1 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:16:38 -0400 Subject: [PATCH 05/17] Update README.rst --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index d020921..9af1c67 100644 --- a/README.rst +++ b/README.rst @@ -2,9 +2,9 @@ JSONLab: An open-source MATLAB/Octave JSON encoder and decoder ############################################################################## -*Copyright (C) 2011-2017 Qianqian Fang -*License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt -*Version: 1.5 (Nominus - alpha) +* Copyright (C) 2011-2017 Qianqian Fang +* License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt +* Version: 1.5 (Nominus - alpha) Table of Content: From 51c90802523ade40e144d417a61525b50e890bf7 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:17:45 -0400 Subject: [PATCH 06/17] Update README.rst --- README.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index 9af1c67..2d3295f 100644 --- a/README.rst +++ b/README.rst @@ -7,13 +7,12 @@ * Version: 1.5 (Nominus - alpha) -Table of Content: - -I. Introduction -II. Installation -III.Using JSONLab -IV. Known Issues and TODOs -V. Contribution and feedback +################# +Table of Contents +################# +.. contents:: + :local: + :depth: 3 ============ Introduction From 8bcf2da02c5781507dd08395f04f8811ac94d6ce Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:20:50 -0400 Subject: [PATCH 07/17] Update README.rst --- README.rst | 127 ++++++++++++++++++++++++++++------------------------- 1 file changed, 66 insertions(+), 61 deletions(-) diff --git a/README.rst b/README.rst index 2d3295f..7bcc5a1 100644 --- a/README.rst +++ b/README.rst @@ -48,7 +48,7 @@ data structure. JSONLab supports both MATLAB and [http://www.gnu.org/software/octave/ GNU Octave] (a free MATLAB clone). ================ -II. Installation +Installation ================ The installation of JSONLab is no different than any other simple @@ -73,66 +73,71 @@ and savejson.m -- a MATLAB->JSON encoder, for the text-based JSON, and two equivallent functions -- loadubjson and saveubjson for the binary JSON. The detailed help info for the four functions can be found below: -=== loadjson.m === -
-  data=loadjson(fname,opt)
-     or
-  data=loadjson(fname,'param1',value1,'param2',value2,...)
- 
-  parse a JSON (JavaScript Object Notation) file or string
- 
-  authors:Qianqian Fang (q.fang  neu.edu)
-  created on 2011/09/09, including previous works from 
- 
-          Nedialko Krouchev: http://www.mathworks.com/matlabcentral/fileexchange/25713
-             created on 2009/11/02
-          François Glineur: http://www.mathworks.com/matlabcentral/fileexchange/23393
-             created on  2009/03/22
-          Joel Feenstra:
-          http://www.mathworks.com/matlabcentral/fileexchange/20565
-             created on 2008/07/03
- 
-  $Id$
- 
-  input:
-       fname: input file name, if fname contains "{}" or "[]", fname
-              will be interpreted as a JSON string
-       opt: a struct to store parsing options, opt can be replaced by 
-            a list of ('param',value) pairs - the param string is equivallent
-            to a field in opt. opt can have the following 
-            fields (first in [.|.] is the default)
- 
-            opt.SimplifyCell [0|1]: if set to 1, loadjson will call cell2mat
-                          for each element of the JSON data, and group 
-                          arrays based on the cell2mat rules.
-            opt.FastArrayParser [1|0 or integer]: if set to 1, use a
-                          speed-optimized array parser when loading an 
-                          array object. The fast array parser may 
-                          collapse block arrays into a single large
-                          array similar to rules defined in cell2mat; 0 to 
-                          use a legacy parser; if set to a larger-than-1
-                          value, this option will specify the minimum
-                          dimension to enable the fast array parser. For
-                          example, if the input is a 3D array, setting
-                          FastArrayParser to 1 will return a 3D array;
-                          setting to 2 will return a cell array of 2D
-                          arrays; setting to 3 will return to a 2D cell
-                          array of 1D vectors; setting to 4 will return a
-                          3D cell array.
-            opt.ShowProgress [0|1]: if set to 1, loadjson displays a progress bar.
- 
-  output:
-       dat: a cell array, where {...} blocks are converted into cell arrays,
-            and [...] are converted to arrays
- 
-  examples:
-       dat=loadjson('{"obj":{"string":"value","array":[1,2,3]}}')
-       dat=loadjson(['examples' filesep 'example1.json'])
-       dat=loadjson(['examples' filesep 'example1.json'],'SimplifyCell',1)
- 
-  license:
-      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
-
+---------- +loadjson.m +---------- + +.. code-block:: matlab + + 
+        data=loadjson(fname,opt)
+           or
+        data=loadjson(fname,'param1',value1,'param2',value2,...)
+
+        parse a JSON (JavaScript Object Notation) file or string
+
+        authors:Qianqian Fang (q.fang  neu.edu)
+        created on 2011/09/09, including previous works from 
+
+                Nedialko Krouchev: http://www.mathworks.com/matlabcentral/fileexchange/25713
+                   created on 2009/11/02
+                François Glineur: http://www.mathworks.com/matlabcentral/fileexchange/23393
+                   created on  2009/03/22
+                Joel Feenstra:
+                http://www.mathworks.com/matlabcentral/fileexchange/20565
+                   created on 2008/07/03
+
+        $Id$
+
+        input:
+             fname: input file name, if fname contains "{}" or "[]", fname
+                    will be interpreted as a JSON string
+             opt: a struct to store parsing options, opt can be replaced by 
+                  a list of ('param',value) pairs - the param string is equivallent
+                  to a field in opt. opt can have the following 
+                  fields (first in [.|.] is the default)
+
+                  opt.SimplifyCell [0|1]: if set to 1, loadjson will call cell2mat
+                                for each element of the JSON data, and group 
+                                arrays based on the cell2mat rules.
+                  opt.FastArrayParser [1|0 or integer]: if set to 1, use a
+                                speed-optimized array parser when loading an 
+                                array object. The fast array parser may 
+                                collapse block arrays into a single large
+                                array similar to rules defined in cell2mat; 0 to 
+                                use a legacy parser; if set to a larger-than-1
+                                value, this option will specify the minimum
+                                dimension to enable the fast array parser. For
+                                example, if the input is a 3D array, setting
+                                FastArrayParser to 1 will return a 3D array;
+                                setting to 2 will return a cell array of 2D
+                                arrays; setting to 3 will return to a 2D cell
+                                array of 1D vectors; setting to 4 will return a
+                                3D cell array.
+                  opt.ShowProgress [0|1]: if set to 1, loadjson displays a progress bar.
+
+        output:
+             dat: a cell array, where {...} blocks are converted into cell arrays,
+                  and [...] are converted to arrays
+
+        examples:
+             dat=loadjson('{"obj":{"string":"value","array":[1,2,3]}}')
+             dat=loadjson(['examples' filesep 'example1.json'])
+             dat=loadjson(['examples' filesep 'example1.json'],'SimplifyCell',1)
+
+        license:
+            BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+
=== savejson.m === From 285c10e59d6aadb623678b354c5e5c060f611f8e Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:21:28 -0400 Subject: [PATCH 08/17] Update README.rst --- README.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.rst b/README.rst index 7bcc5a1..9282524 100644 --- a/README.rst +++ b/README.rst @@ -56,6 +56,8 @@ MATLAB toolbox. You only need to download/unzip the JSONLab package to a folder, and add the folder's path to MATLAB/Octave's path list by using the following command: +.. bash:: shell + addpath('/path/to/jsonlab'); If you want to add this path permanently, you need to type "pathtool", From 6e762e7f47779ec728f18fba2bbd6a56a2959077 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:24:41 -0400 Subject: [PATCH 09/17] Update README.rst --- README.rst | 462 ++++++++++++++++++++++++++++------------------------- 1 file changed, 244 insertions(+), 218 deletions(-) diff --git a/README.rst b/README.rst index 9282524..f8dda1a 100644 --- a/README.rst +++ b/README.rst @@ -56,7 +56,7 @@ MATLAB toolbox. You only need to download/unzip the JSONLab package to a folder, and add the folder's path to MATLAB/Octave's path list by using the following command: -.. bash:: shell +.. code:: shell addpath('/path/to/jsonlab'); @@ -141,226 +141,241 @@ loadjson.m BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details -=== savejson.m === +---------- +savejson.m +---------- -
-  json=savejson(rootname,obj,filename)
-     or
-  json=savejson(rootname,obj,opt)
-  json=savejson(rootname,obj,'param1',value1,'param2',value2,...)
- 
-  convert a MATLAB object (cell, struct or array) into a JSON (JavaScript
-  Object Notation) string
- 
-  author: Qianqian Fang (q.fang  neu.edu)
-  created on 2011/09/09
- 
-  $Id$
- 
-  input:
-       rootname: the name of the root-object, when set to '', the root name
-         is ignored, however, when opt.ForceRootName is set to 1 (see below),
-         the MATLAB variable name will be used as the root name.
-       obj: a MATLAB object (array, cell, cell array, struct, struct array,
-       class instance).
-       filename: a string for the file name to save the output JSON data.
-       opt: a struct for additional options, ignore to use default values.
-         opt can have the following fields (first in [.|.] is the default)
- 
-         opt.FileName [''|string]: a file name to save the output JSON data
-         opt.FloatFormat ['%.10g'|string]: format to show each numeric element
-                          of a 1D/2D array;
-         opt.ArrayIndent [1|0]: if 1, output explicit data array with
-                          precedent indentation; if 0, no indentation
-         opt.ArrayToStruct[0|1]: when set to 0, savejson outputs 1D/2D
-                          array in JSON array format; if sets to 1, an
-                          array will be shown as a struct with fields
-                          "_ArrayType_", "_ArraySize_" and "_ArrayData_"; for
-                          sparse arrays, the non-zero elements will be
-                          saved to _ArrayData_ field in triplet-format i.e.
-                          (ix,iy,val) and "_ArrayIsSparse_" will be added
-                          with a value of 1; for a complex array, the 
-                          _ArrayData_ array will include two columns 
-                          (4 for sparse) to record the real and imaginary 
-                          parts, and also "_ArrayIsComplex_":1 is added. 
-         opt.ParseLogical [0|1]: if this is set to 1, logical array elem
-                          will use true/false rather than 1/0.
-         opt.SingletArray [0|1]: if this is set to 1, arrays with a single
-                          numerical element will be shown without a square
-                          bracket, unless it is the root object; if 0, square
-                          brackets are forced for any numerical arrays.
-         opt.SingletCell  [1|0]: if 1, always enclose a cell with "[]" 
-                          even it has only one element; if 0, brackets
-                          are ignored when a cell has only 1 element.
-         opt.ForceRootName [0|1]: when set to 1 and rootname is empty, savejson
-                          will use the name of the passed obj variable as the 
-                          root object name; if obj is an expression and 
-                          does not have a name, 'root' will be used; if this 
-                          is set to 0 and rootname is empty, the root level 
-                          will be merged down to the lower level.
-         opt.Inf ['"$1_Inf_"'|string]: a customized regular expression pattern
-                          to represent +/-Inf. The matched pattern is '([-+]*)Inf'
-                          and $1 represents the sign. For those who want to use
-                          1e999 to represent Inf, they can set opt.Inf to '$11e999'
-         opt.NaN ['"_NaN_"'|string]: a customized regular expression pattern
-                          to represent NaN
-         opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
-                          for example, if opt.JSONP='foo', the JSON data is
-                          wrapped inside a function call as 'foo(...);'
-         opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson 
-                          back to the string form
-         opt.SaveBinary [0|1]: 1 - save the JSON file in binary mode; 0 - text mode.
-         opt.Compact [0|1]: 1- out compact JSON format (remove all newlines and tabs)
- 
-         opt can be replaced by a list of ('param',value) pairs. The param 
-         string is equivallent to a field in opt and is case sensitive.
-  output:
-       json: a string in the JSON format (see http://json.org)
- 
-  examples:
-       jsonmesh=struct('MeshNode',[0 0 0;1 0 0;0 1 0;1 1 0;0 0 1;1 0 1;0 1 1;1 1 1],... 
-                'MeshTetra',[1 2 4 8;1 3 4 8;1 2 6 8;1 5 6 8;1 5 7 8;1 3 7 8],...
-                'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
-                           2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
-                'MeshCreator','FangQ','MeshTitle','T6 Cube',...
-                'SpecialData',[nan, inf, -inf]);
-       savejson('jmesh',jsonmesh)
-       savejson('',jsonmesh,'ArrayIndent',0,'FloatFormat','\t%.5g')
- 
-  license:
-      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
-
+.. code-block:: matlab -=== loadubjson.m === + 
+        json=savejson(rootname,obj,filename)
+           or
+        json=savejson(rootname,obj,opt)
+        json=savejson(rootname,obj,'param1',value1,'param2',value2,...)
 
-
-  data=loadubjson(fname,opt)
-     or
-  data=loadubjson(fname,'param1',value1,'param2',value2,...)
- 
-  parse a JSON (JavaScript Object Notation) file or string
- 
-  authors:Qianqian Fang (q.fang  neu.edu)
-  created on 2013/08/01
- 
-  $Id$
- 
-  input:
-       fname: input file name, if fname contains "{}" or "[]", fname
-              will be interpreted as a UBJSON string
-       opt: a struct to store parsing options, opt can be replaced by 
-            a list of ('param',value) pairs - the param string is equivallent
-            to a field in opt. opt can have the following 
-            fields (first in [.|.] is the default)
- 
-            opt.SimplifyCell [0|1]: if set to 1, loadubjson will call cell2mat
-                          for each element of the JSON data, and group 
-                          arrays based on the cell2mat rules.
-            opt.IntEndian [B|L]: specify the endianness of the integer fields
-                          in the UBJSON input data. B - Big-Endian format for 
-                          integers (as required in the UBJSON specification); 
-                          L - input integer fields are in Little-Endian order.
-            opt.NameIsString [0|1]: for UBJSON Specification Draft 8 or 
-                          earlier versions (JSONLab 1.0 final or earlier), 
-                          the "name" tag is treated as a string. To load 
-                          these UBJSON data, you need to manually set this 
-                          flag to 1.
- 
-  output:
-       dat: a cell array, where {...} blocks are converted into cell arrays,
-            and [...] are converted to arrays
- 
-  examples:
-       obj=struct('string','value','array',[1 2 3]);
-       ubjdata=saveubjson('obj',obj);
-       dat=loadubjson(ubjdata)
-       dat=loadubjson(['examples' filesep 'example1.ubj'])
-       dat=loadubjson(['examples' filesep 'example1.ubj'],'SimplifyCell',1)
- 
-  license:
-      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
-

+        convert a MATLAB object (cell, struct or array) into a JSON (JavaScript
+        Object Notation) string
 
-=== saveubjson.m ===
+        author: Qianqian Fang (q.fang  neu.edu)
+        created on 2011/09/09
 
-
-  json=saveubjson(rootname,obj,filename)
-     or
-  json=saveubjson(rootname,obj,opt)
-  json=saveubjson(rootname,obj,'param1',value1,'param2',value2,...)
- 
-  convert a MATLAB object (cell, struct or array) into a Universal 
-  Binary JSON (UBJSON) binary string
- 
-  author: Qianqian Fang (q.fang  neu.edu)
-  created on 2013/08/17
- 
-  $Id$
- 
-  input:
-       rootname: the name of the root-object, when set to '', the root name
-         is ignored, however, when opt.ForceRootName is set to 1 (see below),
-         the MATLAB variable name will be used as the root name.
-       obj: a MATLAB object (array, cell, cell array, struct, struct array,
-       class instance)
-       filename: a string for the file name to save the output UBJSON data
-       opt: a struct for additional options, ignore to use default values.
-         opt can have the following fields (first in [.|.] is the default)
- 
-         opt.FileName [''|string]: a file name to save the output JSON data
-         opt.ArrayToStruct[0|1]: when set to 0, saveubjson outputs 1D/2D
-                          array in JSON array format; if sets to 1, an
-                          array will be shown as a struct with fields
-                          "_ArrayType_", "_ArraySize_" and "_ArrayData_"; for
-                          sparse arrays, the non-zero elements will be
-                          saved to _ArrayData_ field in triplet-format i.e.
-                          (ix,iy,val) and "_ArrayIsSparse_" will be added
-                          with a value of 1; for a complex array, the 
-                          _ArrayData_ array will include two columns 
-                          (4 for sparse) to record the real and imaginary 
-                          parts, and also "_ArrayIsComplex_":1 is added. 
-         opt.ParseLogical [1|0]: if this is set to 1, logical array elem
-                          will use true/false rather than 1/0.
-         opt.SingletArray [0|1]: if this is set to 1, arrays with a single
-                          numerical element will be shown without a square
-                          bracket, unless it is the root object; if 0, square
-                          brackets are forced for any numerical arrays.
-         opt.SingletCell  [1|0]: if 1, always enclose a cell with "[]" 
-                          even it has only one element; if 0, brackets
-                          are ignored when a cell has only 1 element.
-         opt.ForceRootName [0|1]: when set to 1 and rootname is empty, saveubjson
-                          will use the name of the passed obj variable as the 
-                          root object name; if obj is an expression and 
-                          does not have a name, 'root' will be used; if this 
-                          is set to 0 and rootname is empty, the root level 
-                          will be merged down to the lower level.
-         opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
-                          for example, if opt.JSON='foo', the JSON data is
-                          wrapped inside a function call as 'foo(...);'
-         opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson 
-                          back to the string form
- 
-         opt can be replaced by a list of ('param',value) pairs. The param 
-         string is equivallent to a field in opt and is case sensitive.
-  output:
-       json: a binary string in the UBJSON format (see http://ubjson.org)
- 
-  examples:
-       jsonmesh=struct('MeshNode',[0 0 0;1 0 0;0 1 0;1 1 0;0 0 1;1 0 1;0 1 1;1 1 1],... 
-                'MeshTetra',[1 2 4 8;1 3 4 8;1 2 6 8;1 5 6 8;1 5 7 8;1 3 7 8],...
-                'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
-                           2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
-                'MeshCreator','FangQ','MeshTitle','T6 Cube',...
-                'SpecialData',[nan, inf, -inf]);
-       saveubjson('jsonmesh',jsonmesh)
-       saveubjson('jsonmesh',jsonmesh,'meshdata.ubj')
- 
-  license:
-      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
-

+        $Id$
+
+        input:
+             rootname: the name of the root-object, when set to '', the root name
+               is ignored, however, when opt.ForceRootName is set to 1 (see below),
+               the MATLAB variable name will be used as the root name.
+             obj: a MATLAB object (array, cell, cell array, struct, struct array,
+             class instance).
+             filename: a string for the file name to save the output JSON data.
+             opt: a struct for additional options, ignore to use default values.
+               opt can have the following fields (first in [.|.] is the default)
+
+               opt.FileName [''|string]: a file name to save the output JSON data
+               opt.FloatFormat ['%.10g'|string]: format to show each numeric element
+                                of a 1D/2D array;
+               opt.ArrayIndent [1|0]: if 1, output explicit data array with
+                                precedent indentation; if 0, no indentation
+               opt.ArrayToStruct[0|1]: when set to 0, savejson outputs 1D/2D
+                                array in JSON array format; if sets to 1, an
+                                array will be shown as a struct with fields
+                                "_ArrayType_", "_ArraySize_" and "_ArrayData_"; for
+                                sparse arrays, the non-zero elements will be
+                                saved to _ArrayData_ field in triplet-format i.e.
+                                (ix,iy,val) and "_ArrayIsSparse_" will be added
+                                with a value of 1; for a complex array, the 
+                                _ArrayData_ array will include two columns 
+                                (4 for sparse) to record the real and imaginary 
+                                parts, and also "_ArrayIsComplex_":1 is added. 
+               opt.ParseLogical [0|1]: if this is set to 1, logical array elem
+                                will use true/false rather than 1/0.
+               opt.SingletArray [0|1]: if this is set to 1, arrays with a single
+                                numerical element will be shown without a square
+                                bracket, unless it is the root object; if 0, square
+                                brackets are forced for any numerical arrays.
+               opt.SingletCell  [1|0]: if 1, always enclose a cell with "[]" 
+                                even it has only one element; if 0, brackets
+                                are ignored when a cell has only 1 element.
+               opt.ForceRootName [0|1]: when set to 1 and rootname is empty, savejson
+                                will use the name of the passed obj variable as the 
+                                root object name; if obj is an expression and 
+                                does not have a name, 'root' will be used; if this 
+                                is set to 0 and rootname is empty, the root level 
+                                will be merged down to the lower level.
+               opt.Inf ['"$1_Inf_"'|string]: a customized regular expression pattern
+                                to represent +/-Inf. The matched pattern is '([-+]*)Inf'
+                                and $1 represents the sign. For those who want to use
+                                1e999 to represent Inf, they can set opt.Inf to '$11e999'
+               opt.NaN ['"_NaN_"'|string]: a customized regular expression pattern
+                                to represent NaN
+               opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
+                                for example, if opt.JSONP='foo', the JSON data is
+                                wrapped inside a function call as 'foo(...);'
+               opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson 
+                                back to the string form
+               opt.SaveBinary [0|1]: 1 - save the JSON file in binary mode; 0 - text mode.
+               opt.Compact [0|1]: 1- out compact JSON format (remove all newlines and tabs)
+
+               opt can be replaced by a list of ('param',value) pairs. The param 
+               string is equivallent to a field in opt and is case sensitive.
+        output:
+             json: a string in the JSON format (see http://json.org)
+
+        examples:
+             jsonmesh=struct('MeshNode',[0 0 0;1 0 0;0 1 0;1 1 0;0 0 1;1 0 1;0 1 1;1 1 1],... 
+                      'MeshTetra',[1 2 4 8;1 3 4 8;1 2 6 8;1 5 6 8;1 5 7 8;1 3 7 8],...
+                      'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
+                                 2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
+                      'MeshCreator','FangQ','MeshTitle','T6 Cube',...
+                      'SpecialData',[nan, inf, -inf]);
+             savejson('jmesh',jsonmesh)
+             savejson('',jsonmesh,'ArrayIndent',0,'FloatFormat','\t%.5g')
+
+        license:
+            BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
+
+ +------------- +loadubjson.m +------------- + +.. code-block:: matlab + + 
+        data=loadubjson(fname,opt)
+           or
+        data=loadubjson(fname,'param1',value1,'param2',value2,...)
+
+        parse a JSON (JavaScript Object Notation) file or string
+
+        authors:Qianqian Fang (q.fang  neu.edu)
+        created on 2013/08/01
+
+        $Id$
+
+        input:
+             fname: input file name, if fname contains "{}" or "[]", fname
+                    will be interpreted as a UBJSON string
+             opt: a struct to store parsing options, opt can be replaced by 
+                  a list of ('param',value) pairs - the param string is equivallent
+                  to a field in opt. opt can have the following 
+                  fields (first in [.|.] is the default)
+
+                  opt.SimplifyCell [0|1]: if set to 1, loadubjson will call cell2mat
+                                for each element of the JSON data, and group 
+                                arrays based on the cell2mat rules.
+                  opt.IntEndian [B|L]: specify the endianness of the integer fields
+                                in the UBJSON input data. B - Big-Endian format for 
+                                integers (as required in the UBJSON specification); 
+                                L - input integer fields are in Little-Endian order.
+                  opt.NameIsString [0|1]: for UBJSON Specification Draft 8 or 
+                                earlier versions (JSONLab 1.0 final or earlier), 
+                                the "name" tag is treated as a string. To load 
+                                these UBJSON data, you need to manually set this 
+                                flag to 1.
+
+        output:
+             dat: a cell array, where {...} blocks are converted into cell arrays,
+                  and [...] are converted to arrays
+
+        examples:
+             obj=struct('string','value','array',[1 2 3]);
+             ubjdata=saveubjson('obj',obj);
+             dat=loadubjson(ubjdata)
+             dat=loadubjson(['examples' filesep 'example1.ubj'])
+             dat=loadubjson(['examples' filesep 'example1.ubj'],'SimplifyCell',1)
+
+        license:
+            BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+
+ +------------- +saveubjson.m +------------- -=== examples === +.. code-block:: matlab + + + 
+        json=saveubjson(rootname,obj,filename)
+           or
+        json=saveubjson(rootname,obj,opt)
+        json=saveubjson(rootname,obj,'param1',value1,'param2',value2,...)
+
+        convert a MATLAB object (cell, struct or array) into a Universal 
+        Binary JSON (UBJSON) binary string
+
+        author: Qianqian Fang (q.fang  neu.edu)
+        created on 2013/08/17
+
+        $Id$
+
+        input:
+             rootname: the name of the root-object, when set to '', the root name
+               is ignored, however, when opt.ForceRootName is set to 1 (see below),
+               the MATLAB variable name will be used as the root name.
+             obj: a MATLAB object (array, cell, cell array, struct, struct array,
+             class instance)
+             filename: a string for the file name to save the output UBJSON data
+             opt: a struct for additional options, ignore to use default values.
+               opt can have the following fields (first in [.|.] is the default)
+
+               opt.FileName [''|string]: a file name to save the output JSON data
+               opt.ArrayToStruct[0|1]: when set to 0, saveubjson outputs 1D/2D
+                                array in JSON array format; if sets to 1, an
+                                array will be shown as a struct with fields
+                                "_ArrayType_", "_ArraySize_" and "_ArrayData_"; for
+                                sparse arrays, the non-zero elements will be
+                                saved to _ArrayData_ field in triplet-format i.e.
+                                (ix,iy,val) and "_ArrayIsSparse_" will be added
+                                with a value of 1; for a complex array, the 
+                                _ArrayData_ array will include two columns 
+                                (4 for sparse) to record the real and imaginary 
+                                parts, and also "_ArrayIsComplex_":1 is added. 
+               opt.ParseLogical [1|0]: if this is set to 1, logical array elem
+                                will use true/false rather than 1/0.
+               opt.SingletArray [0|1]: if this is set to 1, arrays with a single
+                                numerical element will be shown without a square
+                                bracket, unless it is the root object; if 0, square
+                                brackets are forced for any numerical arrays.
+               opt.SingletCell  [1|0]: if 1, always enclose a cell with "[]" 
+                                even it has only one element; if 0, brackets
+                                are ignored when a cell has only 1 element.
+               opt.ForceRootName [0|1]: when set to 1 and rootname is empty, saveubjson
+                                will use the name of the passed obj variable as the 
+                                root object name; if obj is an expression and 
+                                does not have a name, 'root' will be used; if this 
+                                is set to 0 and rootname is empty, the root level 
+                                will be merged down to the lower level.
+               opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
+                                for example, if opt.JSON='foo', the JSON data is
+                                wrapped inside a function call as 'foo(...);'
+               opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson 
+                                back to the string form
+
+               opt can be replaced by a list of ('param',value) pairs. The param 
+               string is equivallent to a field in opt and is case sensitive.
+        output:
+             json: a binary string in the UBJSON format (see http://ubjson.org)
+
+        examples:
+             jsonmesh=struct('MeshNode',[0 0 0;1 0 0;0 1 0;1 1 0;0 0 1;1 0 1;0 1 1;1 1 1],... 
+                      'MeshTetra',[1 2 4 8;1 3 4 8;1 2 6 8;1 5 6 8;1 5 7 8;1 3 7 8],...
+                      'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
+                                 2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
+                      'MeshCreator','FangQ','MeshTitle','T6 Cube',...
+                      'SpecialData',[nan, inf, -inf]);
+             saveubjson('jsonmesh',jsonmesh)
+             saveubjson('jsonmesh',jsonmesh,'meshdata.ubj')
+
+        license:
+            BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
+
+ +--------- +examples +--------- Under the "examples" folder, you can find several scripts to demonstrate the basic utilities of JSONLab. Running the "demo_jsonlab_basic.m" script, you @@ -404,11 +419,17 @@ that everyone else can enjoy the improvement. For anyone who want to contribute, please download JSONLab source code from its source code repositories by using the following command: - git clone https://github.com/fangq/jsonlab.git jsonlab + +.. code:: shell + + git clone https://github.com/fangq/jsonlab.git jsonlab or browsing the github site at - https://github.com/fangq/jsonlab +.. code:: shell + + https://github.com/fangq/jsonlab + alternatively, if you prefer svn, you can checkout the latest code by using @@ -418,11 +439,16 @@ You can make changes to the files as needed. Once you are satisfied with your changes, and ready to share it with others, please cd the root directory of JSONLab, and type - git diff --no-prefix > yourname_featurename.patch +.. code:: shell + + git diff --no-prefix > yourname_featurename.patch + or - svn diff > yourname_featurename.patch +.. code:: shell + + svn diff > yourname_featurename.patch You then email the .patch file to JSONLab's maintainer, Qianqian Fang, at the email address shown in the beginning of this file. Qianqian will review From 10a5ac07c0652b0e72648f54e8efcd347e595009 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 19:25:47 -0400 Subject: [PATCH 10/17] Update README.rst --- README.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index f8dda1a..39c6b4f 100644 --- a/README.rst +++ b/README.rst @@ -433,7 +433,9 @@ or browsing the github site at alternatively, if you prefer svn, you can checkout the latest code by using - svn checkout svn://svn.code.sf.net/p/iso2mesh/code/trunk/jsonlab jsonlab +.. code:: shell + + svn checkout svn://svn.code.sf.net/p/iso2mesh/code/trunk/jsonlab jsonlab You can make changes to the files as needed. Once you are satisfied with your changes, and ready to share it with others, please cd the root directory of From d94802348c64b17840d463ff338f2d1a725c91cc Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 22:49:57 -0400 Subject: [PATCH 11/17] Update README.rst --- README.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 39c6b4f..3da4f5a 100644 --- a/README.rst +++ b/README.rst @@ -18,13 +18,13 @@ Table of Contents Introduction ============ -JSON ([http://www.json.org/ JavaScript Object Notation]) is a highly portable, -human-readable and "[http://en.wikipedia.org/wiki/JSON fat-free]" text format +JSON (`JavaScript Object Notation `_) is a highly portable, +human-readable and " `fat-free `_" text format to represent complex and hierarchical data. It is as powerful as -[http://en.wikipedia.org/wiki/XML XML], but less verbose. JSON format is widely + `XML`_, but less verbose. JSON format is widely used for data-exchange in applications, and is essential for the wild success -of [http://en.wikipedia.org/wiki/Ajax_(programming) Ajax] and -[http://en.wikipedia.org/wiki/Web_2.0 Web2.0]. +of (programming) `Ajax`_ and + `Web2.0`_. UBJSON (Universal Binary JSON) is a binary JSON format, specifically optimized for compact file size and better performance while keeping From 441b81767149c8a955961940e1173714e6840e5c Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 22:50:35 -0400 Subject: [PATCH 12/17] Update README.rst --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 3da4f5a..5e04ef6 100644 --- a/README.rst +++ b/README.rst @@ -21,10 +21,10 @@ Introduction JSON (`JavaScript Object Notation `_) is a highly portable, human-readable and " `fat-free `_" text format to represent complex and hierarchical data. It is as powerful as - `XML`_, but less verbose. JSON format is widely + `XML `_, but less verbose. JSON format is widely used for data-exchange in applications, and is essential for the wild success -of (programming) `Ajax`_ and - `Web2.0`_. +of (programming) `Ajax `_ and + `Web2.0 `_. UBJSON (Universal Binary JSON) is a binary JSON format, specifically optimized for compact file size and better performance while keeping From 530a3b50a8b2865fbd80827e0e4523e9cd5135be Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 22:51:13 -0400 Subject: [PATCH 13/17] Update README.rst --- README.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 5e04ef6..6cae4bd 100644 --- a/README.rst +++ b/README.rst @@ -20,11 +20,8 @@ Introduction JSON (`JavaScript Object Notation `_) is a highly portable, human-readable and " `fat-free `_" text format -to represent complex and hierarchical data. It is as powerful as - `XML `_, but less verbose. JSON format is widely -used for data-exchange in applications, and is essential for the wild success -of (programming) `Ajax `_ and - `Web2.0 `_. +to represent complex and hierarchical data. It is as powerful as `XML `_, but less verbose. JSON format is widely used for data-exchange in applications, and is essential for the wild success +of (programming) `Ajax `_ and `Web2.0 `_. UBJSON (Universal Binary JSON) is a binary JSON format, specifically optimized for compact file size and better performance while keeping From f81e3951fccb2ddcfc0bad22afba4ebbdc3bbadd Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 22:52:25 -0400 Subject: [PATCH 14/17] Update README.rst --- README.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 6cae4bd..18b8b24 100644 --- a/README.rst +++ b/README.rst @@ -34,15 +34,14 @@ We envision that both JSON and its binary version will serve as part of the mainstream data-exchange formats for scientific research in the future. It will provide the flexibility and generality achieved by other popular general-purpose file specifications, such as -[http://www.hdfgroup.org/HDF5/whatishdf5.html HDF5], with significantly + `HDF5 `_, with significantly reduced complexity and enhanced performance. JSONLab is a free and open-source implementation of a JSON/UBJSON encoder and a decoder in the native MATLAB language. It can be used to convert a MATLAB data structure (array, struct, cell, struct array and cell array) into JSON/UBJSON formatted strings, or to decode a JSON/UBJSON file into MATLAB -data structure. JSONLab supports both MATLAB and -[http://www.gnu.org/software/octave/ GNU Octave] (a free MATLAB clone). +data structure. JSONLab supports both MATLAB and `GNU Octave `_ (a free MATLAB clone). ================ Installation From fee91ff80c17e134a7aefe7b8d62a06d52243944 Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 22:52:48 -0400 Subject: [PATCH 15/17] Update README.rst --- README.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 18b8b24..1af80f9 100644 --- a/README.rst +++ b/README.rst @@ -33,8 +33,7 @@ without accuracy loss due to text conversions. We envision that both JSON and its binary version will serve as part of the mainstream data-exchange formats for scientific research in the future. It will provide the flexibility and generality achieved by other popular -general-purpose file specifications, such as - `HDF5 `_, with significantly +general-purpose file specifications, such as `HDF5 `_, with significantly reduced complexity and enhanced performance. JSONLab is a free and open-source implementation of a JSON/UBJSON encoder From 8eb39599276c86396f75e90a9ba690bbb0c05e5d Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 22:55:35 -0400 Subject: [PATCH 16/17] Update README.rst --- README.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/README.rst b/README.rst index 1af80f9..ca3c721 100644 --- a/README.rst +++ b/README.rst @@ -372,12 +372,12 @@ saveubjson.m examples --------- -Under the "examples" folder, you can find several scripts to demonstrate the -basic utilities of JSONLab. Running the "demo_jsonlab_basic.m" script, you +Under the ``"examples"`` folder, you can find several scripts to demonstrate the +basic utilities of JSONLab. Running the ``"demo_jsonlab_basic.m"`` script, you will see the conversions from MATLAB data structure to JSON text and backward. -In "jsonlab_selftest.m", we load complex JSON files downloaded from the Internet -and validate the loadjson/savejson functions for regression testing purposes. -Similarly, a "demo_ubjson_basic.m" script is provided to test the saveubjson +In ``"jsonlab_selftest.m"``, we load complex JSON files downloaded from the Internet +and validate the ``loadjson/savejson`` functions for regression testing purposes. +Similarly, a ``"demo_ubjson_basic.m"`` script is provided to test the saveubjson and loadubjson functions for various matlab data structures. Please run these examples and understand how JSONLab works before you use @@ -392,17 +392,17 @@ and robust. Hopefully in a few future releases, the limitations become less. Here are the known issues: -# 3D or higher dimensional cell/struct-arrays will be converted to 2D arrays; -# When processing names containing multi-byte characters, Octave and MATLAB \ -can give different field-names; you can use feature('DefaultCharacterSet','latin1') \ -in MATLAB to get consistant results -# savejson can not handle class and dataset. -# saveubjson converts a logical array into a uint8 ([U]) array -# an unofficial N-D array count syntax is implemented in saveubjson. We are \ -actively communicating with the UBJSON spec maintainer to investigate the \ -possibility of making it upstream -# loadubjson can not parse all UBJSON Specification (Draft 9) compliant \ -files, however, it can parse all UBJSON files produced by saveubjson. + * 3D or higher dimensional cell/struct-arrays will be converted to 2D arrays + + * When processing names containing multi-byte characters, Octave and MATLAB can give different field-names; you can use feature('DefaultCharacterSet','latin1') in MATLAB to get consistant results + + * savejson can not handle class and dataset. + + * saveubjson converts a logical array into a uint8 ([U]) array + + * an unofficial N-D array count syntax is implemented in saveubjson. We are actively communicating with the UBJSON spec maintainer to investigate the possibility of making it upstream + + * loadubjson can not parse all UBJSON Specification (Draft 9) compliant files, however, it can parse all UBJSON files produced by saveubjson. ========================== Contribution and feedback @@ -454,6 +454,6 @@ the changes and commit it to the subversion if they are satisfactory. We appreciate any suggestions and feedbacks from you. Please use the following mailing list to report any questions you may have regarding JSONLab: -https://groups.google.com/forum/?hl=en#!forum/jsonlab-users +`forum/jsonlab-users `_ (Subscription to the mailing list is needed in order to post messages). From 3176d44cdecc9fab9ba64269ee6c70a9668fd17f Mon Sep 17 00:00:00 2001 From: Amirsina Torfi Date: Mon, 17 Jul 2017 22:57:27 -0400 Subject: [PATCH 17/17] Add files via upload --- README.txt | 431 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 431 insertions(+) create mode 100644 README.txt diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..3f537ba --- /dev/null +++ b/README.txt @@ -0,0 +1,431 @@ +=============================================================================== += JSONLab = += An open-source MATLAB/Octave JSON encoder and decoder = +=============================================================================== + +*Copyright (C) 2011-2017 Qianqian Fang +*License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt +*Version: 1.5 (Nominus - alpha) + +------------------------------------------------------------------------------- + +Table of Content: + +I. Introduction +II. Installation +III.Using JSONLab +IV. Known Issues and TODOs +V. Contribution and feedback + +------------------------------------------------------------------------------- + +I. Introduction + +JSON ([http://www.json.org/ JavaScript Object Notation]) is a highly portable, +human-readable and "[http://en.wikipedia.org/wiki/JSON fat-free]" text format +to represent complex and hierarchical data. It is as powerful as +[http://en.wikipedia.org/wiki/XML XML], but less verbose. JSON format is widely +used for data-exchange in applications, and is essential for the wild success +of [http://en.wikipedia.org/wiki/Ajax_(programming) Ajax] and +[http://en.wikipedia.org/wiki/Web_2.0 Web2.0]. + +UBJSON (Universal Binary JSON) is a binary JSON format, specifically +optimized for compact file size and better performance while keeping +the semantics as simple as the text-based JSON format. Using the UBJSON +format allows to wrap complex binary data in a flexible and extensible +structure, making it possible to process complex and large dataset +without accuracy loss due to text conversions. + +We envision that both JSON and its binary version will serve as part of +the mainstream data-exchange formats for scientific research in the future. +It will provide the flexibility and generality achieved by other popular +general-purpose file specifications, such as +[http://www.hdfgroup.org/HDF5/whatishdf5.html HDF5], with significantly +reduced complexity and enhanced performance. + +JSONLab is a free and open-source implementation of a JSON/UBJSON encoder +and a decoder in the native MATLAB language. It can be used to convert a MATLAB +data structure (array, struct, cell, struct array and cell array) into +JSON/UBJSON formatted strings, or to decode a JSON/UBJSON file into MATLAB +data structure. JSONLab supports both MATLAB and +[http://www.gnu.org/software/octave/ GNU Octave] (a free MATLAB clone). + +------------------------------------------------------------------------------- + +II. Installation + +The installation of JSONLab is no different than any other simple +MATLAB toolbox. You only need to download/unzip the JSONLab package +to a folder, and add the folder's path to MATLAB/Octave's path list +by using the following command: + + addpath('/path/to/jsonlab'); + +If you want to add this path permanently, you need to type "pathtool", +browse to the jsonlab root folder and add to the list, then click "Save". +Then, run "rehash" in MATLAB, and type "which loadjson", if you see an +output, that means JSONLab is installed for MATLAB/Octave. + +------------------------------------------------------------------------------- + +III.Using JSONLab + +JSONLab provides two functions, loadjson.m -- a MATLAB->JSON decoder, +and savejson.m -- a MATLAB->JSON encoder, for the text-based JSON, and +two equivallent functions -- loadubjson and saveubjson for the binary +JSON. The detailed help info for the four functions can be found below: + +=== loadjson.m === +
+  data=loadjson(fname,opt)
+     or
+  data=loadjson(fname,'param1',value1,'param2',value2,...)
+ 
+  parse a JSON (JavaScript Object Notation) file or string
+ 
+  authors:Qianqian Fang (q.fang  neu.edu)
+  created on 2011/09/09, including previous works from 
+ 
+          Nedialko Krouchev: http://www.mathworks.com/matlabcentral/fileexchange/25713
+             created on 2009/11/02
+          Fran�ois Glineur: http://www.mathworks.com/matlabcentral/fileexchange/23393
+             created on  2009/03/22
+          Joel Feenstra:
+          http://www.mathworks.com/matlabcentral/fileexchange/20565
+             created on 2008/07/03
+ 
+  $Id$
+ 
+  input:
+       fname: input file name, if fname contains "{}" or "[]", fname
+              will be interpreted as a JSON string
+       opt: a struct to store parsing options, opt can be replaced by 
+            a list of ('param',value) pairs - the param string is equivallent
+            to a field in opt. opt can have the following 
+            fields (first in [.|.] is the default)
+ 
+            opt.SimplifyCell [0|1]: if set to 1, loadjson will call cell2mat
+                          for each element of the JSON data, and group 
+                          arrays based on the cell2mat rules.
+            opt.FastArrayParser [1|0 or integer]: if set to 1, use a
+                          speed-optimized array parser when loading an 
+                          array object. The fast array parser may 
+                          collapse block arrays into a single large
+                          array similar to rules defined in cell2mat; 0 to 
+                          use a legacy parser; if set to a larger-than-1
+                          value, this option will specify the minimum
+                          dimension to enable the fast array parser. For
+                          example, if the input is a 3D array, setting
+                          FastArrayParser to 1 will return a 3D array;
+                          setting to 2 will return a cell array of 2D
+                          arrays; setting to 3 will return to a 2D cell
+                          array of 1D vectors; setting to 4 will return a
+                          3D cell array.
+            opt.ShowProgress [0|1]: if set to 1, loadjson displays a progress bar.
+ 
+  output:
+       dat: a cell array, where {...} blocks are converted into cell arrays,
+            and [...] are converted to arrays
+ 
+  examples:
+       dat=loadjson('{"obj":{"string":"value","array":[1,2,3]}}')
+       dat=loadjson(['examples' filesep 'example1.json'])
+       dat=loadjson(['examples' filesep 'example1.json'],'SimplifyCell',1)
+ 
+  license:
+      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+
+ +=== savejson.m === + +
+  json=savejson(rootname,obj,filename)
+     or
+  json=savejson(rootname,obj,opt)
+  json=savejson(rootname,obj,'param1',value1,'param2',value2,...)
+ 
+  convert a MATLAB object (cell, struct or array) into a JSON (JavaScript
+  Object Notation) string
+ 
+  author: Qianqian Fang (q.fang  neu.edu)
+  created on 2011/09/09
+ 
+  $Id$
+ 
+  input:
+       rootname: the name of the root-object, when set to '', the root name
+         is ignored, however, when opt.ForceRootName is set to 1 (see below),
+         the MATLAB variable name will be used as the root name.
+       obj: a MATLAB object (array, cell, cell array, struct, struct array,
+       class instance).
+       filename: a string for the file name to save the output JSON data.
+       opt: a struct for additional options, ignore to use default values.
+         opt can have the following fields (first in [.|.] is the default)
+ 
+         opt.FileName [''|string]: a file name to save the output JSON data
+         opt.FloatFormat ['%.10g'|string]: format to show each numeric element
+                          of a 1D/2D array;
+         opt.ArrayIndent [1|0]: if 1, output explicit data array with
+                          precedent indentation; if 0, no indentation
+         opt.ArrayToStruct[0|1]: when set to 0, savejson outputs 1D/2D
+                          array in JSON array format; if sets to 1, an
+                          array will be shown as a struct with fields
+                          "_ArrayType_", "_ArraySize_" and "_ArrayData_"; for
+                          sparse arrays, the non-zero elements will be
+                          saved to _ArrayData_ field in triplet-format i.e.
+                          (ix,iy,val) and "_ArrayIsSparse_" will be added
+                          with a value of 1; for a complex array, the 
+                          _ArrayData_ array will include two columns 
+                          (4 for sparse) to record the real and imaginary 
+                          parts, and also "_ArrayIsComplex_":1 is added. 
+         opt.ParseLogical [0|1]: if this is set to 1, logical array elem
+                          will use true/false rather than 1/0.
+         opt.SingletArray [0|1]: if this is set to 1, arrays with a single
+                          numerical element will be shown without a square
+                          bracket, unless it is the root object; if 0, square
+                          brackets are forced for any numerical arrays.
+         opt.SingletCell  [1|0]: if 1, always enclose a cell with "[]" 
+                          even it has only one element; if 0, brackets
+                          are ignored when a cell has only 1 element.
+         opt.ForceRootName [0|1]: when set to 1 and rootname is empty, savejson
+                          will use the name of the passed obj variable as the 
+                          root object name; if obj is an expression and 
+                          does not have a name, 'root' will be used; if this 
+                          is set to 0 and rootname is empty, the root level 
+                          will be merged down to the lower level.
+         opt.Inf ['"$1_Inf_"'|string]: a customized regular expression pattern
+                          to represent +/-Inf. The matched pattern is '([-+]*)Inf'
+                          and $1 represents the sign. For those who want to use
+                          1e999 to represent Inf, they can set opt.Inf to '$11e999'
+         opt.NaN ['"_NaN_"'|string]: a customized regular expression pattern
+                          to represent NaN
+         opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
+                          for example, if opt.JSONP='foo', the JSON data is
+                          wrapped inside a function call as 'foo(...);'
+         opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson 
+                          back to the string form
+         opt.SaveBinary [0|1]: 1 - save the JSON file in binary mode; 0 - text mode.
+         opt.Compact [0|1]: 1- out compact JSON format (remove all newlines and tabs)
+ 
+         opt can be replaced by a list of ('param',value) pairs. The param 
+         string is equivallent to a field in opt and is case sensitive.
+  output:
+       json: a string in the JSON format (see http://json.org)
+ 
+  examples:
+       jsonmesh=struct('MeshNode',[0 0 0;1 0 0;0 1 0;1 1 0;0 0 1;1 0 1;0 1 1;1 1 1],... 
+                'MeshTetra',[1 2 4 8;1 3 4 8;1 2 6 8;1 5 6 8;1 5 7 8;1 3 7 8],...
+                'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
+                           2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
+                'MeshCreator','FangQ','MeshTitle','T6 Cube',...
+                'SpecialData',[nan, inf, -inf]);
+       savejson('jmesh',jsonmesh)
+       savejson('',jsonmesh,'ArrayIndent',0,'FloatFormat','\t%.5g')
+ 
+  license:
+      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
+
+ +=== loadubjson.m === + +
+  data=loadubjson(fname,opt)
+     or
+  data=loadubjson(fname,'param1',value1,'param2',value2,...)
+ 
+  parse a JSON (JavaScript Object Notation) file or string
+ 
+  authors:Qianqian Fang (q.fang  neu.edu)
+  created on 2013/08/01
+ 
+  $Id$
+ 
+  input:
+       fname: input file name, if fname contains "{}" or "[]", fname
+              will be interpreted as a UBJSON string
+       opt: a struct to store parsing options, opt can be replaced by 
+            a list of ('param',value) pairs - the param string is equivallent
+            to a field in opt. opt can have the following 
+            fields (first in [.|.] is the default)
+ 
+            opt.SimplifyCell [0|1]: if set to 1, loadubjson will call cell2mat
+                          for each element of the JSON data, and group 
+                          arrays based on the cell2mat rules.
+            opt.IntEndian [B|L]: specify the endianness of the integer fields
+                          in the UBJSON input data. B - Big-Endian format for 
+                          integers (as required in the UBJSON specification); 
+                          L - input integer fields are in Little-Endian order.
+            opt.NameIsString [0|1]: for UBJSON Specification Draft 8 or 
+                          earlier versions (JSONLab 1.0 final or earlier), 
+                          the "name" tag is treated as a string. To load 
+                          these UBJSON data, you need to manually set this 
+                          flag to 1.
+ 
+  output:
+       dat: a cell array, where {...} blocks are converted into cell arrays,
+            and [...] are converted to arrays
+ 
+  examples:
+       obj=struct('string','value','array',[1 2 3]);
+       ubjdata=saveubjson('obj',obj);
+       dat=loadubjson(ubjdata)
+       dat=loadubjson(['examples' filesep 'example1.ubj'])
+       dat=loadubjson(['examples' filesep 'example1.ubj'],'SimplifyCell',1)
+ 
+  license:
+      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details 
+
+ +=== saveubjson.m === + +
+  json=saveubjson(rootname,obj,filename)
+     or
+  json=saveubjson(rootname,obj,opt)
+  json=saveubjson(rootname,obj,'param1',value1,'param2',value2,...)
+ 
+  convert a MATLAB object (cell, struct or array) into a Universal 
+  Binary JSON (UBJSON) binary string
+ 
+  author: Qianqian Fang (q.fang  neu.edu)
+  created on 2013/08/17
+ 
+  $Id$
+ 
+  input:
+       rootname: the name of the root-object, when set to '', the root name
+         is ignored, however, when opt.ForceRootName is set to 1 (see below),
+         the MATLAB variable name will be used as the root name.
+       obj: a MATLAB object (array, cell, cell array, struct, struct array,
+       class instance)
+       filename: a string for the file name to save the output UBJSON data
+       opt: a struct for additional options, ignore to use default values.
+         opt can have the following fields (first in [.|.] is the default)
+ 
+         opt.FileName [''|string]: a file name to save the output JSON data
+         opt.ArrayToStruct[0|1]: when set to 0, saveubjson outputs 1D/2D
+                          array in JSON array format; if sets to 1, an
+                          array will be shown as a struct with fields
+                          "_ArrayType_", "_ArraySize_" and "_ArrayData_"; for
+                          sparse arrays, the non-zero elements will be
+                          saved to _ArrayData_ field in triplet-format i.e.
+                          (ix,iy,val) and "_ArrayIsSparse_" will be added
+                          with a value of 1; for a complex array, the 
+                          _ArrayData_ array will include two columns 
+                          (4 for sparse) to record the real and imaginary 
+                          parts, and also "_ArrayIsComplex_":1 is added. 
+         opt.ParseLogical [1|0]: if this is set to 1, logical array elem
+                          will use true/false rather than 1/0.
+         opt.SingletArray [0|1]: if this is set to 1, arrays with a single
+                          numerical element will be shown without a square
+                          bracket, unless it is the root object; if 0, square
+                          brackets are forced for any numerical arrays.
+         opt.SingletCell  [1|0]: if 1, always enclose a cell with "[]" 
+                          even it has only one element; if 0, brackets
+                          are ignored when a cell has only 1 element.
+         opt.ForceRootName [0|1]: when set to 1 and rootname is empty, saveubjson
+                          will use the name of the passed obj variable as the 
+                          root object name; if obj is an expression and 
+                          does not have a name, 'root' will be used; if this 
+                          is set to 0 and rootname is empty, the root level 
+                          will be merged down to the lower level.
+         opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
+                          for example, if opt.JSON='foo', the JSON data is
+                          wrapped inside a function call as 'foo(...);'
+         opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson 
+                          back to the string form
+ 
+         opt can be replaced by a list of ('param',value) pairs. The param 
+         string is equivallent to a field in opt and is case sensitive.
+  output:
+       json: a binary string in the UBJSON format (see http://ubjson.org)
+ 
+  examples:
+       jsonmesh=struct('MeshNode',[0 0 0;1 0 0;0 1 0;1 1 0;0 0 1;1 0 1;0 1 1;1 1 1],... 
+                'MeshTetra',[1 2 4 8;1 3 4 8;1 2 6 8;1 5 6 8;1 5 7 8;1 3 7 8],...
+                'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
+                           2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
+                'MeshCreator','FangQ','MeshTitle','T6 Cube',...
+                'SpecialData',[nan, inf, -inf]);
+       saveubjson('jsonmesh',jsonmesh)
+       saveubjson('jsonmesh',jsonmesh,'meshdata.ubj')
+ 
+  license:
+      BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
+
+ + +=== examples === + +Under the "examples" folder, you can find several scripts to demonstrate the +basic utilities of JSONLab. Running the "demo_jsonlab_basic.m" script, you +will see the conversions from MATLAB data structure to JSON text and backward. +In "jsonlab_selftest.m", we load complex JSON files downloaded from the Internet +and validate the loadjson/savejson functions for regression testing purposes. +Similarly, a "demo_ubjson_basic.m" script is provided to test the saveubjson +and loadubjson functions for various matlab data structures. + +Please run these examples and understand how JSONLab works before you use +it to process your data. + +------------------------------------------------------------------------------- + +IV. Known Issues and TODOs + +JSONLab has several known limitations. We are striving to make it more general +and robust. Hopefully in a few future releases, the limitations become less. + +Here are the known issues: + +# 3D or higher dimensional cell/struct-arrays will be converted to 2D arrays; +# When processing names containing multi-byte characters, Octave and MATLAB \ +can give different field-names; you can use feature('DefaultCharacterSet','latin1') \ +in MATLAB to get consistant results +# savejson can not handle class and dataset. +# saveubjson converts a logical array into a uint8 ([U]) array +# an unofficial N-D array count syntax is implemented in saveubjson. We are \ +actively communicating with the UBJSON spec maintainer to investigate the \ +possibility of making it upstream +# loadubjson can not parse all UBJSON Specification (Draft 9) compliant \ +files, however, it can parse all UBJSON files produced by saveubjson. + +------------------------------------------------------------------------------- + +V. Contribution and feedback + +JSONLab is an open-source project. This means you can not only use it and modify +it as you wish, but also you can contribute your changes back to JSONLab so +that everyone else can enjoy the improvement. For anyone who want to contribute, +please download JSONLab source code from its source code repositories by using the +following command: + + git clone https://github.com/fangq/jsonlab.git jsonlab + +or browsing the github site at + + https://github.com/fangq/jsonlab + +alternatively, if you prefer svn, you can checkout the latest code by using + + svn checkout svn://svn.code.sf.net/p/iso2mesh/code/trunk/jsonlab jsonlab + +You can make changes to the files as needed. Once you are satisfied with your +changes, and ready to share it with others, please cd the root directory of +JSONLab, and type + + git diff --no-prefix > yourname_featurename.patch + +or + + svn diff > yourname_featurename.patch + +You then email the .patch file to JSONLab's maintainer, Qianqian Fang, at +the email address shown in the beginning of this file. Qianqian will review +the changes and commit it to the subversion if they are satisfactory. + +We appreciate any suggestions and feedbacks from you. Please use the following +mailing list to report any questions you may have regarding JSONLab: + +https://groups.google.com/forum/?hl=en#!forum/jsonlab-users + +(Subscription to the mailing list is needed in order to post messages).