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!' ], ])->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!
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.
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).
Para
Emph
Type keywords such as Decimal and LowerAlpha to be used as types in other document elements.
Decimal
LowerAlpha
The helper following functions pandoc_json, attributes, citation, and element.
pandoc_json
attributes
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.
to_json
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
class
[ $id, [ @classes ], [ [ key => $value ], ... ] ]
See also attribute methods to get and set element attributes.
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):
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]
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. All elements are blessed objects that provide the following element methods and additional accessor methods specific to each element.
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.
PANDOC_VERSION
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
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.
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.
add_attribute
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
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" in 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 in JSON can be disabled with PANDOC_VERSION.
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
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.
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 ]
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.
-M
is_meta
metavalue
meta
A plain text string metadata value (content).
MetaString $content
MetaString values can also be set via pandoc command line client:
pandoc -M key=$content
A Boolean metadata value (content). The special values "false" and "FALSE" are recognized as false in addition to normal false values (0, undef, ""...).
"false"
"FALSE"
0
undef
""
MetaBool $content
MetaBool values can also be set via pandoc command line client:
pandoc -M key=true pandoc -M key=false
Container for a list of inlines (content) in metadata.
MetaInlines [ @inlines ]
Container for a list of blocks (content) in metadata.
MetaInlines [ @blocks ]
A list of other metadata elements (content).
MetaList [ @values ]
A map of keys to other metadata elements.
MetaMap { %map }
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} }
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
Pandoc implements a wrapper around the pandoc executable.
Text.Pandoc.Definition contains the original definition of Pandoc document data structure in Haskell. This module version was last aligned with pandoc-types-1.16.1.
Jakob Voß <jakob.voss@gbv.de>
Benct Philip Jonsson <bpjonsson@gmail.com>
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.