# packages/docutils/rst

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
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

# 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, 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

    proc rstParsePass1(fragment: string; line, column: int;
                       sharedState: PRstSharedState): PRstNode {.
        ...raises: [Exception, ValueError], tags: [RootEffect], 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