Showing revision 1.0

JSONlab

An open-source MATLAB/Octave JSON encoder and decoder

  • Copyright (c) 2011 Qianqian Fang <fangq at nmr.mgh.harvard.edu>
  • License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt
  • Version: 0.5 (Nexus)

Table of Content:

1. Introduction
2. Installation
3. Using JSONlab
3.1. loadjson.m
3.2. savejson.m
3.3. examples
4. Known Issues and TODOs
5. Contribution and feedback

1. 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 Ajax and Web2.0. With the fast advance of web-based technologies, We envision that JSON will serve as a mainstream data-exchange format for scientific research in the future, and fulfill part of the roles achieved by HDF5.

JSONlab is a free and open-source implementation of a JSON 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 formatted text, or to decode a JSON file into MATLAB data. JSONlab supports both MATLAB and GNU Octave (a free MATLAB clone).

2. 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 iso2mesh folder and add it 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.

3. Using JSONlab

JSONlab provides two functions, loadjson.m -- a MATLAB->JSON decoder, and savejson.m -- a MATLAB->JSON encoder. The detailed help info for the two functions can be found below:

3.1. loadjson.m

 data=loadjson(fname)

 parse a JSON (JavaScript Object Notation) file or string

 authors:Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
            date: 2011/09/09
         Nedialko Krouchev: http://www.mathworks.com/matlabcentral/fileexchange/25713
            date: 2009/11/02
         François Glineur: http://www.mathworks.com/matlabcentral/fileexchange/23393
            date: 2009/03/22
         Joel Feenstra: http://www.mathworks.com/matlabcentral/fileexchange/20565
            date: 2008/07/03

 input:
      fname: input file name, if fname contains "{}" or "[]", fname
      will be interpreted as a JSON string

 output:
      dat: a cell array, where {...} blocks are converted into cell arrays,
           and [...] are converted to arrays

3.2. savejson.m

 json=savejson(rootname,obj,opt)

 convert a MATLAB object (cell, struct or array) into a JSON (JavaScript
 Object Notation) string

 authors:Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
            date: 2011/09/09

 input:
      rootname: name of the root-object, if set to '', will use variable name
      obj: a MATLAB object (array, cell, cell array, struct, struct array)
      opt: a struct for additional options, use [] if all use default
        opt can have the following fields (first in [.|.] is the default)
        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.

 output:
      json: a string in the JSON format (see http://json.org)

 examples:
      a=struct('node',[1  9  10; 2 1 1.2], 'elem',[9 1;1 2;2 3],...
           'face',[9 01 2; 1 2 3; NaN,Inf,-Inf], 'author','FangQ');
      savejson('mesh',a)
      savejson('',a,struct('ArrayIndent',0,'FloatFormat','\t%.5g'))

3.3. 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.

Please run these examples and understand how JSONlab works before you use it to process your data.

4. Known Issues and TODOs

JSONlab has several known limitations. We are striving to make it more general and robust. Hopefully at some future releases, the limitations become less.

Here are the known issues:

  1. A 2D cell-array will be converted to a 1D array;
  2. When processing names containing multi-byte characters, Octave and MATLAB can give different field-names;
  3. Can not handle classes;
  4. Although significantly accelerated, loadjson of large JSON file may still take some time.

5. 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 to back to JSONlab so that everyone else can enjoy the improvement. For anyone who want to contribute, please download JSONlab source code from it's subversion repository by using the following command: 

 svn co https://iso2mesh.svn.sourceforge.net/svnroot/iso2mesh/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 

 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 iso2mesh's mailing list to report any questions you may have with JSONlab:

http://groups.google.com/group/iso2mesh-users?hl=en&pli=1

(Subscription to the mailing list is needed in order to post messages).

Powered by Habitat