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.
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
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
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
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 defaultFindFile(filename: string): string {....raises: [], tags: [ReadDirEffect], 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 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 safeProtocol(linkStr: var string): string {....raises: [], tags: [], forbids: [].}
- Source Edit
proc whichMsgClass(k: MsgKind): MsgClass {....raises: [], tags: [], forbids: [].}
- returns which message class k belongs to. Source Edit