{"id":15062322,"url":"https://github.com/nichtich/pandoc-wrapper","last_synced_at":"2025-11-04T03:04:35.300Z","repository":{"id":55902352,"uuid":"70460624","full_name":"nichtich/Pandoc-Wrapper","owner":"nichtich","description":"Perl wrapper for the mighty Pandoc document converter","archived":false,"fork":false,"pushed_at":"2024-04-29T18:40:56.000Z","size":183,"stargazers_count":2,"open_issues_count":12,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-24T13:04:05.561Z","etag":null,"topics":["pandoc","perl"],"latest_commit_sha":null,"homepage":"https://metacpan.org/pod/Pandoc","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nichtich.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-10T06:59:22.000Z","updated_at":"2024-04-29T18:40:57.000Z","dependencies_parsed_at":"2024-04-29T19:55:12.726Z","dependency_job_id":null,"html_url":"https://github.com/nichtich/Pandoc-Wrapper","commit_stats":{"total_commits":140,"total_committers":6,"mean_commits":"23.333333333333332","dds":0.0714285714285714,"last_synced_commit":"ed07fd86bbee4e8d3ff0ef9a2defc919319f299d"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichtich%2FPandoc-Wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichtich%2FPandoc-Wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichtich%2FPandoc-Wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nichtich%2FPandoc-Wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nichtich","download_url":"https://codeload.github.com/nichtich/Pandoc-Wrapper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248233935,"owners_count":21069493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pandoc","perl"],"created_at":"2024-09-24T23:34:24.883Z","updated_at":"2025-11-04T03:04:35.261Z","avatar_url":"https://github.com/nichtich.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nPandoc - wrapper for the mighty Pandoc document converter\n\n# STATUS\n\n[![Linux Build Status](https://travis-ci.org/nichtich/Pandoc-Wrapper.svg)](https://travis-ci.org/nichtich/Pandoc-Wrapper)\n[![Windows Build Status](https://ci.appveyor.com/api/projects/status/8p68qdqv72to633d?svg=true)](https://ci.appveyor.com/project/nichtich/pandoc-wrapper)\n[![Coverage Status](https://coveralls.io/repos/nichtich/Pandoc-Wrapper/badge.svg)](https://coveralls.io/r/nichtich/Pandoc-Wrapper)\n[![Kwalitee Score](http://cpants.cpanauthors.org/dist/Pandoc.png)](http://cpants.cpanauthors.org/dist/Pandoc)\n\n# SYNOPSIS\n\n    use Pandoc;             # check at first use\n    use Pandoc 1.12;        # check at compile time\n    Pandoc-\u003erequire(1.12);  # check at run time\n\n    # execute pandoc\n    pandoc 'input.md', -o =\u003e 'output.html';\n    pandoc -f =\u003e 'html', -t =\u003e 'markdown', { in =\u003e \\$html, out =\u003e \\$md };\n\n    # alternative syntaxes\n    pandoc-\u003erun('input.md', -o =\u003e 'output.html');\n    pandoc [ -f =\u003e 'html', -t =\u003e 'markdown' ], in =\u003e \\$html, out =\u003e \\$md;\n    pandoc [ -f =\u003e 'html', -t =\u003e 'markdown' ], { in =\u003e \\$html, out =\u003e \\$md };\n\n    # check executable\n    pandoc or die \"pandoc executable not found\";\n\n    # check minimum version\n    pandoc-\u003eversion \u003e 1.12 or die \"pandoc \u003e= 1.12 required\";\n\n    # access properties\n    say pandoc-\u003ebin.\" \".pandoc-\u003eversion;\n    say \"Default user data directory: \".pandoc-\u003edata_dir;\n    say \"Compiled with: \".join(\", \", keys %{ pandoc-\u003elibs });\n    say pandoc-\u003elibs-\u003e{'highlighting-kate'};\n\n    # create a new instance with default arguments\n    my $md2latex = Pandoc-\u003enew(qw(-f markdown -t latex --number-sections));\n    $md2latex-\u003erun({ in =\u003e \\$markdown, out =\u003e \\$latex });\n\n    # create a new instance with selected executable\n    my $pandoc = Pandoc-\u003enew('bin/pandoc');\n    my $pandoc = Pandoc-\u003enew('2.1'); # use ~/.pandoc/bin/pandoc-2.1 if available\n\n    # set default arguments on compile time\n    use Pandoc qw(-t latex);\n    use Pandoc qw(/usr/bin/pandoc --number-sections);\n    use Pandoc qw(1.16 --number-sections);\n\n    # utility method to convert from string\n    $latex = pandoc-\u003econvert( 'markdown' =\u003e 'latex', '*hello*' );\n\n    # utility methods to parse abstract syntax tree (requires Pandoc::Elements)\n    $doc = pandoc-\u003eparse( markdown =\u003e '*hello* **world!**' );\n    $doc = pandoc-\u003efile( 'example.md' );\n    $doc = pandoc-\u003efile;  # read Markdown from STDIN\n\n# DESCRIPTION\n\nThis module provides a Perl wrapper for John MacFarlane's\n[Pandoc](http://pandoc.org) document converter. \n\n# INSTALLATION\n\nThis module requires the Perl programming language (\u003e= version 5.14) as\nincluded in most Unix operating systems by default. The recommended method to\ninstall Perl modules is `cpanm` (see its [install\ninstructions](https://metacpan.org/pod/App::cpanminus#INSTALLATION) if needed):\n\n    cpanm Pandoc\n\nInstalling instruction for Pandoc itself are given [at Pandoc\nhomepage](http://pandoc.org/installing.html). On Debian-based systems this\nmodule and script [pandoc-version](https://metacpan.org/pod/pandoc-version) can be used to install and update the\npandoc executable with [Pandoc::Release](https://metacpan.org/pod/Pandoc%3A%3ARelease):\n\n    pandoc-version install\n\nThen add `~/.pandoc/bin` to your `PATH` or copy `~/.pandoc/bin/pandoc` to\na location where it can be executed.\n\n# USAGE\n\nThe utility function [pandoc](#pandoc) is exported, unless the module is\nimported with an empty list (`use Pandoc ();`). Importing this module with a\nversion number or a more complex version requirenment (e.g. `use Pandoc\n1.13;` or `use Pandoc '\u003e= 1.6, !=1.7`) will check version number of\npandoc executable instead of version number of this module (see\n`$Pandoc::VERSION` for the latter). Additional import arguments can be passed\nto set the executable location and default arguments of the global Pandoc\ninstance used by function pandoc.\n\n# FUNCTIONS\n\n## pandoc\n\nIf called without parameters, this function returns a global instance of class\nPandoc to execute [methods](#methods), or `undef` if no pandoc executable was\nfound. The location and/or name of pandoc executable can be set with\nenvironment variable `PANDOC_PATH` (set to the string `pandoc` by default).\n\n## pandoc( ... )\n\nIf called with parameters, this functions runs the pandoc executable configured\nat the global instance of class Pandoc (`pandoc-\u003ebin`). Arguments (given\nas array or array reference) are passed as pandoc command line arguments.\nAdditional options (given as hash or has reference) can control input, output,\nand error stream:\n\n    pandoc @arguments, \\%options;     # ok\n    pandoc \\@arguments, %options;     # ok\n    pandoc \\@arguments, \\%options;    # ok\n    pandoc @arguments;                # ok, if first of @arguments starts with '-'\n    pandoc %options;                  # ok, if %options is not empty\n\n    pandoc @arguments, %options;      # not ok!\n\nReturns `0` on success. On error returns the exit code of pandoc executable or\n`-1` if execution failed. If option `throw` is set, a [Pandoc::Error](https://metacpan.org/pod/Pandoc%3A%3AError) is\nthrown instead. The following options are recognized:\n\n- in / out / err\n\n    These options correspond to arguments `$stdin`, `$stdout`, and\n    `$stderr` of [IPC::Run3](https://metacpan.org/pod/IPC%3A%3ARun3), see there for details.\n\n- binmode\\_stdin / binmode\\_stdout / binmode\\_stderr\n\n    These options correspond to the like-named options to [IPC::Run3](https://metacpan.org/pod/IPC%3A%3ARun3), see\n    there for details.\n\n- binmode\n\n    If defined any binmode\\_stdin/binmode\\_stdout/binmode\\_stderr option which\n    is undefined will be set to this value.\n\n- throw\n\n    Throw a [Pandoc::Error](https://metacpan.org/pod/Pandoc%3A%3AError) instead returning the exit code on error. Disabled by\n    default.\n\n- return\\_if\\_system\\_error\n\n    Set to negation of option `throw` by default.\n\nFor convenience the `pandoc` function (_after_ checking the `binmode`\noption) checks the contents of any scalar references passed to the\nin/out/err options with\n[utf8::is\\_utf8()](https://metacpan.org/pod/utf8#flag-utf8::is_utf8-string)\nand sets the binmode\\_stdin/binmode\\_stdout/binmode\\_stderr options to\n`:encoding(UTF-8)` if the corresponding scalar is marked as UTF-8 and\nthe respective option is undefined. Since all pandoc executable\ninput/output must be UTF-8 encoded this is convenient if you run with\n[use utf8](https://metacpan.org/pod/utf8), as you then don't need to set the binmode options at\nall ([encode nor decode](https://metacpan.org/pod/Encode)) when passing input/output scalar\nreferences.\n\n## pandoc\\_data\\_dir( \\[ @subdirs \\] \\[ $file \\] )\n\nReturns the default pandoc data directory which is directory `.pandoc` in the\nhome directory for Unix or `pandoc` directory in `%APPDATA%` for Windows.\nOptional arguments can be given to refer to a specific subdirectory or file.\n\n# METHODS\n\n## new( \\[ $executable | $version \\] \\[, @arguments \\] )\n\nCreate a new instance of class Pandoc or throw an exception if no pandoc\nexecutable was found.  The first argument, if given and not starting with `-`,\ncan be used to set the pandoc executable (`pandoc` by default).  If a version\nis specified the executable is also searched in `~/.pandoc/bin`, e.g.\n`~/.pandoc/bin/pandoc-2.0` for version `2.0`.  Additional arguments are\npassed to the executable on each run.\n\nRepeated use of this constructor with same arguments is not recommended because\n`pandoc --version` is called for every new instance.\n\n## run( ... )\n\nExecute the pandoc executable with default arguments and optional additional\narguments and options. See [function pandoc](#pandoc) for usage.\n\n## convert( $from =\u003e $to, $input \\[, @arguments \\] )\n\nConvert a string in format `$from` to format `$to`. Additional pandoc options\nsuch as `-N` and `--standalone` can be passed. The result is returned\nin same utf8 mode (`utf8::is_unicode`) as the input. To convert from file to\nstring use method `pandoc`/`run` like this and set input/output format via\nstandard pandoc arguments `-f` and `-t`:\n\n    pandoc-\u003erun( $filename, @arguments, { out =\u003e \\$string } );\n\n## parse( $from =\u003e $input \\[, @arguments \\] )\n\nParse a string in format `$from` to a [Pandoc::Document](https://metacpan.org/pod/Pandoc%3A%3ADocument) object. Additional\npandoc options such as `-N` and `--normalize` can be passed. This method\nrequires at least pandoc version 1.12.1 and the Perl module [Pandoc::Elements](https://metacpan.org/pod/Pandoc%3A%3AElements).\n\nThe reverse action is possible with method `to_pandoc` of [Pandoc::Document](https://metacpan.org/pod/Pandoc%3A%3ADocument).\nAdditional shortcut methods such as `to_html` are available:\n\n    $html = pandoc-\u003eparse( 'markdown' =\u003e '# A *section*' )-\u003eto_html;\n\nMethod `convert` should be preferred for simple conversions unless you want to\nmodify or inspect the parsed document in between.\n\n## file( \\[ $filename \\[, @arguments \\] \\] )\n\nParse from a file (or STDIN) to a [Pandoc::Document](https://metacpan.org/pod/Pandoc%3A%3ADocument) object. Additional pandoc\noptions can be passed, for instance use HTML input format (`@arguments = qw(-f\nhtml)`) instead of default markdown. This method requires at least pandoc\nversion 1.12.1 and the Perl module [Pandoc::Elements](https://metacpan.org/pod/Pandoc%3A%3AElements).\n\n## require( $version\\_requirement )\n\nReturn the Pandoc instance if its version number fulfills a given version\nrequirement. Throw an error otherwise.  Can also be called as constructor:\n`Pandoc-\u003erequire(...)` is equivalent to `pandoc-\u003erequire` but\nthrows a more meaningful error message if no pandoc executable was found.\n\n## version( \\[ $version\\_requirement \\] )\n\nReturn the pandoc version as [Pandoc::Version](https://metacpan.org/pod/Pandoc%3A%3AVersion) object.  If a version\nrequirement is given, the method returns undef if the pandoc version does not\nfulfill this requirement.  To check whether pandoc is available with a given\nminimal version use one of:\n\n    Pandoc-\u003erequire( $minimum_version)                # true or die\n    pandoc and pandoc-\u003eversion( $minimum_version )    # true or false\n\n## bin( \\[ $executable \\] )\n\nReturn or set the pandoc executable. Setting an new executable also updates\nversion and data\\_dir by calling `pandoc --version`.\n\n## symlink( \\[ $name \\] \\[ verbose =\u003e 0|1 \\] )\n\nCreate a symlink with given name to the executable and change executable to the\nsymlink location afterwards. An existing symlink is replaced. If `$name` is an\nexisting directory, the symlink will be named `pandoc` in there. This makes\nmost sense if the directory is listed in environment variable `$PATH`. If the\nname is omitted or an empty string, symlink is created in subdirectory `bin`\nof pandoc data directory.\n\n## arguments( \\[ @arguments | \\\\@arguments )\n\nReturn or set a list of default arguments.\n\n## data\\_dir( \\[ @subdirs \\] \\[ $file \\] )\n\nReturn the stated default data directory, introduced with Pandoc 1.11.  Use\nfunction `pandoc_data_dir` alternatively to get the expected directory without\ncalling Pandoc executable.\n\n## input\\_formats\n\nReturn a list of supported input formats.\n\n## output\\_formats\n\nReturn a list of supported output formats.\n\n## highlight\\_languages\n\nReturn a list of programming languages which syntax highlighting is supported\nfor (via Haskell library highlighting-kate).\n\n## extensions( \\[ $format \\] )\n\nReturn a hash of extensions mapped to whether they are enabled by default.\nThis method is only available since Pandoc 1.18 and the optional format\nargument since Pandoc 2.0.6.\n\n## libs\n\nReturn a hash mapping the names of Haskell libraries compiled into the\npandoc executable to [Pandoc::Version](https://metacpan.org/pod/Pandoc%3A%3AVersion) objects.\n\n# SEE ALSO\n\nThis package includes [Pandoc::Version](https://metacpan.org/pod/Pandoc%3A%3AVersion) to compare Pandoc version numbers,\n[Pandoc::Release](https://metacpan.org/pod/Pandoc%3A%3ARelease) to get Pandoc releases from GitHub, and\n[App::Prove::Plugin::andoc](https://metacpan.org/pod/App%3A%3AProve%3A%3APlugin%3A%3Aandoc) to run tests with selected Pandoc executables.\n\nSee [Pandoc::Elements](https://metacpan.org/pod/Pandoc%3A%3AElements) for a Perl interface to the abstract syntax tree of\nPandoc documents for more elaborate document processing.\n\nSee [Pod::Pandoc](https://metacpan.org/pod/Pod%3A%3APandoc) to parse Plain Old Documentation format ([perlpod](https://metacpan.org/pod/perlpod)) for\nprocessing with Pandoc.\n\nSee [Pandoc wrappers and interfaces](https://github.com/jgm/pandoc/wiki/Pandoc-wrappers-and-interfaces)\nin the Pandoc GitHub Wiki for a list of wrappers in other programming\nlanguages.\n\nOther Pandoc related but outdated modules at CPAN include\n[Orze::Sources::Pandoc](https://metacpan.org/pod/Orze%3A%3ASources%3A%3APandoc) and [App::PDoc](https://metacpan.org/pod/App%3A%3APDoc).\n\n# AUTHOR\n\nJakob Voß\n\n# CONTRIBUTORS\n\nBenct Philip Jonsson\n\n# LICENSE\n\nEuropean Union Public Licence v. 1.2 (EUPL-1.2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnichtich%2Fpandoc-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnichtich%2Fpandoc-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnichtich%2Fpandoc-wrapper/lists"}