--- name: "Pandoc" section: "3pm" platform: "linux" package: "libpandoc-wrapper-perl" version: "0.9.2-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Pandoc" --- # Pandoc(3pm) wrapper for the mighty Pandoc document converter ## 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 \ 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 \ if needed): ``` cpanm Pandoc ``` Installing instruction for Pandoc itself are given at Pandoc homepage \. 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 \ 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)