Pithub::Gists(3)

NAME
Pithub::Gists - Github v3 Gists API

VERSION
version 0.01043

METHODS

  comments
Provides access to Pithub::Gists::Comments.

  create

•   Create a gist

        POST /gists

    Parameters:

    •   data: mandatory hashref, having following keys:

        •   description: optional string

        •   public: mandatory boolean

        •   files: mandatory hashref, please see examples section below

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->create(
            data => {
                description => 'the description for this gist',
                public      => 1,
                files       => { 'file1.txt' => { content => 'String file content' } }
            }
        );
        if ( $result->success ) {
            printf "The new gist is available at %s\n", $result->content->{html_url};
        }

    Response: Status: 201 Created

        {
            "url": "https://api.github.com/gists/1",
            "id": "1",
            "description": "description of gist",
            "public": true,
            "user": {
                "login": "octocat",
                "id": 1,
                "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                "url": "https://api.github.com/users/octocat"
            },
            "files": {
                "ring.erl": {
                    "size": 932,
                    "filename": "ring.erl",
                    "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl",
                    "content": "contents of gist"
                }
            },
            "comments": 0,
            "git_pull_url": "git://gist.github.com/1.git",
            "git_push_url": "git@gist.github.com:1.git",
            "created_at": "2010-04-14T02:15:15Z",
            "forks": [
            {
                "user": {
                    "login": "octocat",
                    "id": 1,
                    "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                    "url": "https://api.github.com/users/octocat"
                },
                "url": "https://api.github.com/gists/5",
                "created_at": "2011-04-14T16:00:49Z"
            }
            ],
            "history": [
            {
                "url": "https://api.github.com/gists/1/57a7f021a713b1c5a6a199b54cc514735d2d462f",
                "version": "57a7f021a713b1c5a6a199b54cc514735d2d462f",
                "user": {
                    "login": "octocat",
                    "id": 1,
                    "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                    "url": "https://api.github.com/users/octocat"
                },
                "change_status": {
                    "deletions": 0,
                    "additions": 180,
                    "total": 180
                },
                "committed_at": "2010-04-14T02:15:15Z"
            }
            ]
        }

  delete

•   Delete a gist

        DELETE /gists/:id

    Parameters:

    •   gist_id: mandatory integer

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->delete( gist_id => 784612 );
        if ( $result->success ) {
            print "The gist 784612 has been deleted\n";
        }

    Response: Status: 204 No Content

  fork

•   Fork a gist

        POST /gists/:id/forks

    Parameters:

    •   gist_id: mandatory integer

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->fork( gist_id => 784612 );
        if ( $result->success ) {
            printf "The gist 784612 has been forked: %s\n", $result->content->{html_url};
        }

    Response: Status: 201 Created

        {
            "url": "https://api.github.com/gists/1",
            "id": "1",
            "description": "description of gist",
            "public": true,
            "user": {
                "login": "octocat",
                "id": 1,
                "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                "url": "https://api.github.com/users/octocat"
            },
            "files": {
                "ring.erl": {
                    "size": 932,
                    "filename": "ring.erl",
                    "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl",
                    "content": "contents of gist"
                }
            },
            "comments": 0,
            "git_pull_url": "git://gist.github.com/1.git",
            "git_push_url": "git@gist.github.com:1.git",
            "created_at": "2010-04-14T02:15:15Z"
        }

  get

•   Get a single gist

        GET /gists/:id

    Parameters:

    •   gist_id: mandatory integer

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->get( gist_id => 784612 );
        if ( $result->success ) {
            print $result->content->{html_url};
        }

    Response: Status: 200 OK

        {
            "url": "https://api.github.com/gists/1",
            "id": "1",
            "description": "description of gist",
            "public": true,
            "user": {
                "login": "octocat",
                "id": 1,
                "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                "url": "https://api.github.com/users/octocat"
            },
            "files": {
                "ring.erl": {
                    "size": 932,
                    "filename": "ring.erl",
                    "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl",
                    "content": "contents of gist"
                }
            },
            "comments": 0,
            "git_pull_url": "git://gist.github.com/1.git",
            "git_push_url": "git@gist.github.com:1.git",
            "created_at": "2010-04-14T02:15:15Z",
            "forks": [
            {
                "user": {
                    "login": "octocat",
                    "id": 1,
                    "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                    "url": "https://api.github.com/users/octocat"
                },
                "url": "https://api.github.com/gists/5",
                "created_at": "2011-04-14T16:00:49Z"
            }
            ],
            "history": [
            {
                "url": "https://api.github.com/gists/1/57a7f021a713b1c5a6a199b54cc514735d2d462f",
                "version": "57a7f021a713b1c5a6a199b54cc514735d2d462f",
                "user": {
                    "login": "octocat",
                    "id": 1,
                    "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                    "url": "https://api.github.com/users/octocat"
                },
                "change_status": {
                    "deletions": 0,
                    "additions": 180,
                    "total": 180
                },
                "committed_at": "2010-04-14T02:15:15Z"
            }
            ]
        }

  is_starred

•   Check if a gist is starred

        GET /gists/:id/star

    Parameters:

    •   gist_id: mandatory integer

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->is_starred( gist_id => 784612 );

    Response: Status: 204 No Content / "Status: 404 Not Found"

  list

•   List a user's gists:

        GET /users/:user/gists

    Parameters:

    •   user: string

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->list( user => 'miyagawa' );
        if ( $result->success ) {
            while ( my $row = $result->next ) {
                printf "%s => %s\n", $row->{html_url}, $row->{description} || 'no description';
            }
        }

•   List the authenticated user's gists or if called anonymously, this will returns all public gists:

        GET /gists

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->list;

•   List all public gists:

        GET /gists/public

    Parameters:

    •   public: boolean

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->list( public => 1 );

•   List the authenticated user's starred gists:

        GET /gists/starred

    Parameters:

    •   starred: boolean

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->list( starred => 1 );

    Response: Status: 200 OK

        [
            {
                "url": "https://api.github.com/gists/1",
                "id": "1",
                "description": "description of gist",
                "public": true,
                "user": {
                    "login": "octocat",
                    "id": 1,
                    "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                    "url": "https://api.github.com/users/octocat"
                },
                "files": {
                    "ring.erl": {
                        "size": 932,
                        "filename": "ring.erl",
                        "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl",
                        "content": "contents of gist"
                    }
                },
                "comments": 0,
                "git_pull_url": "git://gist.github.com/1.git",
                "git_push_url": "git@gist.github.com:1.git",
                "created_at": "2010-04-14T02:15:15Z"
            }
        ]

  star

•   Star a gist

        PUT /gists/:id/star

    Parameters:

    •   gist_id: mandatory integer

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->star( gist_id => 784612 );

    Response: Status: 204 No Content

  unstar

•   Unstar a gist

        DELETE /gists/:id/star

    Parameters:

    •   gist_id: mandatory integer

    Examples:

        my $g = Pithub::Gists->new;
        my $result = $g->unstar( gist_id => 784612 );

    Response: Status: 204 No Content

  update

•   Edit a gist

        PATCH /gists/:id

    Parameters:

    •   gist_id: mandatory integer

    •   data: mandatory hashref, having following keys:

        •   description: optional string

        •   public: mandatory boolean

        •   files: mandatory hashref, please see examples section below

            NOTE: All files from the previous version of the gist are carried over by default if not included in the hash. Deletes can be performed by including the filename with a null hash.

    Examples:

        my $g      = Pithub::Gists->new;
        my $result = $g->update(
            gist_id => 784612,
            data    => {
                description => 'the description for this gist',
                files       => {
                    'file1.txt'    => { content => 'updated file contents' },
                    'old_name.txt' => {
                        filename => 'new_name.txt',
                        content  => 'modified contents'
                    },
                    'new_file.txt'         => { content => 'a new file' },
                    'delete_this_file.txt' => undef
                }
            }
        );

    Response: Status: 200 OK

        {
            "url": "https://api.github.com/gists/1",
            "id": "1",
            "description": "description of gist",
            "public": true,
            "user": {
                "login": "octocat",
                "id": 1,
                "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                "url": "https://api.github.com/users/octocat"
            },
            "files": {
                "ring.erl": {
                    "size": 932,
                    "filename": "ring.erl",
                    "raw_url": "https://gist.github.com/raw/365370/8c4d2d43d178df44f4c03a7f2ac0ff512853564e/ring.erl",
                    "content": "contents of gist"
                }
            },
            "comments": 0,
            "git_pull_url": "git://gist.github.com/1.git",
            "git_push_url": "git@gist.github.com:1.git",
            "created_at": "2010-04-14T02:15:15Z",
            "forks": [
            {
                "user": {
                    "login": "octocat",
                    "id": 1,
                    "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                    "url": "https://api.github.com/users/octocat"
                },
                "url": "https://api.github.com/gists/5",
                "created_at": "2011-04-14T16:00:49Z"
            }
            ],
            "history": [
            {
                "url": "https://api.github.com/gists/1/57a7f021a713b1c5a6a199b54cc514735d2d462f",
                "version": "57a7f021a713b1c5a6a199b54cc514735d2d462f",
                "user": {
                    "login": "octocat",
                    "id": 1,
                    "gravatar_url": "https://github.com/images/error/octocat_happy.gif",
                    "url": "https://api.github.com/users/octocat"
                },
                "change_status": {
                    "deletions": 0,
                    "additions": 180,
                    "total": 180
                },
                "committed_at": "2010-04-14T02:15:15Z"
            }
            ]
        }

AUTHOR
Johannes Plunien <plu@cpan.org>

COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Johannes Plunien.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.