An API over Hacker News

http://stillmaintained.com/bolthar/ruby-hackernews.png

== Requirements

    mechanize (>= 1.0.0)
    require_all (>= 1.1.0)

== Installation

    gem install ruby-hackernews

then, in your script:

    require 'ruby-hackernews'

before using it. If you want to include the namespace (RubyHackernews), add

    include RubyHackernews

otherwise, you'll have to access the gem's classes adding the module, like this:

    RubyHackernews::Entry.all

== Entries

You can get entries on the main page with:

    Entry.all       # returns the main page's entries as an array

You can provide a number of pages:

    Entry.all(3)    # will return the entries on the first 3 pages

There are methods for getting specific entry types:

    Entry.questions # gets the first page of questions (ask HN)
    Entry.newest    # gets the first page of new links (new)
    Entry.jobs      # gets the first page of job offerts (jobs)
    Entry.shows     # gets the first page of shows (show HN)
    Entry.new_shows # gets the first page of new shows (show HN new)

You can also get a single entry by its ID:

    Entry.find(3102321) # gets that specific entry (warning: number will be 0!)

Each Entry instance has the following data:

    entry = Entry.all.first # gets the top entry on the mainpage

    entry.number       # the entry's position on HN

    entry.link.title   # the link's name on HN
    entry.link.href    # the actual link
    entry.link.site    # the referring site, if any

    entry.voting.score # the entry's score on HN

    entry.user.name    # the submitter's user name

    entry.time         # the elapsed time from submission

    entry.text         # the text of the submission (ask/jobs only)
                       # NOTE: it will fetch the inner page 

After you've logged in (see below) you can do the following

    entry.upvote                                # votes the entry
    entry.write_comment("mycomment")            # adds a comment to the entry
    Entry.submit("mytitle", "myurl")            # submit a new link
    Entry.submit("myquestion", "question text") # submit a new question 

    user.submissions.first.comments_url         # returns the url to the current user's comments

== Comments

You get an entry's comments with:

    entry.comments

You can also get a specific comment by id with:

    Comment.find("1234") # returns the comments with id 1234,
                         # and its subcomments.

Note that the method above will send a request to HN. If you just need the comments' count or url, you can instead use:

    entry.comments_count
    
and
  
    entry.comments_url

Either of which will not issue a request to HN's site. 

You can also get the newest comments on HN with:

    Comments.newest
    Comments.newest(3)  # gets the first 3 pages of new comments

Each Comment instance has the following data:

    comment = Entry.all.first.comments.first # gets the first comment of the first entry on HN's main page

    comment.id             # comment's unique identifier
    comment.text           # comment's body
    comment.user.name      # poster's user name on HN
    comment.voting.score   # comment's score

Comments are enumerable and threaded, so you can do like:

    comment[2][0]          # gets the third reply to this comment, then the first reply to the reply
    comment.first          # gets the first reply to this comment
    comment.select do |c|  # gets all the comment replies which text contains "test"
      text ~= /test/
    end
    comment.parent         # gets the comment's parent (nil if no parent)

Once you're logged in (see below), you can do the following:

    comment.upvote
    comment.downvote
    comment.reply("mycomment")

== Logging in

You define a user with:

    user = User.new("username")

Then, you log in with:

    user.login("password")

Or, you can create a new use with that name:

    user.signup("password") # don't abuse this!

You will be also logged in with the new user. So, no need to call user#login after user#signup.

You can log out with:

    user.logout

You have to log out before logging in with a different user.

You can also get the current users submission list by doing this:

    user.submissions
    
This will return a new Entry instance. For example:

    user.submissions.first.comment_url
    
Will return the HN comment url of the last submitted story of that user

== TO DO

    Get user info (comments, saved)
    Change user info/settings

== THANKS TO

- Anton Katunin ( https://github.com/antulik ) for adding the gemfile and putting all specs into modules
- Mike Kelly ( https://github.com/mikekelly ) for fixing a bug in TimeInfo.time
- Marc Köhlbrugge ( http://github.com/marckohlbrugge ) fox fixing and formatting the documentation
- Peter Cooper ( http://github.com/peterc ) for bug reports
- Peter Boctor ( http://github.com/boctor ) for fixing a bug about authentication
- Josh Ellington ( http://github.com/joshellington ) for reporting a bug about job entries
- Wayne ( http://github.com/BlissOfBeing ) for adding User.submissions, Entry.comments_url and cleaning up the Rakefile
- Daniel Da Cunha ( http://github.com/ddacunha ) for a fix on Entry#comments_count
- Nathan Campos ( http://github.com/nathanpc) for adding #text to Entry
- Girish Sonawane ( https://github.com/girishso) for adding Entry#shows and Entry#new_shows methods
- Niels Van Aken ( https://github.com/nvaken ) for a bugfix in EntryPageParser
- Pedro Lambert ( https://github.com/p-lambert ) for fixing bugs and improving structure of CommentInfoParser, TimeInfoParser and UserInfoParser
- FreedomBen ( https://github.com/FreedomBen ) for fixing a typo in the readme
- Davide Santangelo ( https://github.com/davidesantangelo ) for reporting a bug related to jobs and show HN entries