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
# Gruß {.de}
Hello, world!
DESCRIPTION
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.
PANDOC VERSIONS
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.
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.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, 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 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]
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
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 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:
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
Return document metadata elements.
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} }
to_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' );
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 ]
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 }
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 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.