Provided by: libpandoc-wrapper-perl_0.9.2-1_all 
NAME
Pandoc - wrapper for the mighty Pandoc document converter
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 can be
used to install and update the pandoc executable with Pandoc::Release:
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 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,
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 is thrown instead. The following options are recognized:
in / out / err
These options correspond to arguments $stdin, $stdout, and $stderr of IPC::Run3, see there for
details.
binmode_stdin / binmode_stdout / binmode_stderr
These options correspond to the like-named options to IPC::Run3, 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 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() 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, as you then don't need to set the binmode
options at all (encode nor decode) 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 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 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.
The reverse action is possible with method "to_pandoc" of Pandoc::Document. 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 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.
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 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 objects.
SEE ALSO
This package includes Pandoc::Version to compare Pandoc version numbers, Pandoc::Release to get Pandoc
releases from GitHub, and App::Prove::Plugin::andoc to run tests with selected Pandoc executables.
See Pandoc::Elements for a Perl interface to the abstract syntax tree of Pandoc documents for more
elaborate document processing.
See Pod::Pandoc to parse Plain Old Documentation format (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 and App::PDoc.
AUTHOR
Jakob Voß
CONTRIBUTORS
Benct Philip Jonsson
LICENSE
European Union Public Licence v. 1.2 (EUPL-1.2)