git-style-binaries 0.1.10

data/README.markdown

@@ -0,0 +1,280 @@
+git-style-binaries
+==================
+
+Ridiculously easy git-style binaries.
+
+This gem uses [`trollop`](http://trollop.rubyforge.org/) for option parsing
+
+## Installation
+
+    gem install jashmenn-git-style-binaries --source=http://gems.github.com
+
+## Screencast
+
+Checkout <a href="http://www.xcombinator.com/movies/git-style-binaries.mov">the new screencast!</a>
+
+<a href="http://www.xcombinator.com/movies/git-style-binaries.mov"><img src="http://github.com/jashmenn/git-style-binaries/tree/master/doc/gsb-screencast.png?raw=true" width='880' height='784' border=0></a>
+
+## Try it out
+
+    cd `gem env gemdir`/gems/jashmenn-git-style-binaries-0.1.4/test/fixtures
+    ./wordpress -h
+    ./wordpress help post
+
+## Goal
+
+Lets use the imaginary `wordpress` gem. Let's say we have three different
+actions we want to specify:
+
+* categories
+* list
+* post
+
+Each command has its own binary in a directory structure like this:
+
+    bin/
+    |-- wordpress
+    |-- wordpress-categories
+    |-- wordpress-list
+    `-- wordpress-post
+
+The goal is to be able to call commands in this manner:
+
+    wordpress -h          # gives help summary of all commands
+    wordpress-list -h     # gives long help of wordpress-list
+    wordpress list -h     # ditto
+    echo "about me" | wordpress-post --title="new post"  # posts a new post with that title
+
+## Example code
+Our `bin/wordpress` binary is called the *primary* . Our primary only needs to contain the following line:
+
+    #!/usr/bin/env ruby
+    require 'git-style-binary/command'
+
+`git-style-binary` will automatically make this command the primary. 
+
+The `bin/wordpress-post` binary could contain the following: 
+
+    #!/usr/bin/env ruby
+    require 'git-style-binary/command'
+
+    GitStyleBinary.command do
+      short_desc "create a blog post"
+      banner <<-EOS
+    Usage: #{command.full_name} #{all_options_string} {content|STDIN}
+
+    Posts content to a wordpress blog
+
+    EOS
+      opt :blog,     "short name of the blog to use", :default => 'default'
+      opt :category, "tag/category. specify multiple times for multiple categories", :type => String, :multi => true
+      opt :title,    "title for the post", :required => true, :type => String
+      opt :type,     "type of the content [html|xhtml|text]", :default => 'html', :type => String
+
+      run do |command|
+        command.die :type, "type must be one of [html|xhtml|text]" unless command.opts[:type] =~ /^(x?html|text)$/i
+
+        puts "Subcommand name:     #{command.name.inspect}"
+        puts "Options:             #{command.opts.inspect}"
+        puts "Remaining arguments: #{command.argv.inspect}"
+      end
+    end
+
+And so on with the other binaries.
+
+## Running the binaries 
+
+Now if we run `wordpress -h` we get the following output:
+     
+    NAME
+          wordpress
+
+    VERSION
+          0.0.1 (c) 2009 Nate Murray - local
+
+    SYNOPSIS
+          wordpress [--version] [--test-primary] [--help] [--verbose] COMMAND [ARGS]
+
+    SUBCOMMANDS
+       wordpress-categories
+           do something with categories
+
+       wordpress-help      
+           get help for a specific command
+
+       wordpress-list      
+           list blog postings
+
+       wordpress-post      
+           create a blog post
+
+
+      See 'wordpress help COMMAND' for more information on a specific command.
+
+    OPTIONS
+        -v, --verbose         
+          verbose
+
+
+        -t, --test-primary=<s>
+          test an option on the primary
+
+
+        -e, --version         
+          Print version and exit
+
+
+        -h, --help            
+          Show this message
+
+
+
+Default **options**, **version string**, and **usage banner** are automatically selected for you. 
+The subcommands and their short descriptions are loaded automatically!
+
+You can pass the `-h` flag to any one of the subcommands (with or without the
+connecting `-`) or use the built-in `help` subcommand for the same effect. For instance:
+
+    $ wordpress help post
+
+    NAME
+          wordpress-post - create a blog post
+
+    VERSION
+          0.0.1 (c) 2009 Nate Murray - local
+
+    SYNOPSIS
+          wordpress-post [--type] [--version] [--test-primary] [--blog] [--help] [--verbose] [--category]
+          [--title] COMMAND [ARGS] {content|STDIN} 
+
+    OPTIONS
+        -v, --verbose         
+          verbose
+
+
+        -t, --test-primary=<s>
+          test an option on the primary
+
+
+        -b, --blog=<s>        
+          short name of the blog to use (default: default)
+
+
+        -c, --category=<s>    
+          tag/category. specify multiple times for multiple
+          categories
+
+
+        -i, --title=<s>       
+          title for the post
+
+
+        -y, --type=<s>        
+          type of the content [html|xhtml|text] (default: html)
+
+
+        -e, --version         
+          Print version and exit
+
+
+        -h, --help            
+          Show this message
+
+
+For more examples, see the binaries in `test/fixtures/`.
+
+## Primary options
+
+Often you may *want* the primary to have its own set of options. Simply call `GitStyleBinary.primary` with a block like so:
+
+    #!/usr/bin/env ruby
+    require 'git-style-binary/command'
+    GitStyleBinary.primary do
+      version "#{command.full_name} 0.0.1 (c) 2009 Nate Murray - local"
+      opt :test_primary, "a primary string option", :type => String
+
+      run do |command|
+        puts "Primary Options: #{command.opts.inspect}"
+      end
+    end
+
+Primary options are **inherited** by all subcommands. That means in this case
+all subcommands will now get the `--test-primary` option available to them as
+well as this new `version` string.
+
+## Option parsing
+
+Option parsing is done by [trollop](http://trollop.rubyforge.org/).
+`git-style-binary` uses this more-or-less exactly. See the [trollop
+documentation](http://trollop.rubyforge.org/) for information on how to setup
+the options and flags.
+
+## Callbacks
+
+Callbacks are available on the primary and subcommands. Available callbacks currently
+are before/after_run. These execute before the run block of the command parser and take
+take one argument, which is the command itself
+
+## The `run` block
+
+To get the 'introspection' on the individual binaries every binary is `load`ed
+on `primary help`. We need a way to get that information while not running
+every command when calling `primary help`. To achieve that you need to put what
+will be run in the `run` block. 
+
+`run` `yields` a `Command` object which contains a number of useful options
+such as `name`, `full_name`, `opts`, and `argv`. 
+
+* `command.opts` is a hash of the options parsed
+* `command.argv` is an array of the remaining arguments
+
+## Features
+* automatic colorization
+* automatic paging
+
+## To Learn more
+
+Play with the examples in the `test/fixtures` directory.
+
+## Credits
+* `git-style-binary` was written by Nate Murray `<nate@natemurray.com>`
+* `trollop` was written by [William Morgan](http://trollop.rubyforge.org/) 
+* Inspiration comes from Ari Lerner's [git-style-binaries](http://blog.xnot.org/2008/12/16/git-style-binaries/) for [PoolParty.rb](http://poolpartyrb.com)
+* [`colorize.rb`](http://colorize.rubyforge.org) by Michal Kalbarczyk
+* Automatic less paging by [Nathan Weizenbaum](http://nex-3.com/posts/73-git-style-automatic-paging-in-ruby)
+* Color inspiration from [Brian Henderson](http://xcombinator.com) teaching me how to get `man git` colors using `less` on MacOSX
+
+## TODO
+* automagic tab completion - Automatic for subcommands and options for any library that uses this
+
+## Known Bugs/Problems
+* Young
+* A few places of really ugly code
+* A feeling that this could be done in 1/2 lines of code
+
+## Authors
+By Nate Murray and Ari Lerner
+
+## Copyright
+
+The MIT License
+
+Copyright (c) 2009 Nate Murray. See LICENSE for details.
+
+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/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "git-style-binaries"
+    gemspec.description = %Q{Ridiculously easy git-style binaries}
+    gemspec.summary =<<-EOF
+    Add git-style binaries to your project easily.
+    EOF
+    gemspec.email = "nate@natemurray.com"
+    gemspec.homepage = "http://github.com/jashmenn/git-style-binaries"
+    gemspec.authors = ["Nate Murray"]
+    gemspec.add_dependency 'trollop'
+    gemspec.add_dependency 'shoulda' # for running the tests
+
+    excludes = /(README\.html)/
+    gemspec.files = (FileList["[A-Z]*.*", "{bin,examples,generators,lib,rails,spec,test,vendor}/**/*", 'Rakefile', 'LICENSE*']).delete_if{|f| f =~ excludes}
+    gemspec.extra_rdoc_files = FileList["README*", "ChangeLog*", "LICENSE*"].delete_if{|f| f =~ excludes}
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "git-style-binaries #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :bump => ['version:bump:patch', 'gemspec', 'build']

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 10
+:major: 0
+:minor: 1

data/lib/ext/colorize.rb

@@ -0,0 +1,198 @@
+#
+# Colorize String class extension.
+#
+class String
+  
+  #
+  # Version string
+  #
+  COLORIZE_VERSION = '0.5.6'
+
+  #
+  # Colors Hash
+  #
+  COLORS = {
+    :black          => 0,
+    :red            => 1,
+    :green          => 2,
+    :yellow         => 3,
+    :blue           => 4,
+    :magenta        => 5,
+    :cyan           => 6,
+    :white          => 7,
+    :default        => 9,
+    
+    :light_black    => 10,
+    :light_red      => 11,
+    :light_green    => 12,
+    :light_yellow   => 13,
+    :light_blue     => 14,
+    :light_magenta  => 15,
+    :light_cyan     => 16,
+    :light_white    => 17
+  }
+
+  #
+  # Modes Hash
+  #
+  MODES = {
+    :default        => 0, # Turn off all attributes
+    #:bright        => 1, # Set bright mode
+    :underline      => 4, # Set underline mode
+    :blink          => 5, # Set blink mode
+    :swap           => 7, # Exchange foreground and background colors
+    :hide           => 8  # Hide text (foreground color would be the same as background)
+  }
+  
+  protected
+  
+  #
+  # Set color values in new string intance
+  #
+  def set_color_parameters( params )
+    if (params.instance_of?(Hash))
+      @color = params[:color]
+      @background = params[:background]
+      @mode = params[:mode]
+      @uncolorized = params[:uncolorized]
+      self
+    else
+      nil
+    end
+  end
+
+  public
+
+  #
+  # Change color of string
+  #
+  # Examples:
+  #
+  #   puts "This is blue".colorize( :blue )
+  #   puts "This is light blue".colorize( :light_blue )
+  #   puts "This is also blue".colorize( :color => :blue )
+  #   puts "This is blue with red background".colorize( :color => :light_blue, :background => :red )
+  #   puts "This is blue with red background".colorize( :light_blue ).colorize( :background => :red )
+  #   puts "This is blue text on red".blue.on_red
+  #   puts "This is red on blue".colorize( :red ).on_blue
+  #   puts "This is red on blue and underline".colorize( :red ).on_blue.underline
+  #   puts "This is blue text on red".blue.on_red.blink
+  #
+  def colorize( params )
+    
+    unless STDOUT.use_color
+      return self unless STDOUT.isatty
+    end
+    return self if ENV['NO_COLOR']
+    
+    begin
+        require 'Win32/Console/ANSI' if PLATFORM =~ /win32/
+    rescue LoadError
+        raise 'You must gem install win32console to use color on Windows'
+    end
+    
+    color_parameters = {}
+
+    if (params.instance_of?(Hash))
+      color_parameters[:color] = COLORS[params[:color]]
+      color_parameters[:background] = COLORS[params[:background]]
+      color_parameters[:mode] = MODES[params[:mode]]
+    elsif (params.instance_of?(Symbol))
+      color_parameters[:color] = COLORS[params]
+    end
+    
+    color_parameters[:color] ||= @color || 9
+    color_parameters[:background] ||= @background || 9
+    color_parameters[:mode] ||= @mode || 0
+
+    color_parameters[:uncolorized] ||= @uncolorized || self.dup
+   
+    # calculate bright mode
+    color_parameters[:color] += 50 if color_parameters[:color] > 10
+
+    color_parameters[:background] += 50 if color_parameters[:background] > 10
+
+    return "\033[#{color_parameters[:mode]};#{color_parameters[:color]+30};#{color_parameters[:background]+40}m#{color_parameters[:uncolorized]}\033[0m".set_color_parameters( color_parameters )
+  end
+
+  
+  #
+  # Return uncolorized string
+  #
+  def uncolorize
+    return @uncolorized || self
+  end
+  
+  #
+  # Return true if sting is colorized
+  #
+  def colorized?
+    return !@uncolorized.nil?
+  end
+
+  #
+  # Make some color and on_color methods
+  #
+  COLORS.each_key do | key |
+    eval <<-"end_eval"
+      def #{key.to_s}
+        return self.colorize( :color => :#{key.to_s} )
+      end
+      def on_#{key.to_s}
+        return self.colorize( :background => :#{key.to_s} )
+      end
+    end_eval
+  end
+
+  #
+  # Methods for modes
+  #
+  MODES.each_key do | key |
+    eval <<-"end_eval"
+      def #{key.to_s}
+        return self.colorize( :mode => :#{key.to_s} )
+      end
+    end_eval
+  end
+
+  class << self
+    
+    #
+    # Return array of available modes used by colorize method
+    #
+    def modes
+      keys = []
+      MODES.each_key do | key |
+        keys << key
+      end
+      keys
+    end
+
+    #
+    # Return array of available colors used by colorize method
+    #
+    def colors
+      keys = []
+      COLORS.each_key do | key |
+        keys << key
+      end
+      keys
+    end 
+
+    #
+    # Display color matrix with color names.
+    #
+    def color_matrix( txt = "[X]" )
+      size = String.colors.length
+      String.colors.each do | color |
+        String.colors.each do | back |
+         print txt.colorize( :color => color, :background => back )
+        end
+        puts " < #{color}"
+      end
+      String.colors.reverse.each_with_index do | back, index |
+        puts "#{"|".rjust(txt.length)*(size-index)} < #{back}"
+      end 
+    end
+  end
+end