NAME

Pastebin::Gist - Raku interface to https://gist.github.com/

SYNOPSIS

use Pastebin::Gist;
my $p = Pastebin::Gist.new(
    token => '3f2b4ca292960fafc63fb6798f148e3b47ea9fff',
);

my $paste_url = $p.paste("<foo>bar</foo>");

my $paste_url = $p.paste(
    {
        'file1.p6' => { content => "Paste content 1" },
        'meow.css' => { content => "Paste content 2" },
    },
    :desc("Foo Bar"),
    :!public,
);

$p.delete: $paste_url; # delete a gist

DESCRIPTION

This module allows the user to create and paste to GitHub Gists as well as retrieve them.

METHODS

new

# Assuming PASTEBIN_GIST_TOKEN env var has the token:
my $p = Pastebin::Gist.new;

# Set token via an argument:
my $p = Pastebin::Gist.new(
    token => 'ghp_4ca292960fafc63fb6798f148e3b47ea9fff',
)

Creates new C<Pastebin::Gist> object. Accepts the following settings:

token

token => 'ghp_4ca292960fafc63fb6798f148e3b47ea9fff'

To use this module you need to create a GitHub token. Only the gist permission is needed.

You can avoid providing the token argument by setting the PASTEBIN_GIST_TOKEN environmental variable to the value of your token.

Local User Testing

In order to test the module with your token, use the installed executable 'test-pastebin-gist' to insure all works before using this module in other programs.

paste

my $paste_url = $p.paste('Paste content');
my $paste_url = $p.paste('Paste content', filename => 'foo.raku');
my $paste_url = $p.paste(
    {
        'file1.raku' => { content => "Paste content 1" },
        'meow.css'   => { content => "Paste content 2" },
    },
    :desc('Optional summary'),
    :public,
);

Returns URL to the created paste (e.g. https://gist.github.com/5590bc07b8d5bd8fd98d). On failure, throws `Pastebin::Gist::X` exception whose `$.message` method has reason for error. First positional argument can either be a string of content to paste or a hashref where keys are filenames and values are hashrefs with values key content set to content of files to paste. Using a hashref allows you to make a gist with multiple files. All other arguments are optional and are as follows:

desc

desc => 'Optional summary',

Optional. Provides the description (summary) of the gist. By default not specified.

public

public => True,

Optional. Takes True or False values. If set to True, your gist will be visible in search results and recent gists page. Defaults to: False.

filename

filename => "Foo.raku"

Optional. Applies only when the first positional argument to /paste is a string. Specifies the filename to use for your gist (affects syntax highlighting). Defaults to: nopaste.txt.

Note: GitHub's API docs have this blurb in them:

Don't name your files "gistfile" with a numerical suffix.
    This is the format of the automatic naming scheme that
    Gist uses internally.

It tells you not to use files gistfile3 or gistfile33.txt. Behaviour when using this types of values for filename is not defined.

fetch

my ( $files, $desc )
  = $p.fetch('https://gist.github.com/5590bc07b8d5bd8fd98d');

my ( $files, $desc ) = $p.fetch('5590bc07b8d5bd8fd98d');
say "Title: $desc";
for $files.keys {
    say "File: $_\nContent:\n$files{$_}";
}

Returns a two-item list: files in the gist and gist's title. Takes one mandatory argument: a full URL or just the ID number of the gist you want to retrieve. The $files is a hashref, where keys are file names and values are the file's contents. On failure, throws `Pastebin::Gist::X` exception whose `$.message` method has reason for error.

delete

$p.delete: 'https://gist.github.com/5590bc07b8d5bd8fd98d';
$p.delete: '5590bc07b8d5bd8fd98d';

Returns `True`. Deletes an existing gist referenced by either the ID or the full URL to it. On failure, throws `Pastebin::Gist::X` exception whose `$.message` method has reason for error.

AUTHOR

Zoffix Znet

COPYRIGHT AND LICENSE

Copyright 2015 - 2018 Zoffix Znet

Copyright 2019 - 2022 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.