This is JSON.info, produced by Macaulay2, version 1.25.11

JSON -- JSON encoding and decoding
**********************************

Description
===========

JSON (see https://www.json.org/ ) (JavaScript Object Notation) is a common data
interchange format.  This package provides two methods, see toJSON,
and fromJSON, for converting Macaulay2 things to valid JSON
data and vice versa.

+---------------------------------------------------------------------+
|i1 : toJSON {hashTable{"foo" => "bar"}, 1, 3.14159, true, false, nil}|
|                                                                     |
|o1 = [{"foo": "bar"}, 1, 3.14159, true, false, null]                 |
+---------------------------------------------------------------------+
|i2 : fromJSON oo                                                     |
|                                                                     |
|o2 = {HashTable{"foo" => bar}, 1, 3.14159, true, false, nil}         |
|                                                                     |
|o2 : List                                                            |
+---------------------------------------------------------------------+

Author
======

  * Doug Torrance (see https://webwork.piedmont.edu/~dtorrance )
    <dtorrance@piedmont.edu>

Version
=======

This documentation describes version 0.5 of JSON, released November 10, 2025.

Citation
========

If you have used this package in your research, please cite it as follows:

+----------------------------------------------------------------------------+
|@misc{JSONSource,                                                           |
|  title = {{JSON: JSON encoding and decoding. Version~0.5}},                |
|  author = {Doug Torrance},                                                 |
|  howpublished = {A \emph{Macaulay2} package available at                   |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}}|
|}                                                                           |
|                                                                            |
+----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * fromJSON -- decode JSON data into Macaulay2 things
      * toJSON -- encode Macaulay2 things as JSON data
  * Methods
      * "fromJSON(File)" -- see fromJSON, -- decode JSON data
        into Macaulay2 things
      * "fromJSON(String)" -- see fromJSON, -- decode JSON data
        into Macaulay2 things
      * "toJSON(Boolean)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(HashTable)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(Hypertext)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(MutableHashTable)" -- see toJSON, -- encode
        Macaulay2 things as JSON data
      * "toJSON(Nothing)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(Number)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(RR)" -- see toJSON, -- encode Macaulay2 things as
        JSON data
      * "toJSON(String)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(Symbol)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(Thing)" -- see toJSON, -- encode Macaulay2 things
        as JSON data
      * "toJSON(VisibleList)" -- see toJSON, -- encode Macaulay2
        things as JSON data
      * "toJSON(ZZ)" -- see toJSON, -- encode Macaulay2 things as
        JSON data
  * Symbols
      * IndentLevel (missing documentation)
      * nil (Parsing) -- a symbol a parser may return to indicate
        acceptance of the empty string of tokens
      * "Indent" -- see toJSON, -- encode Macaulay2 things as
        JSON data
      * "NameSeparator" -- see toJSON, -- encode Macaulay2 things
        as JSON data
      * "ValueSeparator" -- see toJSON, -- encode Macaulay2
        things as JSON data

For the programmer
==================

The object JSON, is a package (Macaulay2Doc), defined
in JSON.m2, with auxiliary files in JSON/.

-------------------------------------------------------------------------------

The source of this document is in JSON.m2:237:0.

fromJSON -- decode JSON data into Macaulay2 things
**************************************************

  * Usage:
        fromJSON s
  * Inputs:
      * s, a string (Macaulay2Doc), or a file (Macaulay2Doc),
  * Outputs:
      * a thing (Macaulay2Doc), the Macaulay2 equivalent of the
        given data;

Description
===========

The JSON data provided in the given string or file is parsed using the
Parsing, package with the context-free grammar specified by RFC
8259 (see https://datatracker.ietf.org/doc/html/rfc8259 ). The type of the
return value will vary depending on the data.

Numbers will result in ZZ or RR objects, as appropriate.

+-------------------------+
|i1 : fromJSON "2"        |
|                         |
|o1 = 2                   |
+-------------------------+
|i2 : fromJSON "2.71828"  |
|                         |
|o2 = 2.71828             |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+

Strings will result in strings.

+---------------------------------+
|i3 : fromJSON "\"Hello, world!\""|
|                                 |
|o3 = Hello, world!               |
+---------------------------------+

JSON's true and false will result in the corresponding Macaulay2 booleans.

+---------------------+
|i4 : fromJSON "true" |
|                     |
|o4 = true            |
+---------------------+
|i5 : fromJSON "false"|
|                     |
|o5 = false           |
+---------------------+

Due to the implementation of the Parsing package, see null (Macaulay2Doc),
cannot be a return value, and so the symbol nil (Parsing),
is returned when JSON's null is given.

+--------------------+
|i6 : fromJSON "null"|
|                    |
|o6 = nil            |
|                    |
|o6 : Symbol         |
+--------------------+

Objects will result in hash tables.

+----------------------------------------+
|i7 : fromJSON "{\"foo\": 1, \"bar\": 2}"|
|                                        |
|o7 = HashTable{"bar" => 2}              |
|               "foo" => 1               |
|                                        |
|o7 : HashTable                          |
+----------------------------------------+

Arrays will result in lists.

+-------------------------+
|i8 : fromJSON "[1, 2, 3]"|
|                         |
|o8 = {1, 2, 3}           |
|                         |
|o8 : List                |
+-------------------------+

The input may also be a file containing JSON data.

+----------------------------------------------+
|i9 : jsonFile = temporaryFileName() | ".json" |
|                                              |
|o9 = /tmp/M2-180888-0/0.json                  |
+----------------------------------------------+
|i10 : jsonFile << "[1, 2, 3]" << endl << close|
|                                              |
|o10 = /tmp/M2-180888-0/0.json                 |
|                                              |
|o10 : File                                    |
+----------------------------------------------+
|i11 : fromJSON openIn jsonFile                |
|                                              |
|o11 = {1, 2, 3}                               |
|                                              |
|o11 : List                                    |
+----------------------------------------------+

Ways to use fromJSON:
=====================

  * "fromJSON(File)"
  * "fromJSON(String)"

For the programmer
==================

The object fromJSON, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSON.m2:370:0.

IndentLevel
***********

Functions with optional argument named IndentLevel:
===================================================

  * "toJSON(...,IndentLevel=>...)" -- see toJSON, -- encode
    Macaulay2 things as JSON data

For the programmer
==================

The object IndentLevel (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in currentString:1:382.

nil
***

For the programmer
==================

The object nil (Parsing), is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in currentString:1:382.

toJSON -- encode Macaulay2 things as JSON data
**********************************************

  * Usage:
        toJSON x
  * Inputs:
      * x, a thing (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Indent => See null (Macaulay2Doc), an integer (Macaulay2Doc),
        or a string (Macaulay2Doc), default
        value null, how much to indent;
      * IndentLevel => an integer (Macaulay2Doc), default value 0,
        current indentation level (intended for internal use);
      * ValueSeparator => See null (Macaulay2Doc), or a string (Macaulay2Doc),
        default value null, the string between values;
      * NameSeparator => a string (Macaulay2Doc), default value
        ": ", the string after names in object members;
      * Sort => a Boolean value (Macaulay2Doc), default value
        false, whether to sort object members;
  * Outputs:
      * a string (Macaulay2Doc), containing JSON data;

Description
===========

This method (which is also available using its synonym json) returns a string
containing JSON data corresponding to the given Macaulay2 thing.  If the Indent
option is null (the default), then there are no newlines or indentation.

+------------------------------------------------------------+
|i1 : x = hashTable {"foo" => {1, 2, {pi, true, false, nil}}}|
|                                                            |
|o1 = HashTable{"foo" => {1, 2, {pi, true, false, nil}}}     |
|                                                            |
|o1 : HashTable                                              |
+------------------------------------------------------------+
|i2 : toJSON x                                               |
|                                                            |
|o2 = {"foo": [1, 2, [3.141592653589793, true, false, null]]}|
+------------------------------------------------------------+

If the Indent option is an integer, then newlines are added between values of
arrays and members of lists and the given integer determines the number of
spaces to indent for each level of indentation.

+-----------------------------+
|i3 : toJSON(x, Indent => 2)  |
|                             |
|o3 = {                       |
|       "foo": [              |
|         1,                  |
|         2,                  |
|         [                   |
|           3.141592653589793,|
|           true,             |
|           false,            |
|           null              |
|         ]                   |
|       ]                     |
|     }                       |
+-----------------------------+

Alternatively, the Indent option can be a string corresponding to the
indentation used for each level.

+-----------------------------------------------+
|i4 : toJSON(x, Indent => "\t")                 |
|                                               |
|o4 = {                                         |
|             "foo": [                          |
|                     1,                        |
|                     2,                        |
|                     [                         |
|                             3.141592653589793,|
|                             true,             |
|                             false,            |
|                             null              |
|                     ]                         |
|             ]                                 |
|     }                                         |
+-----------------------------------------------+

The ValueSeparator option determines the string to use between values in an
array and members in an object.  If it is null (the default), then the string
will either be ", " or ",", depending on whether Indent is null or not,
respectively. Otherwise, the given string is used.

+-----------------------------------------------------------------+
|i5 : toJSON(x, ValueSeparator => " , ")                          |
|                                                                 |
|o5 = {"foo": [1 , 2 , [3.141592653589793 , true , false , null]]}|
+-----------------------------------------------------------------+

The NameSeparator option determines the string to use after the name of an
object member.  By default, it is ": ".

+-------------------------------------------------------------+
|i6 : toJSON(x, NameSeparator => " : ")                       |
|                                                             |
|o6 = {"foo" : [1, 2, [3.141592653589793, true, false, null]]}|
+-------------------------------------------------------------+

By default, the members of objects are given in arbitrary order.  To sort them
by name in lexicographic order as strings, use the Sort option.

+------------------------------------------------------------------------+
|i7 : toJSON(hashTable{"foo" => 1, "bar" => 2, "baz" => 3}, Sort => true)|
|                                                                        |
|o7 = {"bar": 2, "baz": 3, "foo": 1}                                     |
+------------------------------------------------------------------------+

Ways to use toJSON:
===================

  * "toJSON(Boolean)"
  * "toJSON(HashTable)"
  * "toJSON(Hypertext)"
  * "toJSON(MutableHashTable)"
  * "toJSON(Nothing)"
  * "toJSON(Number)"
  * "toJSON(RR)"
  * "toJSON(String)"
  * "toJSON(Symbol)"
  * "toJSON(Thing)"
  * "toJSON(VisibleList)"
  * "toJSON(ZZ)"

For the programmer
==================

The object toJSON, is a method function with a single argument (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in JSON.m2:314:0.