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 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
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ß
CONTRIBUTORS
Benct Philip Jonsson
COPYRIGHT AND LICENSE
Copyright 2014- Jakob Voß
GNU General Public License, Version 2
This module is heavily based on Pandoc by John MacFarlane.