=pod
=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.41.
See http://github.com/ingydotnet/swim-pm#readme
=encoding utf8
=head1 Name
JSON - JSON for Bash
=for html
=head1 Synopsis
source json.bash
json='{"name":"Jason","friends":["Jimmy","Joe"]}'
JSON.load "$json"
joe=$(JSON.get /friends/1)
JSON.put /friends/2 Jeff
new_json=$(JSON.dump)
=head1 Description
The C<json.bash> library provides functions for loading, manipulating and
dumping JSON data.
Bash doesn't have nestable hashes and arrays to load JSON data into. This
library provides a different data model called a "linear tree". A linear tree
is simply a sequence of text lines, each containing a key-path and a leaf-
value (separated by a tab):
/key/path<HARD-TAB>"leaf value"
Thus this JSON:
{
"name": {
"first": "Jimmy",
"last": "James"
},
"list": [
"A string",
42,
[ true, false, null ]
]
}
Would be loaded as this linear tree:
/name/first "Jimmy"
/name/last "James"
/list/0 "A string"
/list/1 42
/list/2/0 true
/list/2/1 false
/list/2/2 null
Since Bash has many tools for searching and manipulating text, the linear form
works fairly well for common JSON data operations.
=head1 Installation
Just run:
make install
This may require C permission.
By default, this will install:
/usr/local/lib/bash/test-simple.bash
/usr/local/share/man/man1/test-simple.1
You can change the install locations with these environment variables:
=over
=item * C - default is C</usr/local>
=item * C<INSTALL_LIB>
=item * C<INSTALL_MAN>
=back
Run C to see all the C targets that are available.
=head1 API Functions
The library contains functions to B JSON to the linear form and to
B that form back into JSON. It also has functions to retrieve, modify,
add and remove data from the linear form.
=over
=item C<< JSON.load [ []] >>
This function takes JSON as input and generates a linear tree as output.
With no arguments, input is read from stdin and output is written to stdout.
With one argument, the input is provided as a string argument and the output
is stored in an internal cache variable. With two arguments the input is
again provided as a string argument, and the output is copied into the
variable name provided.
=item C<< JSON.dump [] >>
This function takes a linear tree as input and generates JSON as output.
With no arguments, input is read from stdin. With one argument, input is taken
from the provided variable name. To use the internal cache, use C<-> as the
variable name. Output is always written to stdout.
=item C<< JSON.get [-a|-s|-b|-n|-z] [] >>
This function takes a key path and returns the corresponding value. If the key
is found, the exit status is 0, otherwise it is 1. If the value is a string,
it will be enclosed in double quotes. Otherwise it will be a number or the
unquoted strings: C, C or C.
With just the one required argument, the linear tree will be obtained from
stdin. Otherwise it can be provided with a variable name (or C<-> for the
cache). The value (if any) is written to stdout.
See FLAGS below for an explanation of the flag options.
=item C<< JSON.keys [] >>
This function takes a key path and returns the keys of the corresponding
object, one per line. If the key is not found or the value of the key is not
an object, it will return nothing.
=item C<< JSON.object [] >>
This function takes a key path and returns the corresponding object. If the
key is not found, it will return nothing.
=item C<< JSON.put [-s|-b|-n|-z] [] >>
This function adds a path/value pair to the linear tree. If the path already
exists, the value will be replaced, otherwise it will be added.
With just the two required arguments, the linear tree will be obtained
from stdin. Otherwise it can be provided with a variable name (or C<-> for
the cache). Nothing will be written to stdout and the exit status will
always be 0.
=item C<< JSON.del [] >>
This function removes a path/value pair from the linear tree, if it exists.
With just the one required argument, the linear tree will be obtained
from stdin. Otherwise it can be provided with a variable name (or C<->
for the cache). Nothing will be written to stdout and the exit status
will always be 0.
Heuristics will be used to determine what type the value is. The -s flag
indicates the value is a string, the -n flag indicates a number,the -b flag
indicates a boolean and the -z flag indicates a null value.
=item C<< JSON.cache [] >>
Outputs the value of the internal linear tree cache string.
With no arguments, the value is written to stdout. With one argument, the
value is copied to the variable name provided.
=back
=head1 Flags
The command flags C<-a>, C<-s>, C<-n>, C<-b> and C<-z> indicate the B of
value provided or expected, and they refer to Any, String, Number, Boolean and
Null respectively. If the type of data doesn't look like the type indicated by
the flag, the command will return with a status code of 2.
If C<-a> is used, the double quotes at each end (if any) will be removed for a
C<JSON.get>.
If C<-s> is used and the data is a string, the double quotes will be removed
for a C<JSON.get> or added for a C<JSON.put>.
The C<-n> flag requires no value transformation, but it will cause the command
to fail (status 2) if the value is not a number.
If C<-b> is used for a C<JSON.get>, true will become 0 and false will become
- C<JSON.put> will do the reverse. This follows Bash's idea of using 0 for a
successful return code.
The C<-z> flag on a C<JSON.get> will turn C into the empty string, and
for a C<JSON.put> will turn any value into C.
=head1 Examples
# Load JSON to linear tree
JSON.load "$(< file.json)" tree
# or:
tree=$(cat file.json | JSON.load)
# Get a value
first_name=$(JSON.get /name/first tree)
# or:
first_name=$(echo "$tree" | JSON.get /name/first)
# Change a value
JSON.put /name/first Jimmy tree
# or:
tree=(echo "$tree" | JSON.put /name/first Jimmy)
# Delete a value
JSON.del /name/middle tree
# or:
tree=(echo "$tree" | JSON.del /name/middle)
# Dump a linear tree to JSON
JSON.dump tree > new-file.json
# or:
echo "$tree" | JSON.dump > new-file.json
=head1 Problems
This library is meant to be useful for solving common problems involving JSON.
However, without the native JSON object model in Bash, it becomes problematic
the further you stray from the norm.
Here is a list of known issues. Some may be addressed, some are very likely to
stay out of scope:
=over
=item * No support for empty arrays and empty objects.
=item * No support for key-paths that refer to objects or arrays.
=item * No support for common array operations like C, C, C, etc.
=back
=head1 Todo
=over
=item * Support object keys that:
=over
=item * Contain whitespace
=item * Consist of all digit characters
=item * Contain backslashes
=back
=item * Implement JSON.dump
=back
=head1 Status
Please report any issues to Lhttps://github.com/ingydotnet/json-bash/issues
Or find me on ingy@irc.freenode.net.
=head1 Author
Written by Ingy döt Net ingy@ingy.net
=head1 Copyright & License
Copyright 2013-2016 Ingy döt Net
The MIT License (MIT)
=cut