packages/docutils/rst

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.

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

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  

Made with Nim. Generated: 2024-11-16 09:56:34 UTC