vagrant-devcommands 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2286eb231a9e6537418f0a60167b17b3022f386c
-  data.tar.gz: 9faa6c649189f8626c622441c4ff9bb26a37a67c
+  metadata.gz: 32211b187c89aedb28b7e3b084553e07030fa971
+  data.tar.gz: 2be8cec37c79264056981c70acdd490ebdeb4d18
 SHA512:
-  metadata.gz: f993ab2fff187f77800617b595e443ff15e3a7b4376bd8a733a0e7c2e30589475fa6790f29ee2d2cc6df910f015a7a7e52758f234966d100a93988096c0ccff6
-  data.tar.gz: 3c2ae42e63a90567cb49085f5646143f115db29ec960def9eacce7b0b1704c0c3b717bc5d3c219544c07cfe274fb6923129448ea8fff653b1a76cbf61cfa2e8f
+  metadata.gz: a6a418391c08c271c88d3c334a88c1ad02173725fe2300bc81523ce9302b3344068769cdf52c23da6fd869a307bf8ba01f0a78855aca86afbaa2a42de384e858
+  data.tar.gz: cabdfa5024114480df1ae410ddfd7d78928a62099672fd6909838260fa0e314f708a73abd00d08e01d57917b14fe203a1149217aeefec1735cb1aca91466af37

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.8.0 (2017-04-19)
+
+- Enhancements
+  - Chains can be defined to execute multiple commands in order
+  - Commands can define flags (always optional!) for script interpolation
+
 ## v0.7.2 (2017-03-12)
 
 - Bug fixes

data/README.md

@@ -22,6 +22,8 @@ vagrant run your_command
 vagrant run your_box your_command
 ```
 
+This runs commands or alternatively a command chain with the passed name.
+
 ### Command Definition
 
 Add to a `Commandfile` besides your `Vagrantfile`:
@@ -30,11 +32,11 @@ Add to a `Commandfile` besides your `Vagrantfile`:
 command 'basic', 'hostname'
 
 command 'with_options',
-    box: :my_box,
-    desc: 'executes "hostname" on the box "my_box"',
-    script: 'hostname',
-    usage: 'vagrant run %{command}',
-    help: <<-eoh
+  box: :my_box,
+  desc: 'executes "hostname" on the box "my_box"',
+  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".
 
@@ -97,6 +99,36 @@ Escaping rules are defined as `{ "char_to_escape": "char_to_use_as_escape" }`.
 These are applied prior to interpolation into the command. Regular ruby escaping
 rules apply.
 
+#### Commands with Flags
+
+Every command can be associated with (by definition optional) flags available
+for later command interpolation:
+
+```ruby
+command 'with_flags',
+  flags: {
+    f_standard: { desc: "standard flag" },
+    f_valued:   { value: "--f_modified" }
+  },
+  script: 'echo "flags: %{f_standard}"'
+```
+
+This definition allows the following executions:
+
+```shell
+# will execute 'echo "flags: "'
+vagrant run with_flags
+
+# will execute 'echo "flags: --f_standard"'
+vagrant run with_flags --f_standard
+
+# will execute 'echo "flags: --f_modified"'
+vagrant run with_flags --f_valued
+```
+
+By default a flag gets interpolated as "--#{flagname}". If a value is defined
+this value will be interpolated unmodified.
+
 #### Commands defined by Lambda/Proc
 
 You can (more or less) dynamically generate your scripts by defining the
@@ -111,8 +143,7 @@ These will be evaluated when running the command.
 
 Every rule from regular scripts (parameters, escaping "%", ...) still apply.
 
-
-### Experimental: global command definitions
+### Global Command Definitions
 
 To have commands available even wihout a `Commandfile` you can define the
 globally. To do this just create a file named `.vagrant.devcommands` in your
@@ -126,7 +157,70 @@ ruby -e "require 'pathname'; puts Pathname.new(Dir.home).join('.vagrant.devcomma
 
 Any commands defined there will silently be overwritten by a local definition.
 
-### Abort parsing inside Commandfile
+### Experimental: Chain Definitions
+
+You can define command chains to execute multiple commands in order:
+
+```ruby
+chain 'my_chain',
+  break_on_error: false,
+  commands: [
+    { command: 'first' },
+    { command: 'second' },
+    { command: 'third' }
+  ],
+  desc: 'Command chain for three commands.',
+  help: <<-eoh
+I am the help message for the chain "my_chain".
+I get displayed when running "vagrant run help my_chain".
+
+The usage printed above the help can interpolate the name
+of the command name using %{command}.
+eoh
+```
+
+The configured commands will be executed in the order defined.
+
+If one or more of your commands requires parameters all of them have to be
+passed to the chain execution.
+
+By default a chain breaks upon the first non-zero return value of any
+configured command. To deactivate this behaviour you can set `:break_on_error`
+to `false`. Any value other than `false` will stick to the default.
+
+#### Chain Definitions with Pre-Defined Parameters
+
+If required you can modify the arguments given to each chain element by setting
+additional/custom argv values for a single chain element:
+
+```ruby
+command 'chainecho',
+  parameters: { first: {}, second: {} },
+  script: 'echo %{first} %{second}'
+
+chain 'my_customized_chain',
+  commands: [
+    { command: 'chainecho', argv: ['--first="param"'] },
+    { command: 'chainecho' },
+    { command: 'chainecho', argv: ['--first="param"', '--second="param"'] }
+  ]
+```
+
+Running the chain will execute the following commands:
+
+```shell
+> vagrant run my_customized_chain --first="initial" --second="initial"
+
+vagrant run chainecho --first="param" --second="initial"
+vagrant run chainecho --first="initial" --second="initial"
+vagrant run chainecho --first="param" --second="param"
+```
+
+By default every command will be executed using the box defined by the command
+itself or the only one available. You can, however, run the complete chain
+against a specific box using `vagrant run your_box your_chain`.
+
+### Abort Parsing inside Commandfile
 
 If you, for whatever reasons, want to abort further parsing of a `Commandfile`
 you can simple return from it:
@@ -166,10 +260,10 @@ a sigil notation like the following:
 
 ```ruby
 command 'long_running_task',
-    script: %(cd /path/to/somewhere \
-                  && echo "starting long running task" \
-                  && ./long_running_task.sh \
-                  && echo "finished long running task")
+  script: %(cd /path/to/somewhere \
+                && echo "starting long running task" \
+                && ./long_running_task.sh \
+                && echo "finished long running task")
 ```
 
 Using a quote delimited command definition might otherwise result in not that

data/lib/vagrant/devcommands/command.rb

@@ -2,10 +2,13 @@ module VagrantPlugins
   module DevCommands
     # Defines the executable vagrant command
     class Command < Vagrant.plugin(2, :command)
-      UTIL = VagrantPlugins::DevCommands::Util
+      NAMESPACE_RUNNER = VagrantPlugins::DevCommands::Runner
+      MESSAGES         = VagrantPlugins::DevCommands::Messages
 
       def self.synopsis
-        'runs vagrant commands from a Commandfile'
+        synopsis = VagrantPlugins::DevCommands::SYNOPSIS
+
+        synopsis[0, 1].downcase + synopsis[1..-1]
       end
 
       def initialize(argv, env)
@@ -17,55 +20,52 @@ module VagrantPlugins
       def execute
         return 127 unless read_commandfile
 
-        command = argv_command
+        command = Util.argv_command(@argv, @env)
 
-        return 127 unless check_command(command)
+        return 127 unless non_empty?(command)
+        return 127 unless available?(command)
 
         return run_internal(command) if @registry.reserved_command?(command)
 
-        run @registry.commands[command]
+        run command
       end
 
-      private
-
-      attr_accessor :registry
+      def proxy_with_target_vms(names = nil, options = nil, &block)
+        # allows public access to protected method with_target_vms
+        with_target_vms(names, options, &block)
+      end
 
-      def check_command(command)
-        unless command
-          run_internal('help')
-          return false
-        end
+      private
 
-        unless @registry.valid_command?(command)
+      def available?(command)
+        unless @registry.available?(command)
           display_error("Invalid command \"#{command}\"!")
           run_internal('help', ['--commands'])
-
-          return false
         end
 
-        true
+        @registry.available?(command)
       end
 
-      def argv_command
-        return nil if @argv.empty?
-
-        command = @argv[0].to_s
-        command = @argv[1].to_s if UTIL.machine_name?(@argv[1].to_s,
-                                                      @env.machine_index)
-
-        command
+      def display_error(msg, post_ln = false)
+        @env.ui.error msg
+        @env.ui.error '' if post_ln
       end
 
-      def display_error(msg)
-        @env.ui.error msg
-        @env.ui.error ''
+      def non_empty?(command)
+        unless command
+          run_internal('help')
+          return false
+        end
+
+        true
       end
 
       def read_commandfile
-        commandfile = CommandFile.new(@env)
+        commandfile = Commandfile.new(@env)
 
         unless commandfile.exist?
-          @env.ui.error 'Missing Commandfile'
+          MESSAGES.missing_commandfile(&@env.ui.method(:error))
+          MESSAGES.pre_ln(:plugin_readme, &@env.ui.method(:info))
 
           return false
         end
@@ -76,56 +76,39 @@ module VagrantPlugins
       end
 
       def run(command)
-        argv   = run_argv
-        box    = run_box(command)
-        script = run_script(command, argv)
-
-        return 2 unless script
-
-        with_target_vms(box, single_target: true) do |vm|
-          env = vm.action(:ssh_run,
-                          ssh_opts: { extra_args: ['-q'] },
-                          ssh_run_command: script)
-
-          return env[:ssh_run_exit_status] || 0
-        end
-      end
-
-      def run_argv
-        argv = @argv.dup
-
-        argv.shift if UTIL.machine_name?(argv[0].to_s, @env.machine_index)
-        argv.shift
-        argv
-      end
+        runner   = runner_for(command)
+        runnable = runnable_for(command)
 
-      def run_box(cmd)
-        box = nil
-        box = cmd.box.to_s if cmd.box
-        box = @argv[0] if UTIL.machine_name?(@argv[0].to_s, @env.machine_index)
+        runner.run(runnable)
+      rescue RuntimeError => e
+        display_error(e.message, true)
+        run_internal('help', [command])
 
-        box
+        nil
       end
 
       def run_internal(command, args = nil)
-        Internal.new(@env, @registry).run(command, args || run_argv)
-      end
+        runner = NAMESPACE_RUNNER::InternalCommand.new(
+          self, @argv, @env, @registry
+        )
 
-      def run_script(command, argv)
-        command.run_script(argv)
-      rescue KeyError => e
-        param = e.message.match(/{(.+)}/).captures.first
-
-        run_script_error(command.name, "missing parameter '#{param}'")
-      rescue OptionParser::InvalidOption => e
-        run_script_error(command.name, "invalid parameter '#{e.args.first}'")
+        runner.run(command, args)
       end
 
-      def run_script_error(command, error)
-        display_error("Could not execute #{command}: #{error}!")
-        run_internal('help', [command])
+      def runnable_for(command)
+        if @registry.valid_command?(command)
+          @registry.commands[command]
+        else
+          @registry.chains[command]
+        end
+      end
 
-        nil
+      def runner_for(command)
+        if @registry.valid_command?(command)
+          NAMESPACE_RUNNER::Command.new(self, @argv, @env, @registry)
+        else
+          NAMESPACE_RUNNER::Chain.new(self, @argv, @env, @registry)
+        end
       end
     end
   end

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

@@ -3,7 +3,7 @@ require 'pathname'
 module VagrantPlugins
   module DevCommands
     # Loads and handles the Commandfile
-    class CommandFile
+    class Commandfile
       def initialize(env)
         @env = env
       end
@@ -26,12 +26,10 @@ module VagrantPlugins
 
       private
 
-      attr_accessor :env
-
       def find_commandfile
         return nil unless @env.root_path
 
-        %w(Commandfile commandfile).each do |commandfile|
+        %w[Commandfile commandfile].each do |commandfile|
           current_path = @env.root_path.join(commandfile)
 
           return current_path if current_path.file?

data/lib/vagrant/devcommands/help_printer/chain.rb

@@ -0,0 +1,62 @@
+module VagrantPlugins
+  module DevCommands
+    module HelpPrinter
+      # Prints help for a command chain
+      class Chain
+        UTIL     = VagrantPlugins::DevCommands::Util
+        MESSAGES = VagrantPlugins::DevCommands::Messages
+
+        def initialize(env)
+          @env = env
+        end
+
+        def output(chain)
+          header(chain)
+          commands(chain)
+          body(chain.help)
+        end
+
+        private
+
+        def body(help)
+          return message(:chain_no_help, true) if help.nil?
+
+          info(help.strip, true)
+        end
+
+        def chain_help_line(cmd)
+          return cmd[:command] unless cmd.key?(:argv)
+
+          "#{cmd[:command]} #{cmd[:argv]}"
+        end
+
+        def commands(chain)
+          info('Chained commands (in order):', true)
+
+          chain.commands.each do |cmd, _options|
+            info(UTIL.padded_columns(0, chain_help_line(cmd)))
+          end
+        end
+
+        def header(chain)
+          usage = "vagrant run [box] #{chain.name}"
+
+          info(I18n.t('vagrant_devcommands.internal.help.usage', what: usage))
+        end
+
+        def info(msg, pre_ln = false)
+          @env.ui.info '' if pre_ln
+          @env.ui.info msg
+        end
+
+        def message(msg, pre_ln = false)
+          if pre_ln
+            MESSAGES.pre_ln(msg, &@env.ui.method(:info))
+          else
+            MESSAGES.public_send(msg, &@env.ui.method(:info))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/devcommands/help_printer/command.rb

@@ -0,0 +1,78 @@
+module VagrantPlugins
+  module DevCommands
+    module HelpPrinter
+      # Prints help for a command
+      class Command
+        UTIL     = VagrantPlugins::DevCommands::Util
+        MESSAGES = VagrantPlugins::DevCommands::Messages
+
+        def initialize(env)
+          @env = env
+        end
+
+        def output(command)
+          header(command)
+          arguments(command.parameters, 'Parameters')
+          arguments(command.flags, 'Flags')
+          body(command.help)
+        end
+
+        private
+
+        def arguments(arguments, title)
+          return if arguments.nil?
+
+          info("#{title}:", true)
+          arguments_body(arguments)
+        end
+
+        def arguments_body(arguments)
+          pad_to = UTIL.pad_to(arguments)
+
+          arguments.sort.each do |name, options|
+            info(UTIL.padded_columns(pad_to, name, options[:desc]))
+          end
+        end
+
+        def body(help)
+          return message(:command_no_help, true) if help.nil?
+
+          info(help.strip, true)
+        end
+
+        def header(command)
+          usage = "vagrant run [box] #{command.name}"
+          usage = usage_params(usage, command)
+
+          unless command.usage.nil?
+            usage = format(command.usage, command: command)
+          end
+
+          info(I18n.t('vagrant_devcommands.internal.help.usage', what: usage))
+        end
+
+        def info(msg, pre_ln = false)
+          @env.ui.info '' if pre_ln
+          @env.ui.info msg
+        end
+
+        def message(msg, pre_ln = false)
+          if pre_ln
+            MESSAGES.pre_ln(msg, &@env.ui.method(:info))
+          else
+            MESSAGES.public_send(msg, &@env.ui.method(:info))
+          end
+        end
+
+        def usage_params(usage, command)
+          [
+            usage,
+            UTIL.collect_mandatory_params(command.parameters || {}),
+            UTIL.collect_optional_params(command.parameters || {}),
+            UTIL.collect_flags(command.flags || {})
+          ].flatten.compact.join(' ').strip
+        end
+      end
+    end
+  end
+end