NAME

Pandoc::Release - get pandoc releases from GitHub

SYNOPSIS

From command line:

  # print latest release name
  perl -MPandoc::Release -E 'say latest->{name}'

  # download latest release unless already in ~/.pandoc/bin
  perl -MPandoc::Release -E 'latest->download'

  # same and create symlink ~/.pandoc/bin/pandoc
  perl -MPandoc::Release -E 'latest->download->symlink'

In Perl code:

  use Pandoc::Release;

  my $release = get('2.1.3');   # get a specific release
  my $latest = latest;          # get a latest release

  # get multiple releases
  my @releases = list( since => '2.0', verbose => 1 );
  foreach my $release (@releases) {

      # print version number
      say $release->{tag_name};

      # download Debian package and executable
      $release->download( dir => './deb', bin => './bin' );
  }

  # download executable and use as temporary Pandoc object:
  my $pandoc = get('2.1.3)->download( bin => './bin' );

DESCRIPTION

This utility module fetches information about pandoc releases via GitHub API. On Debian-bases systems, this module can update and switch locally installed pandoc versions if you add directory ~/.pandoc/bin to your $PATH.

FUNCTIONS

All functions are exported by default.

get( $version, %options )

Get a specific release by its version or die if the given version does not exist. Returns data as returned by GitHub releases API: https://developer.github.com/v3/repos/releases/#get-a-release-by-tag-name.

list( %options )

Get a list of all pandoc releases, optionally since some version or within a version range such as !=1.16, <=1.17 or ==2.1.2. See "Version Ranges" in CPAN::Meta::Spec for possible values. Option verbose will print URLs before each request. Option limit limits the maximum number of releases to be returned.

latest( %options )

Get the latest release, optionally since some version or within a version range. Equivalent to method list with option limit => 1.

METHODS

download( %options )

Download the Debian release file for some architecture (e.g. amd64) Pandoc executables is then extracted to directory bin named by pandoc version number (e.g. pandoc-2.1.2). Skips downloading if an executable of this name is already found there. Returns a Pandoc instance if bin is not false or Pandoc::Version otherwise. Additional options:

dir

Where to download release files to. A temporary directory is used by default.

arch

System architecture, detected with dpkg --print-architecture by default.

bin

Where to extract pandoc binary to. By default set to ~/.pandoc/bin on Unix (see Pandoc function pandoc_data_dir). Extraction of executables can be disabled by setting bin to a false value.

symlink

Create a symlink to the executable. This is just a shortcut for calling function symlink of Pandoc:

  $release->download( verbose => $v )->symlink( $l, verbose => $v )
  $release->download( verbose => $v, symlink => $l )   # equivalent

COMMON OPTIONS

verbose

Print what's going on (disabled by default).

token

GitHub token to avoid rate limiting.

SEE ALSO

https://developer.github.com/v3/repos/releases/