Pandoc::Elements - create and process Pandoc documents
The output of this script hello.pl
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 # Gruß {.de} Hello, world!
Pandoc::Elements provides utility functions to parse, serialize, and modify abstract syntax trees (AST) of Pandoc 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.
The Pandoc document model is defined in file Text.Pandoc.Definition as part of Haskell package pandoc-types.
Pandoc::Elements is compatible with pandoc-types 1.12.3 (released with pandoc 1.12.1) up to at least pandoc-types-1.17.0.4 (first releases with pandoc 1.18). 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.17 and downgraded to another api version on serialization with to_json.
pandoc_json
parse
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.
--version
pandoc-types
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:
api_version
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.
t
c
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).
Para
Emph
Type keywords such as Decimal and LowerAlpha to be used as types in other document elements.
Decimal
LowerAlpha
The following helper functions pandoc_json, pandoc_version, attributes, metadata, citation, and element.
pandoc_version
attributes
metadata
citation
element
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.
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.
id
class
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):
citationId
citationPrefix
citationSuffix
citationMode
NormalCitation
AuthorInText
SuppressAuthor
citationNoteNum
citationHash
prefix
suffix
mode
note
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.
$citation->citationId(...)
$citation->id(...)
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.
$PANDOC_VERSION
See also method version of module Pandoc to get the current version of pandoc executable on your system.
version
Create a Pandoc document element of arbitrary name. This function is only exported on request.
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.
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.
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.
Return the name of the element, e.g. "Para" for a paragraph element.
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.
attr
classes
keyvals
content
target
url
title
True if the element is a Block element
True if the element is an inline Inline element
True if the element is a Metadata element
True if the element is a Document element
Return the element unmodified if it is a block element or wrapped in a Plain or Div otherwise.
Check whether the element matches a given Pandoc::Selector (given as instance or string).
Walk the element tree with Pandoc::Walker
Query the element to extract results with Pandoc::Walker
Transform the element tree with Pandoc::Walker
Returns a concatenated string of element content, leaving out all formatting.
Some elements have attributes which can be an identifier, ordered class names and ordered key-value pairs. Elements with attributes provide the following methods:
Get or set the attributes in Pandoc internal structure:
[ $id, [ @classes ], [ [ key => $value ], ... ] ]
See helper function attributes to create this structure.
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
Get or set the identifier. See also Pandoc::Filter::HeaderIdentifiers for utility functions to handle Header identifiers.
Get or set the list of classes, separated by whitespace.
Append an attribute. The special attribute names id and class set or append identifier or class, respectively.
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:
meta
blocks
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 1.17 which was also introduced with pandoc release 1.18.
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:
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.
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.
Get or set the array of block elements of the document.
Get and/or set combined document metadata. Use method value to get selected metadata fields and values.
value
Get selected document metadata field value(s). See Pandoc::Metadata for documentation. Can also be called as metavalue, so the following are equivalent:
metavalue
$doc->value( ... ); $doc->meta->value( ... ); $doc->metavalue( ... );
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.
Process the document into markdown (pandoc's extended Markdown), latex (LaTeX), html (HTML), rst (reStructuredText), or plain (plain text). The following are equivalent:
markdown
latex
html
rst
plain
$doc->to_markdown( @args ); $doc->to_pandoc( @args, '-t' => 'markdown' );
Returns an outline of the document structure based on Header elements. The outline is a hierarchical hash reference with the following fields:
Header element (not included at the document root)
List of block elements before the next Header element (of given depth or less if a maximum depth was given)
List of subsections, each having the same outline structure.
Block quote, consisting of a list of blocks (content)
BlockQuote [ @blocks ]
Unnumbered list of items (content=items), each a list of blocks
items
BulletList [ [ @blocks ] ]
Code block (literal string content) with attributes (attr, id, class, classes, keyvals)
CodeBlock $attributes, $content
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).
term
definitions
DefinitionList [ @definitions ] # each item in @definitions being a pair of the form [ [ @inlines ], [ @blocks ] ]
Generic container of blocks (content) with attributes (attr, id, class, classes, keyvals).
Div $attributes, [ @blocks ]
Header with level (integer), attributes (attr, id, class, classes, keyvals), and text (content, a list of inlines).
level
Header $level, $attributes, [ @inlines ]
Horizontal rule
HorizontalRule
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.
Nothing
Null
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.
DefaultStyle
Example
LowerRoman
UpperRoman
UpperAlpha
Supported delimiters are DefaultDelim, Period, OneParen, and TwoParens.
DefaultDelim
Period
OneParen
TwoParens
Paragraph, consisting of a list of Inline elements (content).
Para [ $elements ]
Plain text, not a paragraph, consisting of a list of Inline elements (content).
Plain [ @inlines ]
Raw block with format and content string.
format
RawBlock $format, $content
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).
caption
alignments
widths
headers
rows
Table [ @inlines ], [ @alignments ], [ @width ], [ @headers ], [ @rows ]
Possible alignments are AlignLeft, AlignRight, AlignCenter, and AlignDefault.
AlignLeft
AlignRight
AlignCenter
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"]]]];
Citation, a list of citations and a list of inlines (content). See helper function citation to construct citations.
citations
Cite [ @citations ], [ @inlines ]
Inline code, a literal string (content) with attributes (attr, id, class, classes, keyvals)
Code attributes { %attr }, $content
Emphasized text, a list of inlines (content).
Emph [ @inlines ]
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.
Hard line break
LineBreak
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 ]
TeX math, given as literal string (content) with type (one of DisplayMath and InlineMath).
type
DisplayMath
InlineMath
Math $type, $content
Footnote or Endnote, a list of blocks (content).
Note [ @blocks ]
Quoted text with quote type (one of SingleQuote and DoubleQuote) and a list of inlines (content).
SingleQuote
DoubleQuote
Quoted $type, [ @inlines ]
Raw inline with format (a string) and content (a string).
RawInline $format, $content
Small caps text, a list of inlines (content).
SmallCaps [ @inlines ]
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.
Inter-word space
Space
Generic container of inlines (content) with attributes (attr, id, class, classes, keyvals).
Span attributes { %attr }, [ @inlines ]
Plain text, a string (content).
Str $content
Strikeout text, a list of inlines (content).
Strikeout [ @inlines ]
Strongly emphasized text, a list of inlines (content).
Strong [ @inlines ]
Subscripted text, a list of inlines (content).
Supscript [ @inlines ]
Superscripted text, a list of inlines (content).
Superscript [ @inlines ]
See Pandoc::Metadata for documentation of metadata elements MetaBool, MetaString, MetaMap, MetaInlines, MetaList, and MetaBlocks.
MetaBool
MetaString
MetaMap
MetaInlines
MetaList
MetaBlocks
Helper function metadata can be used to convert scalars, hash references, array references, and Pandoc Inline/Block elements into metadata elements.
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
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.
Jakob Voß <jakob.voss@gbv.de>
Benct Philip Jonsson <bpjonsson@gmail.com>
TakeAsk
Copyright 2014- Jakob Voß
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.