Skip to content

Commit 0561b22

Browse files
author
fangq
committed
update documentation, ready to release JSONLab 1.0
git-svn-id: http://svn.code.sf.net/p/iso2mesh/code/trunk/jsonlab@460 786e58fb-9377-0410-9ff7-e4ac0ac0635c
1 parent 2f3f7eb commit 0561b22

File tree

6 files changed

+167
-88
lines changed

6 files changed

+167
-88
lines changed

‎ChangeLog.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@
66

77
JSONlab ChangeLog (key features marked by *):
88

9+
== JSONlab 1.0 (codename: Optimus - Final), FangQ <fangq (at) nmr.mgh.harvard.edu> ==
10+
11+
2015/01/02 polish help info for all major functions, update examples, finalize 1.0
12+
2014/12/19 fix a bug to strictly respect NoRowBracket in savejson
13+
914
== JSONlab 1.0.0-RC2 (codename: Optimus - RC2), FangQ <fangq (at) nmr.mgh.harvard.edu> ==
1015

1116
2014/11/22 show progress bar in loadjson ('ShowProgress')

‎README.txt‎

Lines changed: 91 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
===============================================================================
2-
= JSONlab =
2+
= JSONLab =
33
= An open-source MATLAB/Octave JSON encoder and decoder =
44
===============================================================================
55

6-
*Copyright (C) 2011-2014 Qianqian Fang <fangq at nmr.mgh.harvard.edu>
6+
*Copyright (C) 2011-2015 Qianqian Fang <fangq at nmr.mgh.harvard.edu>
77
*License: BSD or GNU General Public License version 3 (GPL v3), see License*.txt
8-
*Version: 1.0.0-RC2 (Optimus - RC2)
8+
*Version: 1.0 (Optimus - Final)
99

1010
-------------------------------------------------------------------------------
1111

1212
Table of Content:
1313

1414
I. Introduction
1515
II. Installation
16-
III.Using JSONlab
16+
III.Using JSONLab
1717
IV. Known Issues and TODOs
1818
V. Contribution and feedback
1919

@@ -43,19 +43,19 @@ general-purpose file specifications, such as
4343
[http://www.hdfgroup.org/HDF5/whatishdf5.html HDF5], with significantly
4444
reduced complexity and enhanced performance.
4545

46-
JSONlab is a free and open-source implementation of a JSON/UBJSON encoder
46+
JSONLab is a free and open-source implementation of a JSON/UBJSON encoder
4747
and a decoder in the native MATLAB language. It can be used to convert a MATLAB
4848
data structure (array, struct, cell, struct array and cell array) into
4949
JSON/UBJSON formatted strings, or to decode a JSON/UBJSON file into MATLAB
50-
data structure. JSONlab supports both MATLAB and
50+
data structure. JSONLab supports both MATLAB and
5151
[http://www.gnu.org/software/octave/ GNU Octave] (a free MATLAB clone).
5252

5353
-------------------------------------------------------------------------------
5454

5555
II. Installation
5656

57-
The installation of JSONlab is no different than any other simple
58-
MATLAB toolbox. You only need to download/unzip the JSONlab package
57+
The installation of JSONLab is no different than any other simple
58+
MATLAB toolbox. You only need to download/unzip the JSONLab package
5959
to a folder, and add the folder's path to MATLAB/Octave's path list
6060
by using the following command:
6161

@@ -64,13 +64,13 @@ by using the following command:
6464
If you want to add this path permanently, you need to type "pathtool",
6565
browse to the jsonlab root folder and add to the list, then click "Save".
6666
Then, run "rehash" in MATLAB, and type "which loadjson", if you see an
67-
output, that means JSONlab is installed for MATLAB/Octave.
67+
output, that means JSONLab is installed for MATLAB/Octave.
6868

6969
-------------------------------------------------------------------------------
7070

71-
III.Using JSONlab
71+
III.Using JSONLab
7272

73-
JSONlab provides two functions, loadjson.m -- a MATLAB->JSON decoder,
73+
JSONLab provides two functions, loadjson.m -- a MATLAB->JSON decoder,
7474
and savejson.m -- a MATLAB->JSON encoder, for the text-based JSON, and
7575
two equivallent functions -- loadubjson and saveubjson for the binary
7676
JSON. The detailed help info for the four functions can be found below:
@@ -84,28 +84,30 @@ JSON. The detailed help info for the four functions can be found below:
8484
parse a JSON (JavaScript Object Notation) file or string
8585

8686
authors:Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
87-
date: 2011/09/09
87+
created on 2011/09/09, including previous works from
88+
8889
Nedialko Krouchev: http://www.mathworks.com/matlabcentral/fileexchange/25713
89-
date: 2009/11/02
90+
created on 2009/11/02
9091
Fran�ois Glineur: http://www.mathworks.com/matlabcentral/fileexchange/23393
91-
date: 2009/03/22
92+
created on 2009/03/22
9293
Joel Feenstra:
9394
http://www.mathworks.com/matlabcentral/fileexchange/20565
94-
date: 2008/07/03
95+
created on 2008/07/03
9596

9697
$Id: loadjson.m 452 2014-11-22 16:43:33Z fangq $
9798

9899
input:
99100
fname: input file name, if fname contains "{}" or "[]", fname
100101
will be interpreted as a JSON string
101102
opt: a struct to store parsing options, opt can be replaced by
102-
a list of ('param',value) pairs. opt can have the following
103+
a list of ('param',value) pairs - the param string is equivallent
104+
to a field in opt. opt can have the following
103105
fields (first in [.|.] is the default)
104106

105-
opt.SimplifyCell [0|1]: if set to 1, loadjson will call cell2mat
107+
opt.SimplifyCell [0|1]: if set to 1, loadjson will call cell2mat
106108
for each element of the JSON data, and group
107109
arrays based on the cell2mat rules.
108-
opt.FastArrayParser [1|0 or integer]: if set to 1, use a
110+
opt.FastArrayParser [1|0 or integer]: if set to 1, use a
109111
speed-optimized array parser when loading an
110112
array object. The fast array parser may
111113
collapse block arrays into a single large
@@ -119,11 +121,16 @@ JSON. The detailed help info for the four functions can be found below:
119121
arrays; setting to 3 will return to a 2D cell
120122
array of 1D vectors; setting to 4 will return a
121123
3D cell array.
122-
opt.ShowProgress [0|1]: if set to 1, loadjson displays a progress bar.
124+
opt.ShowProgress [0|1]: if set to 1, loadjson displays a progress bar.
123125

124126
output:
125127
dat: a cell array, where {...} blocks are converted into cell arrays,
126128
and [...] are converted to arrays
129+
130+
examples:
131+
dat=loadjson('{"obj":{"string":"value","array":[1,2,3]}}')
132+
dat=loadjson(['examples' filesep 'example1.json'])
133+
dat=loadjson(['examples' filesep 'example1.json'],'SimplifyCell',1)
127134
</pre>
128135

129136
=== savejson.m ===
@@ -138,15 +145,17 @@ JSON. The detailed help info for the four functions can be found below:
138145
Object Notation) string
139146

140147
author: Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
141-
created on 2011/09/09
148+
created on 2011/09/09
142149

143-
$Id: savejson.m 450 2014-11-18 20:53:31Z fangq $
150+
$Id: savejson.m 458 2014-12-19 22:17:17Z fangq $
144151

145152
input:
146-
rootname: name of the root-object, if set to '', will use variable name
147-
obj: a MATLAB object (array, cell, cell array, struct, struct array)
148-
filename: a string for the file name to save the output JSON data
149-
opt: a struct for additional options, use [] if all use default
153+
rootname: the name of the root-object, when set to '', the root name
154+
is ignored, however, when opt.ForceRootName is set to 1 (see below),
155+
the MATLAB variable name will be used as the root name.
156+
obj: a MATLAB object (array, cell, cell array, struct, struct array).
157+
filename: a string for the file name to save the output JSON data.
158+
opt: a struct for additional options, ignore to use default values.
150159
opt can have the following fields (first in [.|.] is the default)
151160

152161
opt.FileName [''|string]: a file name to save the output JSON data
@@ -184,7 +193,7 @@ JSON. The detailed help info for the four functions can be found below:
184193
opt.NaN ['"_NaN_"'|string]: a customized regular expression pattern
185194
to represent NaN
186195
opt.JSONP [''|string]: to generate a JSONP output (JSON with padding),
187-
for example, if opt.JSON='foo', the JSON data is
196+
for example, if opt.JSONP='foo', the JSON data is
188197
wrapped inside a function call as 'foo(...);'
189198
opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson
190199
back to the string form
@@ -197,11 +206,15 @@ JSON. The detailed help info for the four functions can be found below:
197206
json: a string in the JSON format (see http://json.org)
198207

199208
examples:
200-
a=struct('node',[1 9 10; 2 1 1.2], 'elem',[9 1;1 2;2 3],...
201-
'face',[9 01 2; 1 2 3; NaN,Inf,-Inf], 'author','FangQ');
202-
savejson('mesh',a)
203-
savejson('',a,'ArrayIndent',0,'FloatFormat','\t%.5g')
204-
</pre>
209+
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],...
210+
'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],...
211+
'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
212+
2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
213+
'MeshCreator','FangQ','MeshTitle','T6 Cube',...
214+
'SpecialData',[nan, inf, -inf]);
215+
savejson('jmesh',jsonmesh)
216+
savejson('',jsonmesh,'ArrayIndent',0,'FloatFormat','\t%.5g')
217+
</pre>
205218

206219
=== loadubjson.m ===
207220

@@ -213,20 +226,36 @@ JSON. The detailed help info for the four functions can be found below:
213226
parse a JSON (JavaScript Object Notation) file or string
214227

215228
authors:Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
216-
date: 2013/08/01
229+
created on 2013/08/01
217230

218231
$Id: loadubjson.m 436 2014-08-05 20:51:40Z fangq $
219232

220233
input:
221234
fname: input file name, if fname contains "{}" or "[]", fname
222235
will be interpreted as a UBJSON string
223236
opt: a struct to store parsing options, opt can be replaced by
224-
a list of ('param',value) pairs. The param string is equivallent
225-
to a field in opt.
237+
a list of ('param',value) pairs - the param string is equivallent
238+
to a field in opt. opt can have the following
239+
fields (first in [.|.] is the default)
240+
241+
opt.SimplifyCell [0|1]: if set to 1, loadubjson will call cell2mat
242+
for each element of the JSON data, and group
243+
arrays based on the cell2mat rules.
244+
opt.IntEndian [B|L]: specify the endianness of the integer fields
245+
in the UBJSON input data. B - Big-Endian format for
246+
integers (as required in the UBJSON specification);
247+
L - input integer fields are in Little-Endian order.
226248

227249
output:
228250
dat: a cell array, where {...} blocks are converted into cell arrays,
229251
and [...] are converted to arrays
252+
253+
examples:
254+
obj=struct('string','value','array',[1 2 3]);
255+
ubjdata=saveubjson('obj',obj);
256+
dat=loadubjson(ubjdata)
257+
dat=loadubjson(['examples' filesep 'example1.ubj'])
258+
dat=loadubjson(['examples' filesep 'example1.ubj'],'SimplifyCell',1)
230259
</pre>
231260

232261
=== saveubjson.m ===
@@ -241,15 +270,17 @@ JSON. The detailed help info for the four functions can be found below:
241270
Binary JSON (UBJSON) binary string
242271

243272
author: Qianqian Fang (fangq<at> nmr.mgh.harvard.edu)
244-
created on 2013/08/17
273+
created on 2013/08/17
245274

246275
$Id: saveubjson.m 440 2014-09-17 19:59:45Z fangq $
247276

248277
input:
249-
rootname: name of the root-object, if set to '', will use variable name
278+
rootname: the name of the root-object, when set to '', the root name
279+
is ignored, however, when opt.ForceRootName is set to 1 (see below),
280+
the MATLAB variable name will be used as the root name.
250281
obj: a MATLAB object (array, cell, cell array, struct, struct array)
251-
filename: a string for the file name to save the output JSON data
252-
opt: a struct for additional options, use [] if all use default
282+
filename: a string for the file name to save the output UBJSON data
283+
opt: a struct for additional options, ignore to use default values.
253284
opt can have the following fields (first in [.|.] is the default)
254285

255286
opt.FileName [''|string]: a file name to save the output JSON data
@@ -281,37 +312,42 @@ JSON. The detailed help info for the four functions can be found below:
281312
wrapped inside a function call as 'foo(...);'
282313
opt.UnpackHex [1|0]: conver the 0x[hex code] output by loadjson
283314
back to the string form
315+
284316
opt can be replaced by a list of ('param',value) pairs. The param
285-
string is equivallent to a field in opt.
317+
string is equivallent to a field in opt and is case sensitive.
286318
output:
287-
json: a string in the JSON format (see http://json.org)
319+
json: a binary string in the UBJSON format (see http://ubjson.org)
288320

289321
examples:
290-
a=struct('node',[1 9 10; 2 1 1.2], 'elem',[9 1;1 2;2 3],...
291-
'face',[9 01 2; 1 2 3; NaN,Inf,-Inf], 'author','FangQ');
292-
saveubjson('mesh',a)
293-
saveubjson('mesh',a,'meshdata.ubj')
322+
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],...
323+
'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],...
324+
'MeshTri',[1 2 4;1 2 6;1 3 4;1 3 7;1 5 6;1 5 7;...
325+
2 8 4;2 8 6;3 8 4;3 8 7;5 8 6;5 8 7],...
326+
'MeshCreator','FangQ','MeshTitle','T6 Cube',...
327+
'SpecialData',[nan, inf, -inf]);
328+
saveubjson('jsonmesh',jsonmesh)
329+
saveubjson('jsonmesh',jsonmesh,'meshdata.ubj')
294330
</pre>
295331

296332

297333
=== examples ===
298334

299335
Under the "examples" folder, you can find several scripts to demonstrate the
300-
basic utilities of JSONlab. Running the "demo_jsonlab_basic.m" script, you
336+
basic utilities of JSONLab. Running the "demo_jsonlab_basic.m" script, you
301337
will see the conversions from MATLAB data structure to JSON text and backward.
302338
In "jsonlab_selftest.m", we load complex JSON files downloaded from the Internet
303339
and validate the loadjson/savejson functions for regression testing purposes.
304340
Similarly, a "demo_ubjson_basic.m" script is provided to test the saveubjson
305341
and loadubjson pairs for various matlab data structures.
306342

307-
Please run these examples and understand how JSONlab works before you use
343+
Please run these examples and understand how JSONLab works before you use
308344
it to process your data.
309345

310346
-------------------------------------------------------------------------------
311347

312348
IV. Known Issues and TODOs
313349

314-
JSONlab has several known limitations. We are striving to make it more general
350+
JSONLab has several known limitations. We are striving to make it more general
315351
and robust. Hopefully in a few future releases, the limitations become less.
316352

317353
Here are the known issues:
@@ -325,31 +361,33 @@ in MATLAB to get consistant results
325361
# an unofficial N-D array count syntax is implemented in saveubjson. We are \
326362
actively communicating with the UBJSON spec maintainer to investigate the \
327363
possibility of making it upstream
364+
# loadubjson can not parse all UBJSON Specification (Draft 9) compliant \
365+
files, however, it can parse all UBJSON files produced by saveubjson.
328366

329367
-------------------------------------------------------------------------------
330368

331369
V. Contribution and feedback
332370

333-
JSONlab is an open-source project. This means you can not only use it and modify
334-
it as you wish, but also you can contribute your changes back to JSONlab so
371+
JSONLab is an open-source project. This means you can not only use it and modify
372+
it as you wish, but also you can contribute your changes back to JSONLab so
335373
that everyone else can enjoy the improvement. For anyone who want to contribute,
336-
please download JSONlab source code from it's subversion repository by using the
374+
please download JSONLab source code from it's subversion repository by using the
337375
following command:
338376

339377
svn checkout svn://svn.code.sf.net/p/iso2mesh/code/trunk/jsonlab jsonlab
340378

341379
You can make changes to the files as needed. Once you are satisfied with your
342380
changes, and ready to share it with others, please cd the root directory of
343-
JSONlab, and type
381+
JSONLab, and type
344382

345383
svn diff > yourname_featurename.patch
346384

347-
You then email the .patch file to JSONlab's maintainer, Qianqian Fang, at
385+
You then email the .patch file to JSONLab's maintainer, Qianqian Fang, at
348386
the email address shown in the beginning of this file. Qianqian will review
349387
the changes and commit it to the subversion if they are satisfactory.
350388

351389
We appreciate any suggestions and feedbacks from you. Please use iso2mesh's
352-
mailing list to report any questions you may have with JSONlab:
390+
mailing list to report any questions you may have with JSONLab:
353391

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

0 commit comments

Comments
 (0)