Provided by: libpandoc-elements-perl_0.38-6_all bug

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!' ],
               ],
               api_version => '1.17.0.4'
           )->to_json;

       can be converted for instance to HTML via

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

       an equivalent Pandoc Markdown document would be

           % Greeting
           # Gruss {.de}
           Hello, world!

DESCRIPTION

       Pandoc::Elements provides utility functions to parse, serialize, and modify abstract
       syntax trees (AST) of Pandoc <http://pandoc.org/> documents. Pandoc can convert this data
       structure to many other document formats, such as HTML, LaTeX, ODT, and ePUB.

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

PANDOC VERSIONS

       The Pandoc document model is defined in file Text.Pandoc.Definition
       <https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html> as
       part of Haskell package pandoc-types <https://hackage.haskell.org/package/pandoc-types>.

       Pandoc::Elements is compatible with pandoc-types 1.12.3 (released with pandoc 1.12.1) up
       to pandoc-types-1.21 (first released with pandoc 2.10). JSON output of all pandoc releases
       since 1.12.1 can be parsed with function "pandoc_json", the "Document" constructor or
       method "parse" of module Pandoc. The AST is always upgraded to pandoc-types 1.22 and
       downgraded to another api version on serialization with "to_json".

       To determine the api version required by a version of pandoc executable since version 1.18
       execute pandoc with the "--version" option and check which version of the "pandoc-types"
       library pandoc was compiled with.

       Beginning with version 1.18 pandoc will not decode a JSON AST representation unless the
       major and minor version numbers (Document method "api_version") match those built into
       that version of pandoc. The following changes in pandoc document model have been
       implemented:

       •   pandoc-types 1.22, released for pandoc 2.11, further modified representation the Table
           element.

       •   pandoc-types 1.21, released for pandoc 2.10, introduced the Underline element and
           modified representation of the Table element.

       •   pandoc-types 1.17, released for pandoc 1.18, introduced the LineBlock element and
           modified representation of the root Document element.

       •   pandoc-types 1.16, released with pandoc 1.16, introduced attributes to Link and Image
           elements

       •   pandoc-types 1.12.3, released with pandoc 1.12.1, modified the representation of
           elements to objects with field "t" and "c". This is also the internal representation
           of documents used in this module.

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

       •   Type keywords such as "Decimal" and "LowerAlpha" to be used as types in other document
           elements.

       •   The following helper functions "pandoc_json", "pandoc_version", "attributes",
           "metadata", "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 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.

ELEMENTS AND METHODS

       Document elements are encoded as Perl data structures equivalent to the JSON structure,
       emitted with pandoc output format "json". This JSON structure is subject to minor changes
       between versions of pandoc.  All elements are blessed objects that provide common element
       methods (all elements), attribute methods (elements with attributes), and additional
       element-specific methods.

   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:

           header
               Header element (not included at the document root)

           blocks
               List of block elements before the next Header element (of given depth or less if a
               maximum depth was given)

           sections
               List of subsections, each having the same outline structure.

   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"

SEE ALSO

       Perl module Pandoc implements a wrapper around the pandoc executable.

       Similar libraries in other programming languages are listed at
       <https://github.com/jgm/pandoc/wiki/Pandoc-wrappers-and-interfaces>.

AUTHOR

       Jakob Voss <jakob.voss@gbv.de>

CONTRIBUTORS

       Benct Philip Jonsson <bpjonsson@gmail.com>

       TakeAsk <https://github.com/TakeAsh>

COPYRIGHT AND LICENSE

       Copyright 2014- Jakob Voss

       GNU General Public License, Version 2

       This module is heavily based on Pandoc by John MacFarlane.