upoj-rb 0.0.4 → 0.0.5

data/README.md

@@ -0,0 +1,164 @@
+# upoj-rb
+
+This gem is a collection of ruby dependencies which I have found useful
+for scripting, as well as a few additions to existing classes such as
+OptionParser.
+
+## Using
+
+You can install upoj-rb on the command line:
+
+    gem install upoj-rb
+
+Or add it to your project's Gemfile:
+
+    gem 'upoj-rb'
+
+Then require and use it:
+
+    require 'upoj-rb'
+    puts Upoj::VERSION
+
+## Improved Option Parser
+
+Customized version of ruby's [OptionParser](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/classes/OptionParser.html).
+
+### Funnel
+
+By default, all options that are defined without a block can
+be retrieved with `#funnel`.
+
+    # define your options
+    opts = Upoj::Opts.new
+    opts.on('--option'){ # do whatever }
+    opts.on('-f', '--fubar')
+    opts.on('-v', '--value VALUE')
+
+    # parse
+    ARGV          #=> [ '--option', '-f', '--value', '43' ]
+    opts.parse!
+
+    # retrieve options in funnel by default
+    opts.funnel   #=> { 'fubar' => true, 'value' => 43 }
+
+The funnel can be given at construction with initial values.
+
+    # starting funnel
+    funnel = { 'foo' => false }
+
+    # define your options
+    opts = Upoj::Opts.new
+    opts.on('-f', '--fubar')
+
+    # parse
+    ARGV          #=> [ '--fubar' ]
+    opts.parse!
+
+    # retrieve the funnel with initial and new options
+    opts.funnel   #=> { 'foo' => false, '--fubar' => true }
+
+### Structured Banner
+
+A hash can be given for the banner.
+
+    banner = {
+      :usage => '[OPTION]... ARG1 ARG2',
+      :description => 'does stuff with ARG1 and ARG2.'
+    }
+
+    opts = Upoj::Opts.new :banner => banner
+    opts.on('-f', '--fubar', 'do something awful')
+    
+    # the generated banner will look like this,
+    # with USAGE, OPTIONS and my_script in bold
+
+    my_script does stuff with ARG1 and ARG2.
+
+    USAGE
+      my_script [OPTION]... ARG1 ARG2
+
+    OPTIONS
+      -f, --fubar                      do something awful
+
+### Help and Usage
+
+Automatically register `-h`, `--help`, `-u` and `--usage` switches
+with `#help!` and `#usage!`.
+
+    opts = Upoj::Opts.new
+
+    # you can replace this:
+    opts.on('-u', '--usage', 'show this help and exit'){ puts opts; exit 0 }
+
+    # by this:
+    opts.usage!
+
+## Included Dependencies
+
+* __active_support/core_ext/array/extract_options__
+
+  Extraction of hash options from the end of an array.
+
+    # extract options
+    args = [ 'a', 'b', { 'c' => 'd', 'e' => 'f' } ]
+    options = args.extract_options!   #=> { 'c' => 'd', 'e' => 'f' }
+
+    # returns an empty hash if there are no options
+    args = [ 'a', 'b', 'c' ]
+    options = args.extract_options!   #=> {}
+
+    # can be used to easily pass an optional hash to methods
+    def method *args
+      options = args.extract_options!
+    end
+
+* __active_support/core_ext/hash/indifferent_access__
+
+  Hash that makes no difference between strings and
+  symbols as keys.
+
+    h = HashWithIndifferentAccess.new 'a' => 'value a', :b => 'value b'
+    h['a']    #=> 'value a'
+    h[:a]     #=> 'value a'
+    h['b']    #=> 'value b'
+    h[:b]     #=> 'value b'
+
+* __active_support/core_ext/object/blank__
+
+  `#blank?` and `#present?` methods to easily check
+  for empty strings, arrays, hashes, etc.
+
+    ''.present?    #=> false
+    ''.blank?      #=> true
+    [].blank?      #=> true
+    {}.blank?      #=> true
+    nil.blank?     #=> true
+
+* __active_support/core_ext/object/try__
+
+  Allows to attempt to call a method on an object
+  and not throw an error if it's nil.
+
+    s = 'FUBAR'
+    s.try :downcase   #=> 'fubar'
+    s = nil
+    s.try :downcase   #=> nil
+
+* __active_support/core_ext/string/inflections__
+
+  Useful string transformations.
+
+    'Module1::Module2::MyClass'.demodulize   #=> 'MyClass'
+
+* __paint__
+
+  Command-line color output.
+
+    Paint['fubar', :green]
+    Paint['fubar', :bold, :underline]
+
+## Copyright
+
+Copyright (c) 2011 AlphaHydrae. See LICENSE.txt for
+further details.
+

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.5

data/lib/upoj-rb.rb

@@ -4,8 +4,12 @@ require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/object/try'
 require 'active_support/core_ext/string/inflections'
 
+dirname = File.dirname __FILE__
+deps_dir = File.join dirname, 'upoj-rb'
+VERSION_FILE = File.join dirname, '..', 'VERSION'
+
 module Upoj
-  
+  VERSION = File.open(VERSION_FILE, 'r').read
 end
 
-%w( opts signals ).each{ |dep| require File.join(File.dirname(__FILE__), 'upoj-rb', dep) }
+%w( opts signals ).each{ |dep| require File.join(deps_dir, dep) }

data/lib/upoj-rb/opts.rb

@@ -3,7 +3,27 @@ require 'paint'
 
 module Upoj
 
+  # Customized version of ruby's OptionParser.
   class Opts < OptionParser
+
+    # Hash that will be filled with the values of all options
+    # that were defined without a block.
+    #
+    # ==== Examples
+    #   opts = Upoj::Opts.new
+    #   opts.on('--option'){ # do whatever }
+    #   opts.on('-f', '--fubar')
+    #   opts.on('--value VALUE')
+    #
+    #   ARGV          #=> [ '--option', '-f', '--value', 43 ]
+    #   opts.parse!
+    #
+    #   # retrieve options in funnel by default
+    #   opts.funnel   #=> { 'fubar' => true, 'value' => 43 }
+    #
+    #   # a funnel with initial values can be given at construction
+    #   funnel = { 'foo' => false }
+    #   opts = Upoj::Opts.new :funnel => funnel
     attr_accessor :funnel
 
     def self.section_title title
@@ -38,6 +58,27 @@ module Upoj
         super(*args, &block)
       end
     end
+    def program_name
+      @program_name || File.basename($0)
+    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
+
+    private
+
+    def summary_program_name
+      Paint[program_name, :bold]
+    end
 
     def summary_banner_section *args
       options = args.extract_options!
@@ -58,41 +99,5 @@ module Upoj
         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/upoj-rb.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "upoj-rb"
-  s.version = "0.0.4"
+  s.version = "0.0.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["AlphaHydrae"]
@@ -14,7 +14,7 @@ Gem::Specification.new do |s|
   s.email = "hydrae.alpha@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.rdoc"
+    "README.md"
   ]
   s.files = [
     ".document",
@@ -23,7 +23,7 @@ Gem::Specification.new do |s|
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.rdoc",
+    "README.md",
     "Rakefile",
     "VERSION",
     "lib/upoj-rb.rb",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: upoj-rb
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-10-01 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: paint
-  requirement: &2157947360 !ruby/object:Gem::Requirement
+  requirement: &2158212740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2157947360
+  version_requirements: *2158212740
 - !ruby/object:Gem::Dependency
   name: active_support
-  requirement: &2157946860 !ruby/object:Gem::Requirement
+  requirement: &2158212260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '2'
   type: :runtime
   prerelease: false
-  version_requirements: *2157946860
+  version_requirements: *2158212260
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2157946320 !ruby/object:Gem::Requirement
+  requirement: &2158207680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157946320
+  version_requirements: *2158207680
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &2157945640 !ruby/object:Gem::Requirement
+  requirement: &2158207080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157945640
+  version_requirements: *2158207080
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2157945000 !ruby/object:Gem::Requirement
+  requirement: &2158206480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2157945000
+  version_requirements: *2158206480
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2157944360 !ruby/object:Gem::Requirement
+  requirement: &2158205880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *2157944360
+  version_requirements: *2158205880
 - !ruby/object:Gem::Dependency
   name: gemcutter
-  requirement: &2157943700 !ruby/object:Gem::Requirement
+  requirement: &2158205280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157943700
+  version_requirements: *2158205280
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &2157943140 !ruby/object:Gem::Requirement
+  requirement: &2158204560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,7 +98,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157943140
+  version_requirements: *2158204560
 description: This contains common ruby extensions mostly taken from Rails, as well
   as various command-line utilities.
 email: hydrae.alpha@gmail.com
@@ -106,7 +106,7 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
-- README.rdoc
+- README.md
 files:
 - .document
 - .rspec
@@ -114,7 +114,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - lib/upoj-rb.rb
@@ -140,7 +140,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4175343367105993820
+      hash: -2066870811834978715
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/README.rdoc

@@ -1,9 +0,0 @@
-= upoj-rb
-
-Ruby scripting utilities.
-
-== Copyright
-
-Copyright (c) 2011 AlphaHydrae. See LICENSE.txt for
-further details.
-