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!

    See module Pandoc::Filter and Pandoc::Walker for processing the
    abstract syntax tree of pandoc documents in Perl.

    See also script pandoc-walk installed with this module.

DESCRIPTION

    Pandoc::Elements provides utility functions to create abstract syntax
    trees (AST) of Pandoc <http://johnmacfarlane.net/pandoc/> documents.
    The resulting data structure can be converted by Pandoc to many other
    document formats, such as HTML, LaTeX, ODT, and ePUB.

 EXPORTED FUNCTIONS

      * 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. For
    instance

        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

 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

        BlockQuote [ [ @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

    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

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

AUTHOR

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

COPYRIGHT AND LICENSE

    Copyright 2014- Jakob Voß

    GNU General Public License, Version 2

    This module is heavily based on Pandoc by John MacFarlane.

