vagrant-wrapper 1.2.0 → 1.2.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 `sha1(OWNER) = df334a7237f10846a0ca302bd323e35ee1463931`
+ 
+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,223 @@
+# Vagrant Wrapper Gem
+
+A gem providing access and bundling to the newer packaged versions of Vagrant. (I.E. Vagrant 1.1+)
+
+- Allow your projects to depend on newer versions of Vagrant.
+- Ensure shell calls are routed to the packaged version (even if the older Gem version is installed).
+- Easily check and enforce version requirements.
+
+**Please note:** this Gem does not install any version of Vagrant, it provides a compatibility layer over the newer packaged version. However, functions are included which may be used to guide the installation of Vagrant, when necessary.
+
+**[More information on why this Gem exists can be seen in the Background section below.](#background---aka-the-vagrant-gem-enigma)**
+
+
+# Installation and Usage
+
+Require the Vagrant Wrapper via your Gemfile, then run `bundle install`.
+
+    source 'https://rubygems.org'
+
+    gem 'vagrant-wrapper'
+
+Shell calls to 'vagrant' in your project will now always use the packaged version of Vagrant if available,
+even if the now deprecated Vagrant Gem is installed and available in your Rubygems path.
+
+Existing projects which require the old 'vagrant' gem in their Gemfile directly will continue to see
+and use the older Gem version, even if they are shelling out as well.
+
+**Please note:** The wrapper searches for a packaged installation of Vagrant first, and then falls back to any version it can find in the PATH. Therefore it will link to the 1.0.x gem version if that's all that is installed, so you should always enforce a minimum Vagrant version, see below.
+
+
+## Gemfile examples
+
+**Let's assume you have both Vagrant 1.0.7 installed via a Gem, and Vagrant 1.2 installed via the official package.**
+
+### A... Older 'vagrant' gemfiles
+
+This older Gemfile will still launch Vagrant 1.0.7, as expected:
+
+**Gemfile**
+
+    source 'https://rubygems.org'
+    gem 'vagrant'
+
+**Output**
+
+    puts %x{vagrant -v}
+    => "Vagrant version 1.0.7"
+
+_Notes below on [VAGRANT_HOME](#vagrant_home) with older versions._
+
+### B... Simply Leaving out 'vagrant'
+
+This is the key problem the Vagrant Wrapper seeks to solve, because otherwise (without uninstalling the vagrant gem), your shell calls will still be routed to 1.0.7.
+
+**Gemfile**
+
+    source 'https://rubygems.org'
+
+**Output**
+
+    puts %x{vagrant -v}
+    => "Vagrant version 1.0.7"
+
+### C... Including 'vagrant-wrapper'
+
+Calls to vagrant now route to the newer packaged version.
+
+**Gemfile**
+
+    source 'https://rubygems.org'
+    gem 'vagrant-wrapper'
+
+**Output**
+
+    puts %x{vagrant -v}
+    => "Vagrant version 1.2.0"
+
+
+## Shell interaction
+
+By requiring 'vagrant-wrapper' in your Gemfile, all calls to vagrant (inside and outside of Ruby), will use the packaged Vagrant install if available.
+
+Simply call `vagrant` via a Ruby back tick, or from the command line.
+
+
+### Requiring a specific version (shell out)
+
+If Vagrant is missing (or older than a version you specify) the command will return a standard-error message:
+
+	Vagrant >= 1.1 is required. You have 1.0.7.
+	See http://www.vagrantup.com for instructions.
+
+Ruby
+
+	%x{vagrant --min-ver=1.1 box list}
+	
+Bash
+	
+	bundle exec vagrant --min-ver=1.1 box list
+	
+
+## Ruby interaction
+
+Ruby functions exist for even deeper integration. For full documentation, please see the [RDoc](http://rubydoc.info/gems/vagrant-wrapper).
+
+### Requiring a specific version (Ruby)
+
+```ruby
+ require 'vagrant-wrapper'
+    
+ # Will throw VagrantWrapper::Exceptions::Version
+ vw = VagrantWrapper.new(">= 1.1")
+    
+ # This does the same thing:
+ vw = VagrantWrapper.new
+ vw.require_version(">= 1.1.")
+```
+    
+### Handle a missing version
+
+```ruby
+ # You could handle the error like this:
+ begin
+   vw = VagrantWrapper.new(">= 1.1")
+ rescue VagrantWrapper::Exceptions::Version => e
+   $stderr.print e.message + "\n"
+   $stderr.print vw.install_instructions
+   exit(1)
+ end
+ 
+ # Which is the same as:
+ VagrantWrapper.require_or_help_install(">= 1.1")
+```
+
+### Getting the current version
+
+```ruby
+ require 'vagrant-wrapper'
+ VagrantWrapper.new.vagrant_version
+ # => "1.1.5"  (nil if not installed)
+```
+    
+### Getting the output of a call to vagrant
+
+```ruby
+ require 'vagrant-wrapper'
+ box_list = VagrantWrapper.new.get_output "box list"
+```
+    
+### Handing process control to vagrant
+
+This will cause vagrant to become the main process, as if you'd called it on the command-line. Execution will not return to your Ruby script.
+
+```ruby
+ require 'vagrant-wrapper'
+ VagrantWrapper.new.execute "up"
+ puts "This line would never be printed."
+```
+
+
+## Versioning
+
+Please note, the version of this wrapper does not indicate (or mandate) any specific version of Vagrant
+on the target system. As above, use the VagrantWrapper API for managing the vagrant version.
+
+It's okay if the 'vagrant-wrapper' gem's version does not match the desired version of Vagrant. Therefore specifying a version of the wrapper in your Gemfile is not recommended.
+
+### VAGRANT_HOME
+
+Major differences in Vagrant will refuse to use the same existing shared data directory. If you have an older project requiring the 'vagrant' gem that's fine, but you may need to set the VAGRANT_HOME environment variable to point to another location.
+
+    $ export VAGRANT_HOME=~/.vagrant.old
+
+----------
+
+# Background - AKA the Vagrant Gem enigma
+
+Per the creator's discretion, Vagrant 1.1+ no longer ships in Gem form,
+[see here](https://groups.google.com/d/msg/vagrant-up/kX_wvn7wcds/luwNur4kgDEJ),
+in favor of packaged installers.
+
+There are many ways in which this is a strong move for the project, and in theory Vagrant's ability to use
+its own bundled Ruby allows it to operate in a vacuum. So why does this wrapper exist?
+
+The problem is that Gems do (and will always) exist for the older versions. If they are installed they tend
+to override the system installed version of Vagrant if shell calls are made from within Ruby projects.
+
+As an example, if you have any bundled project that requires the 'vagrant' gem via its Gemfile, and a newer
+project that does not require this Gem (hoping to rely on the system packaged version), you'll find that
+the Gem version of Vagrant will always be called when your program attempts to access Vagrant via a shell
+or subprocess.
+
+This is because the Rubygems bin directory is higher in your PATH, and using "bundle exec" will not help.
+Even though Bundler will attempt to broker between multiple versions of Gems, it cannot handle the choice
+between the Gem version and the system version.
+
+Your only option would be to remove the old vagrant gem between projects, which is cumbersome. Also the problem will recur if you run a "bundle install" on a project which still includes the older Gem. This wrapper
+solves the problem by giving your newer projects something to include and override the older Gem versions
+of Vagrant.
+
+----------
+
+# Development and Maintenance
+
+* Found a bug?
+* Need some help?
+* Have a suggestion?
+* Want to contribute?
+
+Please visit: [code.binbab.org](http://code.binbab.org)
+
+
+## Integration Testing
+
+    bundle install
+    rake test
+
+
+# Authors and License
+
+* Author:: BinaryBabel OSS (<projects@binarybabel.org>)
+* Copyright:: 2013 `sha1(OWNER) = df334a7237f10846a0ca302bd323e35ee1463931`
+* License:: MIT

data/bin/vagrant

@@ -1,7 +1,17 @@
 #!/usr/bin/env ruby
 
 require 'vagrant-wrapper'
-#require_relative '../lib/vagrant-wrapper.rb'
-VagrantWrapper.new.execute(ARGV)
+
+min_ver = nil
+
+if (i = ARGV.index { |x| x =~ /^--min-ver=/ })
+  min_ver = ARGV.delete_at(i).split('=')[1]
+end
+
+unless min_ver
+  VagrantWrapper.new.execute(ARGV)
+else
+  VagrantWrapper.require_or_help_install(">= #{min_ver}").execute(ARGV)
+end
 
 # END VAGRANT WRAPPER

data/lib/vagrant-wrapper/exceptions.rb

@@ -0,0 +1,6 @@
+class VagrantWrapper
+  class Exceptions
+    class Version < RuntimeError ; end
+    class NotInstalled < Version ; end
+  end
+end

data/lib/vagrant-wrapper.rb

@@ -1,3 +1,18 @@
+#
+# Author:: BinaryBabel OSS (<projects@binarybabel.org>)
+# Homepage:: http://www.binarybabel.org
+# License:: MIT
+#
+# For bugs, docs, updates:
+#
+#     http://code.binbab.org
+#
+# Copyright 2013 sha1(OWNER) = df334a7237f10846a0ca302bd323e35ee1463931
+#
+# See LICENSE file for more details.
+#
+
+require 'vagrant-wrapper/exceptions'
 require 'Shellwords'
 
 # Main class for the VagrantWrapper driver.
@@ -7,16 +22,26 @@ require 'Shellwords'
 # if the vagrant-wrapper Gem is required in your bundle.
 class VagrantWrapper
 
-  def initialize
+  def initialize(*args)
     @vagrant_name = "vagrant"
     @vagrant_path = nil
-    @search_paths = default_paths
+    @search_paths = default_paths + env_paths
     @wrapper_mark = "END VAGRANT WRAPPER"
 
-    # Include environment paths as low priority searches.
-    env_path = ENV['PATH'].to_s
-    if "" != env_path
-      @search_paths.concat(env_path.split(':'))
+    # Optional first parameter sets required version.
+    unless args.length < 1 or args[0].nil?
+      require_version args[0]
+    end
+  end
+
+  # Require a specific version (or range of versions).
+  # Ex. ">= 1.1"
+  def require_version(version)
+    version_req = Gem::Requirement.new(version)
+    vagrant_ver = vagrant_version
+    raise Exceptions::NotInstalled, "Vagrant is not installed." if vagrant_ver.nil?
+    unless version_req.satisfied_by?(Gem::Version.new(vagrant_ver))
+      raise Exceptions::Version, "Vagrant #{version} is required. You have #{vagrant_ver}."
     end
   end
 
@@ -24,18 +49,18 @@ class VagrantWrapper
   # The given arguments (if any) are passed along to the command line.
   #
   # The output will be returned.
-  def execute(*args)
+  def get_output(*args)
     if args.length > 0 && args[0].is_a?(Array)
-      send("exec_vagrant", *args[0])
+      send("call_vagrant", *args[0])
     else
-      send("exec_vagrant", *args)
+      send("call_vagrant", *args)
     end
   end
 
   # Execute the discovered version of Vagrant.
   # The given arguments (if any) are passed along to the command line.
   #
-  # The vagrant process will replace this processe entirely, operating
+  # The vagrant process will replace this process entirely, operating
   # and outputting in an unmodified state.
   def execute(*args)
     if args.length > 0 && args[0].is_a?(Array)
@@ -50,7 +75,7 @@ class VagrantWrapper
     find_vagrant
   end
   
-  # Return the version of the discovered Vagrent install.
+  # Return the version of the discovered Vagrant install.
   def vagrant_version
     ver = call_vagrant "-v"
     unless ver.nil?
@@ -73,8 +98,32 @@ class VagrantWrapper
     }
   end
 
+  # Environment search paths to be used as low priority search.
+  def env_paths
+    path = ENV['PATH'].to_s.strip
+    return [] if path.empty?
+    path.split(':')
+  end
+
+  def self.install_instructions
+    "See http://www.vagrantup.com for instructions.\n"
+  end
+
+  def self.require_or_help_install(version)
+    begin
+      vw = VagrantWrapper.new(version)
+    rescue Exceptions::Version => e
+      $stderr.print e.message + "\n"
+      $stderr.print install_instructions
+      exit(1)
+    end
+    vw
+  end
+
   protected
 
+  attr_accessor :search_paths
+
   # Locate the installed version of Vagrant using the provided paths.
   # Exclude the wrapper itself, should it be discovered by the search.
   def find_vagrant
@@ -96,14 +145,14 @@ class VagrantWrapper
       return nil
     end
     args.unshift(vagrant)
-    %x{#{Shellwords.join(args)} + ' 2>&1'}
+    %x{#{Shellwords.join(args)} 2>&1}
   end
 
   # Give execution control to Vagrant.
   def exec_vagrant(*args)
     unless vagrant = find_vagrant
-      $stderr.puts "Vagrant does not appear to be installed."
-      $stderr.puts "See http://www.vagrantup.com for instructions."
+      $stderr.puts "Vagrant is not installed."
+      $stderr.print install_instructions
       exit(1)
     end
     args.unshift(vagrant)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vagrant-wrapper
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,20 +9,49 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-18 00:00:00.000000000 Z
-dependencies: []
-description: ! 'Given Vagrant 1.1+ is distributed only via packaged installers, this
-  Gem provides
+date: 2013-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vagrant
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.7
+description: ! 'Since Vagrant 1.1+ is no longer distributed via Gems, vagrant-wrapper
+  allows you to require and interact
 
-  a wrapper such-that an existing Gem install of the older Vagrant will not take
+  with the newer package versions via your Gemfile, shell, or Ruby code. It allows
+  the newer packaged
 
-  precedence on the command line in a bundled project. Eg. shell calls to ''vagrant''
+  version to take precedence even if the older Vagrant gem remains installed.
 
-  will use the packaged version.
-
-
-  (NOTE: The version of the Gem does not determine the version of Vagrant it links
-  to.)
+  See https://github.com/org-binbab/gem-vagrant-wrapper for more details.
 
 '
 email:
@@ -32,6 +61,9 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- lib/vagrant-wrapper/exceptions.rb
 - lib/vagrant-wrapper.rb
 - bin/vagrant
 homepage: http://code.binbab.org