pageme 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pageme.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 David R. MacIver
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# 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
+
+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.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/pageme/version.rb

@@ -0,0 +1,3 @@
+module Pageme
+  VERSION = "0.0.1"
+end

data/lib/pageme.rb

@@ -0,0 +1,133 @@
+require "#{File.dirname __FILE__}/pageme/version"
+require "rubygems"
+
+module PageMe
+  if RUBY_VERSION < "1.9" || defined?(JRUBY_VERSION)
+    require "posix/spawn"
+    include POSIX::Spawn
+  end
+
+  def self.use_domain_socket_for_paging=(f)
+    if f
+      require "tempfile"
+      require "socket"
+    end
+    @use_domain_socket_for_paging = f
+  end
+
+  def self.use_domain_socket_for_paging?
+    @use_domain_socket_for_paging
+  end
+
+  self.use_domain_socket_for_paging = (defined? JRUBY_VERSION)
+
+  attr_writer :pager, :paging_disabled
+
+  def paging_disabled?
+    return @paging_disabled if defined? paging_disabled
+
+    !(STDOUT.tty?)
+  end
+
+  def disable_paging
+    self.paging_disabled = true
+  end
+
+  def enable_paging
+    self.paging_disabled = false
+  end
+
+  def pager
+    @pager || ENV["PAGER"] || "less"
+  end
+
+  def page *args, &p
+    args << p
+    args.compact!
+
+    if paging_disabled?
+      page_to STDOUT, args
+      return
+    end
+
+    t, w, server = nil
+
+    if defined? JRUBY_VERSION
+      loop do
+        begin
+          t = File.join(Dir::tmpdir, "socket-for-jruby-pager-#{rand(2**16)}")
+          server = UNIXServer.new(t)
+          break
+        rescue Errno::EADDRINUSE
+        end
+      end
+
+
+      child_pid = spawn "netcat -U #{t} | #{pager}"
+
+      w = server.accept
+    else
+      r, w = IO.pipe
+      child_pid = spawn pager, :in => r, w => :close
+      r.close
+    end
+
+    Kernel.trap("SIGINT"){ Process.kill "INT", child_pid }
+
+    begin
+      page_to w, args
+    rescue Errno::EPIPE
+    rescue Exception => e
+      unless w.closed?
+        w.puts "#{e.class}: #{e.message}"
+        e.backtrace.each{|l| w.puts "\t#{l}" }
+      end 
+      raise 
+    ensure
+      w.close
+      Process.wait child_pid
+      Kernel.trap("SIGINT", "DEFAULT")
+      File.delete(t) if t
+      server.close if server
+    end
+    nil
+  end 
+
+  def page_file file
+    raise Errno::ENOENT, file unless File.exist? file
+
+    system pager, file
+    nil
+  end
+
+  def with_paged_output
+    page do |o|
+      original_stdout = STDOUT.dup
+      original_stderr = STDERR.dup
+      begin
+        STDERR.reopen(o)
+        STDOUT.reopen(o)
+        yield
+      ensure
+        STDERR.reopen(original_stderr)
+        STDOUT.reopen(original_stdout)
+      end 
+    end
+  end
+
+  private
+
+  def page_to w, a
+    if a.kind_of? IO
+      a.each{|d| w.write d }
+    elsif a.kind_of? Proc
+      a.call(w)
+    elsif a.kind_of? String
+      w.write a
+    elsif a.kind_of? Enumerable
+      a.each{|e| page_to w, e; w.puts }
+    else
+      w.write a.to_s
+    end
+  end
+end

data/pageme.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/pageme/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["David R. MacIver"]
+  gem.email         = ["david@drmaciver.com"]
+  gem.description   = %q{Methods for invoking a pager}
+  gem.summary       = %q{Trivial gem for invoking a pager for your program data}
+  gem.homepage      = "https://github.com/DRMacIver/pageme"
+
+  gem.add_dependency 'posix-spawn', '>= 0.3.6'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "pageme"
+  gem.require_paths = ["lib"]
+  gem.version       = Pageme::VERSION
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: pageme
+version: !ruby/object:Gem::Version
+  prerelease:
+  version: 0.0.1
+platform: ruby
+authors:
+- David R. MacIver
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2012-04-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: posix-spawn
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.3.6
+    none: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.3.6
+    none: false
+  prerelease: false
+  type: :runtime
+description: Methods for invoking a pager
+email:
+- david@drmaciver.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- !binary |-
+  LmdpdGlnbm9yZQ==
+- !binary |-
+  R2VtZmlsZQ==
+- !binary |-
+  TElDRU5TRQ==
+- !binary |-
+  UkVBRE1FLm1k
+- !binary |-
+  UmFrZWZpbGU=
+- !binary |-
+  bGliL3BhZ2VtZS5yYg==
+- !binary |-
+  bGliL3BhZ2VtZS92ZXJzaW9uLnJi
+- !binary |-
+  cGFnZW1lLmdlbXNwZWM=
+homepage: https://github.com/DRMacIver/pageme
+licenses: []
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: !binary |-
+        MA==
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: !binary |-
+        MA==
+  none: false
+requirements: []
+rubyforge_project:
+rubygems_version: 1.8.24
+signing_key:
+specification_version: 3
+summary: Trivial gem for invoking a pager for your program data
+test_files: []
+...