Merge pull request #38 from DannyBen/param

Add param command

Author: DannyBen

cucumber.yml

@@ -1,10 +1,6 @@
 <%
-  rerun = File.file?('rerun.txt') ? IO.read('rerun.txt') : ""
-  rerun_opts = rerun.to_s.strip.empty? ? "--format #{ENV['CUCUMBER_FORMAT'] || 'progress'} features" : "--format #{ENV['CUCUMBER_FORMAT'] || 'pretty'} #{rerun}"
-  std_opts = "--format #{ENV['CUCUMBER_FORMAT'] || 'pretty'} --strict --tags ~@wip"
+  std_opts = "--format #{ENV['CUCUMBER_FORMAT'] || 'pretty'} --strict"
 %>
 
 default: --no-source <%= std_opts %> features
-wip:     --tags @wip:3 --wip features
-current: -s <%= std_opts %> --tags @current features
-rerun:   <%= rerun_opts %> --format rerun --out rerun.txt --strict --tags ~@wip
+

examples/c_documented/Runfile

@@ -1,5 +1,5 @@
 #---
-# Global Commands
+# Global Definitions
 # each Runfile may have a summary and a version. Both are optional.
 #---
 
@@ -36,6 +36,18 @@ help "Say hello to <name>. Use --long to show a longer greeting, and this line i
 option "--long", "Show a longer greeting"
 option "-c --color", "Use colored output"
 
+# the third optional parameter can be used to specify a different 
+# (additional) title that will appear above all options
+option "--quiet", "Do not output anything", "Special Options"
+
+# param adds a help text for a positional parameter under the Parameters 
+# section.
+param "SOURCE", "Source file to copy"
+
+# the third optional parameter can be used to specify a different title, in
+# a way similar to the 'option' command.
+param "SOURCE", "Source file to copy", "Copy Options"
+
 # example adds an example command.
 # the command accepts one parameter: the example command.
 # you do not need to include "run" at the beginning of your example, it will 
@@ -74,3 +86,7 @@ action :up do |args|
   say args['--high'] ? "\b..." : "and get down."
 end
 
+# the optional command 'endcommand' closes any 'command' block that 
+# was opened. it can be used to create several namespaces in the same 
+# Runfile.
+endcommand

examples/u_params/Runfile

@@ -0,0 +1,22 @@
+# this example shows how to add positional params to the generated help text.
+# note that this is only used in the generated help, and has no other purpose.
+# as with docopt, you can use either the <param> or PARAM syntax.
+# 
+# run 'run -h' to see how it works
+
+usage  "connect HOST PORT"
+param  "HOST", "Host to connect to"
+param  "PORT", "Port to connect to"
+action :connect do |args|
+  say "Connecting #{args['HOST']}:#{args['PORT']}"
+end
+
+# specifying a third parameter to the `param` command, will add it under a 
+# different caption
+
+usage  "ssh USER PASS"
+param  "USER", "SSH user", "SSH Parameters"
+param  "PASS", "SSH password", "SSH Parameters"
+action :ssh do |args|
+  say "Connecting as #{args['USER']}:#{args['PASS']}"
+end

examples/u_params/output.txt

@@ -0,0 +1,24 @@
+Runfile
+
+Usage:
+  run connect HOST PORT
+  run ssh USER PASS
+  run (-h|--help)
+
+Options:
+  -h --help
+      Show this screen
+
+Parameters:
+  HOST
+      Host to connect to
+
+  PORT
+      Port to connect to
+
+SSH Parameters:
+  USER
+      SSH user
+
+  PASS
+      SSH password

features/m_make_runfile.feature

@@ -6,7 +6,7 @@ Feature: Make Runfile
 Background:
   Given the folder "sandbox" exists
 
-Scenario: "Show help when running without a Runfile"
+Scenario: Show help when running without a Runfile
   Given I am in the "sandbox" folder
     And the folder is empty
    When I run "run"
@@ -22,7 +22,7 @@ Scenario: Create a runfile
     And the file "Runfile" should exist
     And the file "Runfile" should contain "hello [<name> --color]"
 
-Scenario: "Create a named runfile"
+Scenario: Create a named runfile
   Given I am in the "sandbox" folder
     And the folder is empty
    When I run "run new one"
@@ -33,15 +33,15 @@ Scenario: "Create a named runfile"
     And the output should match "Tip: Type 'run new'..."
     And the output should match "run .*sandbox"
 
-Scenario: "Dont show the new tip if the user is already trained"
+Scenario: Dont show the new tip if the user is already trained
   Given I am in the "sandbox" folder
     And the file "one.runfile" exists
     And the file "two.runfile" exists
     And the file "three.runfile" exists
    When I run "run"
    Then the output should not match "Tip: Type 'run new' or 'run new name'..."
 
-Scenario: "Dont show the new tip if .runfile is present"
+Scenario: Dont show the new tip if .runfile is present
   Given I am in the "examples/s_settings" folder
    When I run "run new"
    Then the output should match "Usage: run <file>"

features/n_exec.feature

@@ -7,52 +7,52 @@ Background:
   Given I am in the "examples/r_exec" folder
     And the folder "tmp" exists
 
-Scenario: "Run an external command"
+Scenario: Run an external command
     When I run "run solve"
     Then the output should say "If there was a problem, yo, I'll solve it"
 
-Scenario: "Execute a before and after block"
+Scenario: Execute a before and after block
    When I run "run solve"
    Then the output should be like "output.txt"
 
-Scenario: "Execute a background job"
+Scenario: Execute a background job
    When I run "run behind"
    Then the output should say "> exec ls >/dev/null 2>&1"
 
-Scenario: "Execute a background job with a given pid alias"
+Scenario: Execute a background job with a given pid alias
    When I run "run pid"
    Then the output should say "> exec ls >/dev/null 2>&1"
     And the file "ls.pid" should exist
     And the file "ls.pid" should match "\d+"
 
-Scenario: "Execute a background job storing pid in another folder"
+Scenario: Execute a background job storing pid in another folder
   Given the file "tmp/pidfile.pid" does not exist
    When I run "run piddir"
    Then the file "tmp/pidfile.pid" should exist
     And the file "tmp/pidfile.pid" should match "\d+"
     And the file "pidfile.pid" should not exist
 
-Scenario: "Execute a background job and direct output to a log"
+Scenario: Execute a background job and direct output to a log
   Given the file "log.log" does not exist
    When I run "run log"
     And I wait "1" second
    Then the file "log.log" should exist
     And the file "log.log" should match "logged"
 
-Scenario: "Stop a background job"
+Scenario: Stop a background job
    When I run "run sleep"
     And I run "run sleep --stop"
    Then the file "sleeper.pid" should not exist
     And the output should match "kill -s TERM \d+"
 
-Scenario: "Stop a non existing background job"
+Scenario: Stop a non existing background job
    When I run "run error"
    Then the output should say "PID file not found"
 
-Scenario: "Configure with a block"
+Scenario: Configure with a block
    When I run "run block-config"
    Then the output should say "pid_dir = what-a-lovely-folder"
 
-Scenario: "Run without showing the command"
+Scenario: Run without showing the command
    When I run "run quiet"
    Then the output should match "BEFORE echo quietly\nquietly\nAFTER echo quietly"

features/p_params.feature

@@ -0,0 +1,11 @@
+Feature: Params
+  In order to provide a better help text
+  Users can document params
+
+Scenario: Show proper help
+  Given I am in the "examples/u_params" folder
+   When I run "run -h"
+   Then the output should be like "output.txt"
+    And the output should have "Parameters:"
+    And the output should have "SSH Parameters:"
+

lib/runfile/docopt_helper.rb

@@ -22,6 +22,7 @@ def initialize(options)
       @summary    = options.summary
       @actions    = options.actions
       @options    = options.options
+      @params     = options.params
       @examples   = options.examples
     end
 
@@ -35,6 +36,7 @@ def docopt
       doc += docopt_usage
       doc += docopt_commands width
       doc += docopt_options width
+      doc += docopt_params width
       doc += docopt_examples width
       doc.join "\n"
     end
@@ -74,17 +76,12 @@ def docopt_options(width)
       @options['Options'] = {} unless @options['Options']
       @options['Options']['-h --help'] = 'Show this screen'
       @options['Options']['--version'] = 'Show version number' if @version
+      section_block @options, width
+    end
 
-      doc = []
-      @options.each do |scope, values|
-        doc << "#{scope}:"
-        values.each do |flag, text|
-          helpline = "      #{text}"
-          wrapped  = word_wrap helpline, width
-          doc << "  #{flag}\n#{wrapped}\n"
-        end
-      end
-      doc
+    # Return all docopt params for 'Params' section
+    def docopt_params(width)
+      section_block @params, width
     end
 
     # Return all docopt lines for the 'Examples' section
@@ -101,6 +98,21 @@ def docopt_examples(width)
       doc
     end
 
+    # Return a generic block containing scope section (e.g. "Options"), 
+    # followed by key value paragraphs.
+    def section_block(definitions, width)
+      doc = []
+      definitions.each do |scope, values|
+        doc << "#{scope}:"
+        values.each do |label, text|
+          helpline = "      #{text}"
+          wrapped  = word_wrap helpline, width
+          doc << "  #{label}\n#{wrapped}\n"
+        end
+      end
+      doc
+    end
+
     # Call the docopt handler, which will either return a parsed
     # arguments list, or halt execution and show usage.
     def args(argv)

lib/runfile/dsl.rb

@@ -43,6 +43,12 @@ def option(flag, text, scope=nil)
       Runner.instance.add_option flag, text, scope
     end
 
+    # Add a parameter (can be called multiple times)
+    #   param 'FOLDER', 'Folder to copy'
+    def param(name, text, scope=nil)
+      Runner.instance.add_param name, text, scope
+    end
+
     # Set an example command (can be called multiple times)
     #   example 'server --background'
     def example(text)

lib/runfile/runner.rb

@@ -13,7 +13,8 @@ class Runner
     include SettingsMixin
 
     attr_accessor :last_usage, :last_help, :name, :version, 
-      :summary, :namespace, :superspace, :actions, :examples, :options
+      :summary, :namespace, :superspace, :actions, :examples, :options, 
+      :params
 
     # Initialize all variables to sensible defaults.
     def initialize
@@ -23,6 +24,7 @@ def initialize
       @namespace  = nil     # dsl: command
       @actions  = {}        # dsl: action
       @options  = {}        # dsl: option
+      @params   = {}        # dsl: param
       @examples = []        # dsl: example
       @name     = "Runfile" # dsl: name
       @version  = false     # dsl: version
@@ -72,6 +74,13 @@ def add_option(flag, text, scope=nil)
       @options[scope][flag] = text
     end
 
+    # Add a patameter and its help text.
+    def add_param(name, text, scope=nil)
+      scope or scope = 'Parameters'
+      @params[scope] ||= {}
+      @params[scope][name] = text
+    end
+
     # Add example command.
     def add_example(command)
       @examples << (@namespace ? "#{@namespace} #{command}" : command)