pandoc_json $json¶

Parse a JSON string, as emitted by pandoc in JSON format. This is the reverse to method "to_json" but it can read both old (before Pandoc 1.16) and new format.

attributes { key => $value, ... }¶

Maps a hash reference or instance of Hash::MultiValue into the internal structure of Pandoc attributes. The special keys "id" (string), and "class" (string or array reference with space-separated class names) are recognized. See attribute methods for details.

citation { ... }¶

A citation as part of document element Cite must be a hash reference with fields "citationId" (string), "citationPrefix" (list of inline elements) "citationSuffix" (list of inline elements), "citationMode" (one of "NormalCitation", "AuthorInText", "SuppressAuthor"), "citationNoteNum" (integer), and "citationHash" (integer). The helper method "citation" can be used to construct such a hash by filling in default values and optionally using shorter field names ("id", "prefix", "suffix", "mode", "note", and "hash"):

    citation {
        id => 'foo',
        prefix => [ Str "see" ],
        suffix => [ Str "p.", Space, Str "42" ]
    }
    # in Pandoc Markdown
    [see @foo p. 42]

The values returned by this function, as well as any citations contained in document objects returned by "pandoc_json", are blessed hashrefs with getter/setter accessors corresponding to both the full and short field names, so that e.g. "$citation->citationId(...)" and "$citation->id(...)" get or set the same value.

pandoc_version( [ $document ] )¶

Return a Pandoc::Version object with expected version number of pandoc executable to be used for serializing documents with to_json.

If a Document element is given as argument, the minimal pandoc release version compatible with its api version is returned.

Without argument, package variable $PANDOC_VERSION is checked for a preferred pandoc release. By default this variable is set from an environment variable of same name. If no preferred pandoc release has been specified, the function returns version 1.18 because this is the first pandoc release compatible with most recent api version supported by this module.

See also method "version" of module Pandoc to get the current version of pandoc executable on your system.

element( $name => $content )¶

Create a Pandoc document element of arbitrary name. This function is only exported on request.

COMMON METHODS¶

to_json

Return the element as JSON encoded string. The following are equivalent:

    $element->to_json;
    JSON->new->utf8->canonical->convert_blessed->encode($element);

The serialization format can be adjusted to different pandoc versions with module and environment variable "PANDOC_VERSION" or with Document element properties "api_version" and "pandoc_version".

When writing filters you can normally just rely on the api version value obtained from pandoc, since pandoc expects to receive the same JSON format as it emits.

name

Return the name of the element, e.g. "Para" for a paragraph element.

content

Return the element content. For most elements (Para, Emph, Str...) the content is an array reference with child elements. Other elements consist of multiple parts; for instance the Link element has attributes ("attr", "id", "class", "classes", "keyvals") a link text ("content") and a link target ("target") with "url" and "title".

is_block

True if the element is a Block element

is_inline

True if the element is an inline Inline element

is_meta

True if the element is a Metadata element

is_document

True if the element is a Document element

as_block

Return the element unmodified if it is a block element or wrapped in a Plain or Div otherwise.

match( $selector )

Check whether the element matches a given Pandoc::Selector (given as instance or string).

walk(...)

Walk the element tree with Pandoc::Walker

query(...)

Query the element to extract results with Pandoc::Walker

transform(...)

Transform the element tree with Pandoc::Walker

string

Returns a concatenated string of element content, leaving out all formatting.

ATTRIBUTE METHODS¶

Some elements have attributes which can be an identifier, ordered class names and ordered key-value pairs. Elements with attributes provide the following methods:

attr

Get or set the attributes in Pandoc internal structure:

  [ $id, [ @classes ], [ [ key => $value ], ... ] ]

See helper function attributes to create this structure.

keyvals

Get all attributes (id, class, and key-value pairs) as new Hash::MultiValue instance, or replace all key-value pairs plus id and/or class if these are included as field names. All class fields are split by whitespaces.

  $e->keyvals                           # return new Hash::MultiValue
  $e->keyvals( $HashMultiValue )        # update by instance of Hash::MultiValue
  $e->keyvals( key => $value, ... )     # update by list of key-value pairs
  $e->keyvals( \%hash )                 # update by hash reference
  $e->keyvals( { } )                    # remove all key-value pairs
  $e->keyvals( id => '', class => '' )  # remove all key-value pairs, id, class

id

Get or set the identifier. See also Pandoc::Filter::HeaderIdentifiers for utility functions to handle Header identifiers.

class

Get or set the list of classes, separated by whitespace.

add_attribute( $name => $value )

Append an attribute. The special attribute names "id" and "class" set or append identifier or class, respectively.

DOCUMENT ELEMENT¶

Document

Root element, consisting of metadata hash ("meta"), document element array ("content"="blocks") and optional "api_version". The constructor accepts either two arguments and an optional named parameter "api_version":

    Document { %meta }, [ @blocks ], api_version => $version_string

or a hash with three fields for metadata, document content, and an optional pandoc API version:

    {
        meta               => { %metadata },
        blocks             => [ @content ],
        pandoc-api-version => [ $major, $minor, $revision ]
    }

The latter form is used as pandoc JSON format since pandoc release 1.18. If no api version is given, it will be set to 1.21 which was also introduced with pandoc release 2.10.

A third ("old") form is accepted for compatibility with pandoc JSON format before release 1.18 and since release 1.12.1: an array with two elements for metadata and document content respectively.

    [ { unMeta => { %meta } }, [ @blocks ] ]

The api version is set to 1.16 in this case, but older versions down to 1.12.3 used the same format.

Document elements provide the following special methods in addition to common element methods:

api_version( [ $api_version ] )

Return the pandoc-types version (aka "pandoc-api-version") of this document as Pandoc::Version object or sets it to a new value. This version determines how method to_json serializes the document.

See "PANDOC VERSIONS" for details.

pandoc_version( [ $pandoc_version ] )

Return the minimum required version of pandoc executable compatible with the api_version of this document. The following are equivalent:

  $doc->pandoc_version;
  pandoc_version( $doc );
    

If used as setter, sets the api version of this document to be compatible with the given pandoc version.

content or blocks

Get or set the array of block elements of the document.

meta( [ $metadata ] )

Get and/or set combined document metadata. Use method "value" to get selected metadata fields and values.

value( [ $pointer ] [ %options ] )

Get selected document metadata field value(s). See Pandoc::Metadata for documentation. Can also be called as "metavalue", so the following are equivalent:

  $doc->value( ... );
  $doc->meta->value( ... );
  $doc->metavalue( ... );
    

to_pandoc( [ [ $pandoc, ] @arguments ])

Process the document with Pandoc executable and return its output:

    $doc->to_pandoc( -o => 'doc.html' );
    my $markdown = $doc->to_pandoc( -t => 'markdown' );
    

The first argument can optionally be an instance of Pandoc to use a specific executable.

to_...( [ @arguments ] )

Process the document into "markdown" (pandoc's extended Markdown), "latex" (LaTeX), "html" (HTML), "rst" (reStructuredText), or "plain" (plain text). The following are equivalent:

    $doc->to_markdown( @args );
    $doc->to_pandoc( @args, '-t' => 'markdown' );
    

outline( [ $depth ] )

Returns an outline of the document structure based on Header elements. The outline is a hierarchical hash reference with the following fields:

BLOCK ELEMENTS¶

BlockQuote

Block quote, consisting of a list of blocks ("content")

    BlockQuote [ @blocks ]

BulletList

Unnumbered list of items ("content"="items"), each a list of blocks

    BulletList [ [ @blocks ] ]

CodeBlock

Code block (literal string "content") with attributes ("attr", "id", "class", "classes", "keyvals")

    CodeBlock $attributes, $content

DefinitionList

Definition list, consisting of a list of pairs ("content"="items"), each a term ("term", a list of inlines) and one or more definitions ("definitions", a list of blocks).

    DefinitionList [ @definitions ]
    # each item in @definitions being a pair of the form
        [ [ @inlines ], [ @blocks ] ]

Div

Generic container of blocks ("content") with attributes ("attr", "id", "class", "classes", "keyvals").

    Div $attributes, [ @blocks ]

Header

Header with "level" (integer), attributes ("attr", "id", "class", "classes", "keyvals"), and text ("content", a list of inlines).

    Header $level, $attributes, [ @inlines ]

HorizontalRule

Horizontal rule

    HorizontalRule

LineBlock

List of lines ("content"), each a list of inlines.

    LineBlock [ @lines ]

This element was added in pandoc 1.18. Before it was represented Para elements with embedded LineBreak elements. This old serialization form can be enabled by setting $PANDOC_VERSION package variable to a lower version number.

Null

Nothing

    Null

OrderedList

Numbered list of items ("content"="items"), each a list of blocks), preceded by list attributes (start number, numbering style, and delimiter).

    OrderedList [ $start, $style, $delim ], [ [ @blocks ] ]

Supported styles are "DefaultStyle", "Example", "Decimal", "LowerRoman", "UpperRoman", "LowerAlpha", and "UpperAlpha".

Supported delimiters are "DefaultDelim", "Period", "OneParen", and "TwoParens".

Para

Paragraph, consisting of a list of Inline elements ("content").

    Para [ $elements ]

Plain

Plain text, not a paragraph, consisting of a list of Inline elements ("content").

    Plain [ @inlines ]

RawBlock

Raw block with "format" and "content" string.

    RawBlock $format, $content

Table

Table, with "caption", column "alignments", relative column "widths" (0 = default), column "headers" (each a list of blocks), and "rows" (each a list of lists of blocks).

    Table [ @inlines ], [ @alignments ], [ @width ], [ @headers ], [ @rows ]

Possible alignments are "AlignLeft", "AlignRight", "AlignCenter", and "AlignDefault".

An example:

    Table [Str "Example"], [AlignLeft,AlignRight], [0.0,0.0],
     [[Plain [Str "name"]]
     ,[Plain [Str "number"]]],
     [[[Plain [Str "Alice"]]
      ,[Plain [Str "42"]]]
     ,[[Plain [Str "Bob"]]
      ,[Plain [Str "23"]]]];

INLINE ELEMENTS¶

Cite

Citation, a list of "citations" and a list of inlines ("content"). See helper function citation to construct citations.

    Cite [ @citations ], [ @inlines ]

Code

Inline code, a literal string ("content") with attributes ("attr", "id", "class", "classes", "keyvals")

    Code attributes { %attr }, $content

Emph

Emphasized text, a list of inlines ("content").

    Emph [ @inlines ]

Image

Image with alt text ("content", a list of inlines) and "target" (list of "url" and "title") with attributes ("attr", "id", "class", "classes", "keyvals").

    Image attributes { %attr }, [ @inlines ], [ $url, $title ]

Serializing the attributes is disabled in api version less then 1.16.

LineBreak

Hard line break

    LineBreak

Link

Hyperlink with link text ("content", a list of inlines) and "target" (list of "url" and "title") with attributes ("attr", "id", "class", "classes", "keyvals").

    Link attributes { %attr }, [ @inlines ], [ $url, $title ]

Serializing the attributes is disabled in api version less then 1.16.

Math

TeX math, given as literal string ("content") with "type" (one of "DisplayMath" and "InlineMath").

    Math $type, $content

Note

Footnote or Endnote, a list of blocks ("content").

    Note [ @blocks ]

Quoted

Quoted text with quote "type" (one of "SingleQuote" and "DoubleQuote") and a list of inlines ("content").

    Quoted $type, [ @inlines ]

RawInline

Raw inline with "format" (a string) and "content" (a string).

    RawInline $format, $content

SmallCaps

Small caps text, a list of inlines ("content").

    SmallCaps [ @inlines ]

SoftBreak

Soft line break

    SoftBreak

This element was added in pandoc 1.16 as a matter of editing convenience to preserve line breaks (as opposed to paragraph breaks) from input source to output. If you are going to feed a document containing "SoftBreak" elements to Pandoc < 1.16 you will have to set the package variable or environment variable "PANDOC_VERSION" to 1.15 or below.

Space

Inter-word space

    Space

Span

Generic container of inlines ("content") with attributes ("attr", "id", "class", "classes", "keyvals").

    Span attributes { %attr }, [ @inlines ]

Str

Plain text, a string ("content").

    Str $content

Strikeout

Strikeout text, a list of inlines ("content").

    Strikeout [ @inlines ]

Strong

Strongly emphasized text, a list of inlines ("content").

    Strong [ @inlines ]

Subscript

Subscripted text, a list of inlines ("content").

    Supscript [ @inlines ]

Superscript

Superscripted text, a list of inlines ("content").

    Superscript [ @inlines ]

Underline

Underlined text, a list of inlines ("content").

    Underline [ @inlines ]

This element was added in pandoc 2.10. If you are going to feed a document containing "Underline" elements to Pandoc < 2.10 you will have to set the package variable or environment variable "PANDOC_VERSION" to 2.9 or below.

Table

Underlined text, a list of inlines ("content").

    Underline [ @inlines ]

This element was added in pandoc 2.10. If you are going to feed a document containing "Underline" elements to Pandoc < 2.10 you will have to set the package variable or environment variable "PANDOC_VERSION" to 2.9 or below.

METADATA ELEMENTS¶

See Pandoc::Metadata for documentation of metadata elements "MetaBool", "MetaString", "MetaMap", "MetaInlines", "MetaList", and "MetaBlocks".

Helper function "metadata" can be used to convert scalars, hash references, array references, and Pandoc Inline/Block elements into metadata elements.

TYPE KEYWORDS¶

The following document elements are only as used as type keywords in other document elements:

• "SingleQuote", "DoubleQuote"
• "DisplayMath", "InlineMath"
• "AuthorInText", "SuppressAuthor", "NormalCitation"
• "AlignLeft", "AlignRight", "AlignCenter", "AlignDefault"
• "DefaultStyle", "Example", "Decimal", "LowerRoman", "UpperRoman", "LowerAlpha", "UpperAlpha"
• "DefaultDelim", "Period", "OneParen", "TwoParens"