vagrant-devcommands 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3fcb38ef1de935682eb7936180d0751237b8af1a
-  data.tar.gz: a43fd04b478b34cee2d0526803493b3ab122e8ed
+  metadata.gz: 264d76e5ba1857747eeb893b4c41ed6a907e8c30
+  data.tar.gz: 8333fdbe0a699481c5bc4e56dea0000394aca710
 SHA512:
-  metadata.gz: 192a3deea7cfee00afb89e743efc3556e0cba8b9c252c1092e68f089c8a551622d20899c6576b5bfdf02f670e04d13c78fb870a4cfe65b4bbd04bfd79a75ce23
-  data.tar.gz: a1eab7b292767c1d421d1674579e0a49164640fc408e12e2ba807b3b2cbee9fb6cc22851023fa38922133228fa94318516a083750bc57da86e909ce4d88f14d8
+  metadata.gz: 2712542700027f4d3c4e5f33b9e902d7cf237489bf9ee26c9a54cbb5fda6c91e6628195820fa8aad15b39c7f9054f62323814dc627cbd47bec1390c9e213aef2
+  data.tar.gz: 8c2f25a37e8385d6933dabad95d5453343b92214a9c753eedb10c640b60e9c57a9911632b37cf1a8c2214a89b70967c8f87937bb2b28673fdde770bc2e5881e1

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.5.0 (2015-03-21)
+
+- Enhancements
+  - Commands can define a detailed help message
+  - Commands can define a custom usage string
+  - Commands can be defined using a lambda/proc
+  - Commands can be defined with additional named parameters to be interpolated
+  - Internal commands are included in the command listing (help)
+  - Script parameters can be optional
+
+- Backwards incompatible changes
+  - Positional parameters have been replaced with named parameters
+
+- Bug fixes
+  - Displays actual command name when an error occurs due to missing arguments
+
 ## v0.4.2 (2015-12-15)
 
 - Bug fixes

data/README.md

@@ -5,6 +5,23 @@ Runs vagrant commands from a Commandfile.
 
 ## Usage
 
+### Command Listing
+
+```shell
+vagrant run
+```
+
+### Command Execution
+
+```shell
+# single-vm environment
+# or multi-vm environment with :box option
+vagrant run your_command
+
+# multi-vm environment
+vagrant run your_box your_command
+```
+
 ### Command Definition
 
 Add to a `Commandfile` besides your `Vagrantfile`:
@@ -15,46 +32,74 @@ command 'basic', 'hostname'
 command 'with_options',
     box: :my_box,
     desc: 'executes "hostname" on the box "my_box"',
-    script: 'hostname'
+    script: 'hostname',
+    usage: 'vagrant run %{command}',
+    help: <<-eoh
+I am the help message for the command "with_options".
+I get displayed when running "vagrant run help with_options".
+
+The usage printed above the help can interpolate the name
+of the command name using %{command}.
+eoh
 ```
 
-#### Command Definition (parameters)
+_Note_: If you are defining literal `%` (percent sign) in your commands you
+have to escape them using a second `%`. For example `date "+%%Y-%%m-%%d"`.
+
+#### Experimental: Command Definition (parameters)
 
 Passing additional parameters to a command is (minimally) supported using an
 sprintf syntax:
 
 ```ruby
-command 'with_param', script: 'echo "%s"'
+command 'with_param',
+  parameters: {
+    # mandatory parameter
+    mdtry: {},
+    # parameter with default (implies optional)
+    dflt: { default: "always" },
+    # optional parameter
+    optnl: { optional: true },
+    # wrapped option value
+    wrppd: { wrap: "--and %s wrapped" }
+  },
+  script: 'echo %{mdtry} %{dflt} %{optnl} %{wrppd}'
 ```
 
 This allows you to execute the following command:
 
 ```shell
-# will execute something like 'echo "works"'
-vagrant run with_param works
+# will execute 'echo works always'
+vagrant run with_param --mdtry works
+
+# will execute 'echo works always like a charm'
+vagrant run with_param --mdtry works --optnl "like a charm"
+
+# will execute 'echo works sometimes like a charm --and is wrapped'
+vagrant run with_param \
+    --mdtry works \
+    --dflt sometimes \
+    --optnl "like a charm" \
+    --wrppd is
 ```
 
 For now a command expecting one or more parameters will fail if the user does
 not provide them. Any arguments exceeding the number used are silently
 discarded.
 
-### Command Listing
-
-```shell
-vagrant run
-```
+#### Experimental: Command Definition (lambda/proc)
 
+You can (more or less) dynamically generate your scripts by defining the
+command with a lambda or proc as its script.
 
-### Command Execution
+```ruby
+command 'from_lambda', script: lambda { 'echo "lambda works"' }
+command 'from_proc', script: proc { 'echo "proc works"' }
+```
 
-```shell
-# single-vm environment
-# or multi-vm environment with :box option
-vagrant run your_command
+These will be evaluated when running the command.
 
-# multi-vm environment
-vagrant run your_box your_command
-```
+Every rule from regular scripts (parameters, escaping "%", ...) still apply.
 
 
 ## Notes for Windows Users

data/lib/vagrant/devcommands/command.rb

@@ -56,7 +56,7 @@ module VagrantPlugins
       end
 
       def read_commandfile
-        commandfile = Commandfile.new(@env)
+        commandfile = CommandFile.new(@env)
 
         unless commandfile.exist?
           display_error('Missing "Commandfile"')
@@ -71,7 +71,7 @@ module VagrantPlugins
       def run(command)
         argv   = run_argv
         box    = run_box(command)
-        script = run_script(command[:script], argv)
+        script = run_script(command, argv)
 
         return 2 unless script
 
@@ -87,26 +87,26 @@ module VagrantPlugins
       def run_argv
         argv = @argv.dup
 
-        argv.shift if @env.machine_index.include?(argv[0])
+        argv.shift if @env.machine_index.include?(argv[0].to_s)
         argv.shift
         argv
       end
 
       def run_box(cmd)
-        return cmd[:box].to_s if cmd[:box]
-        return @argv[0] if @env.machine_index.include?(@argv[0])
+        return cmd.box.to_s if cmd.box
+        return @argv[0].to_s if @env.machine_index.include?(@argv[0].to_s)
 
         nil
       end
 
       def run_internal(command)
-        Internal.new(@registry).run(command)
+        Internal.new(@registry).run(command, run_argv)
       end
 
-      def run_script(script, argv)
-        script % argv
-      rescue ArgumentError
-        error = "Not enough parameters to execute \"command[:name]\"!"
+      def run_script(command, argv)
+        command.run_script(argv)
+      rescue KeyError, OptionParser::InvalidOption
+        error = "Invalid/Missing parameters to execute \"#{command.name}\"!"
 
         display_error(error)
 

data/lib/vagrant/devcommands/command_def.rb

@@ -0,0 +1,75 @@
+require 'optparse'
+
+module VagrantPlugins
+  module DevCommands
+    # Definition of an executable command
+    class CommandDef
+      attr_reader :name
+      attr_reader :parameters
+      attr_reader :script
+
+      attr_reader :box
+      attr_reader :desc
+      attr_reader :help
+      attr_reader :usage
+
+      def initialize(spec)
+        @name       = spec[:name]
+        @parameters = spec[:parameters]
+        @script     = spec[:script]
+
+        @box   = spec[:box]
+        @desc  = spec[:desc]
+        @help  = spec[:help]
+        @usage = spec[:usage]
+      end
+
+      def run_script(argv)
+        script = @script
+        script = script.call if script.is_a?(Proc)
+
+        opts = {}
+        opts = parse_argv(argv) if @parameters
+
+        (script % opts).strip
+      end
+
+      private
+
+      def parse_argv(argv)
+        options = options_with_defaults
+
+        OptionParser.new do |opts|
+          @parameters.each do |key, _conf|
+            opts.on("--#{key} OPTION", "Parameter: #{key}") do |o|
+              options[key] = o
+            end
+          end
+        end.parse!(argv)
+
+        wrap_option_values options
+      end
+
+      def options_with_defaults
+        options = {}
+
+        @parameters.each do |key, conf|
+          options[key] = '' if conf[:optional]
+          options[key] = conf[:default] if conf[:default]
+        end
+
+        options
+      end
+
+      def wrap_option_values(options)
+        @parameters.each do |key, conf|
+          next if conf[:wrap].nil?
+
+          options[key] = conf[:wrap] % options[key]
+        end
+
+        options
+      end
+    end
+  end
+end

data/lib/vagrant/devcommands/{commandfile.rb → command_file.rb}

@@ -1,7 +1,7 @@
 module VagrantPlugins
   module DevCommands
     # Loads and handles the Commandfile
-    class Commandfile
+    class CommandFile
       def initialize(env)
         @env = env
       end

data/lib/vagrant/devcommands/internal.rb

@@ -2,53 +2,23 @@ module VagrantPlugins
   module DevCommands
     # Handles internal commands and their execution.
     class Internal
-      def initialize(registry)
-        @registry = registry
-      end
-
-      def run(command)
-        case command
-        when 'help'
-          print_help
-        when 'version'
-          print_version
-        end
-
-        0
-      end
-
-      private
+      NAMESPACE = VagrantPlugins::DevCommands::InternalCommand
 
-      def print_help
-        if @registry.commands.empty?
-          puts 'No commands defined!'
-          return
-        end
+      COMMANDS = {
+        'help'    => CommandDef.new(NAMESPACE::Help::SPEC),
+        'version' => CommandDef.new(NAMESPACE::Version::SPEC)
+      }.freeze
 
-        display_help_header
-        display_help_commands
-      end
-
-      def display_help_commands
-        pad_to = @registry.commands.keys.map(&:length).max
-
-        @registry.commands.each do |name, command|
-          if command.key?(:desc)
-            puts "     #{name.ljust(pad_to)}   #{command[:desc]}"
-          else
-            puts "     #{name}"
-          end
-        end
-      end
-
-      def display_help_header
-        puts 'Usage: vagrant run [box] <command>'
-        puts ''
-        puts 'Available commands:'
+      def initialize(registry)
+        @internal = {
+          'help'    => NAMESPACE::Help.new(registry),
+          'version' => NAMESPACE::Version.new
+        }
+        @registry = registry
       end
 
-      def print_version
-        puts "vagrant-devcommands, version #{VERSION}"
+      def run(command, args)
+        @internal[command].execute(args) if @internal.key?(command)
       end
     end
   end

data/lib/vagrant/devcommands/internal_command/help.rb

@@ -0,0 +1,118 @@
+module VagrantPlugins
+  module DevCommands
+    module InternalCommand
+      # Internal "help" command
+      class Help
+        SPEC = {
+          desc: 'display this help message',
+          name: 'help',
+          usage: 'vagrant run %{command} [command]',
+          help: <<-eoh
+Display the help of the command given as the first argument if defined.
+Just like this help for the help command!
+eoh
+        }.freeze
+
+        def initialize(registry)
+          @registry = registry
+        end
+
+        def execute(argv)
+          if @registry.commands.empty?
+            puts 'No commands defined!'
+            return
+          end
+
+          return plugin_help unless @registry.valid_command?(argv[0])
+          return internal_help(argv[0]) if @registry.reserved_command?(argv[0])
+
+          command_help(argv[0])
+        end
+
+        private
+
+        def collect_commands
+          internal = VagrantPlugins::DevCommands::Internal::COMMANDS
+
+          @registry.commands.merge internal
+        end
+
+        def command_help(command)
+          command_help_header(command)
+
+          puts ''
+
+          if @registry.commands[command].help.nil?
+            puts 'No detailed help for this command available.'
+          else
+            puts @registry.commands[command].help
+          end
+        end
+
+        def command_help_header(command)
+          usage = "vagrant run [box] #{command}"
+          usage = usage_params(usage, @registry.commands[command])
+
+          unless @registry.commands[command].usage.nil?
+            usage = @registry.commands[command].usage % { command: command }
+          end
+
+          puts "Usage: #{usage}"
+        end
+
+        def internal_help(command)
+          internal_help_header(command)
+
+          puts ''
+          puts VagrantPlugins::DevCommands::Internal::COMMANDS[command].help
+        end
+
+        def internal_help_header(command)
+          spec  = VagrantPlugins::DevCommands::Internal::COMMANDS[command]
+          usage = spec.usage % { command: command }
+
+          puts "Usage: #{usage}"
+        end
+
+        def plugin_help
+          plugin_help_header
+          plugin_help_commands
+        end
+
+        def plugin_help_commands
+          commands = collect_commands
+          pad_to   = commands.keys.map(&:length).max
+
+          commands.each do |name, command|
+            if command.desc.nil?
+              puts "     #{name}"
+            else
+              puts "     #{name.ljust(pad_to)}   #{command.desc}"
+            end
+          end
+        end
+
+        def plugin_help_header
+          puts 'Usage: vagrant run [box] <command>'
+          puts 'Help:  vagrant run help <command>'
+          puts ''
+          puts 'Available commands:'
+        end
+
+        def usage_params(usage, command)
+          return usage if command.parameters.nil?
+
+          params = command.parameters.collect do |key, opts|
+            if opts[:optional]
+              "[#{key}]"
+            else
+              "<#{key}>"
+            end
+          end
+
+          "#{usage} #{params.join(' ')}"
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/devcommands/internal_command/version.rb

@@ -0,0 +1,21 @@
+module VagrantPlugins
+  module DevCommands
+    module InternalCommand
+      # Internal "version" command
+      class Version
+        SPEC = {
+          desc: 'display currently used the plugin version',
+          name: 'version',
+          usage: 'vagrant run %{command}',
+          help: <<-eoh
+Displays the currently installed version the plugin you are using right now.
+eoh
+        }.freeze
+
+        def execute(_args)
+          puts "vagrant-devcommands, version #{VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/devcommands/registry.rb

@@ -2,7 +2,7 @@ module VagrantPlugins
   module DevCommands
     # Vagrant command registry
     class Registry
-      RESERVED_COMMANDS = %w(help version)
+      RESERVED_COMMANDS = %w(help version).freeze
 
       attr_accessor :commands
 
@@ -29,12 +29,13 @@ module VagrantPlugins
       def command(name, options)
         return reserved_warning(name) if reserved_command?(name)
 
-        options = { script: options } if options.is_a?(String)
+        options = { script: options } unless options.is_a?(Hash)
 
         return script_warning(name) unless options.key?(:script)
 
-        @commands[name]        = options
-        @commands[name][:name] = name
+        options[:name] = name
+
+        @commands[name] = CommandDef.new(options)
       end
 
       def script_warning(name)

data/lib/vagrant/devcommands/version.rb

@@ -1,6 +1,6 @@
 module VagrantPlugins
   # Defines the current plugin version
   module DevCommands
-    VERSION = '0.4.2'
+    VERSION = '0.5.0'.freeze
   end
 end

data/lib/vagrant/devcommands.rb

@@ -1,7 +1,11 @@
 require 'vagrant'
 
+require 'vagrant/devcommands/internal_command/help'
+require 'vagrant/devcommands/internal_command/version'
+
 require 'vagrant/devcommands/command'
-require 'vagrant/devcommands/commandfile'
+require 'vagrant/devcommands/command_def'
+require 'vagrant/devcommands/command_file'
 require 'vagrant/devcommands/internal'
 require 'vagrant/devcommands/plugin'
 require 'vagrant/devcommands/registry'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vagrant-devcommands
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Marc Neudert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-15 00:00:00.000000000 Z
+date: 2016-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -99,8 +99,11 @@ files:
 - README.md
 - lib/vagrant/devcommands.rb
 - lib/vagrant/devcommands/command.rb
-- lib/vagrant/devcommands/commandfile.rb
+- lib/vagrant/devcommands/command_def.rb
+- lib/vagrant/devcommands/command_file.rb
 - lib/vagrant/devcommands/internal.rb
+- lib/vagrant/devcommands/internal_command/help.rb
+- lib/vagrant/devcommands/internal_command/version.rb
 - lib/vagrant/devcommands/plugin.rb
 - lib/vagrant/devcommands/registry.rb
 - lib/vagrant/devcommands/version.rb
@@ -125,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Runs vagrant commands from a Commandfile