Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nichtich/pandoc-wrapper

Perl wrapper for the mighty Pandoc document converter
https://github.com/nichtich/pandoc-wrapper

pandoc perl

Last synced: 2 months ago
JSON representation

Perl wrapper for the mighty Pandoc document converter

Awesome Lists containing this project

README 

        
# 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)