☰

# packages/docutils/rstast

Theme:

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

Search:
Source Edit

This module implements an AST for the reStructuredText parser.

# Imports

strutils, json, assertions

# Types

    FileIndex = distinct int32

  Source Edit

    PRstNode = ref RstNode

  an RST node Source Edit

    RstNode {.acyclic, final.} = object
      case kind*: RstNodeKind    ## the node's kind
      of rnLeaf, rnSmiley:
        text*: string            ## string that is expected to be displayed
      of rnEnumList:
        labelFmt*: string        ## label format like "(1)"
      of rnLineBlockItem:
        lineIndent*: string      ## a few spaces or newline at the line beginning
      of rnAdmonition:
        adType*: string          ## admonition type: "note", "caution", etc. This
                                 ## text will set the style and also be displayed
      of rnOverline, rnHeadline, rnMarkdownHeadline:
        level*: int              ## level of headings starting from 1 (main
                                 ## chapter) to larger ones (minor sub-sections)
                                 ## level=0 means it's document title or subtitle
      of rnFootnote, rnCitation, rnOptionListItem:
        order*: int              ## footnote order (for auto-symbol footnotes and
                                 ## auto-numbered ones without a label)
      of rnMarkdownBlockQuoteItem:
        quotationDepth*: int     ## number of characters in line prefix
      of rnRstRef, rnPandocRef, rnSubstitutionReferences, rnInterpretedText,
         rnField, rnInlineCode, rnCodeBlock, rnFootnoteRef:
        info*: TLineInfo         ## To have line/column info for warnings at
                                 ## nodes that are post-processed after parsing
      of rnNimdocRef:
        tooltip*: string
      of rnTable, rnGridTable, rnMarkdownTable:
        colCount*: int           ## Number of (not-united) cells in the table
      of rnTableRow:
        endsHeader*: bool        ## Is last row in the header of table?
      of rnTableHeaderCell, rnTableDataCell:
        span*: int               ## Number of table columns that the cell occupies
      else:
        nil
      anchor*: string            ## anchor, internal link target
                                 ## (aka HTML id tag, aka Latex label/hypertarget)
      sons*: RstNodeSeq          ## the node's sons

  AST node (result of RST parsing) Source Edit

    RstNodeKind = enum
      rnInner, rnHeadline, rnOverline, rnMarkdownHeadline, rnTransition,
      rnParagraph, rnBulletList, rnBulletItem, rnEnumList, rnEnumItem, rnDefList,
      rnMdDefList, rnDefItem, rnDefName, rnDefBody, rnFieldList, rnField,
      rnFieldName, rnFieldBody, rnOptionList, rnOptionListItem, rnOptionGroup,
      rnOption, rnOptionString, rnOptionArgument, rnDescription, rnLiteralBlock,
      rnMarkdownBlockQuote, rnMarkdownBlockQuoteItem, rnLineBlock, rnLineBlockItem,
      rnBlockQuote, rnTable, rnGridTable, rnMarkdownTable, rnTableRow,
      rnTableHeaderCell, rnTableDataCell, rnFootnote, rnCitation, rnFootnoteGroup,
      rnStandaloneHyperlink, rnHyperlink, rnRstRef, rnPandocRef, rnInternalRef,
      rnFootnoteRef, rnNimdocRef, rnDirective, rnDirArg, rnRaw, rnTitle, rnContents,
      rnImage, rnFigure, rnCodeBlock, rnAdmonition, rnRawHtml, rnRawLatex,
      rnContainer, rnIndex, rnSubstitutionDef, rnInlineCode, rnCodeFragment,
      rnUnknownRole, rnSub, rnSup, rnIdx, rnEmphasis, rnStrongEmphasis,
      rnTripleEmphasis, rnInterpretedText, rnInlineLiteral, rnInlineTarget,
      rnSubstitutionReferences, rnSmiley, rnDefaultRole, rnLeaf

  the possible node kinds of an PRstNode Source Edit

    RstNodeSeq = seq[PRstNode]

  Source Edit

    TLineInfo = object
      line*: uint16
      col*: int16
      fileIndex*: FileIndex

  Source Edit

# Procs

    proc `==`(a, b: FileIndex): bool {.borrow, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc add(father, son: PRstNode) {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc add(father: PRstNode; s: string) {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc addIfNotNil(father, son: PRstNode) {....raises: [], tags: [], forbids: [].}

  Source Edit

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

  Source Edit

    proc len(n: PRstNode): int {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc newRstLeaf(s: string): PRstNode {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc newRstNode(kind: RstNodeKind; info: TLineInfo; sons: seq[PRstNode] = @[]): PRstNode {.
        ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc newRstNode(kind: RstNodeKind; s: string): PRstNode {....deprecated,
        raises: [], tags: [], forbids: [].}

  Deprecated
  Source Edit

    proc newRstNode(kind: RstNodeKind; sons: seq[PRstNode] = @[]; anchor = ""): PRstNode {.
        ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc renderRstToJson(node: PRstNode): string {....raises: [], tags: [], forbids: [].}

  Writes the given RST node as JSON that is in the form

      {
        "kind":string node.kind,
        "text":optional string node.text,
        "level":optional int node.level,
        "sons":optional node array
      }

  Source Edit

    proc renderRstToRst(n: PRstNode; result: var string) {....raises: [Exception],
        tags: [RootEffect], forbids: [].}

  renders `n` into its string representation and appends to `result`. Source Edit

    proc renderRstToText(node: PRstNode): string {....raises: [], tags: [], forbids: [].}

  minimal text representation of markup node Source Edit

    proc treeRepr(node: PRstNode; indent = 0): string {....raises: [], tags: [],
        forbids: [].}

  Writes the parsed RST `node` into an AST tree with compact string representation in the format (one line per every sub-node): `indent - kind - [text|level|order|adType] - anchor (if non-zero)` (suitable for debugging of RST parsing). Source Edit