8.1 library(http/json): Reading and writing JSON serialization

author

Jan Wielemaker

See also

- http_json.pl links JSON to the HTTP client and server modules.
- json_convert.pl converts JSON Prolog terms to more comfortable terms.

This module supports reading and writing JSON objects. This library supports two Prolog representations (the new representation is only supported in SWI-Prolog version 7 and later):

• The classical representation is provided by json_read/3 and json_write/3. This represents a JSON object as json(NameValueList), a JSON string as an atom and the JSON constants null, true and false as @(null), @(true) and @false.
• The new representation is provided by json_read_dict/3 and json_write_dict/3. This represents a JSON object as a dict, a JSON string as a Prolog string and the JSON constants using the Prolog atoms null, true and false.

[det]atom_json_term(?Atom, ?JSONTerm, +Options)

Convert between textual representation and a JSON term. In write mode (JSONTerm to Atom), the option

as(Type)

defines the output type, which is one of atom (default), string, codes or chars.

[det]json_read(+Stream, -Term)

[det]json_read(+Stream, -Term, +Options)

Read next JSON value from Stream into a Prolog term. The canonical representation for Term is:

• A JSON object is mapped to a term json(NameValueList), where NameValueList is a list of Name=Value. Name is an atom created from the JSON string.
• A JSON array is mapped to a Prolog list of JSON values.
• A JSON string is mapped to a Prolog atom
• A JSON number is mapped to a Prolog number
• The JSON constants true and false are mapped -like JPL- to @(true) and @(false).
• The JSON constant null is mapped to the Prolog term @(null)

Here is a complete example in JSON and its corresponding Prolog term.

{ "name":"Demo term",
  "created": {
    "day":null,
    "month":"December",
    "year":2007
  },
  "confirmed":true,
  "members":[1,2,3]
}

json([ name='Demo term',
       created=json([day= @null, month='December', year=2007]),
       confirmed= @true,
       members=[1, 2, 3]
     ])

The following options are processed:

null(+NullTerm)

Term used to represent JSON null. Default @(null)

true(+TrueTerm)

Term used to represent JSON true. Default @(true)

false(+FalseTerm)

Term used to represent JSON false. Default @(false)

end_of_file(+ErrorOrTerm)

If end of file is reached after skipping white space but before any input is processed take the following action (default error):

• If ErrorOrTerm == error, throw an unexpected end of file syntax error
• Otherwise return ErrorOrTerm.

Returning an status term is required to process Concatenated JSON. Suggested values are @(eof) or end_of_file.

value_string_as(+Type)

Prolog type used for strings used as value. Default is atom. The alternative is string, producing a packed string object. Please note that codes or chars would produce ambiguous output and are therefore not supported.

See also

json_read_dict/3 to read a JSON term using the version 7 extended data types.

[det]json_write(+Stream, +Term)

[det]json_write(+Stream, +Term, +Options)

Write a JSON term to Stream. The JSON object is of the same format as produced by json_read/2, though we allow for some more flexibility with regard to pairs in objects. All of Name=Value, Name-Value and Name(Value) produce the same output.

Values can be of the form #(Term), which causes Term to be stringified if it is not an atom or string. Stringification is based on term_string/2.

Rational numbers are emitted as floating point numbers. The hook json_write_hook/4 can be used to realize domain specific alternatives.

The version 7 dict type is supported as well. Optionally, if the dict has a tag, a property "type":"tag" can be added to the object. This behaviour can be controlled using the tag option (see below). For example:

?- json_write(current_output, point{x:1,y:2}).
{
  "x":1,
  "y":2
}

?- json_write(current_output, point{x:1,y:2}, [tag(type)]).
{
  "type":"point",
  "x":1,
  "y":2
}

In addition to the options recognised by json_read/3, we process the following options are recognised:

width(+Width)

Width in which we try to format the result. Too long lines switch from horizontal to vertical layout for better readability. If performance is critical and human readability is not an issue use Width = 0, which causes a single-line output.

step(+Step)

Indentation increnment for next level. Default is 2.

tab(+TabDistance)

Distance between tab-stops. If equal to Step, layout is generated with one tab per level.

serialize_unknown(+Boolean)

If true (default false), serialize unknown terms and print them as a JSON string. The default raises a type error. Note that this option only makes sense if you can guarantee that the passed value is not an otherwise valid Prolog reporesentation of a Prolog term.

If a string is emitted, the sequence </ is emitted as <\/. This is valid JSON syntax which ensures that JSON objects can be safely embedded into an HTML <script> element.

[semidet,multifile]json_write_hook(+Term, +Stream, +State, +Options)

Hook that can be used to emit a JSON representation for Term to Stream. If the predicate succeeds it must have written a valid JSON data element and if it fails it may not have produced any output. This facility may be used to map arbitrary Prolog terms to JSON. It was added to manage the precision with which floating point numbers are emitted.

Note that this hook is shared by all users of this library. It is generally adviced to map a unique compound term to avoid interference with normal output.

State

and Options are opaque handles to the current output state and settings. Future versions may provide documented access to these terms. Currently it is adviced to ignore these arguments.

[semidet,multifile]json_dict_pairs(+Dict, -Pairs)

This hook may be used to order the keys of an object. If it fails, dict_pairs/3 is used which produces an ordered list of keys.

[semidet]is_json_term(@Term)

[semidet]is_json_term(@Term, +Options)

True if Term is a json term. Options are the same as for json_read/2, defining the Prolog representation for the JSON true, false and null constants.

[det]json_read_dict(+Stream, -Dict)

[det]json_read_dict(+Stream, -Dict, +Options)

Read a JSON object, returning objects as a dicts. The representation depends on the options, where the default is:

• String values are mapped to Prolog strings
• JSON true, false and null are represented using these Prolog atoms.
• JSON objects are mapped to dicts.
• Optionally, a type field in an object assigns a tag for the dict.

The predicate json_read_dict/3 processes the same options as json_read/3, but with different defaults. In addition, it processes the tag option. See json_read/3 for details about the shared options.

tag(+Name)

When converting to/from a dict, map the indicated JSON attribute to the dict tag. No mapping is performed if Name is the empty atom (” , default). See json_read_dict/2 and json_write_dict/2.

default_tag(+Tag)

Provide the default tag if the above tag option does not apply.

null(+NullTerm)

Default the atom null.

true(+TrueTerm)

Default the atom true.

false(+FalseTerm)

Default the atom false

end_of_file(+ErrorOrTerm)

Action on reading end-of-file. See json_read/3 for details.

value_string_as(+Type)

Prolog type used for strings used as value. Default is string. The alternative is atom, producing a packed string object.

[det]json_write_dict(+Stream, +Dict)

[det]json_write_dict(+Stream, +Dict, +Options)

Write a JSON term, represented using dicts. This is the same as json_write/3, but assuming the default representation of JSON objects as dicts.

[det]atom_json_dict(+Atom, -JSONDict, +Options)

[det]atom_json_dict(-Text, +JSONDict, +Options)

Convert between textual representation and a JSON term represented as a dict. Options are as for json_read/3. In write mode, the addtional option

as(Type)

defines the output type, which is one of atom, string or codes.