このページの内容

Guidedog / ドキュメント 0.2.0

readers/rst

Package rst reads reStructuredText as the Docutils markup specification defines it, implemented independently. It owns lines, block structure, and directives; inline markup and reference resolution live in the inline subpackage.

Types

rst.Arg_Rule :: enum u8

None

Optional

Required

rst.Content_Rule :: enum u8

None

Optional

Required

rst.Dir_Opt :: struct

spec: Opt_Spec

lines: []Line

the value: the rest of the marker line, then continuation lines.

span: gd.Source_Span

rst.Dir_Spec :: struct

name: string

kind: Dir_Kind

arg: Arg_Rule

final_ws: bool

content: Content_Rule

opts: Opt_Set

value: gd.Admonition_Kind

rst.Directive :: struct

spec: ^Dir_Spec

span: gd.Source_Span

name_span: gd.Source_Span

arg: []Line

argument lines, trimmed; empty when there is no argument.

opts: [MAX_OPTIONS]Dir_Opt

nopts: int

content: []Line

sections: bool

subst: bool

inside a substitution definition.

ext: ^Directive_Handler

a dialect’s handler, or nil for a standard directive.

arg_block: []Line

the argument lines with their relative indentation.

subst_name: string

the name of the substitution definition it is in, as written.

rst.Directive_Handler :: struct

name: string

compared case-insensitively, as directive names are.

arg: Arg_Rule

final_ws: bool

the last argument may contain white space.

content: Content_Rule

options: []Opt_Spec

run: Directive_Proc

rst.Directive_Proc :: #type proc(p: ^Parser, d: ^Directive, user: rawptr)

Directive_Proc runs a parsed directive. user is Extension.user.

rst.Directive_Shape :: struct

Directive_Shape tells a host how a directive takes its parts.

arg: Arg_Rule

final_ws: bool

the last argument may contain white space.

content: Content_Rule

options: []Opt_Spec

rst.Extension :: struct

directives: []Directive_Handler

lookup: proc(name: string, user: rawptr) -> ^Directive_Handler

lookup, when set, finds handlers the table does not list, such as names that depend on reader state (a default domain). It returns nil for unknown names.

roles: []Role_Handler

role: Role_Proc

role, when set, is offered every role the table does not list.

begin: Hook_Proc

before the main source’s blocks (reader state).

prologue: Hook_Proc

prologue runs after the main source’s leading field lines, where Sphinx inserts rst_prolog: after a document’s bibliographic fields, else before everything.

end: Hook_Proc

after them, before sections close (e.g. an epilogue).

substitution: proc(name: string, user: rawptr) -> (text: string, ok: bool)

substitution, when set, supplies default substitutions: resolution offers it each reference whose name no definition in the document has (see rst_inline.Substitution_Hook). It runs after parsing, with the extension’s user.

user: rawptr

rst.Frame :: struct

src: gd.Source_Id

text: string

tab: int

rst.Hook_Proc :: #type proc(p: ^Parser, user: rawptr)

Hook_Proc runs at a fixed point of the read, with the reader’s state.

rst.Host :: struct

Host procedures receive Host.user. Lines are views of the current source (p.src), as the block parser’s are, so every node keeps exact spans.

body: proc(p: ^Parser, lines: []Line, sections: bool, each: gd.Text, user: rawptr)

body parses nested body content of the open node; sections allows headings to make sections, and each, when set, gives these classes to every top-level element (the class directive).

inline: proc(p: ^Parser, lines: []Line, user: rawptr)

inline parses inline content of the open node.

items: proc(p: ^Parser, lines: []Line, user: rawptr) -> (items: [][]Line, starts: []int, ok: bool)

items splits lines that hold one bullet list into its items』 content, with where each item starts in lines (list-table, with the host’s list syntax); ok is false when the lines are not one bullet list.

user: rawptr

rst.Host_Directive :: struct

Host_Directive is a directive the host has split into its parts.

name: string

name_span: gd.Source_Span

span: gd.Source_Span

arg: []Line

the argument lines; empty when there is none.

options: []Host_Option

content: []Line

sections: bool

the directive stands where sections are allowed.

rst.Host_Option :: struct

Host_Option is a directive option as the host wrote it: its name and value lines.

name: string

value: []Line

span: gd.Source_Span

rst.Hosted_Result :: enum u8

Ran

Unknown

no directive of that name; nothing was reported.

Failed

the arguments, options, or content were refused and reported.

rst.Line :: struct

Line is a view of one input line in columns: tabs are expanded to tab stops and trailing white space is stripped. A line that held a tab, form feed, or vertical tab is a copy in scratch; raw then keeps the source line so columns map back to source bytes. Nested blocks use cut views of their parent’s lines, so every node keeps exact spans.

text: string

raw: string

the source line of an expanded copy, else 「」.

offset: u32

source offset of text[0]; of raw[0] when raw is set.

col: i32

column of text[0] in the expanded line when raw is set.

rst.Opt_Spec :: struct

name: string

type: Opt_Type

choices: string

space-separated, for Choice.

rst.Opt_Type :: enum u8

Flag

Text

Text_Required

Int

Nonneg_Int

Pos_Int

Opt_Int

Length

Length_Percent

Figwidth

Percentage

Class

Name

Choice

Encoding

Char

Widths

Path

rst.Parser :: struct

ctx: ^gd.Read_Context

b: ^gd.Builder

inl: rst_inline.Inline_State

src: gd.Source_Id

the source the current lines come from.

text: string

tab: int

depth: int

stack: gd.Stack_Guard

bounds the machine stack of the recursion (enter).

styles: [MAX_LEVELS]Style

styles_used: int

sections: [MAX_LEVELS]Section_Entry

sections_used: int

section_base: int

sections open before titled content (parse_titled) began.

level_base: int

the level of the last of them: titled content’s sections nest in it.

top_count: int

top-level elements since the current section began.

top_transition: bool

the last top-level element was a transition.

transition_span: gd.Source_Span

pending: gd.Text

classes from a class directive, for the next element.

pending_span: gd.Source_Span

has_pending: bool

in_sidebar: int

ext: ^Extension

a dialect’s directives and roles; see extension.odin.

host: ^Host

another markup that uses the directives; see host.odin.

hosted: bool

the running directive was written in the host markup.

table_extra: ^Table_Extra

a table directive’s title and options for the host.

rst.Role_Handler :: struct

name: string

compared case-insensitively.

run: Role_Proc

rst.Role_Proc :: #type proc(p: ^Parser, call: ^rst_inline.Role_Call, user: rawptr) -> bool

Role_Proc handles interpreted text; it returns false for a role it does not know.

rst.Settings :: struct

Settings are the reader’s dialect settings. They reach the reader through gd.Read_Options.extension, made with gd.read_extension(&settings); settings of another type are refused. A dialect’s own configuration embeds Settings and passes a pointer to that embedded field when it runs this reader. An empty extension means defaults (default_settings); a caller that supplies Settings starts from default_settings, because the zero value turns bibliographic fields off.

extension: ^Extension

Directive and role handlers consulted before the standard ones.

host: ^Host

Another markup (MyST Markdown) that reads the main source and nested directive content with these directives and roles; see host.odin.

pep_references: bool

Implicit 「PEP nnn」 and 「RFC nnn」 references in running text become links.

rfc_references: bool

pep_base_url: string

「」 means https://peps.python.org/

rfc_base_url: string

「」 means https://datatracker.ietf.org/doc/html/

trim_footnote_reference_space: bool

White space before a footnote reference is removed.

smart_quotes: Smart_Quotes

Typographic quotation marks, apostrophes, dashes, and ellipses in text.

smart_quotes_locales: string

Quotation marks per language, overriding the built-in ones, as 「tag:“”‘’,tag2:«»‹›」: primary open and close, then secondary open and close.

language: string

BCP 47 tag of the document language: bibliographic field names, generated titles, and quotation marks. 「」 means 「en」.

docinfo: bool

A field list first in the document becomes bibliographic data (docinfo).

sectsubtitle: bool

A lone subsection title becomes the section’s subtitle.

tab_width: int

Tab stops; zero means gd.Read_Options.tab_width, which zero makes 8.

character_level_inline_markup: bool

Inline markup is recognized inside words (Docutils』 character_level_inline_markup).

rst.Smart_Quotes :: rst_inline.Smart_Quotes

rst.Table_Extra :: struct

Table_Extra carries what table directives add to a table: a title and attributes.

title: []Line

classes: gd.Text

name: gd.Text

align: string

width: string

widths: []int

from :widths:; nil keeps the table’s own widths.

auto_widths: bool

:widths: auto leaves widths to the renderer.

width_class: string

「colwidths-auto」 or 「colwidths-given」 from :widths:.

found: bool

set by the table parser when it emits a table.

Procedures

rst.add_common :: proc(p: ^Parser, id: gd.Node_Id, d: ^Directive, class_opt := "class")

add_common adds the :class: and :name: options as attributes. Directive nodes keep their Name attribute for the directive name, so :name: becomes Custom 「name」.

rst.blank :: proc(l: Line) -> bool

blank tells whether l has no text (white space is stripped when lines are split).

rst.bullet_width :: proc(t: string) -> int

bullet_width returns the byte length of a bullet that starts t, or 0.

rst.class_directive :: proc(p: ^Parser, d: ^Directive)

class_directive runs the class directive: its classes go to the content’s elements, or, without content, to the next element; invalid names are reported.

rst.close :: proc(p: ^Parser, id: gd.Node_Id)

close ends the element open returned id for.

rst.code_text :: proc(p: ^Parser, lines: []Line) -> gd.Text

code_text writes lines to the text pool, each ending in 「\n」.

rst.custom :: proc(p: ^Parser, id: gd.Node_Id, name, value: string)

custom adds a Custom attribute name=value to node id; both strings are copied to the text pool. A full pool poisons the builder, as every builder write does.

rst.cut :: proc(l: Line, k: int) -> Line

cut drops the first k columns.

rst.dedent :: proc(lines: []Line)

dedent strips the least indentation of the non-blank lines, in place.

rst.default_settings :: proc() -> Settings

default_settings returns Docutils』 defaults: bibliographic fields on, everything else off or empty. The value owns nothing.

rst.directive_node :: proc(p: ^Parser, d: ^Directive, name: string) -> gd.Node_Id

directive_node opens a generic Directive node named after the directive.

rst.directive_shape :: proc(p: ^Parser, name: string) -> (shape: Directive_Shape, found: bool)

directive_shape looks a directive up as the reader would, a dialect’s handlers first.

rst.embed_begin :: proc(p: ^Parser, ctx: ^gd.Read_Context)

embed_begin prepares p for a host that reads the main source itself: the settings of ctx.options.extension apply as for read, and the dialect’s begin hook runs.

rst.embed_end :: proc(p: ^Parser) -> gd.Status

embed_end runs the dialect’s end hook and resolves the document as read does.

rst.enter_source :: proc(p: ^Parser, id: gd.Source_Id, tab: int) -> Frame

enter_source makes lines of another source current, for spans and inline parsing.

rst.find_role :: proc(p: ^Parser, name: string) -> int

find_role returns the index of the role the document defined with the role directive under name, in p.inl.roles, or -1. The search spends work budget.

rst.get_opt :: proc(d: ^Directive, name: string) -> ^Dir_Opt

get_opt returns the option called name that the directive was given, or nil. The result points into d and lives as long as it.

rst.has_option :: proc(d: ^Directive, name: string) -> bool

has_option reports whether a directive was given an option, flags included.

rst.head :: proc(l: Line, n: int) -> Line

head keeps the first n columns, without trailing spaces.

rst.host_lines :: proc(p: ^Parser, views: []rst_inline.Line) -> ([]Line, bool)

host_lines makes lines of views of source text (a host’s lines): tabs are expanded to the parser’s tab stops, as split_lines does.

rst.host_views :: proc(p: ^Parser, lines: []Line) -> ([]rst_inline.Line, bool)

host_views gives the host the source text of lines, tabs unexpanded (inline_view).

rst.indent_of :: proc(s: string) -> int

indent_of counts the spaces s starts with.

rst.inline :: proc(p: ^Parser, lines: []Line)

inline parses lines as inline content of the currently open node.

rst.inline_node :: proc(p: ^Parser, kind: gd.Node_Kind, lines: []Line)

inline_node adds a node of kind holding lines parsed as inline content (inline); nothing for no lines.

rst.is_indented :: proc(l: Line) -> bool

is_indented tells whether l starts with a space.

rst.join_lines :: proc(p: ^Parser, lines: []Line, sep: string) -> string

join_lines joins lines into a scratch copy, or returns the single line’s text.

rst.leave_source :: proc(p: ^Parser, f: Frame)

leave_source makes the source that enter_source returned f for current again.

rst.line_span :: proc(p: ^Parser, l: Line) -> gd.Source_Span

line_span is the source span of one line (span_of).

rst.lines_span :: proc(p: ^Parser, lines: []Line) -> gd.Source_Span

lines_span is the source span of lines without trailing blank lines; empty lines give an empty span at the start of the source.

rst.mark :: proc(p: ^Parser) -> gd.Scratch_Mark

mark records the scratch position; release returns scratch to it. Pair them with defer around work that takes scratch.

rst.open :: proc(p: ^Parser, kind: gd.Node_Kind, span: gd.Source_Span) -> gd.Node_Id

open begins an element and gives it the classes of a preceding class directive.

rst.opt_value :: proc(p: ^Parser, d: ^Directive, name: string) -> (string, bool)

opt_value returns an option’s value lines joined by spaces and trimmed; ok is false when the option was not given. The text is a view of the source or a scratch copy, valid until the caller’s scratch mark is released.

rst.option_lines :: proc(d: ^Directive, name: string) -> ([]Line, bool)

option_lines returns the value lines of a directive option, or nil.

rst.parse_blocks :: proc(p: ^Parser, lines: []Line, sections := false, each := gd.Text{})

parse_blocks parses body elements. sections allows titles and transitions; each gives classes to every element parsed at this level (class directive content).

rst.parse_body :: proc(p: ^Parser, lines: []Line, sections := false, each := gd.Text{})

parse_body parses nested body content of the open node in the markup of the running directive (see Host). Outside hosted directives it is parse_blocks.

rst.parse_source :: proc(p: ^Parser, id: gd.Source_Id, sections: bool)

parse_source parses a whole registered source (gd.add_source) as body content at the current position, as if its lines stood there. sections allows titles.

rst.parse_titled :: proc(p: ^Parser, lines: []Line)

parse_titled parses content in which titles begin sections, in a title context of its own (Sphinx’s nested parse with titles): adornments take levels afresh, the first nesting in the innermost open section, and the sections close when the content ends. The surrounding adornments are kept for what follows.

rst.path_of :: proc(p: ^Parser, lines: []Line) -> string

path_of joins path lines without white space, as the specification treats paths.

rst.place_titled :: proc(p: ^Parser, lines: []Line)

place_titled prepares for titled content (parse_titled) as Sphinx’s only directive does: when the content’s first title has an adornment the document already uses, the content stands where a title of that level would, so deeper sections close first.

rst.pool_classes :: proc(p: ^Parser, s: string) -> (gd.Text, bool)

pool_classes writes white-space separated class names as identifiers, one space apart. It fails when a name has no letters.

rst.pool_lines :: proc(p: ^Parser, lines: []Line, sep: string) -> gd.Text

pool_lines writes the lines joined by sep into the text pool and returns the text, which lives as long as the document; a full pool poisons the builder.

rst.pool_lower :: proc(p: ^Parser, s: string) -> string

pool_lower writes s in lower case to the text pool and returns the pooled string.

rst.push_lines :: proc(p: ^Parser, lines: []Line, sep: string)

push_lines writes the lines joined by sep into the text pool.

rst.read :: proc(ctx: ^gd.Read_Context) -> gd.Status

read reads ctx.source as reStructuredText into ctx.b (gd.Read_Proc). Settings of another type than ^Settings are refused with Invalid_Input before anything is read. It borrows ctx for the call and keeps nothing; its tables live in scratch, released before it returns. Problems go to ctx.reports; the result is the builder’s status (.Capacity when a table is full, .Limit past the nesting or stack limits), or that of reference resolution.

rst.read_inline :: proc(ctx: ^gd.Read_Context, span: gd.Source_Span) -> gd.Status

read_inline parses a span of ctx.source as inline content of the builder’s open node, with the settings of ctx.options.extension, as Sphinx parses a translated message (gd.Read_Inline_Proc). Each line’s leading white space is dropped, as the lines of a paragraph lose their indentation. References are left for the caller to resolve.

rst.reader :: proc() -> gd.Reader

reader returns the 「rst」 reader descriptor, for a gd.Registry. It is a value with no state: registering it twice or copying it is harmless.

rst.release :: proc(p: ^Parser, m: gd.Scratch_Mark)

release frees the scratch taken since mark m; views into it become invalid.

rst.report :: proc(p: ^Parser, m: gd.Message, span: gd.Source_Span, a := gd.Diagnostic_Arg{}, b := gd.Diagnostic_Arg{})

report adds diagnostic m at span, with its arguments, to the read’s reports; a full reports region counts it as suppressed (gd.report) rather than failing the read.

rst.run_hosted :: proc(p: ^Parser, h: Host_Directive) -> Hosted_Result

run_hosted checks and runs a directive written in the host markup. Options are checked as in reStructuredText; a host with other rules checks them first (directive_shape, option_problem) and passes only the ones it keeps.

rst.span_of :: proc(p: ^Parser, first, last: Line) -> gd.Source_Span

span_of is the source span from the start of first to the end of last, in the current source, clamped to its text.

rst.standard_role :: proc(name: string) -> (rst_inline.Role_Base, bool)

standard_role finds a standard role or alias by name, compared case-insensitively; ok is false (base .Custom) for another name.

rst.table_decorate :: proc(p: ^Parser, id: gd.Node_Id, span: gd.Source_Span, cols: int, widths: []int, extra: ^Table_Extra)

table_decorate gives an open Table, before its rows, its widths and a table directive’s attributes and title. A host calls it for the table it emits inside a table directive (Parser.table_extra).

rst.take :: proc(p: ^Parser, $T: typeid, n: int) -> ([]T, bool)

take returns n zeroed items of T from scratch, valid until the enclosing mark is released. When scratch is short it records the capacity need on the builder (poisoning it) and returns false.

rst.trim_blank_end :: proc(lines: []Line) -> []Line

trim_blank_end returns lines without its trailing blank lines (a subslice).

Constants

rst.CONFORMANCE :: gd.Conformance.Partial

rst.DIRECTIVE_UNKNOWN

DIRECTIVE_UNKNOWN is what the reader reports for a directive no handler knows; a handler that finds it cannot serve a directive it was given reports it too.

rst.VERSION :: "0.1.0"