GlotIO - use glot.io API via Raku

use GlotIO;
my GlotIO $glot .= new: :key<89xxxx9f-a3ec-4445-9f14-6xxxe6ff3846>;

say $glot.languages;

• NAME
• SYNOPSIS
• DESCRIPTION
• KEY
• METHODS
  • .new
  • .languages
  • .versions
  • .run
  • .stdout
  • .stderr
  • .list
  • .create
  • .get
  • .update
  • .delete
• REPOSITORY
• BUGS
• AUTHOR
• LICENSE

This module lets you use API provided glot.io which is a pastebin that also lets you execute code in a number of languages.

Some parts of the API require you register at glot.io and obtain an API key

my GlotIO $glot .= new: :key<89xxxx9f-a3ec-4445-9f14-6xxxe6ff3846>;

Constructs and returns a new GlotIO object. Takes one optional argument: key, which is the API key. Methods that require the key are marked as such.

say "Glot.io supports $_" for $glot.languages;

Returns a list of languages supported by GlotIO.

say "Glot.io supports $_ version of Raku"
    for $glot.versions: 'raku';

Returns a list of supported versions for a language that must be supplied as the mandatory positional argument. List of valid language names can be obtained via .languages method. Using an invalid language will fail as an HTTP 404 error.

    say $glot.run: 'raku', 'say "Hello, World!"';

    say $glot.run: 'raku', [
        'main.raku'   => 'use lib "."; use Foo; doit;',
        'Foo.rakumod' => 'unit module Foo; sub doit is export { say "42" }',
    ];

    say $glot.run: 'python', 'print "Hello, World!"', :ver<2>;

Requests code to run on Glot. The first positional argument specifies the language to use (see .languages method). Second argument can either be an Str of code to run or an Array of Pairs. If the array is specified, the key of each Pair specifies the filename and the value specifies the code for that file. The first file in the array will be executed by Glot, while the rest are supporting files, such as modules loaded by the first file.

The optional named argument ver can be used to specify the version of the language to use. See .versions method.

Returns a Hash with three keys: stdout, stderr which specify the output streams received from the program and error that seems to contain an error code, if the program doesn't successfully exit.

If an incorrect language or version are specified, will fail with an HTTP 404 error.

    say $glot.stdout: 'raku', 'say "Hello, World!"';

A shortcut for calling .run (takes same arguments) and returning just the stdout key. Will fail with the entire Hash returned from .run if the program errors out.

    say $glot.stderr: 'raku', 'note "Hello, World!"';

A shortcut for calling .run (takes same arguments) and returning just the stderr key. Will fail with the entire Hash returned from .run if the program errors out.

say $glot.list<content>[0..3];

say $glot.list: :3page, :50per-page, :mine;

Fetches a list of metadata for snippets. Takes optional named arguments:

• page positive integer starting at and defaulting to 1. Specifies the page to display
• per-page positive integer stating the maximum number of items to return per page. Defaults to 100. Maximum value is 100.
• mine boolean specifying whether public or your own snippets should be listed. Defaults to False. Requires key argument to .new to be provided if set to True.

Returns a Hash in the following format:

    {
        first   => 1,
        last    => 20,
        next    => 5,
        prev    => 3,
        content => [
            {
                created    => "2016-04-09T17:52:19Z",
                files_hash => "2afa1f37cc0bc7d033e4b3a049659792f5caac6d",
                id         => "edltstt3n0",
                language   => "cpp",
                modified   => "2016-04-09T17:52:19Z",
                owner      => "anonymous",
                public     => Bool::True,
                title      => "Untitled",
                url        => "https://snippets.glot.io/snippets/edltstt3n0",
            },
            ...
        ]
    }

The first, last, next, prev keys indicate the corresponding page number. All 4 will NOT be present at all times. The content key is a list of hashes, each representing metadata for a snipet.

Attempting to fetch a page that doesn't exist will fail with an HTTP 404 error.

    say $glot.create: 'perl6', 'say "Hello, World!"';

    say $glot.create: 'perl6', [
            'main.p6' => 'use lib "."; use Foo; say "Hello, World!"',
            'Foo.pm6' => 'unit module Foo;',
        ], 'Module import example',
        :mine;

Creates a new snippet. Takes: a valid language (see .languages method), either a Str of code or an array of filename => code pairs, and an optional title of the snippet as positional arguments. An optional Bool mine named argument, which defaults to False can be set to True to specify your snippet should not be public. API Key (see .key in .new) must be specified for this option to succeed.

Returns a hash with metadata for the newly created snippet:

    {
      created    => "2016-04-10T17:42:20Z".Str,
      files      => [
        {
          content => "say \"Hello, World!\"".Str,
          name    => "main".Str,
        },
      ],
      files_hash => "6ed47f09569b36dc8d83b6af82026e5f86e3967e".Str,
      id         => "edmx7tewwu".Str,
      language   => "perl6".Str,
      modified   => "2016-04-10T17:42:20Z".Str,
      owner      => "c490baa3-1ecb-42f5-8742-216abbb97f8d".Str,
      public     => Bool::False.Bool,
      title      => "Untitled".Str,
      url        => "https://snippets.glot.io/snippets/edmx7tewwu".Str,
    }

    say $glot.get: 'edmxttmtd5';

Fetches a snippet. Takes one mandatory argument: the ID of the snippet to fetch. Returns a hash with the snippet details:

    {
      created    => "2016-04-10T18:04:30Z".Str,
      files      => [
        {
          content => "use lib \".\"; use Foo; say \"Hello, World!\"".Str,
          name    => "main.raku".Str,
        },
        {
          content => "unit module Foo;".Str,
          name    => "Foo.rakumod".Str,
        },
      ],
      files_hash => "8042cf6813f1772e63c8afd0a556004ad9591ce2".Str,
      id         => "edmxttmtd5".Str,
      language   => "raku".Str,
      modified   => "2016-04-10T18:04:30Z".Str,
      owner      => "c490baa3-1ecb-42f5-8742-216abbb97f8d".Str,
      public     => Bool::True.Bool,
      title      => "Module import example".Str,
      url        => "https://snippets.glot.io/snippets/edmxttmtd5".Str,
    }

    say $glot.update: 'snippet-id', 'perl6', 'say "Hello, World!"';

    # Or
    say $glot.update: 'snippet-id', 'perl6', [
            'main.p6' => 'use lib "."; use Foo; say "Hello, World!"',
            'Foo.pm6' => 'unit module Foo;',
        ], 'Module import example';

    # Or
    my $snippet = $glot.get: 'edmxttmtd5';
    $snippet<title> = 'New title';
    $glot.update: $snippet;

Updates an existing snippet. Requires the use of API key (see .key in constructor). As positional arguments, takes snippet ID to update, the language of the snippet, snippet code, and snippet title. The title is optional and will be set to Untitled by default. Snippet code can be provided as a single string of code or as an array of Pairs, where the key is the filename and the value is the code for the file.

In addition, .update can also take a Hash. This form is useful when you already have a snippet Hash from .create or .get methods and simply wish to modify it. The required keys in the hash are id, title, language, and files, where the first three are strings and files is an array of Hashes, with each hash having keys name and content representing the filename of a file and its code.

Returns a Hash with the updated snippet data:

    {
        created    => "2016-04-10T18:04:30Z".Str,
        files      => [
          {
            content => "use lib \".\"; use Foo; say \"Hello, World!\"".Str,
            name    => "main.p6".Str,
          },
          {
            content => "unit module Foo;".Str,
            name    => "Foo.pm6".Str,
          },
        ],
        files_hash => "8042cf6813f1772e63c8afd0a556004ad9591ce2".Str,
        id         => "edmxttmtd5".Str,
        language   => "perl6".Str,
        modified   => "2016-04-13T00:05:02Z".Str,
        owner      => "c490baa3-1ecb-42f5-8742-216abbb97f8d".Str,
        public     => Bool::False.Bool,
        title      => "New title".Str,
        url        => "https://snippets.glot.io/snippets/edmxttmtd5".Str,
    }

    $glot.delete: 'snippet-id';

Deletes a snippet. Requires the use of API key (see .key in constructor). Takes one positional argument: the ID of the snippet to delete. On success, returns True. Attempting to delete a non-existant snippet will fail with an HTTP 404 error.

Fork this module on GitHub: https://github.com/raku-community-modules/GlotIO

To report bugs or request features, please use https://github.com/raku-community-modules/GlotIO/issues

Zoffix Znet (http://zoffix.com/)

You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.