We wrote hnwatch primarily for our own use, but surely we can't be the only ones who spend most of their lives in terminal windows. hnwatch is a real-time Hacker News API watcher/reader for Linux x86_64, written entirely in assembly language (as we do). Knowing that the only people who will appreciate this particular showcase piece are other HN members, we will save going through lengthy explanations and cut straight to the chase.

You'll need an x86_64 Linux environment and the terminal program of your choice. As with everything we release, this too is GPLv3 and full source code is available. If you don't bother reading the rest of this page, do note that there are some "oddities" with the Hacker News API, but that it works well once you know what to expect.

Contents

• Download and Source
• Screenshots
• Known Issues
• Usage Instructions
• Status Bar Counters

Download

A standalone executable binary of hnwatch can be downloaded from our Products page. Please note that youi will have to chmod +x it after download. Alternatively, as with all our products, hnwatch is bundled in binary form and source code in the HeavyThing library itself. The download link for the library is located in the upper right of every page on this site.

Source code as mentioned is included in the library, but also viewable as HTML:

• hnwatch/hnwatch.asm
  63 lines
• hnwatch/eventstream.inc
  458 lines
• hnwatch/hnmodel.inc
  703 lines
• hnwatch/textify.inc
  221 lines
• hnwatch/ui.inc
  1,715 lines

ScreenShots

Hacker News Top Stories (the initial view when hnwatch starts):

Hacker News "Item View" (the view when you click on a story/job/ask/show):

Known Issues

With very poor internet connectivity, there is a possibility that hnwatch may segfault due to an unpleasant retry-timer issue. Recreating said net conditions is nontrivial, and we are happy with how it works overall so unless there is a strong demand for 100% bug-free, we are not too worried about it. Please let us know if you encounter any issues that we didn't catch.

Usage Instructions

There really isn't much to it, but 80x25 is TOO SMALL! To start it:

$ ./hnwatch

On startup, our "signature" TUI splash page runs, you can cancel it by pressing any key. Your internet connectivity directly affects the time delay until stories start to appear on the primary view page (though a few seconds usually does the trick). Once items start populating, cursor up and down to move through the stories, and ENTER to select one.

On the item screen, ESC, left-arrow, or any of the primary navigation keys (shown in the lower right of the status bar) can be used to return to the primary listing screen, and Up and Down arrow will scroll through the comments. Note that at least with Mac OS X Terminal.app, anywhere URLs appear (as with all terminal windows) cmd-click works to open them with your default browser.

NOTE: On slow internet (like ours), a story with a decent number of comments on it load in nesting-level order, such that all outer comments load first, then the next, and so on. These will update the view in real-time as they arrive. Also note that because the item viewer is realtime, when comments are voted up or down, they will do so in the view (we can attest that for "hot" stories where a lot of activity occurs, this can make actually reading the comments in a sensible way quite difficult, YMMV :-)

Status Bar Counters

The status bar contains four counters, and an "uptime" on the far right. The counters are:

1. I: Number of Items currently in memory
2. R: Number of Retrieval requests performed
3. B: Bytes of Item JSON received
4. E: Number of Errors (see below)

The error count is one of the "oddities" discovered when this was built. Since we make use of the EventSource/Server-Sent Events API, when the SSE stream sends us item IDs to retrieve, we do so then and there. For reasons wholly unknown however, we get a fair number of 401 Permission Denied when we request IDs that were just handed to us. The current hnwatch configuration waits 30 secodns and tries again, and this seems to remedy most of them, but on occasion some still do occur (maybe this delay needs to be longer?)