doctools::toc::export::json

ИМЯ

doctools::toc::export::json — плагин экспорта в JSON

Содержание

Содержание
Краткое описание
Описание
API
Представление оглавлений в JSON
Конфигурация
Формат сериализации оглавления
Ошибки, идеи, отзывы
Категория
Авторские права

КРАТКОЕ ОПИСАНИЕ

package require Tcl 8.5 9
package require doctools::toc::export::json ?0.2?
package require textutil::adjust

export serial configuration

ОПИСАНИЕ

Этот пакет реализует плагин экспорта оглавлений doctools для создания разметки JSON.

Это внутренний пакет doctools, предназначенный для использования пакетами управления более высокого уровня, работающими с оглавлениями, в частности doctools::toc::export, диспетчером экспорта.

Его можно использовать из обычного интерпретатора, однако для этого потребуются обходные решения, поэтому такой способ не рекомендуется. Правильный способ использовать эту функциональность — обратиться к пакету doctools::toc::export и предоставляемым им объектам диспетчера экспорта.

API

API, предоставляемый этим пакетом, соответствует спецификации API плагинов экспорта doctoc версии 2.

export serial configuration

Эта команда принимает каноническую сериализацию оглавления, описанную в разделе Формат сериализации оглавления и содержащуюся в serial, а также configuration — словарь — и создает разметку JSON, кодирующую это оглавление. Созданная строка возвращается в качестве результата команды.

Представление оглавлений в JSON

Формат JSON, используемый для оглавлений, представляет собой прямое преобразование формата сериализации оглавления: словари Tcl отображаются в объекты JSON, а списки Tcl — в массивы JSON. Например, сериализация Tcl

doctools::toc {
    items {
        {reference {
	    desc {DocTools - Tables of Contents}
	     id introduction.man
	     label doctools::toc::introduction
	}}
	{division {
	     id processing.man
	     items {
	         {reference {
		     desc {doctoc serialization utilities}
		     id structure.man
		     label doctools::toc::structure
		 }}
		 {reference {
		     desc {Parsing text in doctoc format}
		     id parse.man
		     label doctools::toc::parse
		 }}
	     }
             label Processing
        }}
    }
    label {Table of Contents}
    title TOC
}

эквивалентна строке JSON

{
    "doctools::toc" : {
        "items" : [{
            "reference" : {
                "desc"  : "DocTools - Tables of Contents",
                "id"    : "introduction.man",
                "label" : "doctools::toc::introduction"
            }
        },{
            "division" : {
                "id"    : "processing.man",
                "items" : [{
                    "reference" : {
                        "desc"  : "doctoc serialization utilities",
                        "id"    : "structure.man",
                        "label" : "doctools::toc::structure"
                    }
                },{
                    "reference" : {
                        "desc"  : "Parsing text in doctoc format",
                        "id"    : "parse.man",
                        "label" : "doctools::toc::parse"
                    }
                }],
                "label" : "Processing"
            }
        }],
        "label" : "Table of Contents",
        "title" : "TOC"
    }
}

Конфигурация

Плагин экспорта в JSON распознает следующие переменные конфигурации и изменяет свое поведение в соответствии с их значениями.

boolean indented

Если этот флаг установлен, плагин разбивает сгенерированный код JSON на строки и форматирует его отступами в соответствии с его внутренней структурой, располагая каждый ключ словаря на отдельной строке.

Если этот флаг не установлен (по умолчанию), весь объект JSON записывается в одну строку с минимальными пробелами между элементами.
boolean aligned

Если этот флаг установлен, генератор выравнивает значения ключей словаря по вертикали, создавая аккуратное табличное представление. Для этого флаг indented также должен быть установлен.

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

Примечание: этот плагин игнорирует стандартные переменные конфигурации user, format, file и map, а также их значения.

Формат сериализации оглавления

В этом разделе описывается формат, используемый пакетами doctools версии 2 для сериализации оглавлений в неизменяемые значения, предназначенные для передачи, сравнения и т. д.

Различаются обычная и каноническая сериализации. У оглавления может быть несколько обычных сериализаций, но только одна из них может быть канонической.

обычная сериализация
1. Сериализация любого оглавления представляет собой вложенный словарь Tcl.
2. Этот словарь содержит один ключ — doctools::toc — и соответствующее ему значение. В этом значении содержится содержимое оглавления.
3. Содержимое оглавления представляет собой словарь Tcl, в котором указаны заголовок оглавления, метка и его элементы. Значимые ключи и соответствующие им значения:
  - title
    
    Значение — строка, содержащая заголовок оглавления.
  - label
    
    Значение — строка, содержащая метку оглавления.
  - items
    
    Значение — список Tcl, содержащий элементы оглавления в порядке их отображения.
    
    Каждый элемент представляет собой список Tcl, содержащий тип элемента и его описание именно в таком порядке. Иначе говоря, это словарь Tcl с одним ключом — типом элемента — и соответствующим ему описанием.
    
    Допустимы два типа элементов и следующие описания для них:
    - reference
      
      Этот элемент описывает одну запись оглавления, ссылающуюся на отдельный документ. Для этого его значение представляет собой словарь Tcl, содержащий идентификатор связанного документа, метку и более подробное текстовое описание, которое можно связать с записью. Значимые ключи и соответствующие им значения:
      - id
        
        Значение — строка, содержащая идентификатор документа, связанного с записью.
      - label
        
        Значение — строка, содержащая метку этой записи. Эта строка также служит идентификатором записи. Записи (ссылки и разделы) в одном списке не могут иметь одинаковые метки.
      - desc
        
        Значение — строка, содержащая более подробное описание этой записи.
    - division
      
      Этот элемент описывает группу записей оглавления, формируя иерархию записей. Для этого его значение представляет собой словарь Tcl, содержащий метку группы, необязательный идентификатор документа для всей группы и список записей группы. Значимые ключи и соответствующие им значения:
      - id
        
        Значение — строка, содержащая идентификатор документа, связанного со всей группой. Этот ключ необязателен.
      - label
        
        Значение — строка, содержащая метку группы. Эта строка также служит идентификатором записи. Записи (ссылки и разделы) в одном списке не могут иметь одинаковые метки.
      - items
        
        Значение — список Tcl, содержащий элементы группы в порядке их отображения. Этот список имеет ту же структуру, что и значение ключевого слова items, используемое для описания всего оглавления (см. выше). Так завершается рекурсивное определение структуры: разделы содержат элементы того же типа, что и все оглавление, включая другие разделы.
каноническая сериализация

Каноническая сериализация оглавления имеет формат, описанный в предыдущем пункте, и дополнительно удовлетворяет приведенным ниже ограничениям, благодаря которым она является единственной среди всех возможных сериализаций этого оглавления.
1. Ключи во всех вложенных словарях Tcl отсортированы по возрастанию в порядке сортировки словарей, используемом встроенной командой Tcl lsort -increasing -dict.

Ошибки, идеи, отзывы

В этом документе и описываемом в нем пакете неизбежно содержатся ошибки и другие проблемы. Пожалуйста, сообщайте о них в категории doctools системы отслеживания ошибок Tcllib. Также сообщайте о любых идеях по улучшению пакета и/или документации.

Предлагая изменения кода, пожалуйста, прикладывайте унифицированные различия, то есть вывод команды diff -u.

Кроме того, предпочтительно прикладывать вложения, а не вставлять исправления в текст. Чтобы добавить вложение, сразу после создания заявки откройте форму Редактировать, а затем нажмите самую левую кнопку на дополнительной панели навигации.

КАТЕГОРИЯ

Плагин форматирования текста

АВТОРСКИЕ ПРАВА

Licensed under the BSD license
https://core.tcl-lang.org/tcllib/doc/trunk/embedded/md/tcllib/files/modules/doctools2toc/toc_export_json.md