upoj-rb 0.0.0 → 0.0.1

data/Gemfile

@@ -3,6 +3,8 @@ source "http://rubygems.org"
 # Example:
 #   gem "activesupport", ">= 2.3.5"
 
+gem 'paint'
+
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do

data/Gemfile.lock

@@ -8,6 +8,7 @@ GEM
       bundler (~> 1.0)
       git (>= 1.2.5)
       rake
+    paint (0.8.3)
     rake (0.9.2)
     rdoc (3.9.4)
     rspec (2.6.0)
@@ -27,6 +28,7 @@ DEPENDENCIES
   bundler (~> 1.0.0)
   gemcutter
   jeweler (~> 1.6.4)
+  paint
   rdoc
   rspec
   shoulda

data/Rakefile

@@ -25,7 +25,6 @@ Jeweler::Tasks.new do |gem|
 end
 Jeweler::RubygemsDotOrgTasks.new
 
-
 require 'rspec/core/rake_task'
 desc "Run specs"
 RSpec::Core::RakeTask.new do |t|

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.0.1

data/lib/upoj-rb.rb

@@ -2,4 +2,4 @@ module Upoj
   
 end
 
-%w( ext opts ).each{ |dep| require File.join(File.dirname(__FILE__), 'upoj-rb', dep) }
+%w( ext opts signals ).each{ |dep| require File.join(File.dirname(__FILE__), 'upoj-rb', dep) }

data/lib/upoj-rb/opts.rb

@@ -1,12 +1,98 @@
 require 'optparse'
+require 'paint'
 
 module Upoj
 
   class Opts < OptionParser
     attr_accessor :funnel
 
-    def on_funnel name, *args
-      super(*args){ |val| (@funnel ||= Hash.new)[name] = val }
+    def self.section_title title
+      Paint[title, :bold]
+    end
+
+    def self.section_title_ref ref
+      Paint[ref, :underline]
+    end
+
+    def initialize *args
+      options = args.extract_options!
+
+      @funnel = options[:funnel] || {}
+      @footer = options[:footer]
+      @examples = options[:examples]
+
+      width = options[:width] || 32
+      indent = options[:indent] || (' ' * 2)
+      super nil, width, indent
+
+      @banner = options[:banner].kind_of?(Hash) ? summary_banner_section(options[:banner]) : options[:banner]
+    end
+
+    def on *args
+      if block_given?
+        super(*args)
+      else
+        sw = make_switch(args)[0]
+        name = sw.long.first.sub /^\-+/, ''
+        block = lambda{ |val| @funnel[name] = val }
+        super(*args, &block)
+      end
+    end
+
+    def summary_banner_section *args
+      options = args.extract_options!
+      %|#{summary_program_name} #{options[:description]}
+
+#{self.class.section_title :USAGE}
+#{@summary_indent}#{summary_program_name} #{options[:usage]}
+
+#{self.class.section_title :OPTIONS}
+|
+    end
+
+    def summary_examples_section
+      return nil unless @examples
+      String.new("\n#{self.class.section_title :EXAMPLES}").tap do |s|
+        @examples.each do |example|
+          s << "\n#{@summary_indent}#{summary_program_name} #{example}"
+        end
+      end
+    end
+
+    def program_name
+      @program_name || File.basename($0)
+    end
+
+    def summary_program_name
+      Paint[program_name, :bold]
+    end
+
+    def parse_or_exit!
+      begin
+        parse!
+      rescue Exception => err
+        unless err.kind_of?(SystemExit)
+          puts
+          Kernel.warn Paint["Error: #{err.message}", :yellow]
+          puts
+          puts self
+          exit 2
+        else
+          exit err.status
+        end
+      end
+    end
+
+    def to_s
+      "#{super}#{summary_examples_section}#{@footer}"
+    end
+
+    def help!
+      self.on('-h', '--help', 'show this help and exit'){ puts self; exit 0 }
+    end
+
+    def usage!
+      self.on('-u', '--usage', 'show this help and exit'){ puts self; exit 0 }
     end
   end
 end

data/lib/upoj-rb/signals.rb

@@ -0,0 +1,121 @@
+module Upoj
+
+  # Register of blocks of code to execute when the script receives a particular signal.
+  module Signals
+
+    # Traps script signals. Blocks registered with Signals.on will be
+    # executed when the script receives the corresponding status.
+    #
+    # Blocks previously trapped without using this class will be replaced.
+    #
+    # Returns true if any signals were trapped.
+    def self.trap
+      @@trapped.each_key{ |signal| Signal.trap(signal){ self.run signal } }
+      @@trapped.any?
+    end
+
+    # Clears all blocks registered for the given signal.
+    # Use nil to clear all blocks for all signals.
+    #
+    # No error will be raised if the signal is unknown.
+    def self.clear signal = nil
+      signal ? @@trapped[signal_number(signal, false)].try(:clear) : @@trapped.clear; nil
+    end
+
+    # Registers a block to be executed when the script
+    # receives a given signal. This method can be called several
+    # times; all registered blocks will be called in the order they
+    # were registered when the signal is received. If the signal
+    # is not known, ArgumentError is raised (see #known?).
+    #
+    # Signals.trap must be called after registering the blocks
+    # for them to be activated.
+    #
+    # ==== Arguments
+    # * <tt>signal</tt> - The signal to trap.
+    # * <tt>&block</tt> - The block to execute when the signal is trapped.
+    #
+    # ==== Examples
+    #   Upoj::CLI::Signals.on(:exit){ cleanup_temporary_files }
+    #   Upoj::CLI::Signals.on("TERM"){ close_connections }
+    #   Upoj::CLI::Signals.on(2) do
+    #     puts usage
+    #   end
+    def self.on signal, &block
+      (@@trapped[signal_number(signal)] ||= []) << block; block
+    end
+
+    # Blocks registered with this method will be executed if the
+    # script exits with any of the following statuses: <tt>QUIT,
+    # TERM, KILL, INT</tt> (2, 3, 9, 15).
+    #
+    # Signals.trap must be called after registering the blocks
+    # for them to be activated.
+    #
+    # ==== Arguments
+    # * <tt>&block</tt> - The block to execute when the script
+    #   fails.
+    #
+    # ==== Examples
+    #   Upoj::CLI::Signals.on_failure{ close_connections }
+    def self.on_failure &block
+      FAILURE_STATUSES.each{ |status| self.on status, &block }; block
+    end
+
+    # Blocks registered with this method will be executed if the
+    # script exits successfully with status <tt>EXIT</tt> (0).
+    #
+    # Signals.trap must be called after registering the blocks
+    # for them to be activated.
+    #
+    # ==== Arguments
+    # * <tt>&block</tt> - The block to execute when the script
+    #   exits successfully.
+    #
+    # ==== Examples
+    #   Upoj::CLI::Signals.on_success{ FileUtils.rm_fr tmp }
+    def self.on_success &block
+      SUCCESS_STATUSES.each{ |status| self.on status, &block }; block
+    end
+
+    # Indicates whether the given signal is valid, i.e. whether
+    # it is either a number or one of the text signals returned
+    # by Signal#list.
+    def self.known? signal
+      !!signal_number(signal, false)
+    end
+
+    private
+
+    # Returns the map of signal names and their numerical value
+    # returned by Signal#list.
+    def self.signals
+      @@signals ||= Signal.list
+    end
+
+    # Returns the numerical value of the given signal.
+    # Statuses in Signal#list can be given as text.
+    def self.signal_number signal, raise_if_unknown = true
+      (signal.kind_of?(Fixnum) ? signal : signals[signal.to_s.upcase]).tap do |n|
+        raise ArgumentError, "Unknown signal '#{signal}'. Signal must either be a number or one of the text signals returned by Signal.list." if raise_if_unknown && !n
+      end
+    end
+
+    # Runs all the blocks registered for the given signal.
+    def self.run signal
+      @@trapped[signal].try(:each){ |block| block.try :call, signal }
+    end
+
+    # List of exit statuses considered a termination.
+    # 2 = INT, 3 = QUIT, 9 = KILL, 15 = TERM
+    FAILURE_STATUSES = [ 2, 3, 9, 15 ]
+
+    # List of exit statuses considered successful.
+    # 0 = EXIT
+    SUCCESS_STATUSES = [ 0 ]
+
+    # Map of numerical exit statuses and the corresponding list of
+    # blocks to execute.
+    @@trapped = {}
+  end
+end

data/spec/signals_spec.rb

@@ -0,0 +1,152 @@
+require 'helper'
+
+describe Upoj::Signals do
+  before :each do
+    Upoj::Signals.clear
+  end
+
+  describe "#trap" do
+    it "should return false if no blocks are registered" do
+      Upoj::Signals.trap.should == false
+    end
+
+    it "should return true if any block is registered" do
+      Upoj::Signals.on(0){}
+      Upoj::Signals.trap.should == true
+    end
+  end
+
+  describe "#on" do
+    it "should register all given blocks in order" do
+      result = String.new
+      Upoj::Signals.on(0){ result << 'a' }
+      Upoj::Signals.on(0){ result << 'b' }
+      Upoj::Signals.on(0){ result << 'c' }
+      Upoj::Signals.send :run, 0
+      result.should == 'abc'
+    end
+
+    it "should register all given blocks for known signals" do
+      result = String.new
+      Upoj::Signals.on(1){ result << 'a' }
+      Upoj::Signals.on(2){ result << 'b' }
+      Upoj::Signals.on(3){ result << 'c' }
+      Upoj::Signals.send :run, 1
+      Upoj::Signals.send :run, 2
+      Upoj::Signals.send :run, 3
+      result.should == 'abc'
+    end
+
+    it "should not execute blocks whose signal was not trapped" do
+      result = String.new
+      Upoj::Signals.on(1){ result << 'abc' }
+      Upoj::Signals.on(2){ result << 'def' }
+      Upoj::Signals.send :run, 1
+      result.should == 'abc'
+    end
+
+    it "should raise an ArgumentError for unknown signals" do
+      [ nil, false, true, Object.new, :random, 'foo', 'BAR' ].each do |sig|
+        lambda{ Upoj::Signals.on(sig){} }.should raise_error(ArgumentError)
+      end
+    end
+  end
+
+  describe "#on_success" do
+    it "should execute registered blocks on successful exit" do
+      result = String.new
+      Upoj::Signals.on_success{ result << 'abc' }
+      Upoj::Signals.send :run, 0
+      result.should == 'abc'
+    end
+
+    it "should not execute registered blocks on failure" do
+      result = String.new
+      Upoj::Signals.on_success{ result << 'abc' }
+      (1..255).each do |sig|
+        Upoj::Signals.send :run, sig
+      end
+      result.should be_empty
+    end
+  end
+
+  describe "#on_failure" do
+    it "should execute registered blocks on failure" do
+      result = String.new
+      Upoj::Signals.on_failure{ result << 'a' }
+      [ 2, 3, 9, 15 ].each do |sig|
+        Upoj::Signals.send :run, sig
+      end
+      result.should == 'aaaa'
+    end
+
+    it "should not execute registered blocks on successful exit" do
+      result = String.new
+      Upoj::Signals.on_failure{ result << 'abc' }
+      Upoj::Signals.send :run, 0
+      result.should be_empty
+    end
+  end
+
+  describe "#known?" do
+    it "should return true for every known signal name" do
+      Signal.list.keys.each do |name|
+        Upoj::Signals.known?(name).should == true
+      end
+    end
+
+    it "should return true for numbers between 0 and 255" do
+      (0..255).each do |n|
+        Upoj::Signals.known?(n).should == true
+      end
+    end
+
+    it "should return false for unknown signal names" do
+      [ nil, false, true, Object.new, :random, 'foo', 'BAR' ].each do |unknown|
+        Upoj::Signals.known?(unknown).should == false
+      end
+    end
+  end
+
+  describe "#clear" do
+    it "should clear blocks for a given signal" do
+      result = String.new
+      Upoj::Signals.on(0){ result << 'abc' }
+      Upoj::Signals.clear 0
+      Upoj::Signals.send :run, 0
+      result.should be_empty
+    end
+
+    it "should only clear blocks for the given signal" do
+      result = String.new
+      Upoj::Signals.on(1){ result << 'a' }
+      Upoj::Signals.on(2){ result << 'b' }
+      Upoj::Signals.on(3){ result << 'c' }
+      Upoj::Signals.clear 2
+      Upoj::Signals.send :run, 1
+      Upoj::Signals.send :run, 2
+      Upoj::Signals.send :run, 3
+      result.should == 'ac'
+    end
+
+    it "should clear all blocks when no signal is given" do
+      result = String.new
+      Upoj::Signals.on(0){ result << 'a' }
+      Upoj::Signals.on(1){ result << 'b' }
+      Upoj::Signals.on(2){ result << 'c' }
+      Upoj::Signals.on(3){ result << 'd' }
+      Upoj::Signals.clear
+      Upoj::Signals.send :run, 0
+      Upoj::Signals.send :run, 1
+      Upoj::Signals.send :run, 2
+      Upoj::Signals.send :run, 3
+      result.should be_empty
+    end
+
+    it "should not raise an error for unknown signals" do
+      [ nil, false, true, Object.new, :random, 'foo', 'BAR' ].each do |sig|
+        lambda{ Upoj::Signals.clear(sig){} }.should_not raise_error(ArgumentError)
+      end
+    end
+  end
+end

data/upoj-rb.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "upoj-rb"
-  s.version = "0.0.0"
+  s.version = "0.0.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["AlphaHydrae"]
-  s.date = "2011-09-30"
+  s.date = "2011-10-01"
   s.description = "This contains common ruby extensions mostly taken from Rails, as well as various command-line utilities."
   s.email = "hydrae.alpha@gmail.com"
   s.extra_rdoc_files = [
@@ -29,9 +29,11 @@ Gem::Specification.new do |s|
     "lib/upoj-rb.rb",
     "lib/upoj-rb/ext.rb",
     "lib/upoj-rb/opts.rb",
+    "lib/upoj-rb/signals.rb",
     "spec/blank_spec.rb",
     "spec/ext_spec.rb",
     "spec/helper.rb",
+    "spec/signals_spec.rb",
     "upoj-rb.gemspec"
   ]
   s.homepage = "http://github.com/AlphaHydrae/upoj-rb"
@@ -44,6 +46,7 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<paint>, [">= 0"])
       s.add_development_dependency(%q<rspec>, [">= 0"])
       s.add_development_dependency(%q<shoulda>, [">= 0"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
@@ -51,6 +54,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<gemcutter>, [">= 0"])
       s.add_development_dependency(%q<rdoc>, [">= 0"])
     else
+      s.add_dependency(%q<paint>, [">= 0"])
       s.add_dependency(%q<rspec>, [">= 0"])
       s.add_dependency(%q<shoulda>, [">= 0"])
       s.add_dependency(%q<bundler>, ["~> 1.0.0"])
@@ -59,6 +63,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<rdoc>, [">= 0"])
     end
   else
+    s.add_dependency(%q<paint>, [">= 0"])
     s.add_dependency(%q<rspec>, [">= 0"])
     s.add_dependency(%q<shoulda>, [">= 0"])
     s.add_dependency(%q<bundler>, ["~> 1.0.0"])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: upoj-rb
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-30 00:00:00.000000000Z
+date: 2011-10-01 00:00:00.000000000Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: paint
+  requirement: &2156246260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2156246260
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2154063700 !ruby/object:Gem::Requirement
+  requirement: &2156244680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2154063700
+  version_requirements: *2156244680
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &2156225260 !ruby/object:Gem::Requirement
+  requirement: &2156243180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156225260
+  version_requirements: *2156243180
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2156838500 !ruby/object:Gem::Requirement
+  requirement: &2156242180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +54,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2156838500
+  version_requirements: *2156242180
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2156866340 !ruby/object:Gem::Requirement
+  requirement: &2156241300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +65,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *2156866340
+  version_requirements: *2156241300
 - !ruby/object:Gem::Dependency
   name: gemcutter
-  requirement: &2156867780 !ruby/object:Gem::Requirement
+  requirement: &2156239520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156867780
+  version_requirements: *2156239520
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &2156869220 !ruby/object:Gem::Requirement
+  requirement: &2156238460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,7 +87,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156869220
+  version_requirements: *2156238460
 description: This contains common ruby extensions mostly taken from Rails, as well
   as various command-line utilities.
 email: hydrae.alpha@gmail.com
@@ -98,9 +109,11 @@ files:
 - lib/upoj-rb.rb
 - lib/upoj-rb/ext.rb
 - lib/upoj-rb/opts.rb
+- lib/upoj-rb/signals.rb
 - spec/blank_spec.rb
 - spec/ext_spec.rb
 - spec/helper.rb
+- spec/signals_spec.rb
 - upoj-rb.gemspec
 homepage: http://github.com/AlphaHydrae/upoj-rb
 licenses:
@@ -117,7 +130,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1617318451971428399
+      hash: 2937755540580952162
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: