---
name: "Pithub::Gists"
section: "3pm"
platform: "linux"
package: "libpithub-perl"
version: "0.01043-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pithub::Gists"
---

# Pithub::Gists(3pm)

Github v3 Gists API

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