packages/docutils/rst

Этот модуль реализует парсер reStructuredText (RST) и Markdown. Руководство пользователя по поддерживаемому синтаксису разметки и использованию в командной строке можно найти в Руководстве по Nim-совместимым Markdown и reStructuredText.

• См. также Руководство по Nim DocGen для обработки файлов .nim.
• См. также модуль packages/docutils/rstgen, чтобы узнать, как генерировать строки HTML или Latex (для их встраивания в пользовательские документы).

Выбор между Markdown и RST, а также дополнительные опции, включаются путём передачи options: RstParseOptions в процедуру rstParse.

Импорты

os, strutils, enumutils, algorithm, списки, sequtils, таблицы, strscans, dochelpers, rstidx, rstast, miscdollars, highlite

Типы

EParseError = object of ValueError

Исходный код Редактировать

FindFileHandler = proc (filename: string): string {.closure, ...gcsafe.}

Исходный код Редактировать

FindRefFileHandler = proc (targetRelPath: string): tuple[targetPath: string,
    linkRelPath: string] {.closure, ...gcsafe.}

возвращает местоположение файла .html или .idx по его относительному пути; linkRelPath — префикс, добавляемый перед якорем ссылки из такого файла Исходный код Редактировать

MsgClass = enum
  mcHint = "Hint", mcWarning = "Warning", mcError = "Error"

Исходный код Редактировать

MsgHandler = proc (filename: string; line, col: int; msgKind: MsgKind;
                   arg: string) {.closure, ...gcsafe.}

действия в случае ошибки Исходный код Редактировать

MsgKind = enum
  meCannotOpenFile = "cannot open \'$1\'", meExpected = "\'$1\' expected",
  meMissingClosing = "$1",
  meGridTableNotImplemented = "grid table is not implemented",
  meMarkdownIllformedTable = "illformed delimiter row of a Markdown table",
  meIllformedTable = "Illformed table: $1",
  meNewSectionExpected = "new section expected $1",
  meGeneralParseError = "general parse error",
  meInvalidDirective = "invalid directive: \'$1\'",
  meInvalidField = "invalid field: $1",
  meFootnoteMismatch = "mismatch in number of footnotes and their refs: $1",
  mwRedefinitionOfLabel = "redefinition of label \'$1\'",
  mwUnknownSubstitution = "unknown substitution \'$1\'",
  mwAmbiguousLink = "ambiguous doc link $1",
  mwBrokenLink = "broken link \'$1\'",
  mwUnsupportedLanguage = "language \'$1\' not supported",
  mwUnsupportedField = "field \'$1\' not supported",
  mwRstStyle = "RST style: $1",
  mwUnusedImportdoc = "importdoc for \'$1\' is not used",
  meSandboxedDirective = "disabled directive: \'$1\'"

возможные сообщения Исходный код Редактировать

PRstSharedState = ref RstSharedState

Исходный код Редактировать

RstFileTable = object
  filenameToIdx*: Table[string, FileIndex]
  idxToFilename*: seq[string]

Исходный код Редактировать

RstParseOption = enum
  roSupportSmilies,         ## make the RST parser support smilies like ``:)``
  roSupportRawDirective,    ## support the ``raw`` directive (don't support
                             ## it for sandboxing)
  roSupportMarkdown,        ## support additional features of Markdown
  roPreferMarkdown,         ## parse as Markdown (keeping RST as "extension"
                             ## to Markdown) -- implies `roSupportMarkdown`
  roNimFile,                ## set for Nim files where default interpreted
                             ## text role should be :nim:
  roSandboxDisabled          ## this option enables certain options
                             ## (e.g. raw, include, importdoc)
                             ## which are disabled by default as they can
                             ## enable users to read arbitrary data and
                             ## perform XSS if the parser is used in a web
                             ## app.

опции для парсера RST Исходный код Редактировать

RstParseOptions = set[RstParseOption]

Исходный код Редактировать

Константы

ColRstInit = 0

Начальный номер столбца для автономного текста RST (глобальный вывод Nim добавляет ColOffset=1) Исходный код Редактировать

ColRstOffset = 1

1: копия ColOffset для внутреннего использования Исходный код Редактировать

LineRstInit = 1

Начальный номер строки для автономного текста RST Исходный код Редактировать

Процедуры

proc addAnchorNim(s: var PRstSharedState; external: bool; refn: string;
                  tooltip: string; langSym: LangSymbol; priority: int;
                  info: TLineInfo; module: FileIndex) {....raises: [], tags: [],
    forbids: [].}

Добавляет якорь refn, который следует правилу arNim (т.е. символ в файле *.nim). Исходный код Редактировать

proc addFilename(s: PRstSharedState; file1: string): FileIndex {....raises: [],
    tags: [], forbids: [].}

Возвращает индекс имени файла, добавив его, если он ранее не использовался. Исходный код Редактировать

proc addNodes(n: PRstNode): string {....raises: [], tags: [], forbids: [].}

Исходный код Редактировать

proc completePass2(s: PRstSharedState) {....raises: [ValueError, Exception],
    tags: [RootEffect], forbids: [].}

Исходный код Редактировать

proc defaultFindFile(filename: string): string {....raises: [],
    tags: [ReadDirEffect], forbids: [].}

Исходный код Редактировать

proc defaultFindRefFile(filename: string): (string, string) {....raises: [],
    tags: [], forbids: [].}

Исходный код Редактировать

proc defaultMsgHandler(filename: string; line, col: int; msgkind: MsgKind;
                       arg: string) {....raises: [ValueError, EParseError, IOError],
                                      tags: [WriteIOEffect], forbids: [].}

Исходный код Редактировать

proc getArgument(n: PRstNode): string {....raises: [], tags: [], forbids: [].}

Исходный код Редактировать

proc getFieldValue(n: PRstNode): string {....raises: [], tags: [], forbids: [].}

Возвращает значение узла rnField.

Процедура будет проверять соответствие типа узла. В качестве минимума возвращается пустая строка. Любое значение из rst будет очищено от начальных и конечных пробелов.

Исходный код Редактировать

proc getFieldValue(n: PRstNode; fieldname: string): string {....gcsafe, raises: [],
    tags: [], forbids: [].}

Исходный код Редактировать

proc newRstSharedState(options: RstParseOptions; filename: string;
                       findFile: FindFileHandler;
                       findRefFile: FindRefFileHandler; msgHandler: MsgHandler;
                       hasToc: bool): PRstSharedState {....raises: [], tags: [],
    forbids: [].}

Исходный код Редактировать

proc preparePass2(s: var PRstSharedState; mainNode: PRstNode; importdoc = true) {.
    ...raises: [Exception, ValueError, KeyError], tags: [RootEffect, ReadIOEffect],
    forbids: [].}

Записывает заголовки в узел mainNode и упорядочивает сноски. Исходный код Редактировать

proc resolveSubs(s: PRstSharedState; n: PRstNode): PRstNode {.
    ...raises: [ValueError, Exception, KeyError],
    tags: [ReadEnvEffect, RootEffect], forbids: [].}

Выполняет второй этап разбора RST. Разрешает подстановки и псевдонимы якорей, группирует сноски. Принимает входной узел n и возвращает тот же узел с рекурсивными подстановками от n.sons до result. Исходный код Редактировать

proc rstMessage(filenames: RstFileTable; f: MsgHandler; info: TLineInfo;
                msgKind: MsgKind; arg: string) {.
    ...raises: [ValueError, Exception], tags: [RootEffect], forbids: [].}

Выводит предупреждения, используя info, т.е. предупреждения во втором проходе для сносок/подстановок/ссылок или от rstgen.nim. Исходный код Редактировать

proc rstnodeToRefname(n: PRstNode): string {....raises: [], tags: [], forbids: [].}

Исходный код Редактировать

proc rstParse(text, filename: string; line, column: int;
              options: RstParseOptions; findFile: FindFileHandler = nil;
              findRefFile: FindRefFileHandler = nil;
              msgHandler: MsgHandler = nil): tuple[node: PRstNode,
    filenames: RstFileTable, hasToc: bool] {.
    ...raises: [Exception, ValueError, KeyError],
    tags: [RootEffect, ReadIOEffect, ReadEnvEffect], forbids: [].}

Парсит весь text. Результат готов к rstgen.renderRstToOut, обратите внимание, что второй элемент кортежа должен быть передан в аргумент initRstGenerator filenames (он заполняется здесь, по крайней мере, filename и, возможно, другими файлами из RST .. include:: утверждение). Исходный код Редактировать

proc rstParsePass1(fragment: string; line, column: int;
                   sharedState: PRstSharedState): PRstNode {.
    ...raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}

Парсит RST fragment. Результат должен быть далее обработан функциями preparePass2 и resolveSubs (это второй этап). Исходный код Редактировать

proc safeProtocol(linkStr: var string): string {....raises: [], tags: [],
    forbids: [].}

Исходный код Редактировать

proc setCurrFilename(s: PRstSharedState; file1: string) {....raises: [], tags: [],
    forbids: [].}

Исходный код Редактировать

proc whichMsgClass(k: MsgKind): MsgClass {....raises: [], tags: [], forbids: [].}

Возвращает класс сообщения, к которому относится k. Исходный код Редактировать