Merge pull request #44 from DannyBen/add/env-var-usage

Add 'env_var' DSL command to specify environment variables used by the Runfile

examples/c_documented/Runfile

@@ -48,6 +48,13 @@ param "SOURCE", "Source file to copy"
 # a way similar to the 'option' command.
 param "SOURCE", "Source file to copy", "Copy Options"
 
+# env_vars adds a help text for specifying which environment variables can
+# be set to influence the output.
+env_var "HEADER", "Set the display header"
+
+# the third optional parameter can be used to specify a different title.
+env_var "HEADER", "Set the display header", "Layout Environment Variables"
+
 # 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 

examples/c_documented/output.txt

@@ -0,0 +1,49 @@
+Runner 0.1.0
+The first ever Runfile program
+
+Usage:
+  run greet <name> [--long --color]
+  run jump around
+  run jump up [--high]
+  run (-h|--help|--version)
+
+Commands:
+  greet <name> [--long --color]
+      Say hello to <name>. Use --long to show a longer greeting, and this line
+      is long on purpose to see how it is displayed.
+
+Options:
+  --long
+      Show a longer greeting
+
+  -c --color
+      Use colored output
+
+  -h --help
+      Show this screen
+
+  --version
+      Show version number
+
+Special Options:
+  --quiet
+      Do not output anything
+
+Parameters:
+  SOURCE
+      Source file to copy
+
+Copy Options:
+  SOURCE
+      Source file to copy
+
+Environment Variables:
+  HEADER
+      Set the display header
+
+Layout Environment Variables:
+  HEADER
+      Set the display header
+
+Examples:
+  run greet Danny --color

features/a_basic_execution.feature

@@ -17,3 +17,8 @@ Scenario: Show a more detailed help
    When I run "run -h"
    Then the output should be like "output.txt"
 
+Scenario: Show an evem more detailed help
+  Given I am in the "examples/c_documented" folder
+   When I run "run -h"
+   Then the output should be like "output.txt"
+

lib/runfile/docopt_helper.rb

@@ -23,6 +23,7 @@ def initialize(options)
       @actions    = options.actions
       @options    = options.options
       @params     = options.params
+      @env_vars   = options.env_vars
       @examples   = options.examples
     end
 
@@ -37,6 +38,7 @@ def docopt
       doc += docopt_commands width
       doc += docopt_options width
       doc += docopt_params width
+      doc += docopt_env_vars width
       doc += docopt_examples width
       doc.join "\n"
     end
@@ -84,6 +86,11 @@ def docopt_params(width)
       section_block @params, width
     end
 
+    # Return all docopt params for 'Environment Variables' section
+    def docopt_env_vars(width)
+      section_block @env_vars, width
+    end
+
     # Return all docopt lines for the 'Examples' section
     def docopt_examples(width)
       return [] if @examples.empty?

lib/runfile/dsl.rb

@@ -49,6 +49,12 @@ def param(name, text, scope=nil)
       Runner.instance.add_param name, text, scope
     end
 
+    # Set an environment variable (can be called multiple times)
+    #   env_var 'USER', 'Set the user (same as --user)'
+    def env_var(name, text, scope = nil)
+      Runner.instance.add_env_var name, text, scope
+    end
+
     # Set an example command (can be called multiple times)
     #   example 'server --background'
     def example(text)

lib/runfile/runner.rb

@@ -14,7 +14,7 @@ class Runner
 
     attr_accessor :last_usage, :last_help, :name, :version, 
       :summary, :namespace, :superspace, :actions, :examples, :options, 
-      :params
+      :params, :env_vars
 
     # Initialize all variables to sensible defaults.
     def initialize
@@ -26,6 +26,7 @@ def initialize
       @options  = {}        # dsl: option
       @params   = {}        # dsl: param
       @examples = []        # dsl: example
+      @env_vars = {}        # dsl: env_var
       @name     = "Runfile" # dsl: name
       @version  = false     # dsl: version
       @summary  = false     # dsl: summary
@@ -48,7 +49,7 @@ def execute(argv, filename='Runfile')
 
     # Add an action to the @actions array, and use the last known
     # usage and help messages sent by the DSL.
-    def add_action(name, altname=nil, &block)
+    def add_action(name, altname = nil, &block)
       if @last_usage.nil?
         @last_usage = altname ? "(#{name}|#{altname})" : name 
       end
@@ -68,19 +69,26 @@ def add_action(name, altname=nil, &block)
     end
 
     # Add an option flag and its help text.
-    def add_option(flag, text, scope=nil)
-      scope or scope = 'Options'
+    def add_option(flag, text, scope = nil)
+      scope ||= 'Options'
       @options[scope] ||= {}
       @options[scope][flag] = text
     end
 
     # Add a patameter and its help text.
-    def add_param(name, text, scope=nil)
-      scope or scope = 'Parameters'
+    def add_param(name, text, scope = nil)
+      scope ||= 'Parameters'
       @params[scope] ||= {}
       @params[scope][name] = text
     end
 
+    # Add env_var command.
+    def add_env_var(name, text, scope = nil)
+      scope ||= 'Environment Variables'
+      @env_vars[scope] ||= {}
+      @env_vars[scope][name] = text
+    end
+
     # Add example command.
     def add_example(command)
       @examples << (@namespace ? "#{@namespace} #{command}" : command)