Pandoc::Release(3pm)

💖 Pandoc::Release — bestie edition 💖

perl v5.38.2 docs, User Contributed Perl Documentation, Pandoc::Release(3pm) — yeah it's a Perl module manual page, but honestly? It's giving glow-up. Let's go. ✨

---

🌸 NAME 🌸

Pandoc::Release — she fetches pandoc releases straight from GitHub. That's the whole job. And she eats. 💅

---

🦋 SYNOPSIS 🦋

From the command line, no cap:

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

# download specific release and create symlink ~/.pandoc/bin/pandoc
perl -MPandoc::Release -E 'get("2.7.3")->download->symlink'

Or if you're living in Perl code, like a main character:

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' );

That last line? Yeah, the quote is unbalanced in the original. We keep it EXACTLY as-is, because facts don't change, only the vibe does. 🫶

---

💫 DESCRIPTION 💫

Okay so. This utility module fetches information about pandoc releases via the GitHub API. Simple. Iconic. No notes.

On Debian-based systems, this module can update and switch locally installed pandoc versions if you add the directory ~/.pandoc/bin to your $PATH. That's it, that's the trick, that's the slay. 🌈

Also: peep pandoc-version — it's a command line script that makes use of this module. iykyk. 💜

---

✨ FUNCTIONS ✨

All functions are exported by default. Everything, handed to you, free of charge. Queen behavior.

🎀 get( $version, %options )

Get a specific release by its version. And if that version doesn't exist? She dies. 💀 Dramatic but honest.

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. For all the possible values, see "Version Ranges" in CPAN::Meta::Spec.

• Option verbose will print URLs before each request. Receipts!
• Option limit limits the maximum number of releases to be returned. Boundaries, bestie. 🛑

🎀 latest( %options )

Get the latest release, optionally since some version or within a version range.

Equivalent to method list with option limit => 1. Same energy, smaller bag. 👜

---

👑 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. Efficiency! She's not doing work twice.

Returns a Pandoc instance if bin is not false, or Pandoc::Version otherwise.

Additional options, babes:

• 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

Two ways, same destination. Choose your fighter. 💅

---

🌈 COMMON OPTIONS 🌈

• verbose — Print what's going on (disabled by default). Turn her on and she'll narrate her whole life to you.
• token — GitHub token <https://github.com/settings/tokens> to avoid rate limiting. Bestie. Get the token. The rate limiter is NOT playing. 🔥

---

🔥 SEE ALSO 🔥

• Pandoc::Version
• <https://developer.github.com/v3/repos/releases/>

---

And that's the whole page, periodt. 🎀 This lil' doc shipped as Pandoc::Release(3pm), built from perl v5.38.2, dated 2024-08-03, and honestly? She ate. Bye bestie! 💖✨🦋