NAME

    Pandoc - interface to the 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 };
    
      # utility method to convert from string
      $latex = pandoc->convert( 'markdown' => 'latex', '*hello*' );
    
      # 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;
    
      # create an instance with default arguments
      my $md2latex = Pandoc->new(qw(-f markdown -t latex --smart));
      $md2latex->run({ in => \$markdown, out => \$latex });
    
      # set default arguments on compile time
      use Pandoc qw(-t latex);
      use Pandoc qw(/ur/bin/pandoc --smart);
      use Pandoc qw(1.16 --smart);

DESCRIPTION

    This module provides a Perl interface to John MacFarlane's Pandoc
    <http://pandoc.org> document converter. The module exports utility
    function pandoc but it can also be used as class.

FUNCTIONS

pandoc

    If called without parameters, this function returns a singleton
    instance of class Pandoc to execute methods, or undef if no pandoc
    executable was found.

 pandoc ...

    If called with parameters, this functions runs the pandoc executable.
    Arguments are passed as command line arguments and options control
    input, output, and error stream as described below. Returns 0 on
    success. Otherwise returns the the exit code of pandoc executable or -1
    if execution failed. Arguments and options can be passed as plain
    array/hash or as (possibly empty) reference in the following ways:

      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!

  Options

    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.

    return_if_system_error

      Set to true by default to return the exit code of pandoc executable.

    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.

METHODS

 new( [ $executable ] [, @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). 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.

 require( $minimum_version )

    Return the Pandoc instance if its version number is at least as high as
    the given minimum version. Throw an error otherwise. This method 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.

 convert( $from => $to, $input [, @arguments ] )

    Convert a string in format $from to format $to. Additional pandoc
    options such as --smart and --standalone can be passed. The result is
    returned in same utf8 mode (utf8::is_unicode) as the input.

 version( [ $minimum_version ] )

    Return the pandoc version as version object. Returns undef if the
    version is lower than a given minimum version.

 bin( [ $executable ] )

    Return or set the pandoc executable.

 arguments( [ @arguments | \@arguments )

    Return or set a list of default arguments.

 data_dir

    Return the default data directory (only available since Pandoc 1.11).

 input_formats

    Return a list of supported input formats.

 output_formats

    Return a list of supported output formats.

SEE ALSO

    Use Pandoc::Elements for more elaborate document processing based on
    Pandoc. 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