packages/docutils/rst

Source Edit

This module implements a reStructuredText (RST) and Markdown parser. User's manual on supported markup syntax and command line usage can be found in Nim-flavored Markdown and reStructuredText.

• See also Nim DocGen Tools Guide for handling of .nim files.
• See also packages/docutils/rstgen module to know how to generate HTML or Latex strings (for embedding them into custom documents).

Choice between Markdown and RST as well as optional additional features are turned on by passing options: RstParseOptions to proc rstParse.

Imports

os, strutils, rstast, dochelpers, enumutils, algorithm, lists, sequtils, miscdollars, tables, strscans, rstidx, highlite

Types

EParseError = object of ValueError

Source Edit

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

Source Edit

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

returns where .html or .idx file should be found by its relative path; linkRelPath is a prefix to be added before a link anchor from such file Source Edit

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

Source Edit

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

what to do in case of an error Source Edit

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\'"

the possible messages Source Edit

PRstSharedState = ref RstSharedState

Source Edit

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

Source Edit

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.

options for the RST parser Source Edit

RstParseOptions = set[RstParseOption]

Source Edit

Consts

ColRstInit = 0

Initial column number for standalone RST text (Nim global reporting adds ColOffset=1) Source Edit

ColRstOffset = 1

1: a replica of ColOffset for internal use Source Edit

LineRstInit = 1

Initial line number for standalone RST text Source Edit

Procs

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

Adds an anchor refn, which follows the rule arNim (i.e. a symbol in *.nim file) Source Edit

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

Returns index of filename, adding it if it has not been used before Source Edit

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

Source Edit

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

Source Edit

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

Source Edit

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

Source Edit

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

Source Edit

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

Source Edit

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

Returns the value of a specific rnField node.

This proc will assert if the node is not of the expected type. The empty string will be returned as a minimum. Any value in the rst will be stripped form leading/trailing whitespace.

Source Edit

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

Source Edit

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

Source Edit

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

Records titles in node mainNode and orders footnotes. Source Edit

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

Makes pass 2 of RST parsing. Resolves substitutions and anchor aliases, groups footnotes. Takes input node n and returns the same node with recursive substitutions in n.sons to result. Source Edit

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

Print warnings using info, i.e. in 2nd-pass warnings for footnotes/substitutions/references or from rstgen.nim. Source Edit

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

Source Edit

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, IOError, KeyError],
    tags: [RootEffect, ReadDirEffect, ReadIOEffect, ReadEnvEffect], forbids: [].}

Parses the whole text. The result is ready for rstgen.renderRstToOut, note that 2nd tuple element should be fed to initRstGenerator argument filenames (it is being filled here at least with filename and possibly with other files from RST .. include:: statement). Source Edit

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

Parses an RST fragment. The result should be further processed by preparePass2 and resolveSubs (which is pass 2). Source Edit

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

Source Edit

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

Source Edit

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

returns which message class k belongs to. Source Edit