packages/docutils/dochelpers

Интеграционные помощники между docgen.nim и rst.nim.

Функция toLangSymbol(linkText) генерирует подпись docLink типа LangSymbol в rst.nim, в то время как match(generated, docLink) сопоставляет её с generated, сгенерированной из PNode с помощью docgen.rst.

Импорты

rstast, strutils

Типы

LangSymbol = object
  symKind*: string           ## "proc", "const", "type", etc
  symTypeKind*: string       ## ""|enum|object|tuple -
                             ## valid only when `symKind == "type"`
  name*: string              ## plain symbol name without any parameters
  generics*: string          ## generic parameters (without brackets)
  isGroup*: bool             ## is LangSymbol a group with overloads?
  parametersProvided*: bool  ## to disambiguate `proc f`_ and `proc f()`_
  parameters*: seq[tuple[name: string, `type`: string]] ## name-type seq, e.g. for proc
  outType*: string           ## result type, e.g. for proc

подпись символа в Nim Source Edit

Процедуры

proc `$`(s: LangSymbol): string {....raises: [ValueError], tags: [], forbids: [].}

Source Edit

proc langSymbolGroup(kind: string; name: string): LangSymbol {.
    ...raises: [ValueError], tags: [], forbids: [].}

Source Edit

proc match(generated: LangSymbol; docLink: LangSymbol): bool {....raises: [],
    tags: [], forbids: [].}

Возвращает true, если generated может быть целевым объектом для docLink. Если generated представляет собой группу перегрузок, то сравниваются только symKind и name. Source Edit

func nimIdentBackticksNormalize(s: string): string {....raises: [], tags: [],
    forbids: [].}

Нормализует строку s как идентификатор Nim.

В отличие от nimIdentNormalize удаляет пробелы и обратные кавычки.

Предупреждение: Не выполняется проверка (например, что идентификаторы не могут начинаться с цифр или '_', или что количество обратных кавычек чётное).

Пример:

doAssert nimIdentBackticksNormalize("Foo_bar") == "Foobar"
doAssert nimIdentBackticksNormalize("FoO BAr") == "Foobar"
doAssert nimIdentBackticksNormalize("`Foo BAR`") == "Foobar"
doAssert nimIdentBackticksNormalize("` Foo BAR `") == "Foobar"
# not a valid identifier:
doAssert nimIdentBackticksNormalize("`_x_y`") == "_xy"

Source Edit

proc toLangSymbol(linkText: PRstNode): LangSymbol {....raises: [ValueError],
    tags: [], forbids: [].}

Анализирует linkText в более структурированную форму с помощью автомата состояний.

Эта процедура предназначена для поддержки синтаксиса ссылок с операторами даже без экранированных обратных кавычек внутри:

`proc *`_
`proc []`_

Эта процедура должна синхронизироваться с процедурой renderTypes из compiler/typesrenderer.nim.

Source Edit