﻿1С:JSON. JavaScript Object Notation парсер и сериализатор.

Copyright © 2010-2013 Александр Переверзев

Данная лицензия разрешает лицам, получившим копию данного программного 
обеспечения и сопутствующей документации (в дальнейшем именуемыми «Программное 
Обеспечение»), безвозмездно использовать Программное Обеспечение без ограничений, 
включая неограниченное право на использование, копирование, изменение, 
добавление, публикацию, распространение, сублицензирование и/или продажу копий 
Программного Обеспечения, также как и лицам, которым предоставляется данное 
Программное Обеспечение, при соблюдении следующих условий:

Указанное выше уведомление об авторском праве и данные условия должны быть 
включены во все копии или значимые части данного Программного Обеспечения.

ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО 
ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ 
ГАРАНТИЯМИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И 
ОТСУТСТВИЯ НАРУШЕНИЙ ПРАВ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ 
ОТВЕТСТВЕННОСТИ ПО ИСКАМ О ВОЗМЕЩЕНИИ УЩЕРБА, УБЫТКОВ ИЛИ ДРУГИХ ТРЕБОВАНИЙ ПО 
ДЕЙСТВУЮЩИМ КОНТРАКТАМ, ДЕЛИКТАМ ИЛИ ИНОМУ, ВОЗНИКШИМ ИЗ, ИМЕЮЩИМ ПРИЧИНОЙ ИЛИ 
СВЯЗАННЫМ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ 
ИЛИ ИНЫМИ ДЕЙСТВИЯМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.


Александр Переверзев
e-mail: a.v.pereverzev@gmail.com
Версия: 2.0.0.17


Особенности:
  Парсер и сериализатор поддерживают два режима (формата) работы:
    - Стандартный – полная поддержка стандарта JSON (подробнее см. <http:www.JSON.org/> и 
      <http:www.ietf.org/rfc/rfc4627.txt?number=4627>);
    - Альтернативный – направлен на применение в проектах подразумевающих постоянный двусторонний
      обмен данными, по каналам связи Интернет, и требующих повышенную скорость обработки данных,
      минимизацию пересылаемых пакетов данных и однозначную идентификацию ссылочных типов во входящих данных.

  Независимо от режима работы сериализатор, по требованию (см. Настройки), позволяет автоматически передавать 
  не только уникальный идентификатор ссылки, но и ее представление, а парсер в свою очередь, 
  анализируя входные данные, опускает представления ссылок, не включая их в результирующий набор данных.

  При работе с проектами, в исходящих строковых данных которых не гарантируется отсутствие символов из диапазонов:
    [0x007f, 0x009f], 0x00ad, [0x0600, 0x0604], 0x070f, [0x17b4, 0x17b5], 
    [0x200c, 0x200f], [0x2028, 0x202f] [0x2060, 0x206f], 0xfeff, [0xfff0, 0xffff],
  рекомендуется не отключать настройку (см. Настройки) полного маскирования символов 
  (подробнее см. <https:github.com/douglascrockford/JSON-js/blob/master/json2.js> и <http:sadesign.ru/tools/unicode>).

  Независимо от режима работы сериализатор, по требованию (см. Настройки), может маскировать кириллические символы 
  современных алфавитов славянских языков "АБВГҐДЂЃЕЀЁЄЖЗЅИЍІЇЙЈКЛЉМНЊОПРСТЋЌУЎФХЦЧЏШЩЪЫЬЭЮЯ" (включая нижний регистр) 
  (подробнее см. <http://ru.wikipedia.org/wiki/Кириллица> и <http://ru.wikipedia.org/wiki/Кириллица_в_Юникоде>).

  Поддерживаются все среды исполнения с ограничением сериализуемых типов. Используется кроссплатформенный код.



История изменения:
  Версия 2.0.0.17:
    - (Новое) Маскирование кириллических символов современных алфавитов славянских языков (по требованию);
    - (Новое) Поддержка сериализатором типов: ДвоичныеДанные, Картинка, ХранилищеЗначения;
    - (Изменение) Рефакторинг переменных и процедур;
    - (Исправление) Сериализация типа COMSafeArray;
    - (Исправление) Удалены лишние ключевые слова "Экспорт".
    - (Оптимизация) Уменьшение проверок связанных с режимом и параметрами парсинга и сериализцаии;
    - (Оптимизация) Проверка необходимости анализа форматирования вынесена из процедуры анализа форматирования;
    - (Оптимизация) Изменен алгоритм автоматического приведение объекта к структуре или соответствию в зависимости от имен свойств;
    - (Оптимизация) Отказ от явного приведения типов в пользу неявного в операторах условий;
    - (Оптимизация) Отказ от оператора "Попытка Исключение" при преобразовании строки к уникальному идентификатору;
    - (Оптимизация) Изменен порядок проверки типов при парсинге.
  Версия 2.0.0.15
    - Релиз.



Методы:
  ПрочитатьJSON – парсер;
  ЗаписатьJSON – сериализатор.

Настройки и параметры:

  Параметры функций:
    Стандарт – определяет режим работы парсера и сериализатора:
      - Истина    – стандартный режим (значение по умолчанию);
      - Ложь      – альтернативный режим;
      - Неопределено  – автоматическое определение режима входящих данных
                (только парсер, не рекомендуется – влияет на производительность).

    ПредставленияСсылок – позволяет автоматически передавать не только значение ссылки, но и ее представление:
      - Истина    - ссылка парсится и сериализуется как объект с двумя свойствами "Ссылка" и "Представление";
      - Ложь      - ссылка парсится и сериализуется как уникальный идентификатор ссылки (значение по умолчанию);
      - Неопределено  – автоматическое определение формата ссылок во входящих данных
                (только парсер, не рекомендуется – влияет на производительность).

  Настройки:
    АвтоматическоеПриведениеОбъектаКСтруктуре – автоматическое приведение объекта к структуре, а не к соответствию.
      Настройка изменяется в функции "АвтоматическоеПриведениеОбъектаКСтруктуре" (по умолчанию отключена).
      Автоматическое приведение к структуре выполняется только для объектов имена свойств, которых могут быть 
      использованы как ключи структуры, все остальные объекты преобразуются в соответствие.

    ПолноеМаскированиеСимволов – маскирование символов некорректно обрабатываемых JavaScript-ом.
      Настройка изменяется в функции "НастройкаПолноеМаскированиеСимволов" (по умолчанию включена).
      Не рекомендуется к использованию, так как влияет на производительность, но гарантирует безопасную передачу данных.
      Маскирование специальных символов из диапазона [0x0000, 0x001f] выполняется в не зависимости от настройки.

    МаскированиеКириллицы – маскирование кириллических символов современных алфавитов славянских языков.
      Настройка изменяется в функции "НастройкаМаскированиеКириллицы" (по умолчанию отключена).
      Не рекомендуется к использованию, так как влияет на производительность.
      Маскирование специальных символов из диапазона [0x0000, 0x001f] выполняется в не зависимости от настройки.

    НеявноеПриведениеПримитивныхЗначенийКлюча – неявное приведение примитивных значений ключей соответствий к строке.
      Настройка изменяется в функции "НеявноеПриведениеПримитивныхЗначенийКлюча" (по умолчанию отключена).


Альтернативный режим:
    - Не поддерживается форматирование, как во входящих, так и в исходящих данных;
    - Сериализация ссылочных типов в строковое служебное представление.


Приятности:
  Парсер:
    - Устойчивость к некорректным данным и не подверженность injection атакам;
    - Продвинутый синтаксический анализатор (указывает место и тип ошибки в данных);
    - Поддержка форматирования во входящих данных (только стандартный режим);
    - Безопасный разбор форматирования - незамаскированные символы форматирования в строковых значениях не будут утеряны;
    - Поддержка строк в одинарных и в двойных кавычках;
    - Автоматическое приведение объекта к структуре или соответствию в зависимости от имен свойств [1];
    - Автоматическое преобразование к типу Дата строки вида "9999-99-99T99:99:99Z";
    - Автоматическое преобразование к типу УникальныйИдентификатор строки вида "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
    - Автоматического определение режима (стандартного или альтернативного) входящих данных;
    - Автоматического определение необходимости отсечения представления ссылок;
    - Однозначная идентификация ссылок (только альтернативный режим).
  Сериализатор:
    - Поддержка форматирования исходящих данных (только стандартный режим);
    - Широкий состав сериализуемых типов данных, в том числе ссылок;
    - Автоматическое приведение значений ключей соответствий к строковому представлению в формате 1С [2];
    - Автоматическое преобразование неподдерживаемых типов к строке;
    - Нечувствительность к локализации [3].
----
 1 Если все имена свойства входящего объекта могут быть использованы как ключи структуры, 
   то такой объект будет автоматически приведен к структуре, а не к соответствию. Управляется настройкой.
 2 Управляется настройкой.
 3 При сериализации некоторых типов, исходящие объекты которых имеют обязательные свойства, 
   такие представления и имена таких свойств всегда имеют русскую локализацию.


Неприятности:
    - Нестандартно форматированный код (Alt+Shift+F в помощь) на гране читаемости; 
    - Сериализатор ориентирован, на средние-крупные пакеты данных.

Сериализуемые типы:
  Сервер, толстый клиент, тонкий клиент, веб-клиент:
    - Неопределено;
    - Null;
    - Примитивные типы (все);
    - Универсальные коллекции значений (клиентские);
    - УникальныйИдентификатор;
    - ДвоичныеДанные;
    - Картинка.
  Сервер, толстый клиент:
    - Универсальные коллекции значений (серверные);
    - ЛюбаяСсылка;
    - Запрос;
    - РезультатЗапроса;
    - ВыборкаИзРезультатаЗапроса;
    - ПостроительЗапроса;
    - ПостроительОтчета;
    - ХранилищеЗначения.
  Сервер:
    - ДанныеФормыКоллекция;
    - ДанныеФормыСтруктураСКоллекцией;
    - ДанныеФормыДерево.

Порядок сериализации типов:
    - Неопределено - сериализуется как Null;
    - Null - согласно стандарту;
    - Примитивные типы - согласно стандарту;
    - Массивы и COMSafeArray - массив, согласно стандарту:
        [ Значение, ... ]

    - Структуры и соответствия – объект, согласно стандарту;
        { Ключ:Значение, ... }

    - СписокЗначений - массив объектов с тремя свойствами "Значение", "Представление" и "Пометка";
        [ { "Значение":Значение, "Представление":Представление, "Пометка":Пометка }, ... ]

    - КлючИЗначение - объект с двумя свойствами "Ключ" и "Значени";
        { "Ключ":Ключ, "Значение":Значение }

    - ТаблицаЗначений - массив объектов: 
        [ { Колонка:Значение, ... }, ... ]

    - ДеревоЗначений - массив объектов с обязательным свойством "Строки":
        [ { Колонка:Значение, ... , "Строки":[ { Колонка:Значение, ... , "Строки":[ ... ] } , ... ] }, ... ]

    - УникальныйИдентификатор - приведение к строке вида "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";

    - ЛюбаяСсылка:
      - Стандартный режим - получение уникального идентификатора ссылки (в том числе и для перечислений) и его сериализация;
      - Альтернативный режим - приведение к строке служебного вида "¦ref¦ ... ¦";

      При сериализации ссылок в режиме автоматически передачи не только сериализованного значения ссылки, 
      но и ее представления. Каждая ссылка передается как объект с двумя свойствами "Ссылка" и "Представление";
        { "Ссылка":Ссылка, "Представление":Представление }

    - Запрос - автоматически выполняется и сериализуется как таблица значений;
    - РезультатЗапроса - сериализуется как таблица значений;
    - ВыборкаИзРезультатаЗапроса - сериализуется как структура значений текущей запись результата запроса;
    - ПостроительЗапроса - автоматически выполняется и сериализуется как таблица значений;
    - ПостроительОтчета - автоматически выполняется и сериализуется как таблица значений;
    - ДанныеФормыКоллекция - сериализуется как таблица значений;
    - ДанныеФормыСтруктураСКоллекцией - сериализуется как таблица значений;
    - ДанныеФормыДерево - сериализуется как дерево значений;
    - ДвоичныеДанные - кодируется по алгоритму base64 [1] и сериализуется как строка;
    - Картинка - автоматически преобразуется и сериализуется как двоичные данные;
    - ХранилищеЗначения - автоматически извлекается сохраненное значение и сериализуется в зависимости от типа извлеченного значения.
----
 1 Следуя рекомендациям стандарта, сериализатор при кодировании по алгоритму base64, не добавляет переводы строк 
   в результирующие данные (подробнее см. <http://tools.ietf.org/html/rfc4648#section-3.1>).

Производительность:
  Производительность парсера исключительно зависит от набора входящих данных, а также от наличия форматирования.
  Наихудшим вариантом является форматированный массив чисел, наилучшим - неформатированный массив строк.

  Intel Core 2 Duo T5870 @ 2GHz - форматированный массив со всеми приблизительно равномерно встречающимися типами данных:
    Парсер:      35 Кбайт/с.
    Сериализатор:  165 Кбайт/с.

Примечание:
  Мало комментариев - без комментариев.

Всем удачного программирования :)