# NAME

Pandoc - wrapper for the mighty Pandoc document converter

# STATUS

[![Linux Build Status](https://travis-ci.org/nichtich/Pandoc-Wrapper.svg)](https://travis-ci.org/nichtich/Pandoc-Wrapper)
[![Windows Build Status](https://ci.appveyor.com/api/projects/status/8p68qdqv72to633d?svg=true)](https://ci.appveyor.com/project/nichtich/pandoc-wrapper)
[![Coverage Status](https://coveralls.io/repos/nichtich/Pandoc-Wrapper/badge.svg)](https://coveralls.io/r/nichtich/Pandoc-Wrapper)
[![Kwalitee Score](http://cpants.cpanauthors.org/dist/Pandoc.png)](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)