README.md
1# NAME
2
3Pithub - Github v3 API
4
5# VERSION
6
7version 0.01036
8
9# SYNOPSIS
10
11 use Pithub;
12 use Data::Dumper;
13
14 my $p = Pithub->new;
15 # my $p = Pithub->new(utf8 => 0); # enable compatibility options for version 0.01029 or lower
16 my $result = $p->repos->get( user => 'plu', repo => 'Pithub' );
17
18 # $result->content is either an arrayref or an hashref
19 # depending on the API call that has been made
20 printf "%s\n", $result->content->{html_url}; # prints https://github.com/plu/Pithub
21 printf "%s\n", $result->content->{clone_url}; # prints https://github.com/plu/Pithub.git
22
23 # if the result is an arrayref, you can use the result iterator
24 my $result = $p->repos->list( user => 'plu' );
25 while ( my $row = $result->next ) {
26 printf "%s\n", $row->{name};
27 }
28
29 # Connect to your local GitHub Enterprise instance
30 my $p = Pithub->new(
31 api_uri => 'https://github.yourdomain.com/api/v3/'
32 );
33
34 # No need to provide user/repo to each module:
35 my $pit = Pithub->new(
36 user => 'plu',
37 repo => 'pithub',
38 token => 'my_oauth_token',
39 );
40
41 $pit->repos->get;
42 $pit->repos->commits->list;
43
44# DESCRIPTION
45
46[Pithub](https://metacpan.org/pod/Pithub) (**P**erl + G**ithub**) provides a set of modules to access the
47[Github v3 API](http://developer.github.com/v3/) in an object
48oriented way. There is also [Net::GitHub](https://metacpan.org/pod/Net%3A%3AGitHub) which does the same for
49all the versions (v1, v2, v3) of the Github API.
50[Pithub](https://metacpan.org/pod/Pithub) supports all API calls so far, but only for v3.
51
52# ATTRIBUTES
53
54## search\_api
55
56 my $p = Pithub->new({ search_api => 'v3' });
57 my $search = $p->search; # $search->isa('Pithub::SearchV3');
58
59This attribute allows the default for the API to use for searches to be
60specified. The two accepted values are `v3` and `legacy`. For compatibility
61reasons the default is `legacy`.
62
63# METHODS
64
65## events
66
67Provides access to [Pithub::Events](https://metacpan.org/pod/Pithub%3A%3AEvents).
68
69## gists
70
71Provides access to [Pithub::Gists](https://metacpan.org/pod/Pithub%3A%3AGists).
72
73## git\_data
74
75Provides access to [Pithub::GitData](https://metacpan.org/pod/Pithub%3A%3AGitData).
76
77## issues
78
79Provides access to [Pithub::Issues](https://metacpan.org/pod/Pithub%3A%3AIssues).
80
81## markdown
82
83Provides access to [Pithub::Markdown](https://metacpan.org/pod/Pithub%3A%3AMarkdown).
84
85## orgs
86
87Provides access to [Pithub::Orgs](https://metacpan.org/pod/Pithub%3A%3AOrgs).
88
89## pull\_requests
90
91Provides access to [Pithub::PullRequests](https://metacpan.org/pod/Pithub%3A%3APullRequests).
92
93## repos
94
95Provides access to [Pithub::Repos](https://metacpan.org/pod/Pithub%3A%3ARepos).
96
97## search
98
99 my $legacy_search = $p->search(search_api => 'legacy');
100 my $v3_search = $p->search(search_api => 'v3');
101 my $default_search = $p->search;
102
103Provides access to [Pithub::Search](https://metacpan.org/pod/Pithub%3A%3ASearch) and [Pithub::SearchV3](https://metacpan.org/pod/Pithub%3A%3ASearchV3). When no
104`search_api` option is given, the value provided by the `search_api`
105attribute is used.
106
107## users
108
109Provides access to [Pithub::Users](https://metacpan.org/pod/Pithub%3A%3AUsers).
110
111# DOCUMENTATION
112
113Quite a lot of the [Pithub](https://metacpan.org/pod/Pithub) documentation has been taken directly
114from the great API documentation at
115[Github](http://developer.github.com/v3/). Please also read the
116documentation there, since it might be more complete and more
117up-to-date.
118
119[Pithub::Base](https://metacpan.org/pod/Pithub%3A%3ABase) contains documentation for attributes inherited by all
120Pithub modules.
121
122# WARNING
123
124[Pithub](https://metacpan.org/pod/Pithub) as well as the
125[Github v3 API](http://developer.github.com/v3/) are still under
126development. So there might be things broken on both sides. Besides
127that it's possible that the API will change. This applies to
128[Pithub](https://metacpan.org/pod/Pithub) itself as well as the
129[Github v3 API](http://developer.github.com/v3/).
130
131# CONTRIBUTE
132
133This module is hosted on [Github](https://github.com/plu/Pithub), so
134feel free to fork it and send pull requests.
135There are two different kinds of test suites, one is just checking
136the HTTP requests that are created by the method calls, without
137actually sending them. The second one is sending real requests to
138the Github API. If you want to contribute to this project, I highly
139recommend to run the live tests on a test account, because it will
140generate a lof of activity.
141
142# MODULES
143
144There are different ways of using the Pithub library. You can either
145use the main module [Pithub](https://metacpan.org/pod/Pithub) to get access to all other
146modules, like [Pithub::Repos](https://metacpan.org/pod/Pithub%3A%3ARepos) for example. Or you can use
147[Pithub::Repos](https://metacpan.org/pod/Pithub%3A%3ARepos) directly and create an instance of it. All
148modules accept the same [attributes](https://metacpan.org/pod/Pithub%3A%3ABase#ATTRIBUTES),
149either in the constructor or later by calling the setters.
150
151Besides that there are other modules involved. Every method call
152which maps directly to a Github API call returns a
153[Pithub::Result](https://metacpan.org/pod/Pithub%3A%3AResult) object. This contains everything interesting
154about the response returned from the API call.
155
156[Pithub::Base](https://metacpan.org/pod/Pithub%3A%3ABase) might be interesting for two reasons:
157
158- The list of [attributes](https://metacpan.org/pod/Pithub%3A%3ABase#ATTRIBUTES) which all modules
159accept.
160- The [request](https://metacpan.org/pod/Pithub%3A%3ABase#request) method: In case Github adds a
161new API call which is not supported yet by [Pithub](https://metacpan.org/pod/Pithub) the
162[request](https://metacpan.org/pod/Pithub%3A%3ABase#request) method can be used directly to
163perform this new API call, there's some documentation on how to
164use it.
165 - [Pithub::Events](https://metacpan.org/pod/Pithub%3A%3AEvents)
166
167 See also: [http://developer.github.com/v3/events/](http://developer.github.com/v3/events/)
168
169 my $events = Pithub->new->events;
170 my $events = Pithub::Events->new;
171
172 - [Pithub::Gists](https://metacpan.org/pod/Pithub%3A%3AGists)
173
174 See also: [http://developer.github.com/v3/gists/](http://developer.github.com/v3/gists/)
175
176 my $gists = Pithub->new->gists;
177 my $gists = Pithub::Gists->new;
178
179 - [Pithub::Gists::Comments](https://metacpan.org/pod/Pithub%3A%3AGists%3A%3AComments)
180
181 See also: [http://developer.github.com/v3/gists/comments/](http://developer.github.com/v3/gists/comments/)
182
183 my $comments = Pithub->new->gists->comments;
184 my $comments = Pithub::Gists->new->comments;
185 my $comments = Pithub::Gists::Comments->new;
186
187 - [Pithub::GitData](https://metacpan.org/pod/Pithub%3A%3AGitData)
188
189 See also: [http://developer.github.com/v3/git/](http://developer.github.com/v3/git/)
190
191 my $git_data = Pithub->new->git_data;
192 my $git_data = Pithub::GitData->new;
193
194 - [Pithub::GitData::Blobs](https://metacpan.org/pod/Pithub%3A%3AGitData%3A%3ABlobs)
195
196 See also: [http://developer.github.com/v3/git/blobs/](http://developer.github.com/v3/git/blobs/)
197
198 my $blobs = Pithub->new->git_data->blobs;
199 my $blobs = Pithub::GitData->new->blobs;
200 my $blobs = Pithub::GitData::Blobs->new;
201
202 - [Pithub::GitData::Commits](https://metacpan.org/pod/Pithub%3A%3AGitData%3A%3ACommits)
203
204 See also: [http://developer.github.com/v3/git/commits/](http://developer.github.com/v3/git/commits/)
205
206 my $commits = Pithub->new->git_data->commits;
207 my $commits = Pithub::GitData->new->commits;
208 my $commits = Pithub::GitData::Commits->new;
209
210 - [Pithub::GitData::References](https://metacpan.org/pod/Pithub%3A%3AGitData%3A%3AReferences)
211
212 See also: [http://developer.github.com/v3/git/refs/](http://developer.github.com/v3/git/refs/)
213
214 my $references = Pithub->new->git_data->references;
215 my $references = Pithub::GitData->new->references;
216 my $references = Pithub::GitData::References->new;
217
218 - [Pithub::GitData::Tags](https://metacpan.org/pod/Pithub%3A%3AGitData%3A%3ATags)
219
220 See also: [http://developer.github.com/v3/git/tags/](http://developer.github.com/v3/git/tags/)
221
222 my $tags = Pithub->new->git_data->tags;
223 my $tags = Pithub::GitData->new->tags;
224 my $tags = Pithub::GitData::Tags->new;
225
226 - [Pithub::GitData::Trees](https://metacpan.org/pod/Pithub%3A%3AGitData%3A%3ATrees)
227
228 See also: [http://developer.github.com/v3/git/trees/](http://developer.github.com/v3/git/trees/)
229
230 my $trees = Pithub->new->git_data->trees;
231 my $trees = Pithub::GitData->new->trees;
232 my $trees = Pithub::GitData::Trees->new;
233
234 - [Pithub::Issues](https://metacpan.org/pod/Pithub%3A%3AIssues)
235
236 See also: [http://developer.github.com/v3/issues/](http://developer.github.com/v3/issues/)
237
238 my $issues = Pithub->new->issues;
239 my $issues = Pithub::Issues->new;
240
241 - [Pithub::Issues::Assignees](https://metacpan.org/pod/Pithub%3A%3AIssues%3A%3AAssignees)
242
243 See also: [http://developer.github.com/v3/issues/assignees/](http://developer.github.com/v3/issues/assignees/)
244
245 my $assignees = Pithub->new->issues->assignees;
246 my $assignees = Pithub::Issues->new->assignees;
247 my $assignees = Pithub::Issues::Assignees->new;
248
249 - [Pithub::Issues::Comments](https://metacpan.org/pod/Pithub%3A%3AIssues%3A%3AComments)
250
251 See also: [http://developer.github.com/v3/issues/comments/](http://developer.github.com/v3/issues/comments/)
252
253 my $comments = Pithub->new->issues->comments;
254 my $comments = Pithub::Issues->new->comments;
255 my $comments = Pithub::Issues::Comments->new;
256
257 - [Pithub::Issues::Events](https://metacpan.org/pod/Pithub%3A%3AIssues%3A%3AEvents)
258
259 See also: [http://developer.github.com/v3/issues/events/](http://developer.github.com/v3/issues/events/)
260
261 my $events = Pithub->new->issues->events;
262 my $events = Pithub::Issues->new->events;
263 my $events = Pithub::Issues::Events->new;
264
265 - [Pithub::Issues::Labels](https://metacpan.org/pod/Pithub%3A%3AIssues%3A%3ALabels)
266
267 See also: [http://developer.github.com/v3/issues/labels/](http://developer.github.com/v3/issues/labels/)
268
269 my $labels = Pithub->new->issues->labels;
270 my $labels = Pithub::Issues->new->labels;
271 my $labels = Pithub::Issues::Labels->new;
272
273 - [Pithub::Issues::Milestones](https://metacpan.org/pod/Pithub%3A%3AIssues%3A%3AMilestones)
274
275 See also: [http://developer.github.com/v3/issues/milestones/](http://developer.github.com/v3/issues/milestones/)
276
277 my $milestones = Pithub->new->issues->milestones;
278 my $milestones = Pithub::Issues->new->milestones;
279 my $milestones = Pithub::Issues::Milestones->new;
280
281 - [Pithub::Orgs](https://metacpan.org/pod/Pithub%3A%3AOrgs)
282
283 See also: [http://developer.github.com/v3/orgs/](http://developer.github.com/v3/orgs/)
284
285 my $orgs = Pithub->new->orgs;
286 my $orgs = Pithub::Orgs->new;
287
288 - [Pithub::Orgs::Members](https://metacpan.org/pod/Pithub%3A%3AOrgs%3A%3AMembers)
289
290 See also: [http://developer.github.com/v3/orgs/members/](http://developer.github.com/v3/orgs/members/)
291
292 my $members = Pithub->new->orgs->members;
293 my $members = Pithub::Orgs->new->members;
294 my $members = Pithub::Orgs::Members->new;
295
296 - [Pithub::Orgs::Teams](https://metacpan.org/pod/Pithub%3A%3AOrgs%3A%3ATeams)
297
298 See also: [http://developer.github.com/v3/orgs/teams/](http://developer.github.com/v3/orgs/teams/)
299
300 my $teams = Pithub->new->orgs->teams;
301 my $teams = Pithub::Orgs->new->teams;
302 my $teams = Pithub::Orgs::Teams->new;
303
304 - [Pithub::PullRequests](https://metacpan.org/pod/Pithub%3A%3APullRequests)
305
306 See also: [http://developer.github.com/v3/pulls/](http://developer.github.com/v3/pulls/)
307
308 my $pull_requests = Pithub->new->pull_requests;
309 my $pull_requests = Pithub::PullRequests->new;
310
311 - [Pithub::PullRequests::Comments](https://metacpan.org/pod/Pithub%3A%3APullRequests%3A%3AComments)
312
313 See also: [http://developer.github.com/v3/pulls/comments/](http://developer.github.com/v3/pulls/comments/)
314
315 my $comments = Pithub->new->pull_requests->comments;
316 my $comments = Pithub::PullRequests->new->comments;
317 my $comments = Pithub::PullRequests::Comments->new;
318
319 - [Pithub::PullRequests::Reviewers](https://metacpan.org/pod/Pithub%3A%3APullRequests%3A%3AReviewers)
320
321 See also: [https://docs.github.com/en/rest/reference/pulls#review-requests](https://docs.github.com/en/rest/reference/pulls#review-requests)
322
323 my $reviewers = Pithub->new->pull_requests->reviewers;
324 my $reviewers = Pithub::PullRequests->new->reviewers;
325 my $reviewers = Pithub::PullRequests::Reviewers->new;
326
327 - [Pithub::Repos](https://metacpan.org/pod/Pithub%3A%3ARepos)
328
329 See also: [http://developer.github.com/v3/repos/](http://developer.github.com/v3/repos/)
330
331 my $repos = Pithub->new->repos;
332 my $repos = Pithub::Repos->new;
333
334 - [Pithub::Repos::Collaborators](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3ACollaborators)
335
336 See also: [http://developer.github.com/v3/repos/collaborators/](http://developer.github.com/v3/repos/collaborators/)
337
338 my $collaborators = Pithub->new->repos->collaborators;
339 my $collaborators = Pithub::Repos->new->collaborators;
340 my $collaborators = Pithub::Repos::Collaborators->new;
341
342 - [Pithub::Repos::Commits](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3ACommits)
343
344 See also: [http://developer.github.com/v3/repos/commits/](http://developer.github.com/v3/repos/commits/)
345
346 my $commits = Pithub->new->repos->commits;
347 my $commits = Pithub::Repos->new->commits;
348 my $commits = Pithub::Repos::Commits->new;
349
350 - [Pithub::Repos::Contents](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AContents)
351
352 See also: [http://developer.github.com/v3/repos/contents/](http://developer.github.com/v3/repos/contents/)
353
354 my $contents = Pithub->new->repos->contents;
355 my $contents = Pithub::Repos->new->contents;
356 my $contents = Pithub::Repos::Contents->new;
357
358 - [Pithub::Repos::Downloads](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3ADownloads)
359
360 Github says: The Downloads API (described below) was deprecated on
361 December 11, 2012. It will be removed at a future date. We recommend
362 using [Pithub::Repos::Releases](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AReleases) instead.
363
364 See also: [http://developer.github.com/v3/repos/downloads/](http://developer.github.com/v3/repos/downloads/)
365
366 my $downloads = Pithub->new->repos->downloads;
367 my $downloads = Pithub::Repos->new->downloads;
368 my $downloads = Pithub::Repos::Downloads->new;
369
370 - [Pithub::Repos::Forks](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AForks)
371
372 See also: [http://developer.github.com/v3/repos/forks/](http://developer.github.com/v3/repos/forks/)
373
374 my $forks = Pithub->new->repos->forks;
375 my $forks = Pithub::Repos->new->forks;
376 my $forks = Pithub::Repos::Forks->new;
377
378 - [Pithub::Repos::Keys](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AKeys)
379
380 See also: [http://developer.github.com/v3/repos/keys/](http://developer.github.com/v3/repos/keys/)
381
382 my $keys = Pithub->new->repos->keys;
383 my $keys = Pithub::Repos->new->keys;
384 my $keys = Pithub::Repos::Keys->new;
385
386 - [Pithub::Repos::Releases](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AReleases)
387
388 See also: [http://developer.github.com/v3/repos/releases/](http://developer.github.com/v3/repos/releases/)
389
390 my $releases = Pithub->new->repos->releases;
391 my $releases = Pithub::Repos->new->releases;
392 my $releases = Pithub::Repos::Releases->new;
393
394 - [Pithub::Repos::Releases::Assets](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AReleases%3A%3AAssets)
395
396 See also: [http://developer.github.com/v3/repos/releases/](http://developer.github.com/v3/repos/releases/)
397
398 my $assets = Pithub->new->repos->releases->assets;
399 my $assets = Pithub::Repos->new->releases->assets;
400 my $assets = Pithub::Repos::Releases->new->assets;
401 my $assets = Pithub::Repos::Releases::Assets->new;
402
403 - [Pithub::Repos::Stats](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AStats)
404
405 See also: [http://developer.github.com/v3/repos/statistics/](http://developer.github.com/v3/repos/statistics/)
406
407 my $watching = Pithub->new->repos->stats;
408 my $watching = Pithub::Repos->new->stats;
409 my $watching = Pithub::Repos::Stats->new;
410
411 - [Pithub::Repos::Statuses](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AStatuses)
412
413 See also: [http://developer.github.com/v3/repos/statuses/](http://developer.github.com/v3/repos/statuses/)
414
415 my $watching = Pithub->new->repos->statuses;
416 my $watching = Pithub::Repos->new->statuses;
417 my $watching = Pithub::Repos::Statuses->new;
418
419 - [Pithub::Repos::Watching](https://metacpan.org/pod/Pithub%3A%3ARepos%3A%3AWatching)
420
421 See also: [http://developer.github.com/v3/repos/watching/](http://developer.github.com/v3/repos/watching/)
422
423 my $watching = Pithub->new->repos->watching;
424 my $watching = Pithub::Repos->new->watching;
425 my $watching = Pithub::Repos::Watching->new;
426
427 - [Pithub::Users](https://metacpan.org/pod/Pithub%3A%3AUsers)
428
429 See also: [http://developer.github.com/v3/users/](http://developer.github.com/v3/users/)
430
431 my $users = Pithub->new->users;
432 my $users = Pithub::Users->new;
433
434 - [Pithub::Users::Emails](https://metacpan.org/pod/Pithub%3A%3AUsers%3A%3AEmails)
435
436 See also: [http://developer.github.com/v3/users/emails/](http://developer.github.com/v3/users/emails/)
437
438 my $emails = Pithub->new->users->emails;
439 my $emails = Pithub::Users->new->emails;
440 my $emails = Pithub::Users::Emails->new;
441
442 - [Pithub::Users::Followers](https://metacpan.org/pod/Pithub%3A%3AUsers%3A%3AFollowers)
443
444 See also: [http://developer.github.com/v3/users/followers/](http://developer.github.com/v3/users/followers/)
445
446 my $followers = Pithub->new->users->followers;
447 my $followers = Pithub::Users->new->followers;
448 my $followers = Pithub::Users::Followers->new;
449
450 - [Pithub::Users::Keys](https://metacpan.org/pod/Pithub%3A%3AUsers%3A%3AKeys)
451
452 See also: [http://developer.github.com/v3/users/keys/](http://developer.github.com/v3/users/keys/)
453
454 my $keys = Pithub->new->users->keys;
455 my $keys = Pithub::Users->new->keys;
456 my $keys = Pithub::Users::Keys->new;
457
458# CONTRIBUTORS
459
460- Andreas Marienborg
461- Alessandro Ghedini
462- Michael G Schwern
463
464# AUTHOR
465
466Johannes Plunien <plu@cpan.org>
467
468# COPYRIGHT AND LICENSE
469
470This software is copyright (c) 2011-2019 by Johannes Plunien.
471
472This is free software; you can redistribute it and/or modify it under
473the same terms as the Perl 5 programming language system itself.
474