rst (original) (raw)

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, enumutils, algorithm, lists, sequtils, tables, strscans, dochelpers, rstidx, rstast, miscdollars, highlite, assertions, syncio

Types

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 fileSource 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 messagesSource Edit

RstParseOption = enum roSupportSmilies,
roSupportRawDirective,

roSupportMarkdown,
roPreferMarkdown,

roNimFile,

roSandboxDisabled

options for the RST parserSource Edit

Consts

ColRstInit = 0

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

Procs

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 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: [].}

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