Skip to content

Commit

Permalink
doco tidies
Browse files Browse the repository at this point in the history
  • Loading branch information
@soniah
soniah committed Jun 23, 2020
1 parent af437e9 commit 661777b
Showing 1 changed file with 67 additions and 42 deletions.
109 changes: 67 additions & 42 deletions User Guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,10 @@

## Displaying JSON
### Pretty printing
If no argument given, `jtc` will expect an input JSON from the `<stdin>`, otherwise JSON is read from the file(s) pointed by the
argument(s). `jtc` will parse and validate input JSON and upon a successful validation will output:
If no argument is given, `jtc` will read JSON from `<stdin>`, otherwise JSON
will be read from the files specified. `jtc` will parse and validate input JSON
and upon successful validation the JSON will be output:

```bash
bash $ <ab.json jtc
{
Expand Down Expand Up @@ -194,7 +196,9 @@ bash $ <ab.json jtc
}
bash $
```
option `-t` controls the indentation of the pretty-printing format (default is 3 white spaces):

option `-t` specifies pretty-printing spacing (default - 3 spaces):

```bash
bash $ <ab.json jtc -t10
{
Expand All @@ -212,29 +216,34 @@ bash $ <ab.json jtc -t10
],
...
```
Majority of the examples and explanations in this document are based on the above simplified version of the above address book JSON model.
The majority of the examples and explanations here use the above address book JSON.

### Compact printing
Option `-r` will instruct to display JSON in a compact (single row) format:

Option `-r` will instruct to display JSON in compact (single row) format:

```bash
bash $ <ab.json jtc -r
{ "Directory": [ { "address": { "city": "New York", "postal code": 10012, "state": "NY", "street address": "599 Lafayette St" }, "age": 25, "children": [ "Olivia" ], "name": "John", "phone": [ { "number": "112-555-1234", "type": "mobile" }, { "number": "113-123-2368", "type": "mobile" } ], "spouse": "Martha" }, { "address": { "city": "Seattle", "postal code": 98104, "state": "WA", "street address": "5423 Madison St" }, "age": 31, "children": [], "name": "Ivan", "phone": [ { "number": "273-923-6483", "type": "home" }, { "number": "223-283-0372", "type": "mobile" } ], "spouse": null }, { "address": { "city": "Denver", "postal code": 80206, "state": "CO", "street address": "6213 E Colfax Ave" }, "age": 25, "children": [ "Robert", "Lila" ], "name": "Jane", "phone": [ { "number": "358-303-0373", "type": "office" }, { "number": "333-638-0238", "type": "home" } ], "spouse": "Chuck" } ] }
bash $
```

By default, the compact printing view will use a single spacer between all tokens, that also could be controlled if `-r` and `-t`
used together, e.g., to print the above JSON w/o spacer:
By default, compact printing view will use a single space between all tokens.
By combining `-r` and `-t` the results can be printed without spaces:

```bash
bash $ <ab.json jtc -rt0
{"Directory":[{"address":{"city":"New York","postal code":10012,"state":"NY","street address":"599 Lafayette St"},"age":25,"children":["Olivia"],"name":"John","phone":[{"number":"112-555-1234","type":"mobile"},{"number":"113-123-2368","type":"mobile"}],"spouse":"Martha"},{"address":{"city":"Seattle","postal code":98104,"state":"WA","street address":"5423 Madison St"},"age":31,"children":[],"name":"Ivan","phone":[{"number":"273-923-6483","type":"home"},{"number":"223-283-0372","type":"mobile"}],"spouse":null},{"address":{"city":"Denver","postal code":80206,"state":"CO","street address":"6213 E Colfax Ave"},"age":25,"children":["Robert","Lila"],"name":"Jane","phone":[{"number":"358-303-0373","type":"office"},{"number":"333-638-0238","type":"home"}],"spouse":"Chuck"}]}
bash $
bash $
```


### Semi-compact printing
A semi-compact view is a middle ground between pretty and compact views. The semi-compact view is engaged with the suffix -`c` appended
to the indent value in `-t` option (e.g.: `-t5c`) . In the semi-compact view all _JSON iterables_ made of only _atomic values_ and/or
empty iterables (`[]`, `{}`) will be printed in a single line, the rest if pretty-printed, compare:

Semi-compact output can be obtained by combining the `-c` and `-t` flags, for
example `-t5c`. All _JSON iterables_ made of only _atomic values_ or empty
iterables (`[]`, `{}`) will be printed in a single line, the rest will be
pretty-printed:

```bash
bash $ <ab.json jtc -tc
{
Expand Down Expand Up @@ -274,54 +283,66 @@ bash $ <ab.json jtc -tc
}
]
}
bash $
bash $
```


### Printing JSON size
JSON size is the total number of the JSON elements found within JSON, it could be printed using `-z`, the size appears after input JSON
is printed (starting from version 1.75b the size is printed in a JSON format):

`-z` prints the total number of JSON elements found, the total will appear
after the input JSON has been printed. From version 1.75b onwards the size is
printed in JSON format.

```bash
bash $ <ab.json jtc -rz
{ "Directory": [ { "address": { "city": "New York", "postal code": 10012, "state": "NY", "street address": "599 Lafayette St" }, "age": 25, "children": [ "Olivia" ], "name": "John", "phone": [ { "number": "112-555-1234", "type": "mobile" }, { "number": "113-123-2368", "type": "mobile" } ], "spouse": "Martha" }, { "address": { "city": "Seattle", "postal code": 98104, "state": "WA", "street address": "5423 Madison St" }, "age": 31, "children": [], "name": "Ivan", "phone": [ { "number": "273-923-6483", "type": "home" }, { "number": "223-283-0372", "type": "mobile" } ], "spouse": null }, { "address": { "city": "Denver", "postal code": 80206, "state": "CO", "street address": "6213 E Colfax Ave" }, "age": 25, "children": [ "Robert", "Lila" ], "name": "Jane", "phone": [ { "number": "358-303-0373", "type": "office" }, { "number": "333-638-0238", "type": "home" } ], "spouse": "Chuck" } ] }
{ "size": 56 }
bash $
bash $
```
if size only required (i.e., w/o printing the input JSON), then use `-zz` option:
To print the total without printing the input JSON, use `-zz`:

```bash
bash $ <ab.json jtc -zz
56
bash $
bash $
```


### Validating JSON
When JSON is read (from a file, or from `stdin`), it get parsed and validated. If an invalid JSON is detected, a short exception
message will be displayed, e.g,:
```bash
bash $ <ab.json jtc

When JSON is read (from a file or `stdin`), it gets parsed and validated. If
invalid JSON is detected, a short exception message will be displayed:
```bash bash $ <ab.json jtc
jtc json parsing exception (<stdin>:1214): unexpected_end_of_line
bash $
bash $
```
and though the message lets us knowing that there's a problem with the input JSON, it not very informative with regards whereabouts the
the problem. To visualize the spot where the problem is, as well as its locus pass a single debug option (`-d`):

The error messsage doesn't explain where the problem is, the `-d` flag (single
debug) will help:

```bash
bash $ <ab.json jtc -d
.display_opts(), option set[0]: -d (internally imposed: )
.init_inputs(), reading json from <stdin>
.exception_locus_(), ...e": 80206,| "state": "CO,| "street address": "6213...
.exception_spot_(), --------------------------------------->| (offset: 1214)
jtc json parsing exception (<stdin>:1214): unexpected_end_of_line
bash $
bash $
```
the vertical pipe symbol `|` in the debug showing JSON locus replaces new lines, thus it becomes easy to spot the problem.
The offset (`1214` in the example) is given in _unicode UTF-8_ characters from the beginning of the input/file/stream.
In that particular failure instance, `jtc` found the end of a line, while _JSON string_ `"Co,` is still open (JSON standard does not
permit multi-line strings). To fix that, the missing quotation mark to be added

The vertical pipe symbol `|` in the debug output shows the location
(`exception_locus .. offset:1214`) of the problem.

The offset (`1214` in the example) is given in _unicode UTF-8_ characters from
the beginning of the input/file/stream. In this example `jtc` found an
unexpected end of line in `"CO,` (the JSON standard doesn't permit multi-line
strings). To fix this, the missing quotation mark must be added.

Multiple debug flags (`-dd`, `-ddd`) can be used to gain greater insight.

### Forcing strict solidus parsing
JSON specification allows escaping solidus (`/`) optionally. By default, `jtc` is relaxed w.r.t. parsing solidus notation - it admits
both unescaped and escaped appearances:

The JSON specification allows optional escaping of solidus (`/`). By default,
`jtc` is looser and allows both unescaped and escaped input:

```bash
bash $ <<<'{ "escaped": "\/", "unescaped": "/" }' jtc
{
Expand All @@ -330,8 +351,9 @@ bash $ <<<'{ "escaped": "\/", "unescaped": "/" }' jtc
}
bash $
```
If there's a need for a strict solidus parsing, option `-q` facilitates the need. It also will throw an exception upon facing
a non-escaped notation:

The `-q` flag will enforce strict solidus parsing:

```bash
bash $ <<<'{ "escaped": "\/", "unescaped": "/" }' jtc -q -d
.display_opts(), option set[0]: -q -d (internally imposed: )
Expand All @@ -343,8 +365,10 @@ bash $
```

### Unquoting JSON strings
If a JSON itself (or a result from walking JSON) is a single JSON string, then sometimes there's a need to unquote it
(especially it comes handy if the string itself is an embedded JSON). `-qq` allows unquoting it, here are a few examples:

Sometimes JSON needs unquoting (for example with embedded JSON), the `-qq` flag
supports this:

```bash
bash $ jsn='"{ \"JSON\": \"example of an embedded JSON\" }"'
bash $ <<<$jsn jtc
Expand All @@ -362,16 +386,18 @@ bash $ <<<$jsn jtc -qq | jtc
bash $
```

When unquoting empty _JSON strings_ (`""`) the resulted blank lines are not even printed:
When unquoting empty _JSON strings_ (`""`) the resulting blank lines aren't printed:

```bash
bash $ <<<'[null, "", true]' jtc -w[:] -qq
null
true
bash $
```

If the source string contains Unicode code points, those will be correctly translated into
respective UTF-8 characters:
If the source string contains Unicode code points, it will be correctly
translated to UTF-8 characters:

```bash
bash $ <<<'"Unicode char: \u1234"' jtc -qq
Unicode char: ሴ
Expand All @@ -384,7 +410,6 @@ jtc json exception: invalid_surrogate_code_pair
bash $
```


> NOTE: _the option notation `-qq` will not engulf a single option notation `-q`, if both behaviors are required then both variants have
to be spelled (e.g. `jtc -q -qq`, or `jtc -qqq`)_
> Also, `-qq` is incompatible with `-j`, `-J` options, because of a risk of forming an ill-formed JSON, thus, when sighted together
Expand Down

0 comments on commit 661777b

Please sign in to comment.