benzo 1.0.1 → 2.0.0

data/README.md

@@ -2,6 +2,9 @@
 
 *Take the edge off when doing (command) lines.*
 
+**This is the unstable/2.0.0 branch. Docs may be incomplete or completely incorrect.
+This is your warning.**
+
 Wrapping [Cocaine](https://github.com/thoughtbot/cocaine), this library will
 greatly simplify building complex and conditional commandline arguments.
 
@@ -11,7 +14,7 @@ This is especially useful when creating wrappers for other commandline tools.
 
 Add this line to your application's Gemfile:
 
-    gem 'benzo'
+    gem 'benzo', '~> 2.0.0'
 
 And then execute:
 
@@ -33,14 +36,11 @@ in your code, you may want to have certain arguments shown or not shown:
 @file = 'app_prod-dump'
 
 # build the Cocaine::Commandline with Benzo
-line = Benzo.line('pg_dump', {
+Benzo.run!('pg_dump', {
   '-v' => @verbose,
   '--schema-only' => @schema_only, # note, @schema_only is nil
   '-f :filename' => @file,
   ':db_name' => @database
-})
-
-line.run # execute the command
 ```
 
 Benzo takes 2 arguments: `command` and `options_map`. The command is, like in
@@ -50,8 +50,41 @@ the data necessary to build the commandline arguments.
 Any value in the hash that evaluates to `false` (this includes `nil`) will be
 omitted from the command.
 
+## A More Complex Example
+
+```ruby
+# the state of our app:
+@verbose = true
+@database = 'app_production'
+@file = 'app_prod-dump'
+
+# build a Benzo object:
+b = Benzo.new('pg_dump',
+  '-v' => @verbose,
+  '--schema-only' => @schema_only, # note, @schema_only is nil
+  '-f :filename' => @file,
+  ':db_name' => @database
+)
+
+b.run # => runs the command: "pg_dump -v -f 'app_prod-dump' 'app_production'"
+
+b.options_map['--schema-only'] = true
+
+b.command # => pg_dump -v --schema-only -f 'app_prod-dump' 'app_production'
+
+c = b.cocaine # => returns a Cocaine::CommandLine object
+
+c.run(:db_name => 'other_db', :filename => 'other_db-dump') # => run it with different options
+```
+
+After creating a Benzo object, you can modify the `options_map` on the fly and
+Benzo will re-map it when calling `#command` or `#run`. There is also a `#cocaine`
+function that will return the `Cocaine::CommandLine` object.
+
 ## How options_map works
 
+See **Limitations and Gotchas** section below if you're not using Benzo in Ruby 1.9.
+
 `options_map` is a hash that gets processed by `Benzo` to create the
 `Cocaine::CommandLine` object. The hash gets iterated over and any values that
 evaluate to `false` are discarded, then the keys are concatinated together with
@@ -95,6 +128,12 @@ rescue Cocaine::ExitStatusError => e
 end
 ```
 
+## Limitations and Gotchas
+
+Because Benzo uses Hash keys to build the commandline string and that order may matter,
+if you're not running Ruby 1.9, you should pass an [OrderedHash](https://rubygems.org/gems/orderedhash)
+for the `options_hash`.
+
 ## Contributing
 
 1. Fork it

data/benzo.gemspec

@@ -15,5 +15,5 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Benzo::VERSION
 
-  gem.add_dependency 'cocaine', "~> 0.3.2"
+  gem.add_dependency 'cocaine', "~> 0.4.2"
 end

data/lib/benzo/version.rb

@@ -1,3 +1,3 @@
 class Benzo
-  VERSION = "1.0.1"
+  VERSION = "2.0.0"
 end

data/lib/benzo.rb

@@ -6,27 +6,52 @@ class Benzo
   attr_accessor :command, :options_map
   attr_accessor :line, :vars
 
-  def initialize(command, options_map)
+  def initialize(command, options_map={})
+    Benzo.show_version_warning
     @command = command
     @options_map = options_map
     @line = []
     @vars = {}
+  end
 
-    map!
+  # given a +command+ and +options_map+, interpolate the variables and
+  # run the command.
+  # returns the output as a string (as returned from Cocaine)
+  def self.run!(command, options_map)
+    show_version_warning
+    b = new(command, options_map)
+    r = b.run
+
+    b = nil # dealocate object
+
+    return r
   end
 
-  # convenience method for creating a new Benzo object with the given
-  # arguments and returning the Cocaine::Commandline
-  def self.line(command, options_map)
+  # given a +command+ and +options_map+, interpolate the variables and
+  # return the command that will be run as a string.
+  def self.command!(command, options_map)
+    show_version_warning
     b = new(command, options_map)
-    line = b.to_cocaine
+    c = b.command
 
-    b = nil
-    line
+    b = nil # dealocate object
+
+    return c
+  end
+
+  # run the +Cocaine::CommandLine+ command and return the output.
+  def run
+    cocaine.run(@vars)
   end
 
-  # convert this object into a Cocaine::CommandLine
-  def to_cocaine
+  # return the +Cocaine::CommandLine+ command as a string
+  def command
+    cocaine.command(@vars)
+  end
+
+  # map the variables and return a +Cocaine::CommandLine+ object
+  def cocaine
+    map!
     ::Cocaine::CommandLine.new(@command, @line.join(' '), @vars)
   end
 
@@ -35,6 +60,10 @@ class Benzo
   # iterate over the options map and build
   # this object's mapping.
   def map!
+    # re-initialize the state
+    @line = []
+    @vars = {}
+
     @options_map.each do |k,v|
       sym = if k.is_a? Symbol
         k
@@ -64,5 +93,13 @@ class Benzo
     :"#{sym}"
   end
 
+  # check the current version of ruby
+  # if it's a 1.8.x, then show a warning.
+  def self.show_version_warning
+    if RUBY_VERSION.match /^1\.8/
+      $stderr.puts "WARNING: Benzo 2.0 requires ruby 1.9.x unless you use an OrderedHash for the options map!"
+    end
+  end
+
 
 end

data/spec/benzo_spec.rb

@@ -4,6 +4,54 @@ describe Benzo do
 
   let(:benzo) { Benzo.new 't', {} }
 
+  context "::run!" do
+
+    it "should not error out" do
+      lambda { Benzo.run! 'echo', 'hello world' => true }.should_not raise_error
+    end
+
+    it "should return the correct output" do
+      Benzo.run!('echo', '-n hello world' => true ).should == 'hello world'
+    end
+
+  end
+
+  context "::command!" do
+
+    it "should not error out" do
+      lambda { Benzo.command! 'echo', 'hello world' => true }.should_not raise_error
+    end
+
+    it "should return the correct command" do
+      Benzo.command!('echo', 'hello world' => true).should == 'echo hello world'
+    end
+
+  end
+
+  context "#cocaine" do
+    let(:benzo) { Benzo.new 'echo', '-n' => true, 'hello world' => true }
+
+    it "should return a Cocaine::CommandLine object" do
+      benzo.cocaine.class.should == ::Cocaine::CommandLine
+    end
+
+    it "should return a Cocaine::CommandLine object with the correct things set" do
+      benzo.cocaine.instance_variable_get('@params').should == '-n hello world'
+    end
+
+    it "should return a Cocaine::CommandLine object with the right Cocaine options"
+
+  end
+
+  context "#command" do
+    let(:benzo) { Benzo.new 'echo', 'hello world' => true }
+
+    it "should properly interpolate variables" do
+      benzo.command.should == 'echo hello world'
+    end
+
+  end
+
   context "#map!" do
 
     it "should append to @line if v evaluates to true" do
@@ -88,4 +136,10 @@ describe Benzo do
 
   end
 
+  context "when checking the ruby version" do
+
+    it "should print a warning if the ruby version is 1.8"
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: benzo
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-16 00:00:00.000000000 Z
+date: 2012-12-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocaine
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 0.4.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 0.4.2
 description: Take the edge off when doing (command) lines.
 email:
 - me@spike.cx