The JSONUtil structure
Author: John Reppy
Keywords: Standard ML, SML, SML/NJ Library

The SML of NJ Library
The `JSONUtil` structure

some overview

## Synopsis

    structure JSONUtil

## Interface

    exception NotBool of JSON.value
    exception NotInt of JSON.value
    exception NotNumber of JSON.value
    exception NotString of JSON.value

    exception NotObject of JSON.value

    exception FieldNotFound of JSON.value * string

    exception NotArray of JSON.value

    exception ArrayBounds of JSON.value * int

    val exnMessage : exn -> string

    val asBool : JSON.value -> bool
    val asInt : JSON.value -> Int.int
    val asIntInf : JSON.value -> IntInf.int
    val asNumber : JSON.value -> Real.real
    val asString : JSON.value -> string

    val findField : JSON.value -> string -> JSON.value option

    val lookupField : JSON.value -> string -> JSON.value

    val asArray : JSON.value -> JSON.value vector

    val arrayMap : (JSON.value -> 'a) -> JSON.value -> 'a list

    datatype edge = SUB of int | SEL of string

    type path = edge list

    val get : JSON.value * path -> JSON.value

    val replace : JSON.value * path * JSON.value -> JSON.value

    val insert : JSON.value * path * string * JSON.value -> JSON.value

    val append : JSON.value * path * JSON.value list -> JSON.value

## Description

`exception NotBool of JSON.value`

  raised by the `asBool` function when the argument is not a JSON boolean.

`exception NotInt of JSON.value`

  raised by the `asInt` and `asIntInf` functions when the argument is not a JSON integer number.

`exception NotNumber of JSON.value`

  raised by the `asNumber` function when the argument is not a JSON number.

`exception NotString of JSON.value`

  raised by the `asString` function when the argument is not a JSON string.

`exception NotObject of JSON.value`

  raised by the `findField` and `lookupField` functions when the argument is not a JSON object.

`exception FieldNotFound of JSON.value * string`

  This exception is raised when the given field is not found in an object.

`exception NotArray of JSON.value`

  This exception is raised when trying to process a non-array value as an array.

`exception ArrayBounds of JSON.value * int`

  This exception is raised when access to an array value is out of bounds.

`val exnMessage : exn -> string`

  `exnMessage exn` returns an error-message string for the exception value `exn`. This function produces specialized messages for the exceptions defined in the `JSONUtil` structure and falls back to the General.exnMessage function for other exceptions.

`val asBool : JSON.value -> bool`

  `asBool (JSON.BOOL b)` returns the value `b`. This function raises the `NotBool` exception if the value is not a JSON boolean value.

`val asInt : JSON.value -> int`

  `asInt (JSON.INT n)` returns the value `n` converted to `int`. This function raises the `NotInt` exception if the value is not a JSON integer value. It may also raise the `Overflow` exception if `n` is too large for the default `int` type.

`val asIntInf : JSON.value -> IntInf.int`

  `asIntInf (JSON.INT n)` returns the value `n`. This function raises the `NotInt` exception if the value is not a JSON integer value.

`val asNumber : JSON.value -> Real.real`

  `asNumber jv` converts the JSON number `jv` to an SML `real` value. The `jv` argument can either have the form `JSON.INT n`, in which case `n` is converted to the `real` type and returned, or `JSON.FLOAT f`, in which case `f` is returned; otherwise, the `NotNumber` exception is raised.

`val asString : JSON.value -> string`

  `asBool (JSON.STRING s)` returns the value `s`. This function raises the `NotString` exception if the value is not a JSON string value.

`val findField : JSON.value -> string -> JSON.value option`

  `findField (JSON.OBJECT flds) key` returns `SOME jv` when the list of fields `flds` contains `(key, jv)` and `NONE` otherwise. If `findField` is called on a value that is not a JSON object, then it raises the `NotObject` exception.

`val lookupField : JSON.value -> string -> JSON.value`

  `lookupField (JSON.OBJECT flds) key` returns `jv` when the list of fields `flds` contains `(key, jv)` and raises the `FieldNotFound` exception otherwise. If `lookupField` is called on a value that is not a JSON object, then it raises the `NotObject` exception.

`val asArray : JSON.value -> JSON.value vector`

  `asArray jv` converts the JSON array value `jv` to an SML vector value. It raises the `NotArray` exception when `jv` is not a JSON array.

`val arrayMap : (JSON.value -> 'a) -> JSON.value -> 'a list`

  map a conversion function over a JSON array to produce a list; this function raises the `NotArray` exception if the second argument is not an array.

`datatype edge = …​`

  specifies an edge of a path into a JSON value. The constructors have the following meaning:

  `SUB of int`

    `SUB i` specifies the `i`th element of a JSON array.

  `SEL of string`

    `SEL key` specifies the value labeled by `key` in a JSON object.

`type path = edge list`

  specifies a path into a JSON value.

`val get : JSON.value * path -> JSON.value`

  `get (jv, path)` returns the component of `jv` named by `path`. It raises one of the `NotObject`, `NotArray`, or `FieldNotFound` exceptions if there is an inconsistency between the path and the structure of `jv`.

## See Also

`JSON`, The JSON Library

SML/NJ Version 110.99 (December 24, 2020)
Last updated 2020-05-17 14:37:46 UTC