# JSON Library

The package `json` contains a library for serialization, deserialization, and manipulation of JSON data. The central part of the library is the class `json.JsonValue` that represents a JSON value.

## JSON Values

As mentioned above, the class `json.JsonValue` is used to represent arbitrary JSON values. An instance of `JsonValue` can be thought of as a variant that is specialized for JSON usage. In particular, it implements both the interface for an array and for a map, so that it is convenient to access the data without explicit typechecking. Furthermore, a `JsonValue` that is created with its default constructor is initially empty (i.e. `null`), but can become any type if you try to add data to it. This only works once, however. Once the `JsonValue` contains a value, it will throw an exception if used improperly.

### Creating Values

Creating a `JsonValue` that contains a scalar type (i.e. booleans, numbers, and strings) is done using one of its constructors. These constructors are marked cast constructors to allow the conversion to happen implicitly. Therefore, it is possible to do the following in Basic Storm:

    JsonValue b = false;
    JsonValue n = 32;
    JsonValue d = 3.5;
    JsonValue s = "test";

To create arrays or maps, the most convenient way is to create an empty `JsonValue` and start populating it. Note that `JsonValue` replicates the interface of `Map<T>` and `Array<T>`. There are also constructors that accept `JsonValue[]` and `Str->JsonValue` respectively for programs that produce the contents separately.

    JsonValue array;
    array << 20 << 30;

    JsonValue object;
    object["key"] = "value";
    object["number"] = 12;
    // or
    object.put("key", "value");
    object.put("number", 12);

Note that `array` and `object` above will both have the value `null` before elements are added to them. If you wish to create empty arrays and objects, you can use the static functions `json.JsonValue emptyArray()` and `json.JsonValue emptyObject()`. This is mainly a concern if you need to serialize the representation into empty objects or arrays down the line.

### Inspecting Values

Inspecting the contents of a `JsonValue` is similarly aimed at being similar to existing conventions, but without requiring explicit checks all the time. Instead, the API is designed to throw exceptions whenever the expectations of the program do not match the structure.

The first part of inspecting the contents of a `JsonValue` are the typecast members. As with many other types in the standard library, these are named after the type casted to. All of these throw an exception if the `JsonValue` does not contain the expected type. They are as follows:

- `byte`, `int`, `nat`, `long`, `word`

  Extract an integer type. Note that this only works for types that were integer types from the start (e.g. in the serialization source). Creating a `JsonValue` from a floating point value and trying to extract an integer type will result in an error. Also note that values are stored internally as `core.Long`.

  You can check if the `JsonValue` contains an integer number using `isInteger`.

- `float`, `double`

  Extract a floating point type. Note that integer types are automatically converted to floating point types if required. Values are stored internally as `core.Double`.

  You can check if the `JsonValue` contains a floating point number using `isNumber`. Note that if the value contains an integer, both `isNumber` and `isInteger` will return true.

- `str`

  Extract a `core.Str`. You can check if the value contains a string using `isStr`.

- `array`

  Extract an array of contained elements. In general, this is only necessary when you wish to iterate through the contents of the container. The number of elements can be retrieved using `count`. You can check if the value contains a string using `isArray`.

- `object`

  Extract a map of contained elements. In general, this is only necessary when you wish to iterate through the contents of the container. The number of elements can be retrieved using `count`. You can check if the value contains a string using `isObject`.

For arrays and objects, `JsonValue` additionally implements the interface for arrays and maps. As such, it is possible to access elements using the appropriate operators on the value directly. There is, however, one minor difference regarding the behavior of `[]` for objects. Namely, that `[]` behaves like `get` in that it throws an exception when trying to read a key that does not exist.

Using this API, a JSON object can be inspected as below:

    JsonValue array;
    array << 20 << 20.5;

    JsonValue object;
    object["a"] = "string";
    object["b"] = array;

    for (k, v in object.object) {
        print("${k} -> ${v}");
    }

    Str aValue = object["a"].str;
    JsonValue bValue = object["b"];

    for (id, v in bValue.array) {
        print("${id}: ${v}");
    }

    Double first = bValue[0].double;
    Double second = bValue[1].double;

The `json.JsonValue` also contains a `==` operator to allow comparing arbitrary JSON values. It implements a deep comparison.

### JSON Literals

The library also provides a syntax extension that allows embedding JSON literals into Basic Storm code. Literals start with the keyword `json` and continues with either an object or an array using the standard JSON syntax. All parts of the JSON hierarchy can be replaced by arbitrary Basic Storm expressions except for the keys in object literals.

Keys in JSON objects do not have to be enclosed in quotes if it only contains alphanumeric characters and underscores (which is otherwise required by JSON). As such, to use Basic Storm expressions in keys, either use the interpolated string syntax (i.e. `"${expr}"`) or enclose the expression in `${expr}`.

Below is an example of a json literal. Note that it captures values from the surrounding code.

    Str s = "string";
    Int i = 15;
    Str name = "keyname";
    JsonValue value = json{
       "normal key": "value",
       unquoted-key: s,
       array: [s, i, name],
       "${name}": "key is named 'keyname'",
       ${name + "!"}: "key is named 'keyname!'",
    };

## Serialization

The `json.JsonValue` class serializes JSON to a proper string representation using its `toS` method as usual. By default, the `toS` generates formatted JSON documents, using line breaks and indentation to make it easier to read the structure.

The class provides overloads to change the formatting options. If one parameter is passed to `toS`, it indicates the indentation depth (in number of spaces). If zero is passed, it produces a single line, compact representation. A second parameter to `toS` indicates if keys in objects should be sorted alphabetically. Since `Map<T>` does not preserve the insertion order of elements in Storm, element ordering in objects is otherwise unpredictable.

Similar options are available for the `toS` overload that accepts a `StrBuf` as its first parameter. However, the second parameter is a boolean that instructs if the compact representation should be used rather than a number since this overload uses the `StrBuf`'s standard indentation mechanism.

The output from the serialization is always ASCII (i.e. non-ascii characters are escaped). As such, it can be converted to binary data using `core.io.Buffer toUtf8(core.Str str)` without issues.

Deserialization is provided via the function `parseJson`. There are two overloads, one that accepts a string and another that accepts a `core.io.Buffer`. The second one allows parsing UTF-8-encoded binary data before decoding it first.

## Exceptions

All exceptions thrown by the JSON library inherit from `json.JsonError`. There are two subtypes, `json.JsonParseError` that is thrown by the JSON parser, and `json.JsonAccessError` that is thrown on incorrect accesses to the `json.JsonValue` class. The latter of the two also captures a stacktrace to ease debugging.

## Object Serialization

The library additionally contains the decorator `jsonSerializable` that automatically generates code that converts between `json.JsonValue` and regular Storm classes to make it easier to consume and produce JSON data in a structured manner. This is not too dissimilar from the normal serialization mechanism.

To illustrate how the decorator works, consider the following class:

    class Employee : jsonSerializable {
        Str name;
        Nat salary = 500;
        Str? speciality;
    }

In this case, the `jsonSerializable` decorator adds the following members to the class:

    class Employee : jsonSerializable {
        Str name;
        Nat salary = 500;
        Str? speciality;

        init(JsonValue json) {
            init {
                name = json["name"].str;
                salary = if (value = json.at("salary")) {
                    value.nat;
                } else {
                    500;
                };
                speciality = {
                    element = json["speciality"];
                    if (element.isNull) {
                        Str?();
                    } else {
                        Str?(element.str);
                    }
                };
            }
        }

        JsonValue toJson() {
            var out = JsonValue:emptyObject();
            out.put("name", JsonValue(name));
            out.put("salary", JsonValue(salary));
            if (speciality) {
                out.put("speciality", JsonValue(speciality));
            } else {
                out.put("speciality", JsonValue());
            }
            return out;
        }
    }

As we can see, `jsonSerializable` adds a constructor that converts a `JsonValue` into the type, as well as a `toJson` function that converts the type into JSON. As such, we can use the functions as follows:

    var src = json{
        "name": "Test",
        "salary": 1000,
        "speciality": null
    };
    var converted = src.Employee;
    // or
    var converted = Employee(src);

To convert back, we can of course just call `converted.toJson`.

It is worth noting that the deserialization will only allow members that have explicit default values set to be missing from the JSON. For example, `salary` is allowed to be missing, while `speciality` is not allowed to, even though it is a maybe type.

Finally, even though it is not illustrated above, the serialization library supports serializing and deserializing other types that have an appropriate constructor and a `toJson` function. It also supports arrays, maps with string keys, and maybe types natively. Inheritance is also supported, but since the actual type of an object is not stored in the JSON representation, the support is not as robust as the serialization library in Storm. That is, if we would serialize a subclass to `Employee` using its `toJson`, we will always get `Employee` if we deserialize it using `json.Employee()` since the system does not know which subclass was originally serialized.