markdown

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793816566/FIN+5.3.1+markdown 中文整理基于 FIN 5.3.1

导读： Markdown 解析和渲染

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

mixins
classes
enums
docs
Overview
Usage
HTML Rendering
Plaintext Rendering
Extensions
Slot Details
- center
- fromStr
- left
- right
- unspecified
- vals
- setAttrs
- parent
- setParent
- atColumn
- atIndex
- finalize
- finished
- newColumn
- newIndex
- none
- addLine
- addSourceSpan
- block
- canContain
- canHaveLazyContinuationLines
- closeBlock
- definitions
- isContainer
- parseInlines
- tryContinue
- tryStart
- blockParsers
- isReplaceActiveBlockParser
- of
- replaceActiveBlockParser
- make
- marker
- literal
- toStrAttributes
- addAll
- get
- putIfAbsent
- closingDelim
- openingDelim
- canClose
- canOpen
- chars
- closer
- closers
- delimChar
- next
- opener
- openers
- origSize
- prev
- size
- toStr
- closingChar
- minLen
- openingChar
- process
- file
- withFile
- delimiter
- closingFenceLen
- fenceChar
- fenceIndent
- info
- openingFenceLen
- anchor
- level
- disableHtml
- encodeUrl
- escapeHtml
- extendAttrs
- omitSingleParagraphP
- percentEncodeUrls
- render
- sanitizeUrls
- softbreak
- urlSanitizer
- writer
- builder
- renderTo
- attrProviderFactory
- build
- extensions
- nodeRendererFactory
- withDisableHtml
- withEscapeHtml
- withOmitSingleParagraphP
- withPercentEncodeUrls
- withSanitizeUrls
- withSoftBreak
- line
- raw
- tag
- text
- w
- attrs
- extendHtml
- extendMarkdown
- extendParser
- blocks
- blocks_and_inlines
- tryParse
- create
- triggerChars
- parse
- customDelimiterProcessors
- customLinkMarkers
- customLinkProcessors
- def
- factories
…（其余标题见英文正文）

API 正文（英文）

enums


Alignment
IncludeSourceSpans	Enum for configuring whether to include SourceSpans or not while parsing.
LineBreakRendering	LineBreakRendering

docs

Overview

Fantom library for parsing and rendering Markdown text according to the CommonMark specification.

Usage

using markdown

parser := Parser()
doc := parser.parse("This is *Markdown*")
renderer := HtmlRenderer()
html := renderer.render(doc) // => "<p>This is <em>Markdown</em></p>\n"

This uses the parser and renderer with default options. Both have builders for configuring their behavior. See ParserBuilder and HtmlRendererBuilder for more details.

Use a visitor to process parsed nodes

After the source text has been parsed, the result is a tree of nodes. That tree can be modified before rendering, or just inspected without rendering. See Visitor and the HTML rendering example below.

HTML Rendering

You can take complete control over how HTML is rendered.

In this example, we're changing the rendering of indented code blocks to only wrap them in pre instead of pre and code:

parser := Parser()
renderer := HtmlRenderer.builder
  .nodeRendererFactory(|HtmlContext cx->NodeRenderer| { IndentedCodeBlockRendere(cx) })
  .build
html := renderer.render(parser.parse("Example:\n\n    code"))
// "<p>Example:</p><pre>code</pre>\n"

class IndentedCodeBlockRenderer : NodeRenderer, Visitor
{
  new make(HtmlContext cx) { this.html = cx.writer }
  private HtmlWriter html

  ** We only want to override rendering of the Code node type
  override const Type nodeTypes := [Code#]

  override Void render(Node node) { node.walk(this) }

  override Void visitIndentedCode(IndentedCode code)
  {
    html.line
      .tag("pre")
      .text(code.literal)
      .tag("/pre")
      .line
  }
}

Add your own node types

In case you want to store additional data in the document, or have custom elements in the resulting HTML, you can create your own subclass of CustomNode or CustomBlock and add instances as child nodes to existing nodes.

To define the HTML rendering for them, you can use a NodeRenderer as explained above.

Plaintext Rendering

You can also render markdown to plaintext with most formatting removed. The builder for the TextRenderer supports various methods or rendering line breaks depending on your use case.

// Generate plaintext using the default "compact" rendering
doc := Parser().parse("Here, the **emphasis** is ignored")
str := TextRenderer().render(doc) // => Here the emphasis is ignored

Customize parsing

There are a few ways to extend parsing or even override built-in parsing, all of them via methods on Parser.builder. See Section 3 (Blocks and Inlines) of the spec for an overview of blocks/inlines.

Parsing of specific block types (e.g. headings, code blocks, etc.) can be enabled/disabled with withEnabledBlockTypes
Parsing of blocks can be extended/overridden with customBlockParserFactory
Parsing of inline content can be extended/overridden with customInlineContentParserFactory
Processing of links can be customized with linkProcessor and linkMarker

Thread-safety

Both the Parser and the HtmlRenderer are designed so that you can configure them once and then use them multiple times/from multiple Actors.

Extensions

Extensions are used to extend the parser, the HTML renderer, or both. Extensions are configured on the various builders using the extensions() method. The default parser and HTML renderer conform to the CommonMark specification. This library includes some built-in extensions that you can optionally enable.

For example, the following code enables the ImgAttrsExt which allows you to specify attributes for images.

using markdown

exts := [ImgAttrsExt()]
parser := Parser.builder.extensions(exts).build
renderer := HtmlRenderer.builder.extensions(exts).build

Image Attributes

Adds support for specifying attributes (specifically height and width) for images. Use ImgAttrsExt to enable this extension.

The attribute elements are given as key=value pairs inside curly braces { } after the image node to which they apply. For example:

![text](/url.png){width=640 height=480}

will be rendered as

<img src="/url.png" alt="text" width="640" height="480" />

Tables

Enables tables using pipes as in Github Flavored Markdown. See TablesExt.

| Header1 | Header2 |
| ------- | ------- |
| foo     | bar     |

Alignment

@Js @Serializable { simple=true } enum class Alignment : Enum

Enum


unspecified
left
center
right

Constructors


fromStr	Return the Alignment instance for the specified name.

Fields


vals	List of Alignment values indexed by ordinal

Slot Details

center

const static Alignment center := ...

fromStr

static new fromStr(Str name, Bool checked := true)

Return the Alignment instance for the specified name. If not a valid name and checked is false return null, otherwise throw ParseErr.

left

const static Alignment left := ...

right

const static Alignment right := ...

unspecified

const static Alignment unspecified := ...

vals

const static Alignment[] vals := ...

List of Alignment values indexed by ordinal

AttrProvider

@Js mixin AttrProvider

Extension point for adding/changing attributes on HTML tags for a node.

Methods


setAttrs	Set the attributes for an HTML tag of the specified node by modyfing the provided map.

Slot Details

setAttrs

abstract Void setAttrs(Node node, Str tagName, Str:Str? attrs)

Set the attributes for an HTML tag of the specified node by modyfing the provided map.

This allows to change or even remove default attributes.

The attribute key and values will be escaped (preserving character entities), so don't escape them here, otherwise they will be double-escaped.

This method may be called multiple times for the same node, if the node is rendered using multiple nested tags (e.g. code blocks)

Block

@Js abstract class Block : Node

A block node.

We can think of a document as a sequence of blocks - structural elements like paragraphs, block quotations, lists, headings, rules, and code blocks. Some blocks contain other blocks; others contain inline content (text, images, code spans, etc.).

Methods


parent
setParent

Slot Details

parent

virtual override Block? parent()

setParent

protected virtual override Void setParent(Node? p)

BlockContinue

@Js const class BlockContinue : Obj

Resulting object for continuing parsing of a block.

Constructors


atColumn
atIndex
finished
none

Fields


finalize
newColumn
newIndex

Slot Details

atColumn

static new atColumn(Int newColumn)

atIndex

static new atIndex(Int newIndex)

finalize

const Bool finalize

finished

static new finished()

newColumn

const Int newColumn

newIndex

const Int newIndex

none

static new none()

BlockParser

@Js abstract class BlockParser : Obj

A block parser is able to parse a specific block node.

Methods


addLine	Default implementation does nothing with the source line
addSourceSpan	Add a source span of the currently parsed block.
block	Get the parsed block
canContain	Return true if the this block may contain the child block; false otherwise (default)
canHaveLazyContinuationLines	Return true if the block can have lazy continuation lines.
closeBlock	Do any processing when the block is closed
definitions	Return the definitions parsed by this parser.
isContainer	Return true if the block that is parsed is a container (i.e.
parseInlines	Callback to parse inline content
tryContinue	Attempt to continue parsing the block from the given state

Slot Details

addLine

virtual Void addLine(SourceLine line)

Default implementation does nothing with the source line

addSourceSpan

virtual Void addSourceSpan(SourceSpan sourceSpan)

Add a source span of the currently parsed block. The default implementation adds it to the block. Unless you have some complicated parsing where you need to check source positions, you don't need to override this.

block

abstract Block block()

Get the parsed block

canContain

virtual Bool canContain(Block childBlock)

Return true if the this block may contain the child block; false otherwise (default)

canHaveLazyContinuationLines

virtual Bool canHaveLazyContinuationLines()

Return true if the block can have lazy continuation lines.

Lazy continuation lines are lines that were rejected by this tryContinue but didn't match any other block parser either.

If true is returned here, those lines will get added via addLine. For false (default), the block is closed instead.

closeBlock

virtual Void closeBlock()

Do any processing when the block is closed

definitions

virtual DefinitionMap[] definitions()

Return the definitions parsed by this parser. The definitions returned here can later be accessed during inline parsing.

isContainer

virtual Bool isContainer()

Return true if the block that is parsed is a container (i.e. contains other blocks), or false (default) if it's a leaf.

parseInlines

virtual Void parseInlines(InlineParser inlineParser)

Callback to parse inline content

tryContinue

abstract BlockContinue? tryContinue(ParserState state)

Attempt to continue parsing the block from the given state

BlockParserFactory

@Js abstract const class BlockParserFactory : Obj

Parser factory for a block node for determining when a block starts.

Methods


tryStart

Slot Details

tryStart

abstract BlockStart? tryStart(ParserState state, MatchedBlockParser matchedBlockParser)

BlockQuote

@Js class BlockQuote : Block

Block quote block

Slot Details

BlockStart

@Js class BlockStart : Obj

Resulting object for starting parsing of a block. See BlockParserFactory.

Constructors


none
of

Fields


blockParsers
isReplaceActiveBlockParser
newColumn
newIndex

Methods


atColumn
atIndex
replaceActiveBlockParser

Slot Details

atColumn

This atColumn(Int newColumn)

atIndex

This atIndex(Int newIndex)

blockParsers

BlockParser[] blockParsers { private set }

isReplaceActiveBlockParser

Bool isReplaceActiveBlockParser := false { private set }

newColumn

Int newColumn := -1 { private set }

newIndex

Int newIndex := -1 { private set }

none

static new none()

of

static new of(BlockParser[] blockParsers)

replaceActiveBlockParser

This replaceActiveBlockParser()

BulletList

@Js class BulletList : ListBlock

Bullet list block

Constructors


make

Fields


marker	The bullet list marker that was used, e.g.

Slot Details

make

new make(Str? marker := null)

marker

Str? marker

The bullet list marker that was used, e.g. -, *, or +, if available, or null otherwise.

Code

@Js class Code : Node

Code

Constructors


make

Fields


literal

Methods


toStrAttributes

Slot Details

literal

const Str literal

make

new make(Str literal)

toStrAttributes

protected virtual override Str toStrAttributes()

CustomBlock

@Js abstract class CustomBlock : Block

Custom Block

Slot Details

CustomNode

@Js class CustomNode : Node

Custom node

Slot Details

DefinitionMap

@Js class DefinitionMap : Obj

A map that can be used to store and lookup reference definitions by a label. The labels are case-insensitive and normalized, the same way as for LinkReferenceDefinition nodes.

Constructors


make

Fields


of	The type of definition stored in this map

Methods


addAll
get
putIfAbsent	Store a new definition unless one is already in the map.

Slot Details

addAll

Void addAll(DefinitionMap that)

get

@Operator Block? get(Str label, Block? def := null)

make

new make(Type of)

of

const Type of

The type of definition stored in this map

putIfAbsent

Block? putIfAbsent(Str label, Block def)

Store a new definition unless one is already in the map. If there is no definition for the label yet, return null. Otherwise return the existing definition

The label is normalized by the definition map before storing.

Delimited

@Js mixin Delimited

A node that uses delimiters in the source form, e.g. *bold*

Methods


closingDelim	Return the closing (ending) delimiter, e.g.
openingDelim	Return the opening (beginning) delimiter, e.g.

Slot Details

closingDelim

abstract Str closingDelim()

Return the closing (ending) delimiter, e.g. *

openingDelim

abstract Str openingDelim()

Return the opening (beginning) delimiter, e.g. *

Delimiter

@Js class Delimiter : Obj

Delimiter (emphasis, strong emphasis, or custom emphasis)

Constructors


make

Fields


canClose	can close emphasis, see spec.
canOpen	can open emphasis, see spec.
chars
delimChar
next
origSize	The number of characters originally in this delimiter run; at the start of processing, this is the same as `size`
prev

Methods


closer	Return the innermost closing delimiter, e.g.
closers	Get the closing delimiter nodes for the specified number of delimiters.
opener	Return the innermost opening delimiter, e.g.
openers	Get the opening delimiter nodes for the specified number of delimiters.
size	The number of characters in this delimiter run (that are left for processing)
toStr

Slot Details

canClose

const Bool canClose

can close emphasis, see spec.

canOpen

const Bool canOpen

can open emphasis, see spec.

chars

Text[] chars { private set }

closer

Text closer()

Return the innermost closing delimiter, e.g. for *** this is the first *

closers

Text[] closers(Int len)

Get the closing delimiter nodes for the specified number of delimiters.

For example, for a delimiter run ***, calling this with 1 would return the first *, calling it with 2 would return the first * and the second *.

delimChar

const Int delimChar

make

new make(Text[] chars, Int delimChar, Bool canOpen, Bool canClose, Delimiter? prev)

Delimiter? next

opener

Text opener()

Return the innermost opening delimiter, e.g. for *** this is the last *

openers

Text[] openers(Int len)

Get the opening delimiter nodes for the specified number of delimiters.

For example, for a delimiter run ***, calling this with 1 would return the last *. Calling it with 2 would return the second last * and last *.

origSize

const Int origSize

The number of characters originally in this delimiter run; at the start of processing, this is the same as size

Delimiter? prev

size

Int size()

The number of characters in this delimiter run (that are left for processing)

toStr

virtual override Str toStr()

DelimiterProcessor

@Js const mixin DelimiterProcessor

Custom delimiter processor for additional delimiters besides _ and *.

Note that implementations of this need to be thread-safe, the same instance may be used by multiple parsers.

Methods


closingChar	The character that marks the ending of a delimited node, must not clas with any built-in special characters.
minLen	Minimum number of delimiter characters that are needed to activate this.
openingChar	The character that marks the beginning of a delimited node, must not clash with any built-in special characters.
process	Process the delimiter runs.

Slot Details

closingChar

abstract Int closingChar()

The character that marks the ending of a delimited node, must not clas with any built-in special characters. Note that for a symmetric delimiter such as *, this is the same as the opening.

minLen

abstract Int minLen()

Minimum number of delimiter characters that are needed to activate this. Must be at least 1.

openingChar

abstract Int openingChar()

The character that marks the beginning of a delimited node, must not clash with any built-in special characters.

process

abstract Int process(Delimiter openingRun, Delimiter closingRun)

Process the delimiter runs.

The processor can examine the runs and the nodes and decide if it wants to process or not. If not, it should not change any nodes and return 0. If yes, it should do the processing (wrapping nodes, etc.) and then return how many delimiters were used.

Note that removal (unlinking) of the used delimiter Text nodes is done by the caller.

Returns how many delimiters were used; must not be greater than the length of either opener or closer

Document

@Js class Document : Block

Document is the root node of the AST

Constructors


make

Fields


file	Get the file this document was generated from, or null if not known

Methods


withFile	Set the file that was used to generate this document

Slot Details

file

File? file { private set }

Get the file this document was generated from, or null if not known

make

new make()

withFile

This withFile(File file)

Set the file that was used to generate this document

Emphasis

@Js class Emphasis : Node, Delimited

Emphasis

Constructors


make

Fields


delimiter

Methods


closingDelim
openingDelim

Slot Details

closingDelim

virtual override Str closingDelim()

delimiter

const Str delimiter

make

new make(Str delimiter)

openingDelim

virtual override Str openingDelim()

FencedCode

@Js class FencedCode : Block

Fenced code block

Constructors


make

Fields


closingFenceLen	The length of the closing fence (how many of the `fenceChar` were used to end the code block) if available, or null otherwise
fenceChar	The fence character that was used, e.g.
fenceIndent
info	Optional info string (see spec), e.g.
literal
openingFenceLen	The length of the opening fence (how many of the `fenceChar` were used to start the code block) if available, or null otherwise

Slot Details

closingFenceLen

Int? closingFenceLen

The length of the closing fence (how many of the fenceChar were used to end the code block) if available, or null otherwise

fenceChar

Str? fenceChar

The fence character that was used, e.g. `, or ~, if available, or null otherwise

fenceIndent

Int fenceIndent := 0

info

Str? info

Optional info string (see spec), e.g. fantom in ```fantom

literal

Str? literal

make

new make(Str? fenceChar := null)

openingFenceLen

Int? openingFenceLen

The length of the opening fence (how many of the fenceChar were used to start the code block) if available, or null otherwise

HardLineBreak

@Js class HardLineBreak : Node

Hard line break

Slot Details

Heading

@Js class Heading : Block

Heading block

Constructors


make

Fields


anchor	The anchor id to use for this heading.
level	The heading "level"

Methods


toStrAttributes

Slot Details

anchor

Str? anchor

The anchor id to use for this heading.

level

const Int level

The heading "level"

make

new make(Int level := 0)

toStrAttributes

protected virtual override Str toStrAttributes()

HtmlBlock

@Js class HtmlBlock : Block

HTML block

Constructors


make

Fields


literal

Slot Details

literal

Str? literal

make

new make(Str? literal := null)

HtmlContext

@Js class HtmlContext : Obj

Context for rendering nodes to HTML

Fields


writer

Methods


disableHtml
encodeUrl
escapeHtml
extendAttrs
omitSingleParagraphP
percentEncodeUrls
render
sanitizeUrls
softbreak
urlSanitizer

Slot Details

disableHtml

Bool disableHtml()

encodeUrl

Str encodeUrl(Str url)

escapeHtml

Bool escapeHtml()

extendAttrs

Str:Str? extendAttrs(Node node, Str tagName, Str:Str? attrs := [:])

omitSingleParagraphP

Bool omitSingleParagraphP()

percentEncodeUrls

Bool percentEncodeUrls()

render

Void render(Node node)

sanitizeUrls

Bool sanitizeUrls()

softbreak

Str softbreak()

urlSanitizer

UrlSanitizer urlSanitizer()

writer

HtmlWriter writer { private set }

HtmlInline

@Js class HtmlInline : Node

HTML inline

Constructors


make

Fields


literal

Slot Details

literal

Str? literal

make

new make(Str? literal := null)

HtmlRenderer

@Js const class HtmlRenderer : Obj, Renderer

Renders a tree of nodes to HTML

Constructors


make	Get a renderer with all the default configuration

Methods


builder	Obtain a builder for configuring the renderer
renderTo

Slot Details

builder

static HtmlRendererBuilder builder()

Obtain a builder for configuring the renderer

make

static new make()

Get a renderer with all the default configuration

renderTo

virtual override Void renderTo(OutStream out, Node node)

HtmlRendererBuilder

@Js class HtmlRendererBuilder : Obj

Builder for configuring an HtmlRenderer.

Methods


attrProviderFactory	Add a factory for an attribute provider for adding/changing HTML attributes to the rendered tags.
build	Get the configured `HtmlRenderer`
extensions	Configure the given extensions on this this renderer
nodeRendererFactory	Add a factory for instantiating a node renderer (done when rendering).
withDisableHtml	Whether `HtmlInline` and `HtmlBlock` nodes should be rendered, defaults to `false`.
withEscapeHtml	Whether `HtmlInline` and `HtmlBlock` should be escaped, defaults to `false`.
withOmitSingleParagraphP	Whether documents that only contain a single paragraph shoudl be rendered without the `<p>` tag.
withPercentEncodeUrls	Whether URLs of link or images should be percent-encoded, defaults to `false`.
withSanitizeUrls	Whether `Image` src and `Link` href should be sanitized, defaults to `false`.
withSoftBreak	The HTML to use for rendering a softbreak, default to `\n` (meaning the rendered result doesn't have a line break).

Slot Details

attrProviderFactory

This attrProviderFactory(|HtmlContext->AttrProvider| factory)

Add a factory for an attribute provider for adding/changing HTML attributes to the rendered tags.

build

HtmlRenderer build()

Get the configured HtmlRenderer

extensions

This extensions(MarkdownExt[] exts)

Configure the given extensions on this this renderer

nodeRendererFactory

This nodeRendererFactory(|HtmlContext->NodeRenderer| factory)

Add a factory for instantiating a node renderer (done when rendering). This allows to override the rendering of node types or define rendering for custom node types.

If multiple node renderers for the same node type are created, the one from the factory that was added first "wins". (This is how rendering for core node types can be overriden; the default rendering comes last).

withDisableHtml

This withDisableHtml(Bool val := true)

Whether HtmlInline and HtmlBlock nodes should be rendered, defaults to false.

withEscapeHtml

This withEscapeHtml(Bool val := true)

Whether HtmlInline and HtmlBlock should be escaped, defaults to false.

Note that HtmlInline is only a tag itself, not the text between an opening tag and closing tag. So markup in the text will be parsed as normal and is not affected by this option.

withOmitSingleParagraphP

This withOmitSingleParagraphP(Bool val := true)

Whether documents that only contain a single paragraph shoudl be rendered without the <p> tag. Set to true to render without the tag; the default of false always renders the tag.

withPercentEncodeUrls

This withPercentEncodeUrls(Bool val := true)

Whether URLs of link or images should be percent-encoded, defaults to false.

If enabled, the following is done:

Existing percent-encoded parts are preserved (e.g. "%20" is kept as "%20")
Reserved characters such as "/" are preserved, except for "[" and "]" (see encodeURL in JS).
Other characters such as umlauts are percent-encoded

withSanitizeUrls

This withSanitizeUrls(Bool val := true)

Whether Image src and Link href should be sanitized, defaults to false.

withSoftBreak

This withSoftBreak(Str s)

The HTML to use for rendering a softbreak, default to \n (meaning the rendered result doesn't have a line break).

Set it to <br> or <br /> to make the hard breaks.

Set it to (space) to ingore line wrapping in the source.

HtmlWriter

@Js class HtmlWriter : Obj

HTML writer for markdown rendering

Constructors


make

Methods


line	write a newline character if the last character written wasn't a newline
raw	Write the raw string
tag	Write a tag with the given name ("foo" - opening tag, "/foo" - closing tag) with the given attributes.
text	Write the escaped text
w

Slot Details

line

This line()

write a newline character if the last character written wasn't a newline

make

new make(OutStream out)

raw

This raw(Str s)

Write the raw string

tag

This tag(Str name, [Str:Str?]? attrs := null, Bool empty := false)

Write a tag with the given name ("foo" - opening tag, "/foo" - closing tag) with the given attributes. If empty is true an empty tag is written (e.g. <img />)

text

This text(Str text)

Write the escaped text

w

protected This w(Str s)

Image

@Js class Image : LinkNode

Image node

Constructors


make

Slot Details

make

new make(Str destination, Str? title := null)

ImgAttrs

@Js class ImgAttrs : CustomNode, Delimited

ImgAttrs

Constructors


make

Fields


attrs
closingDelim
openingDelim

Methods


toStrAttributes

Slot Details

attrs

const Str:Str attrs

closingDelim

virtual const override Str closingDelim := "}"

make

new make(Str:Str attrs)

openingDelim

virtual const override Str openingDelim := "{"

toStrAttributes

protected virtual override Str toStrAttributes()

ImgAttrsExt

@Js const class ImgAttrsExt : Obj, MarkdownExt

Extension for adding attributes to image nodes.

Methods


extendHtml
extendMarkdown
extendParser

Slot Details

extendHtml

virtual override Void extendHtml(HtmlRendererBuilder builder)

extendMarkdown

virtual override Void extendMarkdown(MarkdownRendererBuilder builder)

extendParser

virtual override Void extendParser(ParserBuilder builder)

IncludeSourceSpans

@Js @Serializable { simple=true } enum class IncludeSourceSpans : Enum

Enum for configuring whether to include SourceSpans or not while parsing.

Enum


none	Do not include source spans
blocks	Include source spans on Block nodes
blocks_and_inlines	Include source spans on block nodes and inline nodes

Constructors


fromStr	Return the IncludeSourceSpans instance for the specified name.

Fields


vals	List of IncludeSourceSpans values indexed by ordinal

Slot Details

blocks

const static IncludeSourceSpans blocks := ...

Include source spans on Block nodes

blocks_and_inlines

const static IncludeSourceSpans blocks_and_inlines := ...

Include source spans on block nodes and inline nodes

fromStr

static new fromStr(Str name, Bool checked := true)

Return the IncludeSourceSpans instance for the specified name. If not a valid name and checked is false return null, otherwise throw ParseErr.

none

const static IncludeSourceSpans none := ...

Do not include source spans

vals

const static IncludeSourceSpans[] vals := ...

List of IncludeSourceSpans values indexed by ordinal

IndentedCode

@Js class IndentedCode : Block

Indented code block

Constructors


make

Fields


literal	Indented code literal

Slot Details

literal

Str? literal

Indented code literal

make

new make(Str? literal := null)

InlineContentParser

@Js mixin InlineContentParser

Parser for a type of inline content. Registered via a InlineContentParserFactory and created by its InlineContentParserFactory.create method. The lifetime of this is tied to each inline content snippet that is parsed, as a new instance is created for each.

Methods


tryParse	Try to parse inline content starting from the current position.

Slot Details

tryParse

abstract ParsedInline? tryParse(InlineParserState inlineParserState)

Try to parse inline content starting from the current position. Note that the character at the current position is one of InlineContentParserFactory.triggerChars of the factory that created this parser.

For a given inline content snippet that is being parsed, this method can be called multiple times: each time a trigger character is encountered.

Return the result of parsing; can indicate that this parser is not interested, or that parsing was successful.

InlineContentParserFactory

@Js const mixin InlineContentParserFactory

A factory for extending inline content parsing.

Methods


create	Create an `InlineContentParser` that will do the parsing.
triggerChars	An inline content parser needs to have a special "trigger" character which activates it.

Slot Details

create

abstract InlineContentParser create()

Create an InlineContentParser that will do the parsing. Create is called once per text snippet of inline content inside block structures, and then called each time a trigger character is encountered.

triggerChars

abstract Int[] triggerChars()

An inline content parser needs to have a special "trigger" character which activates it. When this character is encountered during inline parsing, InlineContentParser.tryParse is called wit hthe current parser state. It can also register for more than one trigger character

InlineParser

@Js mixin InlineParser

Parser for inline content (text, links, emphasized text, etc.)

Methods


parse	Parse the lines as inline and append resulting nodes to node (as children)

Slot Details

parse

abstract Void parse(SourceLines lines, Node node)

Parse the lines as inline and append resulting nodes to node (as children)

InlineParserContext

@Js class InlineParserContext : Obj

InlineParserContext

Fields


customDelimiterProcessors
customLinkMarkers
customLinkProcessors
factories

Methods


def	Lookup a definition of a type for a given label.

Slot Details

customDelimiterProcessors

const DelimiterProcessor[] customDelimiterProcessors

customLinkMarkers

const Int[] customLinkMarkers

customLinkProcessors

const LinkProcessor[] customLinkProcessors

def

Block? def(Type type, Str label)

Lookup a definition of a type for a given label.

Note that the label does not need to be normalized; implementations are responsible for doing this normalization before lookup.

factories

const InlineContentParserFactory[] factories

InlineParserState

@Js mixin InlineParserState

InlineParserState

Methods


scanner	Return a scanner for the input for the current position (on the trigger character that the inline parser was added for).

Slot Details

scanner

abstract Scanner? scanner()

Return a scanner for the input for the current position (on the trigger character that the inline parser was added for).

Note that this always returns the same instance, if you want to backtrack you need to use Scanner.pos and Scanner.setPos.

LineBreakRendering

@Js @Serializable { simple=true } enum class LineBreakRendering : Enum

LineBreakRendering

Enum


strip	Strip all line breaks within blocks and between blocks, resulting in all the text on a single line.
compact	Use single line breaks between blocks, not a blank line.
separate_blocks	Separate blocks by a blank line (and respect tight vs loose lists)

Constructors


fromStr	Return the LineBreakRendering instance for the specified name.

Fields


vals	List of LineBreakRendering values indexed by ordinal

Slot Details

compact

const static LineBreakRendering compact := ...

Use single line breaks between blocks, not a blank line. Also renderes all lists as tight

fromStr

static new fromStr(Str name, Bool checked := true)

Return the LineBreakRendering instance for the specified name. If not a valid name and checked is false return null, otherwise throw ParseErr.

separate_blocks

const static LineBreakRendering separate_blocks := ...

Separate blocks by a blank line (and respect tight vs loose lists)

strip

const static LineBreakRendering strip := ...

Strip all line breaks within blocks and between blocks, resulting in all the text on a single line.

vals

const static LineBreakRendering[] vals := ...

List of LineBreakRendering values indexed by ordinal

Link

@Js class Link : LinkNode

A link with a destination and an optional title; the link text is in child nodes

Example for an inline link in a CommonMark document

[link](/uri "title")

Note that the text in the link can contain inline formatting, so it could also contain an image or emphasis, etc.

Constructors


make

Slot Details

make

new make(Str destination, Str? title := null)

LinkInfo

@Js mixin LinkInfo

A parsed link/image. There are different types of links.

Inline links:

[text](destination)
[text](destination "title")

Reference links, which have different subtypes. Full:

[text][label]

Collapsed (label is ""):

[text][]

Shorcut (label is null):

[text]

Images use the same syntax as links but with a ! marker front, e.g. ![text](destination).

Methods


afterTextBracket	The position after the closing text bracket, e.g
destination	The destination if available, e.g.
label	The label, or null for inline links or for shortcut links (in which case `text` should be used as the label).
marker	The marker if present, or null.
openingBracket	The text node of the opening bracket `[`
text	The text between the first brackets, e.g.
title	The title if available, e.g.

Slot Details

afterTextBracket

abstract Position afterTextBracket()

The position after the closing text bracket, e.g:

[foo][bar]
     ^

destination

abstract Str? destination()

The destination if available, e.g. in [foo](destination), or null

label

abstract Str? label()

The label, or null for inline links or for shortcut links (in which case text should be used as the label).

marker

abstract Text? marker()

The marker if present, or null. A marker is e.g. ! for an image, or a customer marker.

openingBracket

abstract Text openingBracket()

The text node of the opening bracket [

text

abstract Str text()

The text between the first brackets, e.g. foo in [foo][bar]

title

abstract Str? title()

The title if available, e.g. in [foo](destination "title"), or null

LinkNode

@Js abstract class LinkNode : Node

Base class for Link and Image nodes

Constructors


make

Fields


destination	Link URL destination
title	Optional link title

Methods


toStrAttributes

Slot Details

destination

Str destination

Link URL destination

make

new make(Str destination, Str? title := null)

title

Str? title

Optional link title

toStrAttributes

protected virtual override Str toStrAttributes()

LinkProcessor

@Js const mixin LinkProcessor

A mixin to decide how links/images are handled

When inline parsing is run, each parsed link/image is passed to the processor. This includes links like these:

[text](destination)
[text]
[text][]
[text][label]

And images

![text](destination)
![text]
![text][]
![text][label]

See LinkInfo for accessing various parts of the parsed link/image

The processor can then inspect the link/image and decide what to do with it by returning the appropriate LinkResult. If it returns null, the next registered processor is tried. If none of them apply, the link is handled as it normally would.

Methods


process	`info`: information about the parsed link/image `scanner`: the scanner at the current position aftger the parsed link/image `cx`: context for inline parsing

Slot Details

process

abstract LinkResult? process(LinkInfo info, Scanner scanner, InlineParserContext cx)

info: information about the parsed link/image scanner: the scanner at the current position aftger the parsed link/image cx: context for inline parsing

Return what to do with the link/image, e.g. do nothing (try next processor), wrap the text in a node, or replace the link/image with a node.

LinkReferenceDefinition

@Js class LinkReferenceDefinition : Block

A link reference definition

[foo]: /url "title"

They can be referenced anywhere else in the document to produce a link using [foo]. The definitions themselves are usually not rendered in the final output.

Constructors


make

Fields


destination
label
title

Slot Details

destination

const Str destination

label

const Str label

make

new make(Str label, Str destination, Str? title)

title

const Str? title

LinkResult

@Js class LinkResult : Obj

LinkResult

Constructors


none	Link not handled by processor
replaceWith	Replace the link with a node, e.g.
wrapTextIn	Wrap the link text in a node.

Fields


includeMarker	If a `LinkInfo.marker` is present, include it in processing (i.e.
node
pos
wrap

Methods


replace

Slot Details

includeMarker

Bool includeMarker := false

If a LinkInfo.marker is present, include it in processing (i.e. treat it the same way as the brackets).

node

Node node { private set }

none

static new none()

Link not handled by processor

pos

const Position pos

replace

Bool replace()

replaceWith

static new replaceWith(Node node, Position pos)

Replace the link with a node, e.g. for this:

[^foo]

The processor could decide to create a footnote reference node instead which replaces the link.

node: the node to replace the link with pos: the position to continue parsing from

wrap

const Bool wrap

wrapTextIn

static new wrapTextIn(Node node, Position pos)

Wrap the link text in a node. This is the normal behavior for links, e.g. for this:

[my *text*](destination)

The text is my *text*, a text node and emphasis. The text is wrapped in a link node, which means the text is added as child nodes to it.

node: the node to which the link text nodes will be added as child nodes pos: the position to continue parsing from

ListBlock

@Js abstract class ListBlock : Block

Abstract base class for list blocks

Fields


tight	Whether this list is tight or loose

Slot Details

tight

Bool tight := false

Whether this list is tight or loose

spec: A list is loose if any of its constituent list items are separated by blank lines, or if any of its constituent list items directly contain two block-level elements with a blank line between them. Otherwise, a list is tight. (The difference in HTML output is that paragraphs in a loose list are wrapped in <p> tags, while paragraphs in a tight list are not.)

ListItem

@Js class ListItem : Block

List item

Constructors


make

Fields


contentIndent	The indent of the content in columns (spaces or tab stop of 4) if available or null otherwise.
markerIndent	The indent of the marker such as `-` or `1.` in columns (spaces or tab stop of 4) if available, or null otherwise.

Slot Details

contentIndent

Int? contentIndent

The indent of the content in columns (spaces or tab stop of 4) if available or null otherwise. The content indent is counted from the beginning of the line and includes the marker on the first line

- Foo (content indent: 2)
- Foo (content indent: 3)
1. Foo (content indent: 5)

Note that subsequent lines in the same list item need to be indented by at least the content indent to be counted as part of the list item.

make

new make(Int? markerIndent, Int? contentIndent)

markerIndent

Int? markerIndent

The indent of the marker such as - or 1. in columns (spaces or tab stop of 4) if available, or null otherwise.

- Foo (marker indent: 0)
- Foo (marker indent: 1)
1. Foo (marker indent: 2)

MarkdownContext

@Js class MarkdownContext : Obj

Context for rendering nodes to Markdown

Fields


writer

Methods


render
specialChars

Slot Details

render

Void render(Node node)

specialChars

Int[] specialChars()

writer

MarkdownWriter writer { private set }

MarkdownExt

@Js const mixin MarkdownExt

Mixin for parser/renderer extensions.

Markdown extensions encapsulate all the modifications to the parser/renderer to support a given markdown "feature" (e.g. tables, strikethrough, etc.). The are registered using the methods on the various builders.

Methods


extendHtml	Callback to extend the HTML renderer.
extendMarkdown	Callback to extend the Markdown renderer.
extendParser	Callback to extend the parser.
extendText	Callback to extend the Plaintext renderer.

Slot Details

extendHtml

virtual Void extendHtml(HtmlRendererBuilder builder)

Callback to extend the HTML renderer. Default implementation does nothing.

extendMarkdown

virtual Void extendMarkdown(MarkdownRendererBuilder builder)

Callback to extend the Markdown renderer. Default implementation does nothing.

extendParser

virtual Void extendParser(ParserBuilder builder)

Callback to extend the parser. Default implementation does nothing.

extendText

virtual Void extendText(TextRendererBuilder builder)

Callback to extend the Plaintext renderer. Default implementation does nothing.

MarkdownRenderer

@Js const class MarkdownRenderer : Obj, Renderer

Renders nodes to Markdown (CommonMark syntax).

Constructors


make	Get a renderer with all the default configuration

Methods


builder	Obtain a builder for configuring the renderer
renderTo

Slot Details

builder

static MarkdownRendererBuilder builder()

Obtain a builder for configuring the renderer

make

static new make()

Get a renderer with all the default configuration

renderTo

virtual override Void renderTo(OutStream out, Node node)

MarkdownRendererBuilder

@Js class MarkdownRendererBuilder : Obj

Builder for configuring a MarkdownRenderer

Methods


build	Build the configured `MarkdownRenderer`.
extensions	Enable the given extensions on this renderer.
nodeRendererFactory	Add a factory for a node renderer.
withSpecialChars	Register additional special characters that must be escaped in normal text

Slot Details

build

MarkdownRenderer build()

Build the configured MarkdownRenderer.

extensions

This extensions(MarkdownExt[] exts)

Enable the given extensions on this renderer.

nodeRendererFactory

This nodeRendererFactory(|MarkdownContext->NodeRenderer| factory)

Add a factory for a node renderer. This allows to override the rendering of node types or define rendering for custom node types.

withSpecialChars

This withSpecialChars(Int[] special)

MarkdownWriter

@Js class MarkdownWriter : Obj

Writer for Markdown (CommonMark) text.

Constructors


make

Fields


atLineStart	Wheter we're at the line start (not counting any prefixes), i.e.
lastChar	The last character that was written

Methods


block	Enqueue a block separator to be written before the next text is written.
line	Write a newline (line terminator).
popPrefix	Remove the last prefix from the top of the stack
popRawEscape	Remove the last raw escape from the top of the stack
popTight	Remove the last "tight" setting from the top of the stack
pushPrefix	Push a prefix onto the top of the stack.
pushRawEscape	Escape the characters matching the supplied matcher, in all text (text and raw).
pushTight	Change whether blocks are tight or loose.
raw	Write the supplied string or character (raw/unescaped except if `pushRawEscape` was used).
text	Write the supplied string with escaping
writePrefix	Write a prefix

Slot Details

atLineStart

Bool atLineStart := true { private set }

Wheter we're at the line start (not counting any prefixes), i.e. after a line or block.

block

Void block()

Enqueue a block separator to be written before the next text is written. Block separators are not written straight away because if there are no more blocks to write, we don't want a separator (at the end of the document)

lastChar

Int lastChar := 0 { private set }

The last character that was written

line

Void line()

Write a newline (line terminator).

make

new make(OutStream out)

popPrefix

Void popPrefix()

Remove the last prefix from the top of the stack

popRawEscape

Void popRawEscape()

Remove the last raw escape from the top of the stack

popTight

Void popTight()

Remove the last "tight" setting from the top of the stack

pushPrefix

Void pushPrefix(Str prefix)

Push a prefix onto the top of the stack. All prefixes are written at the beginning of each line, until the prefix is popped again.

pushRawEscape

Void pushRawEscape(|Int->Bool| rawEscape)

Escape the characters matching the supplied matcher, in all text (text and raw). This might be usefult to extensions that add another layer of syntax, e.g. the tables extension that uses | to separate cells and needs all | characters to be escaped (even in code spans)

pushTight

Void pushTight(Bool tight)

Change whether blocks are tight or loose. Loose is the default where blocks are separated by a blank line. Tight is where blocks are not separated by a blank line. Tight blocks are used in lists, if there are no blank lines within the list.

Note that changing this does not affect block separators that have already been enqueued with block, only future ones.

raw

Void raw(Obj obj)

Write the supplied string or character (raw/unescaped except if pushRawEscape was used).

text

Void text(Str s, |Int->Bool|? escape := null)

Write the supplied string with escaping

writePrefix

Void writePrefix(Str prefix)

Write a prefix

MatchedBlockParser

@Js class MatchedBlockParser : Obj

Open block parser that was last matched during the continue phase. This is different from the currently active block parser, as an unmatched block is only closed when a new block is started.

Constructors


make

Fields


matchedBlockParser

Methods


paragraphLines

Slot Details

make

new make(BlockParser matchedBlockParser)

matchedBlockParser

BlockParser matchedBlockParser { private set }

paragraphLines

SourceLines paragraphLines()

Node

@Js abstract class Node : Obj

Base class for all CommonMark AST nodes.

The CommonMark AST is a tree of nodes where each node can have any number of children and one parent - except the root node which has no parent.

Constructors


make

Fields


firstChild
lastChild
next
prev
sourceSpans

Methods


addSourceSpan	Add a source span to the end of the list.
appendChild	Insert the child node as the last child node of this node.
children	Get all the direct children of this node
doc	Get the root `Document` node or null if this node is mounted in a document yet
eachBetween	Get nodes between start (exclusive) and end (exclusive) by iterating siblings of the start node.
eachChild	Invoke the callback on each direct child of this node
eachDescendant	Recursively walk the descendants of this node using a depth-first search and invoke the callback on each node.
find	Recursively try to find a node with the given type within the children of this node.
findAll	Recursively find all children of this node for which the callback returns true
insertAfter	Inserts the sibling node after this node
insertBefore	Inserts the sibiling node before this node
loc	Get the file location for this node from the original parsed source.
parent	The parent node or null if this is the root of the AST
setParent	Used by sub-classes to set or clear this node's parent
setSourceSpans	Replace the current source spans with the provided list
toStr
toStrAttributes
unlink	Completely detach this node from the AST
walk	Walk the AST using the given visitor.

Slot Details

addSourceSpan

Void addSourceSpan(SourceSpan? sourceSpan)

Add a source span to the end of the list. If it is null, this is a no-op

appendChild

This appendChild(Node child)

Insert the child node as the last child node of this node.

children

Node[] children()

Get all the direct children of this node

doc

Document? doc()

Get the root Document node or null if this node is mounted in a document yet

eachBetween

static Void eachBetween(Node start, Node? end, |Node| f)

Get nodes between start (exclusive) and end (exclusive) by iterating siblings of the start node.

// A -> B -> C-> D-> E
        |->B1    |-> D1
        |->B2

Node.eachBetween(A, D, f)    => f(B), f(C)
Node.eachBetween(B, null, f) => f(C), f(D), f(E)

eachChild

Void eachChild(|Node| f)

Invoke the callback on each direct child of this node

eachDescendant

Void eachDescendant(|Node| f)

Recursively walk the descendants of this node using a depth-first search and invoke the callback on each node.

find

Node? find(Type nodeType, Bool checked := true)

Recursively try to find a node with the given type within the children of this node. If checked, throw an error if the node could not be found; otherwise return null.

findAll

Node[] findAll(|Node->Bool| f)

Recursively find all children of this node for which the callback returns true

firstChild

Node? firstChild { private set }

insertAfter

Void insertAfter(Node sibling)

Inserts the sibling node after this node

insertBefore

Void insertBefore(Node sibling)

Inserts the sibiling node before this node

lastChild

Node? lastChild { private set }

loc

FileLoc loc()

Get the file location for this node from the original parsed source. If the location is not known or source spans were not enabled during parsing, then return FileLoc.unknown.

make

new make()

Node? next { private set }

parent

virtual Node? parent()

The parent node or null if this is the root of the AST

Node? prev { private set }

setParent

protected virtual Void setParent(Node? p)

Used by sub-classes to set or clear this node's parent

setSourceSpans

Void setSourceSpans(SourceSpan[] sourceSpans)

Replace the current source spans with the provided list

sourceSpans

SourceSpan[] sourceSpans := SourceSpan[,] { private set }

toStr

virtual override Str toStr()

toStrAttributes

protected virtual Str toStrAttributes()

unlink

Void unlink()

Completely detach this node from the AST

walk

virtual Void walk(Visitor visitor)

Walk the AST using the given visitor. By default, we use reflection to call visitor.visit${this.typeof.name}

NodeRenderer

@Js mixin NodeRenderer

A renderer for a set of node types

Methods


afterRoot	Called after the root node is rendered, to do any final processing at the end
beforeRoot	Called before the root node is rendered, to do any initial processing at the start
nodeTypes	Get the `Node` types that this renderer handles.
render	Render the specified node

Slot Details

afterRoot

virtual Void afterRoot(Node rootNode)

Called after the root node is rendered, to do any final processing at the end

beforeRoot

virtual Void beforeRoot(Node rootNode)

Called before the root node is rendered, to do any initial processing at the start

nodeTypes

abstract Type[] nodeTypes()

Get the Node types that this renderer handles.

render

abstract Void render(Node node)

Render the specified node

OrderedList

@Js class OrderedList : ListBlock

Ordered list block

Constructors


make

Fields


markerDelim	The delimiter used in the marker, e.g.
startNumber	The start number used in the marker, e.g.

Slot Details

make

new make(Int? startNumber, Str? markerDelim)

markerDelim

Str? markerDelim

The delimiter used in the marker, e.g. . or ), if available, or null otherwise

startNumber

Int? startNumber

The start number used in the marker, e.g. 1, if available, or null otherwise

Paragraph

@Js class Paragraph : Block

Paragraph

Slot Details

ParsedInline

@Js class ParsedInline : Obj

ParsedInline

Constructors


none
of

Fields


node
pos

Slot Details

node

Node node { private set }

none

static new none()

of

static new of(Node node, Position pos)

pos

const Position pos

Parser

@Js const class Parser : Obj

Parse input text into a tree of nodes.

The parser is thread-safe meaning the same parser can be shared by multiple actors.

Constructors


make	Get a parser with all the default configuration

Methods


builder	Obtain a builder for configuring the parser
parse	Convenience for `parseStream(text.in)`
parseFile	Convenience to parse a file into a `Document`.
parseStream	Parse the contents of the input stream into a tree of nodes.

Slot Details

builder

static ParserBuilder builder()

Obtain a builder for configuring the parser

make

static new make()

Get a parser with all the default configuration

parse

Document parse(Str text)

Convenience for parseStream(text.in)

parseFile

Document parseFile(File file)

Convenience to parse a file into a Document. If source span parsing is enabled the nodes will have access to the file location using Node.loc.

parseStream

Document parseStream(InStream in)

Parse the contents of the input stream into a tree of nodes.

doc := Parser().parse("Hello *Markdown*!")

ParserBuilder

@Js class ParserBuilder : Obj

Builder for customizing the behavior of the common mark parser

Methods


build	Get the configured `Parser`
customBlockParserFactory	Add a custom block parser factory.
customDelimiterProcessor
customInlineContentParserFactory	Add a factory for a custom inline content parser, for extending inline parsing or overriding built-in parsing.
extensions	Configure the given extensions on this parser.
linkMarker	Add a custom link marker for link processing.
linkProcessor	Add a custom link/image processor for inline parsing.
postProcessorFactory
withEnabledBlockTypes	Describe the list of markdown features the parser will recognize and parse.

Slot Details

build

Parser build()

Get the configured Parser

customBlockParserFactory

This customBlockParserFactory(BlockParserFactory factory)

Add a custom block parser factory.

Note that custom factories are applied before the built-in factories. This is so that extensions can change how some syntax is parsed that would otherwise be handled by built-in factories.

customDelimiterProcessor

This customDelimiterProcessor(DelimiterProcessor delimiterProcessor)

customInlineContentParserFactory

This customInlineContentParserFactory(InlineContentParserFactory factory)

Add a factory for a custom inline content parser, for extending inline parsing or overriding built-in parsing.

Note that parsers are triggered based on a special character as specified by InlineContentParserFactory.triggerChars. It is possible to register multiple parsers for the same character, or even for some built-in special character such as `. The custom parsers are tried first in the order in which they are registered, and then the built-in ones.

extensions

This extensions(MarkdownExt[] exts)

Configure the given extensions on this parser.

linkMarker

This linkMarker(Int marker)

Add a custom link marker for link processing. A link marker is a character like ! which, if it appears before the [ of a link, changes the meaning of the link.

If a link marker followed by a valid link is parsed, the LinkInfo that is passed to the LinkProcessor will have its LinkInfo.marker set. A link processor should check the Text.literal and then do any processing, and will probably want to use LinkResult.includeMarker.

linkProcessor

This linkProcessor(LinkProcessor linkProcessor)

Add a custom link/image processor for inline parsing.

Multiple link processors can be added, and will be tried in the order in which they were added. If no processor applies, the normal behavior applies. That means these can override built-in link parsing.

postProcessorFactory

This postProcessorFactory(|->PostProcessor| factory)

withEnabledBlockTypes

This withEnabledBlockTypes(Type[] enabledBlockTypes)

Describe the list of markdown features the parser will recognize and parse.

By default, we will recognize and parse the following set of "block" elements:

Heading (#)
HtmlBlock (<html></html>)
ThematicBreak (Horizontal Rule) (---)
FencedCode (```)
IndentedCode
BlockQuote (>)
ListBlock (Ordered/Unordered List) (1. / *)

To parse only a subset of the features listed above, pass a lsit of each feature's associated Block type.

Example: to parse only headings and lists:

Parser.builder.withEnabledBlockTypes([Heading#, ListBlock#])

ParserState

@Js mixin ParserState

Block parsing state.

Methods


activeBlockParser	Get the deepest open block parser
column	The colum is the position within the line after tab characters have been processed as 4-space tab stops.
indent	Get the indentation in columns (either by spaces or tab stop of 4), starting from `column`.
index	The current index within the line (0-based)
isBlank	Return true if the current line is blank starting from the `index`
line	The current source line being parsed (full line)
nextNonSpaceIndex	Get the index of the next non-space character starting from `index` (may be the same) (0-based)

Slot Details

activeBlockParser

abstract BlockParser activeBlockParser()

Get the deepest open block parser

column

abstract Int column()

The colum is the position within the line after tab characters have been processed as 4-space tab stops. If the line doesn't contain any tabs, it's the same as the index. If the line starts with a tab, followed by text, then the column for the first character of the text is 4 (the index is 1)

Returns the current column within the line (0-based)

indent

abstract Int indent()

Get the indentation in columns (either by spaces or tab stop of 4), starting from column.

index

abstract Int index()

The current index within the line (0-based)

isBlank

abstract Bool isBlank()

Return true if the current line is blank starting from the index

line

abstract SourceLine? line()

The current source line being parsed (full line)

nextNonSpaceIndex

abstract Int nextNonSpaceIndex()

Get the index of the next non-space character starting from index (may be the same) (0-based)

Position

@Js const class Position : Obj

A position in the Scanner consists of its line index (i.e. line number) and its index within the line

Constructors


make

Fields


index
lineIndex

Methods


toStr

Slot Details

index

const Int index

lineIndex

const Int lineIndex

make

new make(Int lineIndex, Int index)

toStr

virtual override Str toStr()

PostProcessor

@Js mixin PostProcessor

PostProcessors are run as the last step of parsing and provide an opportunity to inspect/modify the parsed AST before rendering.

Methods


process	Post-process this node and return the result (which may be a modified node).

Slot Details

process

abstract Node process(Node node)

Post-process this node and return the result (which may be a modified node).

Renderer

@Js mixin Renderer

Renders a tree of nodes

Methods


render
renderTo

Slot Details

render

virtual Str render(Node node)

renderTo

abstract Void renderTo(OutStream out, Node node)

Scanner

@Js class Scanner : Obj

Scanner is a utility class for parsing lines

Constructors


make
makeLine
makeSourceLines

Methods


find	Scan until we find the given `ch`.
findMatch	Consume characters until the given function returns true, or the end-of-line is reached.
hasNext	Are there more characters to consume
match	Consume characters while the given function returns `true` and return the number of characters consumed.
matchMultiple	Consume as many `ch` in a row as possible and return the number consumed.
next	Advance the scanner to the next character
nextCh	Check if the specified char is next and advance the position.
nextStr	Check if we have the specified content on the line and advance the position.
peek	Peek at the next character without consuming it
peekCodePoint	Peek at the next code point
peekPrevCodePoint	Peek at the previous codepoint
pos	Get the current position (current line, index into that line)
setPos	Set the current position for the scanner
source	For cases where the caller appends the result to a StrBuf, we could offer another method to avoid some unnecessary copying.
whitespace	Consume whitespace and return the number of whitespace characters consumed

Slot Details

find

Int find(Int ch)

Scan until we find the given ch. Return the number of characters skipped, or -1 if we hit the end of the line.

findMatch

Int findMatch(|Int->Bool| f)

Consume characters until the given function returns true, or the end-of-line is reached. Return the number of characters skipped, or -1 if we reach the end.

hasNext

Bool hasNext()

Are there more characters to consume

make

new make(SourceLine[] lines, Int lineIndex := 0, Int index := 0)

makeLine

new makeLine(SourceLine line)

makeSourceLines

new makeSourceLines(SourceLines sourceLines)

match

Int match(|Int->Bool| f)

Consume characters while the given function returns true and return the number of characters consumed.

matchMultiple

Int matchMultiple(Int ch)

Consume as many ch in a row as possible and return the number consumed.

Void next()

Advance the scanner to the next character

nextCh

Bool nextCh(Int ch)

Check if the specified char is next and advance the position.

ch: the char to check (including newline chars)

Return true if matched and position was advanced; false otherwise

nextStr

Bool nextStr(Str content)

Check if we have the specified content on the line and advance the position. Note that if you want to match newline characters, use nextCh.

content: the text content to match on a single line (excluding newline)

Return true if matched and position was advanced; false otherwise

peek

Int peek()

Peek at the next character without consuming it

peekCodePoint

Int peekCodePoint()

Peek at the next code point

peekPrevCodePoint

Int peekPrevCodePoint()

Peek at the previous codepoint

pos

Position pos()

Get the current position (current line, index into that line)

setPos

Void setPos(Position pos)

Set the current position for the scanner

source

SourceLines source(Position begin, Position end)

For cases where the caller appends the result to a StrBuf, we could offer another method to avoid some unnecessary copying.

whitespace

Int whitespace()

Consume whitespace and return the number of whitespace characters consumed

Whitespace is defined as space, \t, \n, \u000B, \f, and \r

SoftLineBreak

@Js class SoftLineBreak : Node

Soft line break

Slot Details

SourceLine

@Js const class SourceLine : Obj

A line or portion of a line from the markdown source text

Constructors


make

Fields


content	The line content
sourceSpan	The source span if the parser was configured to include it

Methods


substring	Get a new source line that is a substring of this one.
toStr

Slot Details

content

const Str content

The line content

make

new make(Str content, SourceSpan? sourceSpan := null)

sourceSpan

const SourceSpan? sourceSpan

The source span if the parser was configured to include it

substring

SourceLine substring(Int beginIndex, Int endIndex)

Get a new source line that is a substring of this one. The beginIndex is inclusive, and the endIndex is exclusive.

toStr

virtual override Str toStr()

SourceLines

@Js class SourceLines : Obj

A set of lines (SourceLine) from the input source.

Constructors


empty
make
makeOne

Fields


lines

Methods


addLine
content
isEmpty
sourceSpans

Slot Details

addLine

Void addLine(SourceLine line)

content

Str content()

empty

static new empty()

isEmpty

Bool isEmpty()

lines

SourceLine[] lines := SourceLine[,] { private set }

make

new make(SourceLine[] lines)

makeOne

new makeOne(SourceLine line)

sourceSpans

SourceSpan[] sourceSpans()

SourceSpan

@Js const class SourceSpan : Obj

References a snippet of text from the source input.

It has a starting positiont (line and column index) and a length of how many characters it spans.

Constructors


of

Fields


columnIndex	0-based index of column (i.e.
inputIndex	0-based index in whole input
len	Length of the span in characters
lineIndex	0-based line index, e.g.

Methods


equals
hash
subSpan
toStr

Slot Details

columnIndex

const Int columnIndex

0-based index of column (i.e. character on line) in source, e.g. 0 for the first character of a line, 1 for the second character, etc.

equals

virtual override Bool equals(Obj? obj)

hash

virtual override Int hash()

inputIndex

const Int inputIndex

0-based index in whole input

len

const Int len

Length of the span in characters

lineIndex

const Int lineIndex

0-based line index, e.g. 0 for first line, 1 for second line, etc.

of

new of(Int lineIndex, Int columnIndex, Int inputIndex, Int len)

subSpan

SourceSpan subSpan(Int beginIndex, Int endIndex := this.len)

toStr

virtual override Str toStr()

SourceSpans

@Js class SourceSpans : Obj

A list of source spans that can be added to. Takes care of merging adjacent source spans

Constructors


empty
priv_make

Fields


sourceSpans

Methods


addAll
addAllFrom

Slot Details

addAll

Void addAll(SourceSpan[] other)

addAllFrom

Void addAllFrom(Node[] nodes)

empty

static new empty()

priv_make

new priv_make()

sourceSpans

SourceSpan[] sourceSpans := SourceSpan[,] { private set }

StrongEmphasis

@Js class StrongEmphasis : Node, Delimited

Strong emphasis

Constructors


make

Fields


delimiter

Methods


closingDelim
openingDelim

Slot Details

closingDelim

virtual override Str closingDelim()

delimiter

const Str delimiter

make

new make(Str delimiter)

openingDelim

virtual override Str openingDelim()

Table

@Js class Table : CustomBlock

Table block containing a TableHead and optionally a TableBody

Slot Details

TableBody

@Js class TableBody : CustomNode

Body part of a Table containing TableRows

Slot Details

TableCell

@Js class TableCell : CustomNode

Table cell of a TableRow containing inline nodes

Constructors


make
makeFields

Fields


alignment	The cell alignment
header	Is the cell a header or not
width	The cell width (the number of dash and colon characters in the delimiter row of the table for this column)

Methods


toStrAttributes

Slot Details

alignment

Alignment alignment

The cell alignment

Bool header

Is the cell a header or not

make

new make()

makeFields

new makeFields(Bool header, Alignment alignment, Int width)

toStrAttributes

protected virtual override Str toStrAttributes()

width

Int width

The cell width (the number of dash and colon characters in the delimiter row of the table for this column)

TableHead

@Js class TableHead : CustomNode

Head part of a Table containing TableRows

Slot Details

TableRow

@Js class TableRow : CustomNode

Table row of a TableHead or TableBody containing TableCells

Slot Details

TablesExt

@Js const class TablesExt : Obj, MarkdownExt

Extension for GFM tables using "|" pipes. (GitHub Flavored Markdown).

See Tables (extension) in GitHub Flavored Markdown Spec

Methods


extendHtml
extendMarkdown
extendParser
extendText

Slot Details

extendHtml

virtual override Void extendHtml(HtmlRendererBuilder builder)

extendMarkdown

virtual override Void extendMarkdown(MarkdownRendererBuilder builder)

extendParser

virtual override Void extendParser(ParserBuilder builder)

extendText

virtual override Void extendText(TextRendererBuilder builder)

Text

@Js class Text : Node

Text

Constructors


make

Fields


literal

Methods


toStrAttributes

Slot Details

literal

Str literal

make

new make(Str literal)

toStrAttributes

protected virtual override Str toStrAttributes()

TextContext

@Js class TextContext : Obj

Context for rendering nodes to plain text

Fields


writer

Methods


render
stripNewLines

Slot Details

render

Void render(Node node)

stripNewLines

Bool stripNewLines()

writer

TextWriter writer { private set }

TextRenderer

@Js const class TextRenderer : Obj, Renderer

Renders a tree of nodes to plain text

Constructors


make	Get a renderer with all the default configuration

Methods


builder	Obtain a builder for configuring the renderer
renderTo

Slot Details

builder

static TextRendererBuilder builder()

Obtain a builder for configuring the renderer

make

static new make()

Get a renderer with all the default configuration

renderTo

virtual override Void renderTo(OutStream out, Node node)

TextRendererBuilder

@Js class TextRendererBuilder : Obj

Builder for configuring a TextRenderer

Methods


build	Get the configured `TextRenderer`
extensions	Enable the given extensions on this renderer.
nodeRendererFactory	Add a factory for instantiating a node renderer (done when rendering).
withLineBreakRendering	Configure how line breaks (newlines) are rendered.

Slot Details

build

TextRenderer build()

Get the configured TextRenderer

extensions

This extensions(MarkdownExt[] exts)

Enable the given extensions on this renderer.

nodeRendererFactory

This nodeRendererFactory(|TextContext->NodeRenderer| factory)

Add a factory for instantiating a node renderer (done when rendering). This allows This allows to override the rendering of node types or define rendering for custom node types.

If multiple node renderers for the same node type are created, the one from the factory that was added first "wins". (This is how the rendering for core node types can be overridden; the default rendering comes last).

withLineBreakRendering

This withLineBreakRendering(LineBreakRendering lineBreakRendering)

Configure how line breaks (newlines) are rendered. The default is LineBreakRendering.compact

TextWriter

@Js class TextWriter : Obj

Text writer for markdown rendering

Constructors


make

Methods


block
colon
line
popTight	Remove the last "tight" setting from the top of the stack.
pushTight	Change whether blocks are tight or loose.
resetBlock
whitespace
write
writeChar
writeStripped

Slot Details

block

This block()

colon

This colon()

line

This line()

make

new make(OutStream out, LineBreakRendering lineBreakRendering := LineBreakRendering.compact)

popTight

Void popTight()

Remove the last "tight" setting from the top of the stack.

pushTight

Void pushTight(Bool tight)

Change whether blocks are tight or loose. Loose is the default where blocks are separated by a blank line. Tight is where blocks are not spearated by a blank line. Tight blocks are used in lists, if there are no blank lines within the list.

Note that changing this does not affect block separators that have already been enqueued with block; only future ones.

resetBlock

This resetBlock()

whitespace

This whitespace()

write

This write(Str s)

writeChar

This writeChar(Int ch)

writeStripped

This writeStripped(Str s)

ThematicBreak

@Js class ThematicBreak : Block

Thematic break block

Constructors


make

Fields


literal	source literal that represents this break, if available

Slot Details

literal

Str? literal

source literal that represents this break, if available

make

new make(Str? literal := null)

UrlSanitizer

@Js const mixin UrlSanitizer

Sanitizes uris for img and a elements by whitelisting protocols. This is intended to prevent XSS payloads like

[Click this totally safe url](javascript:document.xss=true;)

Implementation based on https://github.com/OWASP/java-html-sanitizer/blob/f07e44b034a45d94d6fd010279073c38b6933072/src/main/java/org/owasp/html/FilterUrlByProtocolAttributePolicy.java

Methods


sanitizeImage	Sanitize a url for use in the src attribute of a Image
sanitizeLink	Sanitize a url for use in the href attribute of a Link

Slot Details

sanitizeImage

virtual Str sanitizeImage(Str url)

Sanitize a url for use in the src attribute of a Image

sanitizeLink

abstract Str sanitizeLink(Str url)

Sanitize a url for use in the href attribute of a Link

Visitor

@Js mixin Visitor

Node visitor

Methods


visitBlockQuote
visitBulletList
visitChildren	Visit the children nodes of the parent
visitCode
visitCustomBlock
visitCustomNode
visitDocument
visitEmphasis
visitFencedCode
visitHardLineBreak
visitHeading
visitHtmlBlock
visitHtmlInline
visitImage
visitIndentedCode
visitLink
visitLinkReferenceDefinition
visitListItem
visitOrderedList
visitParagraph
visitSoftLineBreak
visitStrongEmphasis
visitText
visitThematicBreak

Slot Details

visitBlockQuote

virtual Void visitBlockQuote(BlockQuote node)

visitBulletList

virtual Void visitBulletList(BulletList node)

visitChildren

protected virtual Void visitChildren(Node parent)

Visit the children nodes of the parent

visitCode

virtual Void visitCode(Code node)

visitCustomBlock

virtual Void visitCustomBlock(CustomBlock node)

visitCustomNode

virtual Void visitCustomNode(CustomNode node)

visitDocument

virtual Void visitDocument(Document node)

visitEmphasis

virtual Void visitEmphasis(Emphasis node)

visitFencedCode

virtual Void visitFencedCode(FencedCode node)

visitHardLineBreak

virtual Void visitHardLineBreak(HardLineBreak node)

visitHeading

virtual Void visitHeading(Heading node)

visitHtmlBlock

virtual Void visitHtmlBlock(HtmlBlock node)

visitHtmlInline

virtual Void visitHtmlInline(HtmlInline node)

visitImage

virtual Void visitImage(Image node)

visitIndentedCode

virtual Void visitIndentedCode(IndentedCode node)

visitLink

virtual Void visitLink(Link node)

visitLinkReferenceDefinition

virtual Void visitLinkReferenceDefinition(LinkReferenceDefinition node)

visitListItem

virtual Void visitListItem(ListItem node)

visitOrderedList

virtual Void visitOrderedList(OrderedList node)

visitParagraph

virtual Void visitParagraph(Paragraph node)

visitSoftLineBreak

virtual Void visitSoftLineBreak(SoftLineBreak node)

visitStrongEmphasis

virtual Void visitStrongEmphasis(StrongEmphasis node)

visitText

virtual Void visitText(Text node)

visitThematicBreak

virtual Void visitThematicBreak(ThematicBreak node)

markdown ​

目录（导读） ​

API 正文（英文） ​

enums ​

docs ​

Overview ​

Usage ​

HTML Rendering ​

Plaintext Rendering ​

Extensions ​

Alignment ​

Slot Details ​

center ​

fromStr ​

left ​

right ​

unspecified ​

vals ​

AttrProvider ​

Slot Details ​

setAttrs ​

Block ​

Slot Details ​

parent ​

setParent ​

BlockContinue ​

Slot Details ​

atColumn ​

atIndex ​

finalize ​

finished ​

newColumn ​

newIndex ​

none ​

BlockParser ​

Slot Details ​

addLine ​

addSourceSpan ​

block ​

canContain ​

canHaveLazyContinuationLines ​

closeBlock ​

definitions ​

isContainer ​

parseInlines ​

tryContinue ​

BlockParserFactory ​

Slot Details ​

tryStart ​

BlockQuote ​

Slot Details ​

BlockStart ​

Slot Details ​

atColumn ​

atIndex ​

blockParsers ​

isReplaceActiveBlockParser ​

newColumn ​

newIndex ​

none ​

of ​

replaceActiveBlockParser ​

BulletList ​

Slot Details ​

make ​

marker ​

Code ​

Slot Details ​

literal ​

make ​

toStrAttributes ​

CustomBlock ​

Slot Details ​

CustomNode ​

Slot Details ​

DefinitionMap ​

Slot Details ​

addAll ​

get ​

make ​

markdown

目录（导读）

API 正文（英文）

enums

docs

Overview

Usage

HTML Rendering

Plaintext Rendering

Extensions

Alignment

Slot Details

center

fromStr

left

right

unspecified

vals

AttrProvider

Slot Details

setAttrs

Block

Slot Details

parent

setParent

BlockContinue

Slot Details

atColumn

atIndex

finalize

finished

newColumn

newIndex

none

BlockParser

Slot Details

addLine

addSourceSpan

block

canContain

canHaveLazyContinuationLines

closeBlock

definitions

isContainer

parseInlines

tryContinue

BlockParserFactory

Slot Details

tryStart

BlockQuote

Slot Details

BlockStart

Slot Details

atColumn

atIndex

blockParsers

isReplaceActiveBlockParser

newColumn

newIndex

none

of

replaceActiveBlockParser

BulletList

Slot Details

make

marker

Code

Slot Details

literal

make

toStrAttributes

CustomBlock

Slot Details

CustomNode

Slot Details

DefinitionMap

Slot Details

addAll

get

make