Provided by: libpithub-perl_0.01040-1_all bug

NAME

       Pithub::Gists - Github v3 Gists API

VERSION

       version 0.01040

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.