gh3

gh3 is a client-side Javascript API v3 wrapper for GitHub

gh3 is async.js compliant. (thank you to Atinux and mklabs)

Dependencies

Bundled with gh3 :

gh3 supports several kind of objects:

Gh3.Users
Gh3.User
Gh3.Repositories
Gh3.Repository
Gh3.Issue
Gh3.Pull
Gh3.Branch
Gh3.Dir inherits of Gh3.ItemContent
Gh3.File inherits of Gh3.ItemContent
Gh3.Commit
Gh3.Gists
Gh3.Gist
Gh3.GistComment

You can extend all Gh3 types, eg :

var myComment = Gh3.GistComment.extend({
	//...
})

See § "Extend User" for more details.

GitHub Users : Gh3.Users

Static Methods of Gh3.Users

Gh3.Users.search(keyword, pagesInfo, callback) retrieve Gh3.User instances by keyword
- pagesInfo : { start_page : which_page } (always 100 items max. per page) see http://developer.github.com/v3/search/
Gh3.Users.getAll() : return an array of all Gh3.User instances (you have to call search() before)
Gh3.Users.getByName(name) : get a user by his name (you have to call search() before) (return first found user)
Gh3.Users.each(callback) : execute callback for each found users (you have to call search() before)
Gh3.Users.reverse() : reverse order of users (you have to call fetch() before)
Gh3.Users.sort(comparator) : sort users (you have to call search() before)
Gh3.Users.filter(comparator) : return an array of Gh3.User instances filtered by comparator (you have to call search() before)

example :

Gh3.Users.search("mad", {start_page : 3}, function (err, response) {
	if(err) {
		throw "outch ..."
	}
	//console.log(Gh3.Users.getAll());
	console.log(response.getAll());
	response.each(function (user) {
		console.log(user.name, user.login, user.repos, user)
	});
});

See samples/10-users.html

GitHub User : Gh3.User

Declare User

var k33g = new Gh3.User("k33g");

Methods of Gh3.User

fetch(callback) : retrieve GitHub User's informations

Get User data

k33g.fetch(function (err, resUser){

	if(err) {
		throw "outch ..."
	}

	console.log("Blog : ", resUser.blog); // == k33g.blog
	console.log("Name : ", resUser.name);
	//etc. ...
});

See /samples/01-user.html

Extend User

I've cribbed the Backbone object model :

var GitHubUser = Gh3.User.extend({//instance members
	constructor : function(login) {
		GitHubUser.__super__.constructor.call(this, login);
		GitHubUser.allUsers.push(this);
	}
},{ //Static members
	allUsers : [],
	each : function (callback) {
		_.each(GitHubUser.allUsers, function (user) {
			callback(user);
		})
	}
});

var k33g = new GitHubUser("k33g")
,	loicdescotte = new GitHubUser("loicdescotte")
,	mklabs = new GitHubUser("mklabs")
,	chamerling = new GitHubUser("chamerling");

GitHubUser.each(function (user) {
	user.fetch(function (err, resUser) {

		if(err) {
			throw "outch ..."
		}

		console.log(JSON.stringify(resUser));
	});
})

See samples/02-user.html

GitHub Repositories of a user : Gh3.Repositories

Declare and Get Repositories of a user

var k33gRepositories = new Gh3.Repositories(k33g);
k33gRepositories.fetch(function () {
	console.log("Repositories", k33gRepositories);
}, function(){/*error*/},{page:1, per_page:500, direction : "desc"});
//all repositories, one page, 500 items per page, sort : descending

Methods of Gh3.Repositories

fetch(pagesInfoAndParameters, paginationInfo, callback) retrieve Gh3.Repository instances of a user
- pagesInfoAndParameters : { pages : number_of_pages, per_page : number_of_repositories_per page }
- you can pass other parameters as : direction : "desc", see http://developer.github.com/v3/repos/
- paginationInfo : which page. Possible values : see http://developer.github.com/v3/#pagination
  - "next"
  - "last"
  - "first"
  - "prev"
getRepositories() : return an array of Gh3.Repository instances (you have to call fetch() before)
getRepositoryByName(name) : get a repository by his name (you have to call fetch() before)
eachRepository(callback) : execute callback for each repository of the user (you have to call fetch() before)
reverseRepositories() : reverse order of repositories (you have to call fetch() before)
sortRepositories(comparator) : sort repositories (you have to call fetch() before)
filterRepositories(comparator) : return an array of Gh3.Repository instances filtered by comparator (you have to call fetchContents() before)

Static Methods

Gh3.Repositories.search(keyword, pagesInfo, callback) retrieve Gh3.Repository instances by keyword
- pagesInfo : { start_page : which_page } (always 100 items max. per page) see http://developer.github.com/v3/search/
Gh3.Repositories.getAll() : return an array of all Gh3.Repository instances (you have to call search() before)
Gh3.Repositories.getByName(name) : get a repository by his name (you have to call search() before) (return first found repository)
Gh3.Repositories.each(callback) : execute callback for each found repositories (you have to call search() before)
Gh3.Repositories.reverse() : reverse order of repositories (you have to call fetch() before)
Gh3.Repositories.sort(comparator) : sort repositories (you have to call search() before)
Gh3.Repositories.filter(comparator) : return an array of Gh3.Repository instances filtered by comparator (you have to call search() before)

See samples/03-repository.html See samples/09-repositories.html

GitHub Repository : Gh3.Repository

Declare and Get Repository informations

var k33g = new Gh3.User("k33g"); // You need a user first

var k33gBlog = new Gh3.Repository("k33g.github.com", k33g);

k33gBlog.fetch(function (err, res) {
	if(err) { throw "outch ..." }

	console.log(k33gBlog);
});

Methods of Gh3.Repository

getBranches() : return array of Gh3.Branch instances
fetch(callback) : retrieve repository's informations
fetchBranches(callback) : retrieve repository's branches (you have to call fetch() before)
getBranchByName(branch_name) : return a Gh3.Branch instance found by name (you have to call fetchBranches() before)
eachBranch(callback) : execute callback for each branch of the repository (you have to call fetchBranches() before)
reverseBranches() : reverse order of branches
sortBranches(comparator) : sort branches
fetchIssuesByLabel : receive repository issues with certain label or labels

Get Branches of Repository

After calling repository fetch() method :

k33gBlog.fetchBranches(function (err, res) {
	if(err) { throw "outch ..." }

	console.log(k33gBlog.getBranches());
})

branches is an array of Gh3.Branch instances populated when fetchBranches() is called.

You can do that too :

k33gBlog.fetchBranches(function (err, res) {
	if(err) { throw "outch ..." }

	console.log("Array of branches : ", k33gBlog.getBranches());
	k33gBlog.eachBranch(function (branch) {
		console.log(branch.name);
	})

	//and :
	console.log("Master Branch : ", k33gBlog.getBranchByName("master"));

})

See samples/03-repository.html

GitHub Branch : Gh3.Branch

Methods of Gh3.Branch

fetchContents(callback) : retrieve Gh3.File instances and/or Gh3.Dir instances of the branch
getContents() : return array of Gh3.ItemContent instances (so Gh3.File instances and/or Gh3.Dir instances)
getFileByName(file_name) : return a Gh3.File instance found by name (you have to call fetchContents() before)
getDirByName(dir_name) : return a Gh3.Dir instance found by name (you have to call fetchContents() before)
eachContent(callback) : execute callback for each content item of the branch (you have to call fetchContents() before)
reverseContents() : reverse order of contents
sortContents(comparator) : sort contents
filterContents(comparator) : return an array of Gh3.ItemContent instances filtered by comparator (you have to call fetchContents() before)

Get contents of a branch

You have to declare, get repository informations and fetch branches before calling fetchContents(callback) :

var k33g = new Gh3.User("k33g")
,	k33gBlog = new Gh3.Repository("k33g.github.com", k33g);

k33gBlog.fetch(function (err, res) {
	if(err) { throw "outch ..." }

	k33gBlog.fetchBranches(function (err, res) {
		if(err) { throw "outch ..." }

		var master = k33gBlog.getBranchByName("master");

		master.fetchContents(function (err, res) {
			if(err) { throw "outch ..." }

			master.eachContent(function (content) {
				console.log(content.path, content.type);
			});
		});

	})
});

See samples/04-branch.html

You obtain a list of files and directories. You can directly fetch raw content of a file or fetch contents of a directory.

GitHub File : Gh3.File

Methods of Gh3.File

fetchContent(callback) : retrieve (raw) content of the file
fetchCommits(callback) : retrieve commits of the file
getRawContent() : return raw content of the file (you have to call fetchContent() before)
getCommits() : return array of Gh3.Commit instances (you have to call fetchCommits() before)
getLastCommit() : return last Gh3.Commit instance
getFirstCommit() : return first Gh3.Commit instance
eachCommit(callback) : execute callback for each commit of the file (you have to call fetchCommits() before)
filterCommits(comparator) : return an array of Gh3.Commit instances filtered by comparator (you have to call fetchCommits() before)
reverseCommits() : reverse order of commits
sortCommits(comparator) : sort commits

Get raw content of a file

master.fetchContents(function (err, res) {
	if(err) { throw "outch ..." }

	var myfile = master.getFileByName("index.html");

	/* this way is possible to :
		var myfile = master.getContents()[8];
	*/

	myfile.fetchContent(function (err, res) {
		if(err) { throw "outch ..." }

		console.log(myfile.getRawContent());
	});

});

See samples/05-file.html

Get commits of a file

myfile.fetchCommits(function (err, res) {
	if(err) { throw "outch ..." }

	console.log(myfile.getCommits());

	myfile.eachCommit(function (commit) {
		console.log(commit.author.login, commit.message, commit.date);
	});
});

See samples/05-file.html

GitHub Directory : Gh3.Dir

It works much like a Gh3.Branch.

Methods of Gh3.Dir

fetchContents(callback) : retrieve Gh3.File instances and/or Gh3.Dir instances of the directory
getContents() : return array of Gh3.ItemContent instances (so Gh3.File instances and/or Gh3.Dir instances)
getFileByName(file_name) : return a Gh3.File instance found by name (you have to call fetchContents() before)
getDirByName(dir_name) : return a Gh3.Dir instance found by name (you have to call fetchContents() before)
eachContent(callback) : execute callback for each content item of the directory (you have to call fetchContents() before)
reverseContents() : reverse order of contents
sortContents(comparator) : sort contents
filterContents(comparator) : return an array of Gh3.ItemContent instances filtered by comparator (you have to call fetchContents() before)

Get contents of a directory

master.fetchContents(function (err, res) {
	if(err) { throw "outch ..." }

	var dir = master.getDirByName('_posts');

	dir.fetchContents(function (err, res) {
		if(err) { throw "outch ..." }

		console.log(dir.getContents());

		dir.eachContent(function (content) {
			console.log(content.name, content.type, content.size);

		});
	});

});

See samples/06-dir.html

GitHub Gists : Gh3.Gists

Methods of Gh3.Gists

fetch(pagesInfo, paginationInfo, callback) : retrieve Gh3.Gist instances of a user
- pagesInfo : { pages : number_of_pages, per_page : number_of_gists_per page }
- paginationInfo : which page. Possible values : see http://developer.github.com/v3/#pagination
  - "next"
  - "last"
  - "first"
  - "prev"
getGists() : return an array of Gh3.Gist instances (you have to call fetch() before)
eachGist : execute callback for each gist of the user (you have to call fetch() before)
filter(comparator) : return an array of Gh3.Gist instances filtered by comparator (you have to call fetch() before)

Get public gists of a user

	var GistsOfK33g = new Gh3.Gists(new Gh3.User("k33g"));

	GistsOfK33g.fetch(null, null, function (err, res) {
		if(err) {
			throw "outch ..."
		}

		GistsOfK33g.eachGist(function (gist) {
			console.log(gist.description, gist.id);
		});
	});

Get public gists of a user : five gists of the next page

	GistsOfK33g.fetch({page:2, per_page:5}, "next", function (err, res) {
		if(err) {
			throw "outch ..."
		}

		GistsOfK33g.eachGist(function (gist) {
			console.log(gist.description, gist.id);
		});
	};

See samples/07-gists.html

Get public gists of a user only if they have comment(s)

AllGistsOfK33g.fetch(function (err, res) {
	if(err) {
		throw "outch ..."
	}

	console.log("Filtered gists : ", AllGistsOfK33g.filter(function (gist) {
		return gist.comments > 0;
	}));

},function(){//onerror},{page:1, per_page:500});

See samples/07-gists.html

GitHub Gist : Gh3.Gist

Methods of Gh3.Gist

fetchContents(callback) : retrieve contents (files) of the gist
fetchComments(callback) : retrieve comments of the gist
getFileByName() : return a file of the gist, found by his name
getFiles() : return array of files objects
eachFile(callback) : execute callback for each file of the gist (you have to call fetchContents() before)
getComments() : return an array of Gh3.GistComment instances
eachComment(callback) : execute callback for each comment of the gist (you have to call fetchComments() before)
filterComments(comparator) : return an array of Gh3.GistComment instances filtered by comparator (you have to call fetchComments() before)

Get a public gist by id

var oneGist = new Gh3.Gist({id:"2287018"});

oneGist.fetchContents(function (err, res) {
	if(err) {
		throw "outch ..."
	}

	console.log("oneGist : ", oneGist);
	console.log("Files : ", oneGist.files);

	oneGist.eachFile(function (file) {
		console.log(file.filename, file.language, file.type, file.size);
	});
});

Get content of a file of a gist

	console.log(oneGist.getFileByName("use.thing.js").content);

See samples/07-gists.html

Get comments of a public gist

	var anOtherGist = new Gh3.Gist({id:"1096826"});

	anOtherGist.fetchContents(function (err, res) {
		if(err) { throw "outch ..." }

		anOtherGist.fetchComments(function (err, res) {
			if(err) { throw "outch ..." }

			anOtherGist.eachComment(function (comment) {
				console.log(comment.body, "By ", comment.user.login);
			});
		});
	});

See samples/07-gists.html

Filter comments of a public gist

	var PaulIrishGist = new Gh3.Gist({id:"3098860"});

	PaulIrishGist.fetchContents(function (err, res) {
		if(err) { throw "outch ..." }

		PaulIrishGist.fetchComments(function (err, res) {
			if(err) { throw "outch ..." }

			console.log(
				PaulIrishGist.filterComments(function (comment) {
					return comment.user.login == "codepo8";
				})
			);
		});

	});

See samples/08-gists_comments.html

... to be continued

History

2012.07.25 : '0.0.1' : first version
2012.07.26 : '0.0.2' : fixes
2012.07.26 : '0.0.3' : gists pagination
2012.07.28 : '0.0.4' :
- refactoring : Gh3.Helper
- gists filtering
- gist comments filtering
- file commits filtering
- commits sorting
- new Type : Gh3.Repositories (with pagination)
2012.07.29 : '0.0.5' :
- Gh3.Repositories : add search ability
- add Gh3.Users : search user ability
2012.07.29 : '0.0.6' :
- async.js compliant
2014.04.20 : '1.0.0' : bower package + semantic versioning
2014.04.20 : '1.0.1' : temporary fixes

License

Gh3 is available under the terms of the MIT-License.

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
samples		samples
tests		tests
vendors		vendors
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
bower.json		bower.json
gh3.js		gh3.js
gh3.min.js		gh3.min.js

k33g/gh3

Folders and files

Latest commit

History

Repository files navigation

gh3

Dependencies

Bundled with gh3 :

GitHub Users : Gh3.Users

Static Methods of Gh3.Users

example :

GitHub User : Gh3.User

Declare User

Methods of Gh3.User

Get User data

Extend User

GitHub Repositories of a user : Gh3.Repositories

Declare and Get Repositories of a user

Methods of Gh3.Repositories

Static Methods

GitHub Repository : Gh3.Repository

Declare and Get Repository informations

Methods of Gh3.Repository

Get Branches of Repository

GitHub Branch : Gh3.Branch

Methods of Gh3.Branch

Get contents of a branch

GitHub File : Gh3.File

Methods of Gh3.File

Get raw content of a file

Get commits of a file

GitHub Directory : Gh3.Dir

Methods of Gh3.Dir

Get contents of a directory

GitHub Gists : Gh3.Gists

Methods of Gh3.Gists

Get public gists of a user

Get public gists of a user : five gists of the next page

Get public gists of a user only if they have comment(s)

GitHub Gist : Gh3.Gist

Methods of Gh3.Gist

Get a public gist by id

Get content of a file of a gist

Get comments of a public gist

Filter comments of a public gist

History

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 12

Uh oh!

Languages

Packages