std.json - D Programming Language

std.json

JavaScript Object Notation

Авторы:

Jeremie Pelletier, David Herberth

Исходный код std/json.d

Примеры:

import std.conv : to;

// проанализировать json-файл или json-строку в удобную структуру
string s = `{ "language": "D", "rating": 3.5, "code": "42" }`;
JSONValue j = parseJSON(s);
// j и j["language"] возвращает JSONValue,
// j["language"].str возвращает строку
writeln(j["language"].str); // "D"
writeln(j["rating"].floating); // 3.5

// проверка типа
long x;
if (const(JSONValue)* code = "code" in j)
{
    if (code.type() == JSON_TYPE.INTEGER)
        x = code.integer;
    else
        x = to!int(code.str);
}

// создание json-структуры
JSONValue jj = [ "language": "D" ];
// rating пока ещё не существует, поэтому для присвоения используется .object
jj.object["rating"] = JSONValue(3.5);
// создание массива для присвоения списку list
jj.object["list"] = JSONValue( ["a", "b", "c"] );
// list уже существует, поэтому .object необязателен
jj["list"].array ~= JSONValue("D");

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

Application output

Running...

Переместиться к: inf · nan · negativeInf

enum JSONFloatLiteral: string;

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

nan: строка, представляющая значение с плавающей точкой NaN (не-число)
inf: строка, представляющая значение с плавающей точкой Infinity (бесконечность)
negativeInf: строка, представляющая значение с плавающей точкой отрицательное Infinity (минус бесконечность)

Переместиться к: doNotEscapeSlashes · escapeNonAsciiChars · none · specialFloatLiterals

enum JSONOptions: int;

Флаги, которые управляют кодированием и декодированием (парсингом) json.

none: стандартное декодирование
specialFloatLiterals: кодировать float-начения NaN и Inf как строки
escapeNonAsciiChars: кодировать не-ascii-символы через escape-последовательности unicode
doNotEscapeSlashes: не избегать символов косой черты ('/')

Переместиться к: ARRAY · FALSE · FLOAT · INTEGER · NULL · OBJECT · STRING · TRUE · UINTEGER

enum JSON_TYPE: byte;

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

NULL STRING INTEGER UINTEGER FLOAT OBJECT ARRAY TRUE FALSE: Указывает тип JSONValue.

Переместиться к: array · arrayNoRef · floating · integer · isNull · object · objectNoRef · opApply · opBinaryRight · opIndex · opIndexAssign · str · this · toPrettyString · toString · type · uinteger

struct JSONValue;

узел с JSON-значением

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

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

Примеры:

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

Application output

Running...

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

Получение/установка значения с типом JSON_TYPE.STRING.

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.STRING.

Примеры:

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

// получить значение
writeln(j["language"].str); // "D"

// изменить существующий ключ на новую строку
j["language"].str = "Perl";
writeln(j["language"].str); // "Perl"

Application output

Running...

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

Получение/установка значения с типом JSON_TYPE.INTEGER.

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.INTEGER.

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

Получение/установка значения с типом JSON_TYPE.UINTEGER.

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.UINTEGER.

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

Получение/установка значения с типом JSON_TYPE.FLOAT. Обратите внимание, что, несмотря на название, это 64-битный double, а не 32-битный float.

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.FLOAT.

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

Получение/установка значения с типом JSON_TYPE.OBJECT.

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.OBJECT.

Замечание: присутствует квалификатор @system из-за следующего шаблона:

auto a = &(json.object());
json.uinteger = 0;        // перезапись указателя
(*a)["hello"] = "world";  // segmentation fault

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

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

Предостережение: если возвращаемое значение равно null, изменения не будут видны:

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

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.OBJECT.

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

Получение/установка значения с типом JSON_TYPE.ARRAY.

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.ARRAY.

Замечание: присутствует квалификатор @system из-за следующего шаблона:

auto a = &(json.array());
json.uinteger = 0;  // перезапись указателя на массив
(*a)[0] = "world";  // segmentation fault

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

Получение значения для JSON_TYPE.ARRAY. В отличие от array, он извлекает объект по значению и может использоваться в @safe-коде.

Предостережение: при добавлении элементов к возвращённому массиву, новые значения не будут видны в JSONValue

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

Исключения:

JSONException в случае чтения типа, не являющегося JSON_TYPE.ARRAY.

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

Проверка, является ли типом JSON_TYPE.NULL

this(T)(T arg) if (!isStaticArray!T); this(T)(ref T arg) if (isStaticArray!T); inout this(T : JSONValue)(inout T arg);

Конструктор для JSONValue. Если arg сам является JSONValue, его значение и тип будут скопированы в новый JSONValue. Обратите внимание, что это поверхностная копия: если типом является JSON_TYPE.OBJECT или JSON_TYPE.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); // JSON_TYPE.ARRAY

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

Application output

Running...

Переместиться к: 2
inout pure ref @safe inout(JSONValue) opIndex(size_t i);

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

Исключения:

JSONException, если тип не является JSON_TYPE.ARRAY.

Примеры:

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

Application output

Running...

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

Синтаксис ассоциативного массива для json-объектов.

Исключения:

JSONException, если тип не является JSON_TYPE.OBJECT.

Примеры:

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

Application output

Running...

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

Оператор, устанавливающий значение value для элемента JSON-объекта по ключу key.

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

Исключения:

JSONException, если тип не является JSON_TYPE.OBJECT или JSON_TYPE.NULL.

Примеры:

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

Application output

Running...

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

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

Проверяет, можно ли найти ключ в объекте.

Возвращает:

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

Исключения:

JSONException если тип JSON_TYPE правого аргумента не является OBJECT.

Примеры:

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

Application output

Running...

Переместиться к: 2
@system int opApply(scope int delegate(size_t index, ref JSONValue) dg);

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

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

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

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

Неявно вызывает toJSON на этом JSONValue.

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

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

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

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

Переместиться к: 2

JSONValue parseJSON(T)(T json, int maxDepth = -1, JSONOptions options = JSONOptions.none)
if (isInputRange!T && !isInfinite!T && isSomeChar!(ElementEncodingType!T));

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

Исключения:

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

Параметры:

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

JSONValue parseJSON(T)(T json, JSONOptions options)
if (isInputRange!T && !isInfinite!T && isSomeChar!(ElementEncodingType!T));

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

Параметры:

T `json`	строка в формате `json` для декодирования
JSONOptions `options`	включение декодирования строковых представлений NaN/Inf как float-значений

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

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

Для любых объектных типов будут отсортированы их ключи, и сериализация производится в соответствующем порядке.

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

class JSONException: object.Exception;

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