Json

GitHub   Edit on GitHub

JSON (JavaScript Object Notation) parsing, printing, and access utilities.

1
from "json" include Json
1
Json.parse("{\"currency\":\"€\",\"price\":99.99}")
1
2
3
4
5
6
print(
  toString(
    format=Pretty,
    JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
  )
)

Types

Type declarations included in the Json module.

Json.Json

1
2
3
4
5
6
7
8
enum Json {
  JsonNull,
  JsonBoolean(Bool),
  JsonNumber(Number),
  JsonString(String),
  JsonArray(List<Json>),
  JsonObject(List<(String, Json)>),
}

Data structure representing JSON in Grain.

Variants:

1
JsonNull

Represents the JSON null value.

1
JsonBoolean(Bool)

Represents a JSON boolean value.

1
JsonNumber(Number)

Represents a JSON number value.

1
JsonString(String)

Represents a JSON string value.

1
JsonArray(List<Json>)

Represents a JSON array value.

1
JsonObject(List<(String, Json)>)

Represents a JSON object value, as a list of (key, value).

Examples:

1
2
3
4
assert Json.parse("{\"currency\":\"€\",\"price\":99.99}") == JsonObject([
  ("currency", JsonString("€")),
  ("price", JsonNumber(99.99)),
])
1
2
3
4
assert Json.parse("{\n\"currency\":\"€\",\n\"price\":99.99\n}") == JsonObject([
  ("currency", JsonString("€")),
  ("price", JsonNumber(99.99)),
])

Json.JsonToStringError

1
2
3
enum JsonToStringError {
  InvalidNumber(String),
}

Represents errors for cases where a Json data structure cannot be represented as a JSON string.

Variants:

1
InvalidNumber(String)

The Json data structure contains a number value of NaN, Infinity, or -Infinity.

Json.IndentationFormat

1
2
3
4
5
enum IndentationFormat {
  NoIndentation,
  IndentWithTab,
  IndentWithSpaces(Number),
}

Controls how indentation is output in custom formatting.

Variants:

1
NoIndentation

No indentation is emitted.

1
2
3
4
{
"currency": "€",
"price": 99.9
}
1
IndentWithTab

Tabs are emitted.

1
2
3
4
{
    "currency": "€",
    "price": 99.9
}
1
IndentWithSpaces(Number)

The desired number of spaces are emitted.

IndentWithSpaces(2)

1
2
3
4
{
  "currency": "€",
  "price": 99.9
}

IndentWithSpaces(4)

1
2
3
4
{
    "currency": "€",
    "price": 99.9
}

Json.ArrayFormat

1
2
3
4
5
enum ArrayFormat {
  CompactArrayEntries,
  SpacedArrayEntries,
  OneArrayEntryPerLine,
}

Controls how arrays are output in custom formatting.

Variants:

1
CompactArrayEntries

Arrays are emitted in a compact manner.

1
[]
1
[1]
1
[1,2,3]
1
SpacedArrayEntries

Arrays are emitted with spaces between elements.

1
[ ]
1
[1]
1
[1, 2, 3]
1
OneArrayEntryPerLine

Arrays are emitted with newlines and indentation between each element.

1
[]
1
2
3
[
  1
]
1
2
3
4
5
[
  1,
  2,
  3
]

Json.ObjectFormat

1
2
3
4
5
enum ObjectFormat {
  CompactObjectEntries,
  SpacedObjectEntries,
  OneObjectEntryPerLine,
}

Controls how objects are output in custom formatting.

Variants:

1
CompactObjectEntries

Objects are emitted in a compact manner.

1
{}
1
{"a":1}
1
{"a":1,"b":2,"c":3}
1
SpacedObjectEntries

Objects are emitted with spaces between entries.

1
{ }
1
{"a": 1}
1
{"a": 1, "b": 2, "c": 3}
1
OneObjectEntryPerLine

Objects are emitted with each entry on a new line.

1
{}
1
2
3
{
  "a": 1
}
1
2
3
4
5
{
  "a": 1,
  "b": 2,
  "c": 3
}

Json.LineEnding

1
2
3
4
5
6
enum LineEnding {
  NoLineEnding,
  LineFeed,
  CarriageReturnLineFeed,
  CarriageReturn,
}

Controls how line endings are output in custom formatting.

Variants:

1
NoLineEnding

No line endings will be emitted.

1
LineFeed

A \n will be emitted at the end of each line.

1
CarriageReturnLineFeed

A \r\n will be emitted at the end of each line.

1
CarriageReturn

A \r will be emitted at the end of each line.

Json.FormattingChoices

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
enum FormattingChoices {
  Pretty,
  Compact,
  PrettyAndSafe,
  CompactAndSafe,
  Custom{
    indentation: IndentationFormat,
    arrayFormat: ArrayFormat,
    objectFormat: ObjectFormat,
    lineEnding: LineEnding,
    finishWithNewLine: Bool,
    escapeAllControlPoints: Bool,
    escapeHTMLUnsafeSequences: Bool,
    escapeNonASCII: Bool,
  },
}

Allows control of formatting in JSON output.

Variants:

1
Pretty

Recommended human readable formatting.

Escapes all control points for the sake of clarity, but outputs unicode codepoints directly so the result needs to be treated as proper unicode and is not safe to be transported in ASCII encoding.

Roughly Equivalent to:

1
2
3
4
5
6
7
8
9
10
Custom{
 indentation: IndentWithSpaces(2),
 arrayFormat: OneArrayEntryPerLine,
 objectFormat: OneObjectEntryPerLine,
 lineEnding: LineFeed,
 finishWithNewLine: true,
 escapeAllControlPoints: true,
 escapeHTMLUnsafeSequences: false,
 escapeNonASCII: false,
}
1
2
3
4
5
{
  "currency": "€",
  "price": 99.9,
  "currencyDescription": "EURO\u007f",
}
1
Compact

Compact formatting that minimizes the size of resulting JSON at cost of not being easily human readable.

Only performs minimal string escaping as required by the ECMA-404 standard, so the result needs to be treated as proper unicode and is not safe to be transported in ASCII encoding.

Roughly Equivalent to:

1
2
3
4
5
6
7
8
9
10
Custom{
 indentation: NoIndentation,
 arrayFormat: CompactArrayEntries,
 objectFormat: CompactObjectEntries,
 lineEnding: NoLineEnding,
 finishWithNewLine: false,
 escapeAllControlPoints: false,
 escapeHTMLUnsafeSequences: false,
 escapeNonASCII: false,
}
1
{"currency":"€","price":99.9,"currencyDescription":"EURO␡"}
1
PrettyAndSafe

Pretty and conservative formatting to maximize compatibility and embeddability of the resulting JSON.

Should be safe to copy and paste directly into HTML and to be transported in plain ASCII.

Roughly Equivalent to:

1
2
3
4
5
6
7
8
9
10
Custom{
 indentation: IndentWithSpaces(2),
 arrayFormat: OneArrayEntryPerLine,
 objectFormat: OneObjectEntryPerLine,
 lineEnding: LineFeed,
 finishWithNewLine: true,
 escapeAllControlPoints: true,
 escapeHTMLUnsafeSequences: true,
 escapeNonASCII: true,
}
1
2
3
4
5
{
  "currency": "\u20ac",
  "price": 99.9,
  "currencyDescription": "EURO\u007f",
}
1
CompactAndSafe

Compact and conservative formatting to maximize compatibility and embeddability of the resulting JSON.

Should be safe to copy and paste directly into HTML and to transported in plain ASCII.

Roughly Equivalent to:

1
2
3
4
5
6
7
8
9
10
Custom{
 indentation: NoIndentation,
 arrayFormat: CompactArrayEntries,
 objectFormat: CompactObjectEntries,
 lineEnding: NoLineEnding,
 finishWithNewLine: false,
 escapeAllControlPoints: true,
 escapeHTMLUnsafeSequences: true,
 escapeNonASCII: true,
}
1
{"currency":"\u20ac","price":99.9,"currencyDescription":"EURO\u007f"}
1
2
3
4
5
6
7
8
9
10
Custom{
  indentation: IndentationFormat,
  arrayFormat: ArrayFormat,
  objectFormat: ObjectFormat,
  lineEnding: LineEnding,
  finishWithNewLine: Bool,
  escapeAllControlPoints: Bool,
  escapeHTMLUnsafeSequences: Bool,
  escapeNonASCII: Bool,
}

Allows for fined grained control of the formatting output.

Json.JsonParseError

1
2
3
4
5
enum JsonParseError {
  UnexpectedEndOfInput(String),
  UnexpectedToken(String),
  InvalidUTF16SurrogatePair(String),
}

Represents errors for JSON parsing along with a human readable message.

Values

Functions and constants included in the Json module.

Json.toString

Added in 0.6.0 No other changes yet. 
1
2
3
toString :
  (?format: FormattingChoices, json: Json) =>
   Result<String, JsonToStringError>

Converts the Json data structure into a JSON string with specific formatting settings.

Parameters:

param type description
?format FormattingChoices Formatting options
json Json The Json data structure to convert

Returns:

type description
Result<String, JsonToStringError> Ok(str) containing the JSON string or Err(err) if the provided Json data structure cannot be converted to a string

Examples:

1
2
3
assert toString(
  JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))]
) == Ok("{\"currency\":\"€\",\"price\":99.9}")
1
2
3
4
assert toString(
  format=Compact
  JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
) == Ok("{\"currency\":\"€\",\"price\":99.9}")
1
2
3
4
5
6
7
assert toString(
  format=Pretty,
  JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
) == Ok("{
  \"currency\": \"€\",
  \"price\": 99.9
}")
1
2
3
4
5
6
7
8
9
10
11
12
13
assert toString(
  format=Custom{
    indentation: NoIndentation,
    arrayFormat: CompactArrayEntries,
    objectFormat: CompactObjectEntries,
    lineEnding: NoLineEnding,
    finishWithNewLine: false,
    escapeAllControlPoints: true,
    escapeHTMLUnsafeSequences: true,
    escapeNonASCII: true,
  },
  JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
) == Ok("{\"currency\":\"\\u20ac\",\"price\":99.9}")

Json.parse

Added in 0.6.0 No other changes yet. 
1
parse : (str: String) => Result<Json, JsonParseError>

Parses JSON string into a Json data structure.

Parameters:

param type description
str String The JSON string to parse

Returns:

type description
Result<Json, JsonParseError> Ok(json) containing the parsed data structure on a successful parse or Err(err) containing a parse error otherwise

Examples:

1
2
3
4
5
6
assert parse("{\"currency\":\"$\",\"price\":119}") == Ok(
 JsonObject([
   ("currency", JsonString("$")),
   ("price", JsonNumber(119))
 ])
)
Int64
List
This is a notification!