PageMe

PageMe is a trivial rubygem for invoking a pager on application data.

It even works under JRuby. The implementation for the JRuby support is an awful hack (it relies on netcat + unix domain sockets) and I've only tested it under linux, but it appears to be fully functional.

Usage

Include PageMe for use:

include PageMe

Paging a string:

page "some long string\nwhich spans many lines"

Paging an enumerable will page each element to its own line:

page (1..10000)

You can page multiple things at once

page "these", "strings", "will", "each", "go", "on", "their", "own", "line"

You can also page to a block

page do |o|
  10000.times do |i|
    o.puts i
  end
end

You can combine the different formats, which will page the arguments then the block

page "this is the first string" do |o|
  10000.times do |i|
    o.puts i
  end
end

It's ok for the blocks to throw exceptions

page{ raise "Denied!" }

Their results will be printed to the pager.

If you're passing multiple arguments and one of them raises an error then no further data will be paged

page lambda{raise "Denied!"}, "this line will never be printed"

If you want to page the results of the block first you can pass it as an argument

page "This line is printed first", lambda{ |o| 10.times{|i| o.puts i } }, "I just printed a bunch of lines"

You can page to a file either by passing its file name to page_file

page_file "path/to/some/file"

or by passing an IO object

page File.open("path/to/some/file")

but the above example is bad because it won't close the file handle.

You can configure the pager being invoked:

self.pager = "more"
page %w{I hate fun}

You can also just disable paging if you want to print to STDOUT:

self.disable_paging
page %w{this will go to STDOUT as if it were the pager}

This is the default if STDOUT is not a tty.

You can of course enable it again:

self.enable_paging
page %w{this will go to a pager as normal}

Known bugs

The JRuby support is a little flaky:

Closing the pager does not work correctly in some versions of JRuby due to a bug in the Unix domain socket implementation. I've yet to pin down exactly where it's fixed (it might not be fixed in any released versions. It works in head and doesn't work in 1.6.2), but you may see that page continues to block after the pager closes. This is due to JRuby not raising an error when writing to a broken socket and there's not much I can do about it. Sorry.
If the JVM has a melt down and dies without running the ensure block (e.g. because it gets SIGKILLed) your terminal can end up in a messed up state. Typing "stty echo" should fix this
Similarly a JVM meltdown will sometimes leave the unix domain sockets used for communicating lying around

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request