std.json

JavaScript Object Notation

Лицензия:

Boost License 1.0.

Авторы:

Jeremie Pelletier, David Herberth

Ссылки

http://json.org/, http://seriot.ch/parsing_json.html

Исходный код

std/json.d

Примеры:

import std.conv : to;

// parse a file or string of json into a usable structure
string s = `{ "language": "D", "rating": 3.5, "code": "42" }`;
JSONValue j = parseJSON(s);
// j and j["language"] return JSONValue,
// j["language"].str returns a string
writeln(j["language"].str); // "D"
writeln(j["rating"].floating); // 3.5

// check a type
long x;
if (const(JSONValue)* code = "code" in j)
{
    if (code.type() == JSONType.integer)
        x = code.integer;
    else
        x = to!int(code.str);
}

// create a json struct
JSONValue jj = [ "language": "D" ];
// rating doesnt exist yet, so use .object to assign
jj.object["rating"] = JSONValue(3.5);
// create an array to assign to list
jj.object["list"] = JSONValue( ["a", "b", "c"] );
// list already exists, so .object optional
jj["list"].array ~= JSONValue("D");

string jjStr = `{"language":"D","list":["a","b","c","D"],"rating":3.5}`;
writeln(jj.toString); // jjStr

Перечисление JSONFloatLiteral: строка;

Строковые литералы, используемые для представления специальных значений с плавающей точкой в JSON-строках.

nan

строковое представление числового NaN

inf

строковое представление бесконечности с плавающей точкой

negativeInf

строковое представление отрицательной бесконечности с плавающей точкой

Перечисление JSONOptions: целое число;

Флаги, контролирующие, как JSON кодируется и парсится.

none

стандартный парсинг

specialFloatLiterals

кодирование значений NaN и Inf с плавающей точкой как строк

escapeNonAsciiChars

кодирование символов, не входящих в ASCII, с помощью последовательности экранирования Unicode

doNotEscapeSlashes

не экранировать косые черты ('/')

strictParsing

Строгое следование грамматике RFC-8259 при парсинге

Перечисление JSONType: байт;

Перечисление типов JSON

null_

строка

целое число

беззнаковое целое число

число с плавающей точкой

массив

объект

true

false

Указывает тип JSONValue.

Структура JSONValue;

Узел значения JSON

const pure nothrow @nogc @property @safe JSONType type();

Возвращает JSONType значения, хранящегося в этой структуре.

Примеры:

string s = "{ \"language\": \"D\" }";
JSONValue j = parseJSON(s);
writeln(j.type); // JSONType.object
writeln(j["language"].type); // JSONType.string

const pure @property @trusted string str();

pure nothrow @nogc @property @safe string str(string v);

Получение/установка значения для JSONType.string.

Исключения:

JSONException для чтения, если type не является JSONType.string.

Примеры:

JSONValue j = [ "language": "D" ];

// get value
writeln(j["language"].str); // "D"

// change existing key to new string
j["language"].str = "Perl";
writeln(j["language"].str); // "Perl"

const pure @property @safe long integer();

pure nothrow @nogc @property @safe long integer(long v);

Получение/установка значения для JSONType.integer.

Исключения:

JSONException для чтения, если type не является JSONType.integer.

const pure @property @safe ulong uinteger();

pure nothrow @nogc @property @safe ulong uinteger(ulong v);

Получение/установка значения для JSONType.uinteger.

Исключения:

JSONException для чтения, если type не является JSONType.uinteger.

const pure @property @safe double floating();

pure nothrow @nogc @property @safe double floating(double v);

Получение/установка значения для JSONType.float_. Обратите внимание, что, несмотря на название, это 64-битное double, а не 32-битное float.

Исключения:

JSONException для чтения, если type не является JSONType.float_.

const pure @property @safe bool boolean();

pure nothrow @nogc @property @safe bool boolean(bool v);

Получение/установка значения булевого типа, хранящегося в JSON.

Исключения:

JSONException для чтения, если this.type не является JSONType.true_ или JSONType.false_.

Примеры:

JSONValue j = true;
writeln(j.boolean); // true

j.boolean = false;
writeln(j.boolean); // false

j.integer = 12;
import std.exception : assertThrown;
assertThrown!JSONException(j.boolean);

inout pure @property ref @system inout(JSONValue[string]) object();

pure nothrow @nogc @property @safe JSONValue[string] object(JSONValue[string] v);

Получение/установка значения для JSONType.object.

Исключения:

JSONException для чтения, если type не является JSONType.object.

Примечание

это @system из-за следующего паттерна:

auto a = &(json.object());
json.uinteger = 0;        // overwrite AA pointer
(*a)["hello"] = "world";  // segmentation fault

inout pure @property @trusted inout(JSONValue[string]) objectNoRef();

Получение значения для JSONType.object. В отличие от object, это возвращает объект по значению и может использоваться в коде @safe.

Особенность заключается в том, что если возвращаемое значение равно null, то изменения не будут видны:

JSONValue json;
json.object = null;
json.objectNoRef["hello"] = JSONValue("world");
assert("hello" !in json.object);

Исключения:

JSONException для чтения, если type не является JSONType.object.

inout pure @property ref @system inout(JSONValue[]) array();

pure nothrow @nogc @property @safe JSONValue[] array(JSONValue[] v);

Получение/установка значения для JSONType.array.

Исключения:

JSONException для чтения, если type не является JSONType.array.

Примечание

это @system из-за следующего паттерна:

auto a = &(json.array());
json.uinteger = 0;  // overwrite array pointer
(*a)[0] = "world";  // segmentation fault

inout pure @property @trusted inout(JSONValue[]) arrayNoRef();

Получение значения для JSONType.array. В отличие от array, это возвращает массив по значению и может использоваться в коде @safe.

Особенность: если вы добавляете элементы в возвращаемый массив, новые значения не видны в

JSONValue

JSONValue json;
json.array = [JSONValue("hello")];
json.arrayNoRef ~= JSONValue("world");
assert(json.array.length == 1);

Исключения:

JSONException для чтения, если type не является JSONType.array.

const pure nothrow @nogc @property @safe bool isNull();

Проверяет, является ли тип JSONType.null_

inout const pure @property @safe inout(T) get(T)();

inout pure @property @trusted inout(T) get(T : JSONValue[string])();

Получение значения универсального типа. Удобный метод, возвращающий это JSONValue в качестве указанного типа D.

Примечание

принимаются только числовые, bool, string, JSONValue[string] и JSONValue[] типы

Исключения:

JSONException если T не может содержать содержимое этого JSONValue ConvException в случае переполнения при преобразовании в T

Примеры:

import std.exception;
import std.conv;
string s =
`{
    "a": 123,
    "b": 3.1415,
    "c": "text",
    "d": true,
    "e": [1, 2, 3],
    "f": { "a": 1 },
    "g": -45,
    "h": ` ~ ulong.max.to!string ~ `,
 }`;

struct a { }

immutable json = parseJSON(s);
writeln(json["a"].get!double); // 123.0
writeln(json["a"].get!int); // 123
writeln(json["a"].get!uint); // 123
writeln(json["b"].get!double); // 3.1415
assertThrown!JSONException(json["b"].get!int);
writeln(json["c"].get!string); // "text"
writeln(json["d"].get!bool); // true
assertNotThrown(json["e"].get!(JSONValue[]));
assertNotThrown(json["f"].get!(JSONValue[string]));
static assert(!__traits(compiles, json["a"].get!a));
assertThrown!JSONException(json["e"].get!float);
assertThrown!JSONException(json["d"].get!(JSONValue[string]));
assertThrown!JSONException(json["f"].get!(JSONValue[]));
writeln(json["g"].get!int); // -45
assertThrown!ConvException(json["g"].get!uint);
writeln(json["h"].get!ulong); // ulong.max
assertThrown!ConvException(json["h"].get!uint);
assertNotThrown(json["h"].get!float);

this(T)(T arg)
Ограничения: если (!isStaticArray!T);

this(T)(ref T arg)
Ограничения: если (isStaticArray!T);

inout this(T : JSONValue)(inout T arg);

Конструктор для JSONValue. Если arg является JSONValue, его значение и тип будут скопированы в новый JSONValue. Обратите внимание, что это поверхностная копия: если тип JSONType.object или JSONType.array, то будет скопирована только ссылка на данные. В противном случае, arg должен быть неявно преобразуем в один из следующих типов: typeof(null), string, ulong, long, double, ассоциативный массив V[K] для любого V и K т.е. объект JSON, любой массив или bool. Тип будет установлен соответствующим образом.

Примеры:

JSONValue j = JSONValue( "a string" );
j = JSONValue(42);

j = JSONValue( [1, 2, 3] );
writeln(j.type); // JSONType.array

j = JSONValue( ["language": "D"] );
writeln(j.type); // JSONType.object

inout pure ref @safe inout(JSONValue) opIndex(size_t i);

Синтаксис массива для json массивов.

Исключения:

JSONException если type не является JSONType.array.

Примеры:

JSONValue j = JSONValue( [42, 43, 44] );
writeln(j[0].integer); // 42
writeln(j[1].integer); // 43

inout pure ref @safe inout(JSONValue) opIndex(string k);

Синтаксис словаря для json объектов.

Исключения:

JSONException если type не является JSONType.object.

Примеры:

JSONValue j = JSONValue( ["language": "D"] );
writeln(j["language"].str); // "D"

void opIndexAssign(T)(auto ref T value, string key);

Оператор устанавливает value для элемента JSON объекта по key.

Если значение JSON равно null, то оператор инициализирует его объектом, а затем устанавливает value для него.

Исключения:

JSONException если type не является JSONType.object или JSONType.null_.

Примеры:

JSONValue j = JSONValue( ["language": "D"] );
j["language"].str = "Perl";
writeln(j["language"].str); // "Perl"

const @safe auto opBinaryRight(string op : "in")(string k);

Поддержка оператора in.

Проверяет, существует ли ключ в объекте.

Возвращает:

если найден, то const(JSONValue)*, соответствующее ключу, в противном случае null.

Исключения:

JSONException если правое операнд JSONType не является object.

Примеры:

JSONValue j = [ "language": "D", "author": "walter" ];
string a = ("author" in j).str;

@system int opApply(scope int delegate(size_t index, ref JSONValue) dg);

Реализует интерфейс foreach opApply для json массивов.

@system int opApply(scope int delegate(string key, ref JSONValue) dg);

Реализует интерфейс foreach opApply для json объектов.

const @safe string toString(in JSONOptions options = JSONOptions.none);

Неявный вызов toJSON для этого JSONValue.

options может быть использован для настройки поведения преобразования.

const void toString(Out)(Out sink, in JSONOptions options = JSONOptions.none);

const @safe string toPrettyString(in JSONOptions options = JSONOptions.none);

Неявный вызов toJSON для этого JSONValue, как toString, но также передаёт true как аргумент pretty.

options может быть использован для настройки поведения преобразования

const void toPrettyString(Out)(Out sink, in JSONOptions options = JSONOptions.none);

JSONValue parseJSON(T)(T json, int maxDepth = -1, JSONOptions options = JSONOptions.none)
Ограничения: если (isInputRange!T && !isInfinite!T && isSomeChar!(ElementEncodingType!T));

Парсит сериализованную строку и возвращает дерево JSON значений.

Исключения:

JSONException если строка не соответствует грамматике JSON или глубина превышает максимальную глубину, ConvException если число в вводе не может быть представлено родным типом D.

Параметры:

T json	строка в формате JSON для парсинга
int maxDepth	максимальная глубина вложенности, -1 отключает проверку глубины
JSONOptions options	разрешить декодирование строковых представлений NaN/Inf как значений с плавающей точкой

JSONValue parseJSON(T)(T json, JSONOptions options)
Ограничения: если (isInputRange!T && !isInfinite!T && isSomeChar!(ElementEncodingType!T));

Парсит сериализованную строку и возвращает дерево JSON значений.

Исключения:

JSONException если глубина превышает максимальную глубину.

Параметры:

T json	строка в формате JSON для парсинга
JSONOptions options	разрешить декодирование строковых представлений NaN/Inf как значений с плавающей точкой

@safe string toJSON(ref const JSONValue root, in bool pretty = false, in JSONOptions options = JSONOptions.none);

Принимает дерево значений JSON и возвращает сериализованную строку.

Любые типы Object будут сериализованы в отсортированном по ключам порядке.

Если pretty равно false, пробелы не генерируются. Если pretty равно true, сериализованная строка форматируется для удобного чтения. Установите флаг JSONOptions.specialFloatLiterals в options, чтобы закодировать NaN/Infinity как строки.

void toJSON(Out)(auto ref Out json, ref const JSONValue root, in bool pretty = false, in JSONOptions options = JSONOptions.none)
Constraints: if (isOutputRange!(Out, char));

class JSONException: object.Exception;

Исключение, выбрасываемое при ошибках JSON