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 <http://pandoc.org/> 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 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 an
    attributes list with id, classes, and ordered key-value pairs. The
    special keys id (string), and class (string or array reference with
    space-separated class names) are recognized. You can always manually
    create an attributes structure:

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

    See also attribute methods to get and set element attributes.

  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 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->canonical->convert_blessed->encode($element);

    Note that the JSON format changed from Pandoc 1.15 to Pandoc 1.16 by
    introduction of attributes to Link and Image elements. Since
    Pandoc::Elements 0.16 the new format is serialized by default. Set the
    package variable or environment variable PANDOC_VERSION to 1.15 or
    below to use the old format.

  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

  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

    Elements with attributes (element accessor method attr) also provide
    the getter methods id, classes, class, keyvals, and setter methods id,
    class, keyvals, add_attribute. Method keyvals returns a copy of id,
    class, and attribute key-value pairs as Hash::MultiValue. If used as
    setter, all key-value pairs (and optionally id and class if given) are
    replaced.

 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

  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, 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 in JSON can be disabled with PANDOC_VERSION.

  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 in JSON can be disabled with PANDOC_VERSION.

  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

    Note that the SoftBreak element was added in Pandoc 1.16 to 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 ]

 METADATA ELEMENTS

    Metadata can be provided in YAML syntax or via command line option -M.
    All metadata elements return true for is_meta. Metadata elements can be
    converted to unblessed Perl array references, hash references, and
    scalars with method metavalue. On the document level, metadata
    (document method meta) is a hash reference with values being metadata
    elements. Document method metavalue returns a flattened copy of this
    hash.

  MetaString

    A plain text string metadata value (content).

        MetaString $content

    MetaString values can also be set via pandoc command line client:

        pandoc -M key=$content

  MetaBool

    A Boolean metadata value (content). The special values "false" and
    "FALSE" are recognized as false in addition to normal false values (0,
    undef, ""...).

        MetaBool $content

    MetaBool values can also be set via pandoc command line client:

        pandoc -M key=true
        pandoc -M key=false

  MetaInlines

    Container for a list of inlines (content) in metadata.

        MetaInlines [ @inlines ]

  MetaBlocks

    Container for a list of blocks (content) in metadata.

        MetaInlines [ @blocks ]

  MetaList

    A list of other metadata elements (content).

        MetaList [ @values ]

  MetaMap

    A map of keys to other metadata elements.

        MetaMap { %map }

 DOCUMENT ELEMENT

  Document

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

        Document $meta, [ @blocks ]

    Document metavalue returns a copy of the metadata hash with all
    metadata elements flattened to unblessed values:

        $doc->metavalue   # equivalent to
        { map { $_ => $doc->meta->{$_}->metavalue } keys %{$doc->meta} }

 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

SEE ALSO

    Pandoc implements a wrapper around the pandoc executable.

    Text.Pandoc.Definition
    <https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Defi
    nition.html> contains the original definition of Pandoc document data
    structure in Haskell. This module version was last aligned with
    pandoc-types-1.16.1.

AUTHOR

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

CONTRIBUTORS

    Benct Philip Jonsson <bpjonsson@gmail.com>

COPYRIGHT AND LICENSE

    Copyright 2014- Jakob Voß

    GNU General Public License, Version 2

    This module is heavily based on Pandoc by John MacFarlane.

