Json — C# API · Reckfell

Разбор и вывод JSON с явной проверкой результата и схемы данных.

class JsonReckfellSharpНаследует Resource

Создайте Json, вызовите Parse и используйте Data только после Error.Ok. Отдельно проверьте корневой тип, поля и допустимые значения. Парсер допускает завершающие запятые; это не строгая проверка совместимости с любым внешним JSON-потребителем.

При повторном использовании экземпляра сообщение ошибки и сохранённый текст могут остаться от предыдущего вызова. Успех определяет возвращённый Error. ParseString короче, но его Nil не различает отказ и JSON null.

JSON-числа разбираются как Float. Большие идентификаторы сохраняйте в явно согласованном строковом формате либо используйте кодирование FromNative/ToNative для поддерживаемых типов движка. Обычный Stringify не сохраняет автоматически Vector3, Resource или C# класс.

Пример читает целое поле score в диапазоне 0–1000000. Дополнительные поля допускаются; формат, корень, тип, конечность и диапазон проверяются до выдачи результата.

C#
using System;
using Reckfell;

public static class JsonScoreExample
{
    public static bool TryReadScore(string text, out int score)
    {
        score = 0;
        using var document = new Json();
        if (document.Parse(text) != Error.Ok)
            return false;
        using Variant root = document.Data;
        if (root.VariantType != Variant.Type.Dictionary)
            return false;
        using var fields = root.AsReckfellDictionary();
        bool found = fields.TryGetValue("score", out Variant value);
        using (value)
        {
            if (!found || value.VariantType != Variant.Type.Float)
                return false;
            double number = value.AsDouble();
            if (!double.IsFinite(number) || number < 0 || number > 1_000_000
                || number != Math.Truncate(number))
                return false;
            score = (int)number;
            return true;
        }
    }
}

Полный сценарий сохранения — в сохранении игры.

Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.

Конструкторы1

JsonКонструктор

# Json

C#
public Json();

Создаёт экземпляр с Data типа Nil. Для независимого разбора удобнее новый экземпляр: повторный Parse не гарантирует очистку прежних данных, текста и диагностики на всех путях отказа.

Свойства1

DataСвойство

# Data

C#
public Variant Data { get; set; }

Разобранное либо явно присвоенное значение Variant. Читать результат Parse следует только после Error.Ok: отказ может оставить старое значение, а другой путь отказа — Nil. Присваивание Data очищает GetParsedText(), но не является разбором текста или сбросом всей диагностики.

Методы10

FromNativeVariant

# FromNative

C#
public static Variant FromNative(Variant variant, bool fullObjects = false);

Кодирует поддерживаемые типы движка в JSON-совместимые значения с собственными тегами, префиксами и структурой. Возвращает Variant, не строку: при необходимости затем вызовите Stringify. Это протокол пары FromNative/ToNative, а не обычный JSON DTO.

Параметры
Имя	Тип	По умолчанию
`variant`	`Variant`	—
`fullObjects`	`bool`	`false`

variant

Исходное значение движка для кодирования. Не произвольный управляемый C# объект; поддержка определяется типами Variant.

fullObjects

По умолчанию false: кодирование Object не разрешено и может завершиться Nil с диагностикой. true включает сериализацию поддерживаемых свойств объектов; не означает копирование всего состояния приложения.

Возвращает Variant

Кодированное значение Variant; на неподдерживаемом/запрещённом пути возможен Nil с диагностикой. Nil также кодирует исходный Nil.

GetDataVariant

# GetData

C#
public Variant GetData();

Возвращает значение Data. Array/Dictionary внутри значения остаются разделяемыми, а не становятся независимым глубоким клоном. Освобождайте полученный Variant после использования.

Возвращает Variant

Variant из Data. Проверяйте Error последнего Parse до интерпретации результата.

GetErrorLineint

# GetErrorLine

C#
public int GetErrorLine();

Возвращает диагностический номер строки последнего Parse. Счёт начинается с 0; 0 также устанавливается при успехе, поэтому проверяйте сам Error, а не номер строки.

Возвращает int

Индекс строки с 0; 0 не различает успех и ошибку первой строки.

GetErrorMessagestring

# GetErrorMessage

C#
public string GetErrorMessage();

Возвращает сохранённое сообщение разбора. Читайте его при неуспешном Parse. В текущей реализации успешный следующий Parse может оставить старое сообщение; непустая строка сама по себе не означает отказ последнего вызова.

Возвращает string

Сохранённое сообщение; оно может относиться к более раннему отказу.

GetParsedTextstring

# GetParsedText

C#
public string GetParsedText();

Возвращает последний текст, переданный Parse с keepText: true, включая текст неуспешного разбора. Вызов с keepText: false не очищает ранее сохранённый текст. Присваивание Data/SetData очищает его. Это не новая сериализация Data.

Возвращает string

Сохранённый входной текст или пустая строка, если его нет. Может не соответствовать текущему Data.

ParseError

# Parse

C#
public Error Parse(string jsonText, bool keepText = false);

Разбирает текст и возвращает Error. После Error.Ok проверьте корневой тип, обязательные поля и диапазоны. Парсер допускает некоторые отклонения, например завершающие запятые; он не является строгим валидатором формата для любой внешней системы. Не используйте Data после ошибки. При повторном ключе объекта сохраняется последнее значение.

Параметры
Имя	Тип	По умолчанию
`jsonText`	`string`	—
`keepText`	`bool`	`false`

jsonText

Полный входной текст. Парсер проверяет конец документа, но допускает часть нестрогого синтаксиса; успешный разбор не проверяет требования вашей игры.

keepText

При true сохранить входную строку даже при ошибке. При false ранее сохранённая строка остаётся; это не команда очистки.

Возвращает Error

Error.Ok при принятом тексте; иначе код отказа. Используйте это значение как признак успеха, а не GetErrorMessage или Data.

ParseStringVariant

# ParseString

C#
public static Variant ParseString(string jsonString);

Сокращённый разбор без отдельного Error. Валидный JSON null и отказ возвращают Nil; при отказе также выводится нативная диагностика. Для различения этих случаев используйте экземпляр Json.Parse.

Параметры
Имя	Тип	По умолчанию
`jsonString`	`string`	—

jsonString

Текст JSON. Чтобы отдельно получить Error и диагностику, вместо сокращения используйте Parse экземпляра.

Возвращает Variant

Разобранный Variant. Nil не различает ошибку и валидный JSON null.

SetDatavoid

# SetData

C#
public void SetData(Variant data);

Присваивает Data и очищает сохранённый исходный текст. Не читает JSON, не проверяет схему и не очищает автоматически все сведения о предыдущем Parse.

Параметры
Имя	Тип	По умолчанию
`data`	`Variant`	—

data

Значение для операции. Для Stringify придерживайтесь своей JSON-схемы; для SetData это прямое значение Variant, не текст для разбора.

Stringifystring

# Stringify

C#
public static string Stringify(Variant data, string indent = "", bool sortKeys = true, bool fullPrecision = false);

Преобразует Variant в JSON-текст, не записывая файл. Целый Variant выводится десятичным целым, но последующий Parse читает JSON-числа как Float: большие целые могут потерять точность. Для обычного JSON явно задайте схему, строковые ключи и конечные числа. Это не полная сериализация произвольных объектов движка.

Параметры
Имя	Тип	По умолчанию
`data`	`Variant`	—
`indent`	`string`	`""`
`sortKeys`	`bool`	`true`
`fullPrecision`	`bool`	`false`

data

indent

Строка одного уровня отступа. Пустая строка даёт компактный вывод; для читаемого JSON используйте пробелы или табуляцию. Произвольные непустые символы вставляются буквально и могут испортить JSON.

sortKeys

Сортировать ключи словарей перед выводом; по умолчанию true. Для внешнего JSON используйте строковые ключи. Сортировка не превращает результат в универсальный канонический формат.

fullPrecision

Включить более полное представление Float для точного чтения double. Не исправляет потерю точности больших Int при последующем Parse и не добавляет поддержку NaN/Infinity стандартному JSON.

Возвращает string

Сформированный текст. NaN заменяется null с предупреждением, Infinity — числом 1e99999 со знаком. Это не переносимое восстановление нечисловых значений; проверяйте конечность до записи.

ToNativeVariant

# ToNative

C#
public static Variant ToNative(Variant json, bool allowObjects = false);

Декодирует представление, созданное FromNative. При текстовом вводе сначала выполните Parse и проверьте Error. Не передавайте произвольный обычный JSON как будто это кодированное представление. Включение allowObjects может создавать объекты и назначать свойства/скрипты: это не проверка схемы и не песочница.

Параметры
Имя	Тип	По умолчанию
`json`	`Variant`	—
`allowObjects`	`bool`	`false`

json

JSON-совместимый Variant в формате FromNative, а не строка JSON для самостоятельного разбора.

allowObjects

По умолчанию false. true разрешает создание объектов при декодировании; используйте только для доверенного кодированного содержимого с контролируемыми типами.

Возвращает Variant

Восстановленное значение движка; возможен Nil при отказе, а также как валидное исходное значение.