Documentation
¶
Overview ¶
Package parser implements a parser for markdown text that generates an AST (abstract syntax tree).
Index ¶
- Constants
- Variables
- func IsAlnum(c byte) bool
- func IsCallout(data []byte) (id []byte, consumed int)
- func IsEmpty(data []byte) int
- func IsLetter(c byte) bool
- func IsPunctuation(c byte) bool
- func IsPunctuation2(d []byte) bool
- func IsSafeURL(url []byte) bool
- func IsSpace(c byte) bool
- func LinesUntilEmpty(data []byte) int
- func NormalizeNewlines(d []byte) []byte
- type BlockFunc
- type Extensions
- type Flags
- type InlineParser
- type Options
- type Parser
- func (p *Parser) AddBlock(n ast.Node) ast.Node
- func (p *Parser) Block(data []byte)
- func (p *Parser) Finalize(block ast.Node)
- func (p *Parser) Inline(currBlock ast.Node, data []byte)
- func (p *Parser) Parse(input []byte) ast.Node
- func (p *Parser) RegisterInline(trigger byte, fn InlineParser) InlineParser
- type ReadIncludeFunc
- type Reference
- type ReferenceOverrideFunc
Constants ¶
const CommonMarkExtensions = Tables | Strikethrough | Autolink | AutoHeadingIDs
CommonMarkExtensions are the extensions NewCommonMarkWithExtensions supports. They follow GitHub Flavored Markdown where it differs from the historical parser.
Variables ¶
var EscapeChars = []byte("\\`*_{}[]()#+-.!:|&<>~^$")
'\\' backslash escape
var Paths = [][]byte{ []byte("/"), []byte("./"), []byte("../"), }
Functions ¶
func IsCallout ¶
IsCallout detects a callout in the following format: <<N>>, where N is an integer > 0.
func IsEmpty ¶
IsEmpty returns the length of a blank line at the start of data, or 0 if the line is not blank. It is okay to call on an empty buffer.
func IsPunctuation ¶
IsPunctuation returns true if c is a punctuation symbol.
func IsPunctuation2 ¶
func IsSafeURL ¶
IsSafeURL returns true if url starts with one of the valid schemes or is a relative path.
func LinesUntilEmpty ¶
LinesUntilEmpty scans lines up to the first empty line.
func NormalizeNewlines ¶
Types ¶
type BlockFunc ¶
BlockFunc allows registration of a parser function. If successful it returns an ast.Node, a buffer that should be parsed as a block, and the number of bytes consumed.
type Extensions ¶
type Extensions int
Extensions is a bitmask of enabled parser extensions.
const ( NoExtensions Extensions = 0 NoIntraEmphasis Extensions = 1 << iota // Ignore emphasis markers inside words Tables // Parse tables FencedCode // Parse fenced code blocks Autolink // Detect embedded URLs that are not explicitly marked Strikethrough // Strikethrough text using ~~test~~ LaxHTMLBlocks // Loosen up HTML block parsing rules SpaceHeadings // Be strict about prefix heading rules HardLineBreak // Translate newlines into line breaks NonBlockingSpace // Translate backslash-space into a non-breaking space TabSizeEight // Expand tabs to eight spaces instead of four Footnotes // Pandoc-style footnotes NoEmptyLineBeforeBlock // No need to insert an empty line to start a (code, quote, ordered list, unordered list) block HeadingIDs // Specify heading IDs with {#id} Titleblock // Pandoc-style title block AutoHeadingIDs // Create the heading ID from the text BackslashLineBreak // Translate trailing backslashes into line breaks DefinitionLists // Parse definition lists MathJax // Parse MathJax OrderedListStart // Keep track of the first number used when starting an ordered list. Attributes // Block attributes: {#id .class key="value"} before a block or {: ...} after it. See html.SkipHTML for untrusted documents. SuperSubscript // Super- and subscript support: 2^10^, H~2~O. // EmptyLinesBreakList is retained for source compatibility and has no effect. // // Deprecated: this option is ignored. EmptyLinesBreakList Includes // Support including other files. Mmark // Support Mmark syntax, see https://mmark.miek.nl/post/syntax/ InlineAttributes // Parse {key="value"} after links and images. See html.SkipHTML for untrusted documents. MarkdownInHTML // Parse markdown inside HTML table cells and similar tags CommonExtensions Extensions = NoIntraEmphasis | Tables | FencedCode | Autolink | Strikethrough | SpaceHeadings | HeadingIDs | BackslashLineBreak | DefinitionLists | MathJax )
Bit flags representing markdown parsing extensions. Use | (or) to specify multiple extensions.
type Flags ¶
type Flags int
Flags control optional behavior of parser.
const ( FlagsNone Flags = 0 SkipFootnoteList Flags = 1 << iota // Skip adding the footnote list (regardless of whether they are parsed) // CommonMark selects the CommonMark 0.31.2 grammar for Parse, independent // of Extensions. The resulting document uses the usual ast node types. // The flag is off by default to preserve historical parsing behavior. // Custom block and inline parsers are only used by the historical parser. CommonMark )
Parser configuration options.
type InlineParser ¶
InlineParser parses inline data beginning at offset.
type Options ¶
type Options struct {
ParserHook BlockFunc
ReadIncludeFn ReadIncludeFunc
Flags Flags // Flags allow customizing parser's behavior
}
Options is a collection of supplementary parameters tweaking the behavior of various parts of the parser.
type Parser ¶
type Parser struct {
// ReferenceOverride is an optional function callback that is called every
// time a reference is resolved. It can be set before starting parsing.
//
// In Markdown, the link reference syntax can be made to resolve a link to
// a reference instead of an inline URL, in one of the following ways:
//
// * [link text][refid]
// * [refid][]
//
// Usually, the refid is defined at the bottom of the Markdown document. If
// this override function is provided, the refid is passed to the override
// function first, before consulting the defined refids at the bottom. If
// the override function indicates an override did not occur, the refids at
// the bottom will be used to fill in the link details.
ReferenceOverride ReferenceOverrideFunc
// IsSafeURLOverride allows overriding the default URL matcher. URL is
// safe if the overriding function returns true. Can be used to extend
// the default list of safe URLs.
IsSafeURLOverride func(url []byte) bool
Opts Options
// after parsing, this is AST root of parsed markdown text
Doc ast.Node
InsideLink bool
// contains filtered or unexported fields
}
Parser is a type that holds extensions and the runtime state used by Parse. You cannot use it directly; construct it with New.
func NewCommonMark ¶
func NewCommonMark() *Parser
NewCommonMark creates a markdown parser that follows the CommonMark 0.31.2 spec. It sets the CommonMark flag; extensions don't apply in this mode.
func NewCommonMarkWithExtensions ¶
func NewCommonMarkWithExtensions(extensions Extensions) *Parser
NewCommonMarkWithExtensions creates a markdown parser that follows the CommonMark 0.31.2 spec plus the given extensions, of which those in CommonMarkExtensions apply and the rest are ignored:
- Tables: pipe tables, which can interrupt a paragraph.
- Strikethrough: ~~text~~.
- Autolink: bare http://, https://, ftp:// and mailto: URLs become links. Trailing punctuation and unbalanced closing parentheses or brackets are not part of the URL.
- AutoHeadingIDs: heading ids made from the heading text.
Unlike NewCommonMark, the parser also runs Opts.ParserHook, at the start of each block.
func NewWithExtensions ¶
func NewWithExtensions(extension Extensions) *Parser
NewWithExtensions creates a markdown parser with the given extensions.
func (*Parser) Parse ¶
Parse generates AST (abstract syntax tree) representing markdown document.
The result is a root of the tree whose underlying type is *ast.Document
You can then convert AST to html using html.Renderer, to some other format using a custom renderer or transform the tree.
Parse can be called only once on a Parser and panics if called again. Create a new Parser for each document. Inline and Block can be called any number of times, for example from parser hooks.
Parsing takes time linear in the size of input, and limits keep the tree from growing much faster than input for documents that aren't trusted: blocks and inline content are nested at most 64 levels deep, references stop being resolved once they have expanded to more destination and title bytes than the size of input or 100KB, whichever is larger, and table rows stop being padded with empty cells after as many cells. Footnotes and references from ReferenceOverride don't count toward the limit.
func (*Parser) RegisterInline ¶
func (p *Parser) RegisterInline(trigger byte, fn InlineParser) InlineParser
RegisterInline installs fn for a trigger byte and returns the previous parser.
type ReadIncludeFunc ¶
ReadIncludeFunc should read the file under path and return the read bytes. from is the name of the file being parsed, which is empty for the top-level document. address is the optional specifier of which lines of the file to return. If this function is not set, no data will be read.
type Reference ¶
type Reference struct {
// Link is usually the URL the reference points to.
Link string
// Title is the alternate text describing the link in more detail.
Title string
// Text is the optional text to override the ref with if the syntax used was
// [refid][]
Text string
}
Reference represents the details of a link. See Parser.ReferenceOverride for how it's used.
type ReferenceOverrideFunc ¶
ReferenceOverrideFunc resolves a reference, or declines by returning overridden false so the parser can use its document-defined references.
Source Files
¶
- aside.go
- attribute.go
- block.go
- block_index.go
- block_rules.go
- block_table.go
- brackets.go
- byte_index.go
- callout.go
- caption.go
- citation.go
- code.go
- commonmark_blocks.go
- commonmark_inline.go
- config.go
- delimiter.go
- esc.go
- figures.go
- heading.go
- html_block.go
- include.go
- inline.go
- inline_cache.go
- inline_code.go
- inline_emphasis.go
- inline_escape.go
- inline_links.go
- link.go
- link_inline.go
- list.go
- matter.go
- options.go
- paragraph.go
- parser.go
- quote.go
- ref.go
- reference.go
- scan.go
- url.go