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. See Installing pandoc
    <http://pandoc.org/installing.html> or Pandoc::Release for installation
    of pandoc executables.

    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".

  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
    GNU General Public License, Version 2

