NAME

Pandoc::Elements - create and process Pandoc documents

SYNOPSIS

The output of this script hello.pl

    use Pandoc::Elements;
    use JSON;

    print Document({ 
            title => MetaInlines [ Str "Greeting" ] 
        }, [
            Header( 1, attributes { id => 'top' }, [ Str 'Hello' ] ),
            Para [ Str 'Hello, world!' ],
        ])->to_json;

can be converted for instance to HTML with via

    ./hello.pl | pandoc -f json -t html5 --standalone

an equivalent Pandoc Markdown document would be

    % Greeting
    # Gruß {.de}
    Hello, world!

DESCRIPTION

Pandoc::Elements provides utility functions to create abstract syntax trees (AST) of Pandoc documents. Pandoc can convert the resulting data structure to many other document formats, such as HTML, LaTeX, ODT, and ePUB.

Please make sure to use at least Pandoc 1.12 when processing documents

See also module Pandoc::Filter, command line scripts pandocwalk and pod2pandoc, and the internal modules Pandoc::Walker, Pandoc::Filter::Lazy, and Pod::Simple::Pandoc.

EXPORTED FUNCTIONS

The following functions and keywords are exported by default:

Constructors for all Pandoc document element (block elements such as Para and inline elements such as Emph, metadata elements and the "Document" in DOCUMENT ELEMENT).
Type keywords such as Decimal and LowerAlpha to be used as types in other document elements.
The helper following functions pandoc_json, attributes, citation, and element.

pandoc_json $json

Parse a JSON string, as emitted by pandoc in JSON format. This is the reverse to method to_json.

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

Maps a hash reference into an attributes list with id, classes, and ordered key-value pairs. The special keys id and classes are recognized but setting multi-value attributes or controlled order is not supported with this function. You can always manually create an attributes structure:

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

Elements with attributes (element accessor method attr) also provide the accessor method id, classes, and class. See Hash::MultiValue for easy access to key-value-pairs.

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, C>AuthorInText>, SuppressAuthor), citationNoteNum (integer), and citationHash (integer). The helper method citation can be used to construct such hash by filling in default values and 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]

element( $name => $content )

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

ELEMENTS

Document elements are encoded as Perl data structures equivalent to the JSON structure, emitted with pandoc output format json. All elements are blessed objects that provide the following element methods and additional accessor methods specific to each element.

ELEMENT METHODS

to_json

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

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

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 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

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.

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)

    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).

    Div $attributes, [ @blocks ]

Header with level (integer), attributes (attr), and text (content, a list of inlines).

    Header $level, $attributes, [ @inlines ]

HorizontalRule

Horizontal rule

    HorizontalRule

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" in citation to construct citations.

    Cite [ @citations ], [ @inlines ]

Code

Inline code, a literal string (content) with attributes (attr)

    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).

    Image [ @inlines ], [ $url, $title ]

LineBreak

Hard line break

    LineBreak

Link

Hyperlink with link text (content, a list of inlines) and target (list of url and title).

    Link [ @inlines ], [ $url, $title ]

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 ]

Space

Inter-word space

    Space

Span

Generic container of inlines (content) with attributes (attr).

    Span attributes { %attr }, [ @inlines ]

Str

Plain text, a string (content).

    Str $text

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 ]

METADATA ELEMENTS

MetaBlocks

MetaBool

MetaInlines

MetaList

MetaMap

MetaString

DOCUMENT ELEMENT

Document

Root element, consisting of metadata hash (meta) and document element array (content).

    Document $meta, [ @blocks ]

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

AUTHOR

Jakob Voß <jakob.voss@gbv.de>

COPYRIGHT AND LICENSE

GNU General Public License, Version 2

This module is heavily based on Pandoc by John MacFarlane.

To install Pandoc::Elements, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Pandoc::Elements

CPAN shell

perl -MCPAN -e shell
install Pandoc::Elements

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)