json.pl -- Reading and writing JSON serialization

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.

This module provides the json Quasi Quotation syntax that allows for embedding JSON documents in Prolog.

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.

 atom_json_term(?Atom, ?JSONTerm, +Options) is det

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.

 json_read(+Stream, -Term) is det

 json_read(+Stream, -Term, +Options) is det

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.

 ws(+Stream, -Next) is det[private]

 ws(+C0, +Stream, -Next)[private]

Skip white space on the Stream, returning the first non-ws character. Also skips // ... comments.

 json_print_length(+Value, +Options, +Max, +Len0, +Len) is semidet[private]

True if Len-Len0 is the print-length of Value on a single line and Len-Len0 =< Max.

To be done

- Escape sequences in strings are not considered.

 is_json_term(@Term) is semidet

 is_json_term(@Term, +Options) is semidet

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.

 json_read_dict(+Stream, -Dict) is det

 json_read_dict(+Stream, -Dict, +Options) is det

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.

 json_write_dict(+Stream, +Dict) is det

 json_write_dict(+Stream, +Dict, +Options) is det

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.

 atom_json_dict(+Atom, -JSONDict, +Options) is det

atom_json_dict(-Text, +JSONDict, +Options) is det

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

as(Type)

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

 json(+Content, +Vars, +VarDict, -JSON) is det

The predicate json/4 implements JSON quasi quotations. These quotations produce a JSON dict that is suitable for json_write_dict/2. The quasi quoter only accepts valid, but possibly partial JSON documents. The quoter replaces content whose value is a Prolog variable that appears in the argument list of the json indicator. Notably, you can't use a Prolog variable in place of an object key. Here is an example.

  {|json(Name)||
      { "name": Name,
        "created": {
          "day":null,
          "month":"December",
          "year":2007
        },
        "confirmed":true,
        "members":[1,2,3]
      }
  |}.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 json_write_dict(Arg1, Arg2, Arg3)

 json_read_dict(Arg1, Arg2, Arg3)

 is_json_term(Arg1, Arg2)

 json_write(Arg1, Arg2, Arg3)

 json_write(Arg1, Arg2)

 json_read(Arg1, Arg2, Arg3)