# NAME
Pandoc - wrapper for the mighty Pandoc document converter
# STATUS
[](https://travis-ci.org/nichtich/Pandoc-Wrapper)
[](https://ci.appveyor.com/project/nichtich/pandoc-wrapper)
[](https://coveralls.io/r/nichtich/Pandoc-Wrapper)
[](http://cpants.cpanauthors.org/dist/Pandoc)
# SYNOPSIS
use Pandoc; # check at first use
use Pandoc 1.12; # check at compile time
Pandoc->require(1.12); # check at run time
# execute pandoc
pandoc 'input.md', -o => 'output.html';
pandoc -f => 'html', -t => 'markdown', { in => \$html, out => \$md };
# alternative syntaxes
pandoc->run('input.md', -o => 'output.html');
pandoc [ -f => 'html', -t => 'markdown' ], in => \$html, out => \$md;
pandoc [ -f => 'html', -t => 'markdown' ], { in => \$html, out => \$md };
# check executable
pandoc or die "pandoc executable not found";
# check minimum version
pandoc->version > 1.12 or die "pandoc >= 1.12 required";
# access properties
say pandoc->bin." ".pandoc->version;
say "Default user data directory: ".pandoc->data_dir;
say "Compiled with: ".join(", ", keys %{ pandoc->libs });
say pandoc->libs->{'highlighting-kate'};
# create a new instance with default arguments
my $md2latex = Pandoc->new(qw(-f markdown -t latex --number-sections));
$md2latex->run({ in => \$markdown, out => \$latex });
# create a new instance with selected executable
my $pandoc = Pandoc->new('bin/pandoc');
my $pandoc = Pandoc->new('2.1'); # use ~/.pandoc/bin/pandoc-2.1 if available
# set default arguments on compile time
use Pandoc qw(-t latex);
use Pandoc qw(/usr/bin/pandoc --number-sections);
use Pandoc qw(1.16 --number-sections);
# utility method to convert from string
$latex = pandoc->convert( 'markdown' => 'latex', '*hello*' );
# utility methods to parse abstract syntax tree (requires Pandoc::Elements)
$doc = pandoc->parse( markdown => '*hello* **world!**' );
$doc = pandoc->file( 'example.md' );
$doc = pandoc->file; # read Markdown from STDIN
# DESCRIPTION
This module provides a Perl wrapper for John MacFarlane's
[Pandoc](http://pandoc.org) document converter.
# INSTALLATION
This module requires the Perl programming language (>= version 5.14) as
included in most Unix operating systems by default. The recommended method to
install Perl modules is `cpanm` (see its [install
instructions](https://metacpan.org/pod/App::cpanminus#INSTALLATION) if needed):
cpanm Pandoc
Installing instruction for Pandoc itself are given [at Pandoc
homepage](http://pandoc.org/installing.html). On Debian-based systems this
module and script [pandoc-version](https://metacpan.org/pod/pandoc-version) can be used to install and update the
pandoc executable with [Pandoc::Release](https://metacpan.org/pod/Pandoc%3A%3ARelease):
pandoc-version install
Then add `~/.pandoc/bin` to your `PATH` or copy `~/.pandoc/bin/pandoc` to
a location where it can be executed.
# USAGE
The utility function [pandoc](#pandoc) is exported, unless the module is
imported with an empty list (`use Pandoc ();`). Importing this module with a
version number or a more complex version requirenment (e.g. `use Pandoc
1.13;` or `use Pandoc '>= 1.6, !=1.7`) will check version number of
pandoc executable instead of version number of this module (see
`$Pandoc::VERSION` for the latter). Additional import arguments can be passed
to set the executable location and default arguments of the global Pandoc
instance used by function pandoc.
# FUNCTIONS
## pandoc
If called without parameters, this function returns a global instance of class
Pandoc to execute [methods](#methods), or `undef` if no pandoc executable was
found. The location and/or name of pandoc executable can be set with
environment variable `PANDOC_PATH` (set to the string `pandoc` by default).
## pandoc( ... )
If called with parameters, this functions runs the pandoc executable configured
at the global instance of class Pandoc (`pandoc->bin`). Arguments (given
as array or array reference) are passed as pandoc command line arguments.
Additional options (given as hash or has reference) can control input, output,
and error stream:
pandoc @arguments, \%options; # ok
pandoc \@arguments, %options; # ok
pandoc \@arguments, \%options; # ok
pandoc @arguments; # ok, if first of @arguments starts with '-'
pandoc %options; # ok, if %options is not empty
pandoc @arguments, %options; # not ok!
Returns `0` on success. On error returns the exit code of pandoc executable or
`-1` if execution failed. If option `throw` is set, a [Pandoc::Error](https://metacpan.org/pod/Pandoc%3A%3AError) is
thrown instead. The following options are recognized:
- in / out / err
These options correspond to arguments `$stdin`, `$stdout`, and
`$stderr` of [IPC::Run3](https://metacpan.org/pod/IPC%3A%3ARun3), see there for details.
- binmode\_stdin / binmode\_stdout / binmode\_stderr
These options correspond to the like-named options to [IPC::Run3](https://metacpan.org/pod/IPC%3A%3ARun3), see
there for details.
- binmode
If defined any binmode\_stdin/binmode\_stdout/binmode\_stderr option which
is undefined will be set to this value.
- throw
Throw a [Pandoc::Error](https://metacpan.org/pod/Pandoc%3A%3AError) instead returning the exit code on error. Disabled by
default.
- return\_if\_system\_error
Set to negation of option `throw` by default.
For convenience the `pandoc` function (_after_ checking the `binmode`
option) checks the contents of any scalar references passed to the
in/out/err options with
[utf8::is\_utf8()](https://metacpan.org/pod/utf8#flag-utf8::is_utf8-string)
and sets the binmode\_stdin/binmode\_stdout/binmode\_stderr options to
`:encoding(UTF-8)` if the corresponding scalar is marked as UTF-8 and
the respective option is undefined. Since all pandoc executable
input/output must be UTF-8 encoded this is convenient if you run with
[use utf8](https://metacpan.org/pod/utf8), as you then don't need to set the binmode options at
all ([encode nor decode](https://metacpan.org/pod/Encode)) when passing input/output scalar
references.
## pandoc\_data\_dir( \[ @subdirs \] \[ $file \] )
Returns the default pandoc data directory which is directory `.pandoc` in the
home directory for Unix or `pandoc` directory in `%APPDATA%` for Windows.
Optional arguments can be given to refer to a specific subdirectory or file.
# METHODS
## new( \[ $executable | $version \] \[, @arguments \] )
Create a new instance of class Pandoc or throw an exception if no pandoc
executable was found. The first argument, if given and not starting with `-`,
can be used to set the pandoc executable (`pandoc` by default). If a version
is specified the executable is also searched in `~/.pandoc/bin`, e.g.
`~/.pandoc/bin/pandoc-2.0` for version `2.0`. Additional arguments are
passed to the executable on each run.
Repeated use of this constructor with same arguments is not recommended because
`pandoc --version` is called for every new instance.
## run( ... )
Execute the pandoc executable with default arguments and optional additional
arguments and options. See [function pandoc](#pandoc) for usage.
## convert( $from => $to, $input \[, @arguments \] )
Convert a string in format `$from` to format `$to`. Additional pandoc options
such as `-N` and `--standalone` can be passed. The result is returned
in same utf8 mode (`utf8::is_unicode`) as the input. To convert from file to
string use method `pandoc`/`run` like this and set input/output format via
standard pandoc arguments `-f` and `-t`:
pandoc->run( $filename, @arguments, { out => \$string } );
## parse( $from => $input \[, @arguments \] )
Parse a string in format `$from` to a [Pandoc::Document](https://metacpan.org/pod/Pandoc%3A%3ADocument) object. Additional
pandoc options such as `-N` and `--normalize` can be passed. This method
requires at least pandoc version 1.12.1 and the Perl module [Pandoc::Elements](https://metacpan.org/pod/Pandoc%3A%3AElements).
The reverse action is possible with method `to_pandoc` of [Pandoc::Document](https://metacpan.org/pod/Pandoc%3A%3ADocument).
Additional shortcut methods such as `to_html` are available:
$html = pandoc->parse( 'markdown' => '# A *section*' )->to_html;
Method `convert` should be preferred for simple conversions unless you want to
modify or inspect the parsed document in between.
## file( \[ $filename \[, @arguments \] \] )
Parse from a file (or STDIN) to a [Pandoc::Document](https://metacpan.org/pod/Pandoc%3A%3ADocument) object. Additional pandoc
options can be passed, for instance use HTML input format (`@arguments = qw(-f
html)`) instead of default markdown. This method requires at least pandoc
version 1.12.1 and the Perl module [Pandoc::Elements](https://metacpan.org/pod/Pandoc%3A%3AElements).
## require( $version\_requirement )
Return the Pandoc instance if its version number fulfills a given version
requirement. Throw an error otherwise. Can also be called as constructor:
`Pandoc->require(...)` is equivalent to `pandoc->require` but
throws a more meaningful error message if no pandoc executable was found.
## version( \[ $version\_requirement \] )
Return the pandoc version as [Pandoc::Version](https://metacpan.org/pod/Pandoc%3A%3AVersion) object. If a version
requirement is given, the method returns undef if the pandoc version does not
fulfill this requirement. To check whether pandoc is available with a given
minimal version use one of:
Pandoc->require( $minimum_version) # true or die
pandoc and pandoc->version( $minimum_version ) # true or false
## bin( \[ $executable \] )
Return or set the pandoc executable. Setting an new executable also updates
version and data\_dir by calling `pandoc --version`.
## symlink( \[ $name \] \[ verbose => 0|1 \] )
Create a symlink with given name to the executable and change executable to the
symlink location afterwards. An existing symlink is replaced. If `$name` is an
existing directory, the symlink will be named `pandoc` in there. This makes
most sense if the directory is listed in environment variable `$PATH`. If the
name is omitted or an empty string, symlink is created in subdirectory `bin`
of pandoc data directory.
## arguments( \[ @arguments | \\@arguments )
Return or set a list of default arguments.
## data\_dir( \[ @subdirs \] \[ $file \] )
Return the stated default data directory, introduced with Pandoc 1.11. Use
function `pandoc_data_dir` alternatively to get the expected directory without
calling Pandoc executable.
## input\_formats
Return a list of supported input formats.
## output\_formats
Return a list of supported output formats.
## highlight\_languages
Return a list of programming languages which syntax highlighting is supported
for (via Haskell library highlighting-kate).
## extensions( \[ $format \] )
Return a hash of extensions mapped to whether they are enabled by default.
This method is only available since Pandoc 1.18 and the optional format
argument since Pandoc 2.0.6.
## libs
Return a hash mapping the names of Haskell libraries compiled into the
pandoc executable to [Pandoc::Version](https://metacpan.org/pod/Pandoc%3A%3AVersion) objects.
# SEE ALSO
This package includes [Pandoc::Version](https://metacpan.org/pod/Pandoc%3A%3AVersion) to compare Pandoc version numbers,
[Pandoc::Release](https://metacpan.org/pod/Pandoc%3A%3ARelease) to get Pandoc releases from GitHub, and
[App::Prove::Plugin::andoc](https://metacpan.org/pod/App%3A%3AProve%3A%3APlugin%3A%3Aandoc) to run tests with selected Pandoc executables.
See [Pandoc::Elements](https://metacpan.org/pod/Pandoc%3A%3AElements) for a Perl interface to the abstract syntax tree of
Pandoc documents for more elaborate document processing.
See [Pod::Pandoc](https://metacpan.org/pod/Pod%3A%3APandoc) to parse Plain Old Documentation format ([perlpod](https://metacpan.org/pod/perlpod)) for
processing with Pandoc.
See [Pandoc wrappers and interfaces](https://github.com/jgm/pandoc/wiki/Pandoc-wrappers-and-interfaces)
in the Pandoc GitHub Wiki for a list of wrappers in other programming
languages.
Other Pandoc related but outdated modules at CPAN include
[Orze::Sources::Pandoc](https://metacpan.org/pod/Orze%3A%3ASources%3A%3APandoc) and [App::PDoc](https://metacpan.org/pod/App%3A%3APDoc).
# AUTHOR
Jakob Voß
# CONTRIBUTORS
Benct Philip Jonsson
# LICENSE
European Union Public Licence v. 1.2 (EUPL-1.2)