Skip to content

Latest commit

 

History

History
165 lines (138 loc) · 4.25 KB

jsoncvt.adoc

File metadata and controls

165 lines (138 loc) · 4.25 KB

jsoncvt(1)

NAME

jsoncvt - convert JSON to native language representations

SYNOPSIS

jsoncvt [-Akx] [label]

DESCRIPTION

jsoncvt reads JSON formatted data from its standard input, and prints it back out in a native represetnation for various languages on the standard output stream. It is mostly meant for dynamic languages that can evaluate new values on the fly, but do not already have a JSON parser built into them.

If the label argument is supplied, it becomes the name of the toplevel value in the tree of parsed JSON data. Some languages do not require this (XML). Other languages (ksh), which must bind their values to a variable, do require some kind of name to label data. When not supplied, the metaword foobar is used by default.

UTF-8 JSON input is assumed. Both the ksh93 and XML output formats support it and use the appropriate mechanisms.

OPTIONS

-A

When converting to ksh93 format, JSON objects are reprented as associative arrays, instead of compound variables. This is especially useful when object key strings containing characters outside the usual characters used in variable names are present.

-k

Converts the parsed JSON data into ksh93 text.

-x

Converts the parsed JSON data into a compact XML format. This might be useful when you have an XML parser but no JSON parser.

FORMATS

Refer to the following JSON stream when considering the formats below.

{
    "first" : "Bob",
    "last" : "Krzaczek",
    "email" : "Robert.Krzaczek@gmail.com",
    "lucky" : 13,
    "quarter" : 0.25,
    "empty" : null,
    "nerd" : true,
    "lotto" : [ 9, 12, 17, 38, 45, 46 ]
}

ksh93

This output format uses features in a recent version of ksh93, supporting compound variables and typed arrays. Its output is meant to be fed to an eval statement, and assumes standard aliases and setting for variables such as IFS are in place.

The JSON above is rendered in the following format:

compound foobar=(
  first=$'Bob'
  last=$'Krzaczek'
  email=$'Robert.Krzaczek@gmail.com'
  integer lucky=13
  float quarter=0.25
  empty=
  bool nerd=true
  integer -a lotto=(
    9
    12
    17
    38
    45
    46
  )
)

When the -A flag is in effect, the output becomes:

typeset -A foobar=(
  [first]=$'Bob'
  [last]=$'Krzaczek'
  [email]=$'Robert.Krzaczek@gmail.com'
  [lucky]=13
  [quarter]=0.25
  [empty]=
  [nerd]=true
  [lotto]=(
    9
    12
    17
    38
    45
    46
  )
)

XML

This output format is a fairly minimal use of XML, but represents the most natural translation of data that’s already limited to JSON constructs. The result wouldn’t be hard to parse with either SAX or DOM approaches.

The following grammar allows more than just an array or object at the top level of the data; in that way, it is something of a superset of JSON.

link:jsoncvt.dtd[role=include]

Converting the JSON example above yields:

<?xml version='1.0' encoding='utf-8' ?>
<data>
  <object name='foobar'>
  <string name='first'>Bob</string>
  <string name='last'>Krzaczek</string>
  <string name='email'>Robert.Krzaczek@gmail.com</string>
  <number name='lucky'>13</number>
  <number name='quarter'>0.25</number>
  <null name='empty' />
  <true name='nerd' />
  <array name='lotto'>
    <number>9</number>
    <number>12</number>
    <number>17</number>
    <number>38</number>
    <number>45</number>
    <number>46</number>
  </array>
  </object>
</data>

STATUS

0

Success. The JSON file contains no errors, was successfully parsed, and the selected output format was generated.

1

Failure. There was either a problem in the JSON data provided, or some aspect of that data could not be represented in the selected format.

2

Failure. There was a problem with the options or arguments provided on the command line.