rototiller 0.0.0.b → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1d55671811e2416321d690faed5b873e6656bb5a
-  data.tar.gz: c6bd60e740eafc188f462997b429132752806a70
+  metadata.gz: c0293a5f48a1408895a06db0d68fc2c72f6b01f9
+  data.tar.gz: 618d7deee258cfabf05e3ce58444e1b8b5464978
 SHA512:
-  metadata.gz: 2641a1a861d9f54b1218c6b718179ff985b9f2c77a2472729d2a0ba58907279e484e6c448506b83fe8c2234720a28df78e0fe2dfdfca6a823b0f7e2c3c3437b8
-  data.tar.gz: 77a6855654474501fb1152b470e4e71d99c160065f0e46a0940e976f34fd1e9e01b139f7c336d677b8f933474978e210f751b5e41ab6b97e74232189895b83eb
+  metadata.gz: 55d4f136476b7486c36c2793fff8b92762dc04fe96a14654ac116e8cc2f3e96c9872f73ab102f473337d67f2a0609cb9caf88e0eb9f5a2d615b8a7b71973be37
+  data.tar.gz: 8780f143c25e5799bb1aa8a1cf36497d26b1c3778efb9deb7039e203646909cc2e0438b28319e70e0fe7cafcdba3a1c3202d3db1dedf7510d66df501fda24762

data/Gemfile

@@ -2,6 +2,9 @@ source 'https://rubygems.org'
 
 # place all development, system_test, etc dependencies here
 
+# in the Rakefile, so we require it in all groups
+gem 'rspec'                ,'~> 3.1.0'
+
 group :system_tests do
   #gem 'beaker', :path => "../../beaker/"
   gem 'beaker'               ,'~> 2.22'
@@ -9,13 +12,13 @@ group :system_tests do
 end
 
 group :development do
-  gem 'rspec'                ,'~> 3.1.0'
   gem 'simplecov'
   #Documentation dependencies
   gem 'yard'                 ,'~> 0'
   gem 'markdown'             ,'~> 0'
   # restrict version to enable ruby 1.9.3
   gem 'mime-types'           ,'~> 2.0'
+  gem 'google-api-client'    ,'<= 0.9.4'
 end
 
 local_gemfile = "#{__FILE__}.local"

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    rototiller (0.0.0.b)
-      rake
+    rototiller (0.1.0)
+      rake (>= 0.9.0)
 
 GEM
   remote: https://rubygems.org/
@@ -268,6 +268,7 @@ PLATFORMS
 DEPENDENCIES
   beaker (~> 2.22)
   beaker-hostgenerator
+  google-api-client (<= 0.9.4)
   markdown (~> 0)
   mime-types (~> 2.0)
   rototiller!

data/README.md

@@ -1,57 +1,180 @@
-# rototiller
+# Rototiller
 
-A shared rake task library for use at Puppet.
-Goals of Rototiller
+A [Rake](https://github.com/ruby/rake) helper for command-oriented tasks.
 
-* Provide a tool that can house shared rake task code for Puppet Labs.  
-
-* Reduce duplication in rakefiles across projects at Puppet Labs.
+:warning: This version of Rototiller should be considered of _beta_ quality.
+It is already known that the API will change quite a bit for the next release.
+Please see the notes at the top of the [Write](#write) section.
 
+* simplifies the building of command strings in :rototiller_task for task authors
+* abstracts the overriding of command string components: commands, flags, arguments for task users
+* unifies and standardizes messaging surrounding the use of environment variables for task operations
+* Provides a tool that can house shared rake task code for Puppet.
+* Reduce duplication in Rakefiles across projects at Puppet.
 * Reduce effort required to write first class rake tasks.
-
-* Reduce time and effort trying to understand requirement to run rake tasks. 
-
+* Reduce time and effort trying to understand requirement to run rake tasks.
 * Provide a standard interface for executing tests in a given test tier regardless of framework (Not MVP)
 
-## Classes & Modules under development
-For more detailed documentation please refer to the yard docs.  
-
-####[EnvVar](lib/rototiller/utilities/env_var.rb)
-
-  A class that tracks the state of an ENV variable.  
-  This class is responsible for formatting its own messaging, the value that should be used, and if a task should stop.  
-    
-####[Flag](lib/rototiller/utilities/flag.rb)
-
-   A class that tracks the desired state of command line flags used in test invocation.  
-   The desired state of these flags is determined by the user.  
-    
-####[ParamCollection](lib/rototiller/utilities/param_collection.rb)
-
-  A class to contain EnvVar and Flag classes.  
-  Behaves similar to an Array.  
-    
-####[RototillerTask](lib/rototiller/task/rototiller_task.rb)
-
-  A class used to build a rake task.  
-  Similar in approach to [RSpec::Core::RakeTask](https://github.com/rspec/rspec-core/blob/master/lib/rspec/core/rake_task.rb)  
-    
-####[CLIFlags](lib/rototiller/task/flags/cli_flags.rb)
-
-  A class to contain the known CLI flags.
+<a name="install"></a>
+## Install
+    gem install rototiller
+
+<a name="write"></a>
+## Write
+Rototiller provides a Rake DSL addition called 'rototiller_task' which is a fully featured Rake task with environment variable handling, messaging and command-string-building functionality.
+
+:warning: The API below will change for the next release.
+The known changes include (not comprehensive):
+* moving `#add_flag` to `Command` and renaming it `#add_option`
+* adding `#add_env` to `Command` and `#add_option`, so one can add multiple environment variables
+* adding `#add_switch` to Command so one does not have to use the `:is_boolean` parameter for `#add_flag`
+* adding some sort of env_var type so one does not have to use the `:required` parameter for `#add_flag`
+* the above will allow for multiple commands in a task with independent option, switch, and environment variable tracking
+
+Examples (see the [Use](#use) section for outputs):
+    require 'rototiller'
+
+    desc "task dependencies work. this one also uses an environment variable"
+    rototiller_task :parent_task do |task|
+      # most method initializers take either a hash, or block syntax (see next task)
+      task.add_env({:name     => 'RANDOM_VAR', :default => 'default value'})
+      task.add_command({:name => "echo 'i am testing everything with $RANDOM_VAR = #{ENV['RANDOM_VAR']}'"})
+    end
+
+    desc "override command-name with environment variable"
+    rototiller_task :test => :parent_task do |task|
+      # block syntax here. We give up some lines for more readability
+      task.add_command do |cmd|
+        cmd.name         = 'test'
+        cmd.override_env = 'ECHO_EXECUTABLE'
+      end
+      task.add_flag({:name => '-f', :default => 'Rakefile'})
+    end
+
+    desc "override flag values with environment variables"
+    rototiller_task :test_flag_env do |task|
+      task.add_command do |cmd|
+        cmd.name = 'test'
+      end
+      task.add_flag do |flag|
+        flag.name         = '-f'
+        flag.default      = 'Rakefile'
+        flag.override_env = 'FLAG_VALUE'
+      end
+    end
+
+    desc "do not include flag if the final value (either the default or override_env) is nil or empty and not required. add and control switches or boolean flags"
+    rototiller_task :test_flag_env do |task|
+      task.add_command do |cmd|
+        cmd.name = 'test'
+      end
+      task.add_flag do |flag|
+        flag.name         = '-f'
+        flag.default      = ''
+        flag.override_env = 'FLAG_VALUE'
+        flag.required     = false
+      end
+      # examples:
+      # add a boolean option (switch)
+      #task.add_flag({:name => '--switch1', :is_boolean => true})
+      # add a switch which defaults to "off"
+      #task.add_flag({:name => '-s',  :default => '', :is_boolean => true})
+      # add a switch with environment override
+      #task.add_flag({:name => '--switch3', :is_boolean => true, :override_env => 'TEST_FLAG_ENV_SWITCH3'})
+    end
+
+
+    desc "override command argument values with environment variables"
+    rototiller_task :test_arg_env do |task|
+      task.add_command do |cmd|
+        cmd.name                  = 'ls'
+        cmd.argument              = 'Rakefile'
+        cmd.argument_override_env = 'FILENAME'
+      end
+    end
+
+<a name="use"></a>
+## Use
+(with the above sample Rakefile)
+
+    $) rake -T
+    rake parent_task  # some parent task
+    rake test         # test all the things
+
+    $) rake -D
+    rake parent_task
+        task dependencies work. this one also uses an environment variable
+    rake test
+        override command-name with environment variable
+
+    # added environment variable defaults are set, implicitly, if not found
+    #   this way, their value can be used in the task
+    $) rake test
+    INFO: The environment variable: 'RANDOM_VAR' was found with value: 'default value':
+    i am testing everything with $RANDOM_VAR = default value
+    The CLI flag -f will be used with value Rakefile.
+
+    $) rake parent_task RANDOM_VAR=redrum
+    INFO: The environment variable: 'RANDOM_VAR' was found with value: 'redrum':
+    i am testing everything with $RANDOM_VAR = redrum
+
+    $) rake test ECHO_EXECUTABLE='ls' --verbose
+    INFO: The environment variable: 'RANDOM_VAR' was found with value: 'default value':
+    echo 'i am testing everything with $RANDOM_VAR = default value'
+    i am testing everything with $RANDOM_VAR = default value
+    The CLI flag -f will be used with value Rakefile.
+
+    ls -f Rakefile
+    Rakefile
+
+    $) rake test_flag_env
+    The CLI flag -f will be used with value Rakefile.
+    $) echo $?
+    0
+
+    $) rake test_flag_env --verbose
+    The CLI flag -f will be used with value Rakefile.
+
+    test -f Rakefile
+
+    $) rake test_flag_env --verbose FLAG_VALUE='README.md'
+    The CLI flag -f will be used with value README.md.
+
+    test -f README.md
+
+    $) rake test_flag_env --verbose FLAG_VALUE='nonesuch'
+    The CLI flag -f will be used with value README.md.
+
+    test -f README.md
+    test -f nonesuch failed
+
+    $) rake test_arg_env
+    Rakefile
+
+    $) rake test_arg_env FILENAME=README.md
+    README.md
+
+## Issues
+
+* none. it's perfect
+* [Jira: Rototiller](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20QA)
 
 ## More Documentation
 
-
-Rototiller is documented using yard 
-to view yard docs
+Rototiller is documented using yard
+to view yard docs, including internal Classes and Modules:
 
 First build a local copy of the gem
 
-    $ bundle exec rake build 
-    
+    $) bundle exec rake build
+
 Next start the yard server
 
-    $ bundle exec yard server
-    
-Finally navigate to http://0.0.0.0:8808/ to view the documentation
+    $) bundle exec yard server
+
+Finally navigate to http://0.0.0.0:8808/ to view the documentation
+
+## Maintainers
+* [Zach Reichert](zach.reichert@puppetlabs.com), github:[zreichert](https://github.com/zreichert), jira:zach.reichert
+* [Eric Thompson](erict@puppetlabs.com), github:[er0ck](https://github.com/er0ck), jira:erict
+* [QA](qa-team@puppetlabs.com)

data/Rakefile

@@ -1,56 +1,72 @@
 require "bundler/gem_tasks"
 require 'rspec/core/rake_task'
+require 'rototiller'
 
 task :default => :test
 
 desc "Run spec tests"
 RSpec::Core::RakeTask.new(:test) do |t|
   t.rspec_opts = ['--color']
-  t.pattern = 'spec/'
+  t.pattern = ENV['SPEC_PATTERN']
 end
 
+task :test => [:check_test]
+
 task :generate_host_config do |t, args|
-  if ENV["BEAKER_CONFIG"]
-    next
-  end
 
   target = ENV["TEST_TARGET"] || 'centos7-64'
-  generate = "bundle exec beaker-hostgenerator"
+  generate = "beaker-hostgenerator"
   generate += " #{target}"
   generate += " > acceptance/hosts.cfg"
   sh generate
   sh "cat acceptance/hosts.cfg"
 end
 
-task acceptance: :generate_host_config
-
-desc 'Run acceptance tests for Rototiller'
-task :acceptance do |t, args|
-
-  config = ENV["BEAKER_CONFIG"] || 'acceptance/hosts.cfg'
-
-  preserve_hosts = ENV["BEAKER_PRESERVEHOSTS"] || 'never'
-  type = 'pe'
-  keyfile = ENV["BEAKER_KEYFILE"] || "#{ENV['HOME']}/.ssh/id_rsa-acceptance"
-  load_path = ENV["BEAKER_LOADPATH"] || 'acceptance/lib'
-  pre_suite = ENV["BEAKER_PRESUITE"] || 'acceptance/pre-suite'
-  post_suite = ENV["BEAKER_POSTSUITE"] || ''
-  test_suite = ENV["BEAKER_TESTSUITE"] || 'acceptance/tests'
-  opts = ENV["BEAKER_OPTS"] || ''
-
-  beaker = "bundle exec beaker "
-  beaker += " --xml"
-  beaker += " --debug"
-  beaker += " --root-keys"
-  beaker += " --repo-proxy"
-  beaker += " --preserve-hosts #{preserve_hosts}" if preserve_hosts != ''
-  beaker += " --config #{config}" if config != ''
-  beaker += " --type #{type}" if type != ''
-  beaker += " --keyfile #{keyfile}" if keyfile != ''
-  beaker += " --load-path #{load_path}" if load_path != ''
-  beaker += " --pre-suite #{pre_suite}" if pre_suite != ''
-  beaker += " --post-suite #{post_suite}" if post_suite != ''
-  beaker += " --tests #{test_suite}" if test_suite != ''
-  beaker += " #{opts}" if opts != ''
-  sh beaker
+rototiller_task :acceptance => [:generate_host_config] do |t|
+  # with a hash
+  t.add_env({:name => 'TEST_TARGET',:default => 'centos7-64', :message => 'The argument to pass to beaker-hostgenerator'})
+
+  # with new block syntax
+  t.add_flag do |flag|
+    flag.name = '--hosts'
+    flag.default = 'acceptance/hosts.cfg'
+    flag.message = 'The configuration file that Beaker will use'
+    flag.override_env = 'BEAKER_HOSTS'
+  end
+  t.add_flag do |flag|
+    flag.name = '--preserve-hosts'
+    flag.default = 'onfail'
+    flag.message = 'The beaker setting to preserve a provisioned host'
+    flag.override_env = 'BEAKER_PRESERVE-HOSTS'
+  end
+  t.add_flag do |flag|
+    flag.name = '--keyfile'
+    flag.default ="#{ENV['HOME']}/.ssh/id_rsa-acceptance"
+    flag.message = 'The SSH key used to access a SUT'
+    flag.override_env = 'BEAKER_KEYFILE'
+  end
+  t.add_flag do |flag|
+    flag.name = '--load-path'
+    flag.default = 'acceptance/lib'
+    flag.message = 'The load path Beaker will use'
+    flag.override_env = "BEAKER_LOAD-PATH"
+  end
+  t.add_flag do |flag|
+    flag.name = '--pre-suite'
+    flag.default = 'acceptance/pre-suite'
+    flag.message = 'THe path to a directory containing pre-suites'
+    flag.override_env = "BEAKER_PRE-SUITE"
+  end
+  t.add_flag do |flag|
+    flag.name = '--tests'
+    flag.default = 'acceptance/tests'
+    flag.message = 'The path to the tests you want beaker to run'
+    flag.override_env = 'BEAKER_TESTS'
+  end
+
+  t.add_command({:name => 'beaker --debug', :override_env => 'BEAKER_EXECUTABLE'})
+end
+
+Rototiller::Task::RototillerTask.define_task :check_test do |t|
+  t.add_env({:name => 'SPEC_PATTERN', :default => 'spec/', :message => 'The pattern RSpec will use to find tests'})
 end

data/Rakefile.bak

@@ -0,0 +1,72 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+require 'rototiller'
+
+task :default => :test
+
+desc "Run spec tests"
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.rspec_opts = ['--color']
+  t.pattern = ENV['SPEC_PATTERN']
+end
+
+task :test => [:check_test]
+
+task :generate_host_config do |t, args|
+
+  target = ENV["TEST_TARGET"] || 'centos7-64'
+  generate = "beaker-hostgenerator"
+  generate += " #{target}"
+  generate += " > acceptance/hosts.cfg"
+  sh generate
+  sh "cat acceptance/hosts.cfg"
+end
+
+rototiller_task :acceptance => [:generate_host_config] do |t|
+  # with a hash
+  t.add_env({:name => 'TEST_TARGET',:default => 'centos7-64', :message => 'The argument to pass to beaker-hostgenerator'})
+
+  # with new block syntax
+  t.add_flag do |flag|
+    flag.name = '--hosts'
+    flag.default = 'acceptance/hosts.cfg'
+    flag.message = 'The configuration file that Beaker will use'
+    flag.override_env = 'BEAKER_HOSTS'
+  end
+  t.add_flag do |flag|
+    flag.name = '--preserve-hosts'
+    flag.default = 'onfail'
+    flag.message = 'The beaker setting to preserve a provisioned host'
+    flag.override_env = 'BEAKER_PRESERVE-HOSTS'
+  end
+  t.add_flag do |flag|
+    flag.name = '--keyfile'
+    flag.default ="#{ENV['HOME']}/.ssh/id_rsa-acceptance"
+    flag.message = 'The SSH key used to access a SUT'
+    flag.override_env = 'BEAKER_KEYFILE'
+  end
+  t.add_flag do |flag|
+    flag.name = '--load-path'
+    flag.default = 'acceptance/lib'
+    flag.message = 'The load path Beaker will use'
+    flag.override_env = "BEAKER_LOAD-PATH"
+  end
+  t.add_flag do |flag|
+    flag.name = '--pre-suite'
+    flag.default = 'acceptance/pre-suite'
+    flag.message = 'THe path to a directory containing pre-suites'
+    flag.override_env = "BEAKER_PRE-SUITE"
+  end
+  t.add_flag do |flag|
+    flag.name = '--tests'
+    flag.default = 'acceptance/tests'
+    flag.message = 'The path to the tests you want beaker to run'
+    flag.override_env = 'BEAKER_TESTS'
+  end
+
+  t.add_command({:name => 'beaker --debug', :override_env => 'BEAKER_EXECUTABLE'})
+end
+
+Rototiller::Task::RototillerTask.define_task :check_test do |t|
+  t.add_env({:name => 'SPEC_PATTERN', :default => 'spec/', :message => 'The pattern RSpec will use to find tests'})
+end

data/lib/rototiller/rake/dsl/dsl_extention.rb

@@ -3,12 +3,8 @@ require 'rototiller/task/rototiller_task'
 module Rake
   module DSL
 
-    def acceptance_task(*args, &block)
-      # Default task description
-      # can be overridden with 'desc' method
-      desc "Tests in the 'Acceptance' tier" unless ::Rake.application.last_comment
-      Rototiller::Task::RototillerTask.define_task :acceptance, &block
+    def rototiller_task(*args, &block)
+      Rototiller::Task::RototillerTask.define_task(*args, &block)
     end
-
   end
 end

data/lib/rototiller/task/rototiller_task.rb

@@ -2,13 +2,17 @@ require 'rototiller/utilities/env_var'
 require 'rototiller/utilities/param_collection'
 require 'rototiller/utilities/env_collection'
 require 'rototiller/utilities/flag_collection'
+require 'rototiller/utilities/command_flag'
+require 'rototiller/utilities/command'
+require 'rototiller/utilities/block_syntax_object'
 require 'rake/tasklib'
 
 module Rototiller
   module Task
     class RototillerTask < ::Rake::TaskLib
-      attr_accessor :name
-      attr_accessor :command
+      #TODO rename instance vars and methods to not match sub blocks
+      attr_reader :name
+      attr_reader :command
 
       # Whether or not to fail Rake when an error occurs (typically when
       # examples fail). Defaults to `true`.
@@ -20,7 +24,9 @@ module Rototiller
       def initialize(*args, &task_block)
         @name          = args.shift
         @fail_on_error = true
-        @command       = 'echo empty RototillerTask. You should define a command, send a block, or EnvVar to track.'
+        #TODO refactor or remove
+        @command = Rototiller::Command.new
+        @command.name = 'echo empty RototillerTask. You should define a command, send a block, or EnvVar to track.'
         # rake's in-task implied method is true when using --verbose
         @verbose       = verbose == true
         @env_vars      = EnvCollection.new
@@ -35,29 +41,72 @@ module Rototiller
         self.new(*args, &task_block)
       end
 
-      #TODO add arg validation to EnvVar and CommandFlag
-      # add_env(EnvVar.new(), EnvVar.new(), EnvVar.new())
-      # add_env('FOO', 'This is how you use FOO', 'default_value')
-      def add_env(*args)
-        args.all?{ |arg| arg.is_a?(EnvVar)} ? @env_vars.push(*args) : @env_vars.push(EnvVar.new(*args))
+      # adds environment variables to be tracked
+      # @param [Hash] args hashes of information about the environment variable
+      # @option args [String] :name The environment variable
+      # @option args [String] :default The default value for the environment variable
+      # @option args [String] :message A message describing the use of this variable
+      # @option args [Boolean] :required Is used internally by CommandFlag, ignored for a standalone EnvVar
+      #
+      # for block {|a| ... }
+      # @yield [a] Optional block syntax allows you to specify information about the environment variable, available methods track hash keys
+      def add_env(*args,&block)
+        raise ArgumentError.new("add_env takes a block or a hash") if !args.empty? && block_given?
+        attributes = [:name, :default, :message, :required]
+        add_param(@env_vars, EnvVar, attributes, args, {:set_env => true}, &block)
       end
 
-      #TODO add arg validation to CommandFlag
-      # add_flag(CommandFlag.new(), CommandFlag.new(), CommandFlag.new())
-      # add_flag('--foo', 'This is how you use --foo', 'default_value')
-      def add_flag(*args)
-        args.all?{ |arg| arg.is_a?(CommandFlag)} ? @flags.push(*flags) : @flags.push(CommandFlag.new(*args))
+      # adds command line flags to be used in a command
+      # @param       [Hash]   args          hashes of information about the command line flag
+      # @option args [String] :name         The command line flag
+      # @option args [String] :value        The value for the command line flag
+      # @option args [String] :message      A message describing the use of this command line flag
+      # @option args [String] :override_env An environment variable used to override the flag value
+      # @option args [Boolean] :required    Indicates whether an error should be raised
+      #                                     if the value is nil or empty string, vs not including the flag.
+      # @option args [Boolean] :is_boolean  Is the flag really a switch? Is it a boolean-flag?
+      #
+      # for block {|a| ... }
+      # @yield [a] Optional block syntax allows you to specify information about the command line flag, available methods track hash keys
+      def add_flag(*args, &block)
+        raise ArgumentError.new("add_flag takes a block or a hash") if !args.empty? && block_given?
+        attributes = [:name, :default, :message, :override_env, :required, :is_boolean]
+        add_param(@flags, CommandFlag, attributes, args, &block)
+      end
+
+      # adds command to be executed by task
+      # @param [Hash] args hash of information about the command to be executed
+      # @option arg [String] :name The command to be executed
+      # @option arg [String] :override_env An environment variable used to override the command to be executed by the task
+      #
+      # for block {|a| ... }
+      # @yield [a] Optional block syntax allows you to specify information about command, available methods track hash keys
+      def add_command(args={}, &block)
+        attributes = [:name, :override_env, :argument, :argument_override_env]
+        if block_given?
+          attribute_hash = pull_params_from_block(attributes, &block).to_h
+        else
+          attribute_hash = args
+        end
+        @command = Rototiller::Command.new(attribute_hash)
       end
 
       private
 
       # @private
-      def run_task
+      def print_messages
         puts @flags.format_messages
         puts @env_vars.format_messages
-        exit if @env_vars.stop?
+        exit_code = 1
+        exit exit_code if @env_vars.stop? || @flags.stop?
+      end
 
-        command_str = @command << @flags.to_s
+      # @private
+      def run_task
+        print_messages
+        command_str = [
+            (@command.name if @command.name), @flags.to_s, (@command.argument if @command.argument)
+        ].delete_if{ |i| [nil, '', false].any?{|forbidden| i == forbidden}}.join(' ')
         puts command_str if @verbose
 
         return if system(command_str)
@@ -75,7 +124,7 @@ module Rototiller
       def define(args, &task_block)
         # Default task description
         # can be overridden with standard 'desc' DSL method
-        desc "RototillerTask: A Task with optional environment variable and command flag tracking" unless ::Rake.application.last_comment
+        desc 'RototillerTask: A Task with optional environment-variable and command-flag tracking' unless ::Rake.application.last_description
 
         task(@name, *args) do |_, task_args|
           RakeFileUtils.__send__(:verbose, @verbose) do
@@ -90,6 +139,34 @@ module Rototiller
       def set_verbose(verbosity=true)
         @verbose = verbosity
       end
+
+      # @private
+      def add_param(collection, param_class, param_array, args, opts={}, &block)
+
+        if block_given?
+
+          param_hash = pull_params_from_block(param_array, &block).to_h
+          param_hash[:set_env] = true if opts[:set_env]
+          collection.push(param_class.new(param_hash))
+        else
+
+          args.each do |arg|
+
+            #FIXME: add a test for this
+            raise ArgumentError.new("Argument must be a Hash. Received: '#{arg.class}'") unless arg.is_a?(Hash)
+            arg[:set_env] = true if opts[:set_env]
+            collection.push(param_class.new(arg))
+          end
+        end
+      end
+
+      # @private
+      def pull_params_from_block(param_array, &block)
+
+        block_syntax_obj = Rototiller::Block_syntax.new(param_array)
+        yield(block_syntax_obj)
+        block_syntax_obj
+      end
     end
   end
 end

data/lib/rototiller/utilities/block_syntax_object.rb

@@ -0,0 +1,16 @@
+module Rototiller
+  class Block_syntax
+
+    def initialize(param_array)
+      self.class.class_eval { param_array.each { |i| attr_accessor i } }
+    end
+
+    def to_h
+      h = Hash.new
+      self.instance_variables.each do |var|
+        h[var.to_s.delete('@').to_sym] = self.instance_variable_get(var)
+      end
+      h
+    end
+  end
+end

data/lib/rototiller/utilities/command.rb

@@ -0,0 +1,43 @@
+require 'rototiller/utilities/env_var'
+module Rototiller
+  class Command
+
+    include ColorText
+
+    # @return [String] the command to be used, could be considered a default
+    attr_accessor :name
+
+    # @return [EnvVar] the ENV that is equal to this command
+    attr_reader :override_env
+
+    # @return [String, nil] the value that should be used as an argument to the given command
+    attr_reader :argument
+
+    # @return [EnvVar] the ENV that is equal to the argument to be used with this command
+    attr_reader :argument_override_env
+
+    # Creates a new instance of CommandFlag, holds information about desired state of a command
+    # @param [Hash] attribute_hash hashes of information about the command
+    # @option attribute_hash [String] :command The command
+    # @option attribute_hash [String] :override_env The environment variable that can override this command
+    def initialize(attribute_hash = {})
+
+      # check if an override_env is provided
+      if attribute_hash[:override_env]
+        @override_env = EnvVar.new({:name => attribute_hash[:override_env], :default => attribute_hash[:name]})
+        @name = @override_env.value
+      else
+        @name = attribute_hash[:name]
+      end
+
+      # check if an argument_override_env is provided
+      if attribute_hash[:argument_override_env]
+        @argument_override_env = EnvVar.new({:name => attribute_hash[:argument_override_env], :default => attribute_hash[:argument]})
+        @argument = @argument_override_env.value
+      else
+        @argument = attribute_hash[:argument]
+      end
+    end
+  end
+end
+

data/lib/rototiller/utilities/command_flag.rb

@@ -1,4 +1,5 @@
 require 'rototiller/utilities/color_text'
+require 'rototiller/utilities/env_var'
 
 class CommandFlag
 
@@ -10,26 +11,113 @@ class CommandFlag
   # @return [true, false, nil, String] the value if any of the flag
   attr_reader :value
 
+  # @return [EnvVar] the ENV that is equal to this flag
+  attr_reader :override_env
+
+  # @return [Boolean] whether the flag is required or not
+  attr_reader :required
+
+  # @return [true, nil] if the state of the EnvVar requires the task to stop
+  attr_reader :stop
+
+  # @return [true, nil] if this flag/option is really a switch (boolean flag)
+  attr_reader :is_boolean
+
   # Creates a new instance of CommandFlag, holds information about desired state of a CLI flag
-  # @param flag [String] the flag to be set on a CLI '-v' or '--verbose'
-  # @param message [String] the message describing the Flag
-  # @param value [String] the value to use as the value if one is required
-  def initialize(flag, value=nil, message)
-    @flag = flag
-    @message = message
-    @value = value
+  # @param [Hash] attribute_hash hashes of information about the command line flag
+  # @option attribute_hash [String] :name         The command line flag
+  # @option attribute_hash [String] :value        The value for the command line flag
+  # @option attribute_hash [String] :message      A message describing the use of this command line flag
+  # @option attribute_hash [String] :override_env The environment variable that can override this flags value
+  # @option attribute_hash [Boolean] :is_boolean Is the flag really a switch? Is it a boolean-flag?
+  # @option attribute_hash [Boolean] :required Indicates whether an error should be raised
+  # if the final value is nil or empty string, vs not including the flag.
+  def initialize(attribute_hash)
+    validate_attribute_hash(attribute_hash)
+
+    @original_name = attribute_hash[:name]
+    @message       = attribute_hash[:message]
+    @is_boolean    = attribute_hash[:is_boolean] || false
+
+    # handle :required
+    attribute_hash[:required].is_a?(String) ? attribute_hash[:required] = (attribute_hash[:required].downcase == 'true') : attribute_hash[:required]
+    @required = ( !!attribute_hash[:required] == attribute_hash[:required] ? attribute_hash[:required] : true)
+
+    # handle the flag/switch name
+    if attribute_hash[:name] && !attribute_hash[:is_boolean]
+      @flag = attribute_hash[:name]
+    else
+      # default takes precedence in case the default state is "off" aka: empty
+      default_value = attribute_hash[:default] || attribute_hash[:name]
+
+      # FIXME: whoa complexity.  see fixme below
+      #   this looks a lot like below.  we need a method to handle override_env and the logic here for switches vs. options
+      #   but we're just gonna rip all this out when CommandSwitch inherits from future CommandOption
+      if attribute_hash[:override_env]
+        # Create a new EnvVar instance and ask it what the value is
+        @override_env = EnvVar.new({:name => attribute_hash[:override_env], :default => default_value})
+        @flag = @override_env.value
+      else
+        @flag = default_value
+      end
+    end
+
+    # FIXME: this is getting complex. we should not be doing all these complex if/then in here
+    #   we should inherit from CommandOption to form CommandSwitch which overrides is_boolean
+    #   make is_boolean protected (private within a module, parent/child, or similar)
+    if @is_boolean
+      @value = ''
+    else
+      if attribute_hash[:default] && !attribute_hash[:override_env]
+        # the default is the implied hard coded value
+        @value = attribute_hash[:default]
+      else
+        # Create a new EnvVar instance and ask it what the value is
+        @override_env = EnvVar.new({:name => attribute_hash[:override_env], :default => attribute_hash[:default], :required => @required})
+
+        @value = @override_env.value
+        @stop = @override_env.stop
+      end
+    end
   end
 
   # The formatted message to be displayed to the user
   # @return [String] the CommandFlag's message, formatted with color
   def message
-    green_text(@message) << "\n" << describe_flag_state
+    @message ? green_text(@message) << "\n" << describe_flag_state : describe_flag_state
   end
 
   private
   def describe_flag_state
-    only_flag = "The CLI flag #{@flag} will be used, no value was provided."
-    flag_with_value = "The CLI flag #{@flag} will be used with value #{@value}."
-    green_text(@value.nil? ? only_flag : flag_with_value)
+    if @stop
+      required_env = "The CLI flag '#{@flag}' needs a value.\nYou can specify this value with the environment variable '#{override_env.var}'"
+      return red_text(required_env)
+    elsif !@required && (@value.nil? || @value.empty?)
+      flag_without_value = "The CLI flag #{@flag} has no value assigned and will not be included."
+      return yellow_text(flag_without_value)
+    else
+      if @is_boolean
+        has_flag_name = (@flag != '') && (@flag != nil)
+        if has_flag_name
+          flag_with_value = "The CLI switch '#{@flag}' will be used."
+        else
+          flag_with_value = "The CLI switch '#{@original_name}' will NOT be used."
+          return yellow_text(flag_with_value)
+        end
+      else
+        flag_with_value = "The CLI flag '#{@flag}' will be used with value '#{@value}'."
+      end
+      return green_text(flag_with_value)
+    end
+  end
+
+  def validate_attribute_hash(h)
+    # validate the contents of the hash
+    error = String.new
+    error << "A 'name' is required\n" unless h[:name]
+    error << "Cannot use 'required' with 'is_boolean'\n" unless !(h[:required] && h[:is_boolean])
+    error << "Must specify a 'default' or an 'override_env' unless 'is_boolean' is true\n" unless h[:default] || h[:override_env] || h[:is_boolean]
+
+    raise(ArgumentError, error) unless error.empty?
   end
 end

data/lib/rototiller/utilities/env_collection.rb

@@ -7,9 +7,4 @@ class EnvCollection < ParamCollection
     super
   end
 
-  # Do any of the contents of this ParamCollection require the task to stop
-  # @return [true, nil] should the values of this ParamCollection stop the task
-  def stop?
-    @collection.any?{ |param| param.stop }
-  end
 end

data/lib/rototiller/utilities/env_var.rb

@@ -1,10 +1,20 @@
 require 'rototiller/utilities/color_text'
 
 class EnvVar
-
+  MESSAGE_TYPES = {:nodefault_noexist=>0, :exist=>1, :default_noexist=>2, :not_required=>3}
   include ColorText
 
-  attr_accessor :var, :message, :default
+  # @return [String] the value of the :name argument
+  attr_accessor :var
+
+  # @return [String] the value of the :message argument
+  attr_accessor :message
+
+  # @return [String] the value of the :default argument
+  attr_accessor :default
+
+  # @return  [true, nil] If the env_var should error if no value is set. Used internally by CommandFlag, ignored for standalone EnvVar.
+  attr_reader :required
 
   # @return [Symbol] the debug level of the message, ':warning', ':error', ':info'
   attr_reader :message_level
@@ -12,51 +22,109 @@ class EnvVar
   # @return [true, nil] if the state of the EnvVar requires the task to stop
   attr_reader :stop
 
+  # @return [String] the value of the ENV based on specified default and environment state
+  attr_reader :value
+
   # Creates a new instance of EnvVar, holds information about the ENV in the environment
-  # @param var [String] the ENV in the environment, 'HOME'
-  # @param message [String] the message describing the ENV
-  # @param default [String] the value to use as the default if the ENV is not present
-  def initialize(var, default=false, message)
-    @var = var
-    @message = message
-    @default = default
-    set_message_level
-  end
+  # @param [Hash] attribute_hash hash of information about the environment variable
+  # @option attribute_hash [String] :name The environment variable
+  # @option attribute_hash [String] :default The default value for the environment variable
+  # @option attribute_hash [String] :message A message describing the use of this variable
+  # @option attribute_hash [Boolean] :required Used internally by CommandFlag, ignored for a standalone EnvVar
+  def initialize(attribute_hash)
+    raise(ArgumentError, 'A name must be supplied to add_env') unless attribute_hash[:name]
+    @var = attribute_hash[:name]
+    @message = attribute_hash[:message]
+    @default = attribute_hash[:default]
+    @set_env = attribute_hash[:set_env] || false
+    attribute_hash[:required].is_a?(String) ? attribute_hash[:required] = (attribute_hash[:required].downcase == 'true') : attribute_hash[:required]
+    @required = ( !!attribute_hash[:required] == attribute_hash[:required] ? attribute_hash[:required] : true)
 
-  # The value of the ENV determined by the EnvVar class
-  # @return [String] the value determined by the EnvVar class
-  def value
-    ENV[@var] || @default
+    reset
   end
 
   # The formatted message to be displayed to the user
   # @return [String] the EnvVar's message, formatted for color and meaningful to the state of the EnvVAr
   def message
     if message_level == :error
-      red_text("The ENV #{@var} is required, #{@message}")
+      level_str = 'ERROR:'
     elsif message_level == :info
-      green_text("The ENV #{@var} was found in the environment with the value #{value}")
+      level_str = 'INFO:'
     elsif message_level == :warning
-      yellow_text("WARNING: the ENV #{@var} is not set, proceeding with default value: #{@default}")
+      level_str = 'WARNING:'
+    end
+    message_prepend = "#{level_str} The environment variable: '#{@var}'"
+    if get_message_type == MESSAGE_TYPES[:default_noexist]
+      return yellow_text("#{message_prepend} is not set. Proceeding with default value: '#{@default}': #{@message}")
+    end
+    if get_message_type == MESSAGE_TYPES[:not_required]
+      return yellow_text("#{message_prepend} is not set, but is not required. Proceeding with no flag: #{@message}")
+    end
+    if get_message_type == MESSAGE_TYPES[:exist]
+      return green_text("#{message_prepend} was found with value: '#{ENV[@var]}': #{@message}")
     end
+    if get_message_type == MESSAGE_TYPES[:nodefault_noexist]
+      return red_text("#{message_prepend} is required: #{@message}")
+    end
+  end
+
+  # If any of these variables are assigned a new value after this object's creation, reset @value and @message_level.
+  def var=(var)
+    @var = var
+    reset
+  end
+
+  def default=(default)
+    @default = default
+    reset
+  end
+
+  def message=(message)
+    @message = message
+    reset
+  end
+
+  def required=(required)
+    @required = required
+    reset
   end
 
   private
+  def reset
+    # TODO should an env automatically set the ENV?
+    @value = ENV[@var] || @default
+    ENV[@var] = @value if @set_env
+    set_message_level
+  end
+
   def check
     ENV.key?(@var)
   end
 
-  def set_message_level
-    if !@default && !check
+  def get_message_type
+    if (value.nil? || value.empty?) && !required
+      MESSAGE_TYPES[:not_required]
+    elsif !@default && !check
       # ENV is not Present and it has no default value
-      @message_level = :error
-      @stop = true
-    elsif !@default && check || @default && check
-      # ENV is present and it has no default value
-      @message_level = :info
+      MESSAGE_TYPES[:nodefault_noexist]
+    elsif check
+      # ENV is present; may or may not have default, who cares
+      MESSAGE_TYPES[:exist]
     elsif @default && !check
       # ENV is not present and it has default value
-      @message_level = :warning
+      MESSAGE_TYPES[:default_noexist]
+    end
+  end
+
+  def set_message_level
+    case get_message_type
+      when MESSAGE_TYPES[:nodefault_noexist]
+        @message_level = :error
+        @stop = true
+      when MESSAGE_TYPES[:exist], MESSAGE_TYPES[:default_noexist], MESSAGE_TYPES[:not_required]
+        @message_level = :info
+      else
+        raise 'EnvVar: message type not supported'
     end
   end
 end

data/lib/rototiller/utilities/flag_collection.rb

@@ -14,13 +14,15 @@ class FlagCollection < ParamCollection
     flag_str = String.new
 
     @collection.each do |flag|
-      if flag.value.nil?
-        flag_str << ' ' << flag.flag
+      if (flag.value.nil? || flag.value.empty?) && !flag.required
+        #do nothing
+      elsif flag.value.nil?
+        flag_str << flag.flag << ' '
       else
-        flag_str << ' ' << flag.flag << ' ' << flag.value
+        flag_str << flag.flag << ' ' << flag.value << ' '
       end
     end
 
-    flag_str
+    flag_str.rstrip
   end
 end

data/lib/rototiller/utilities/param_collection.rb

@@ -63,5 +63,11 @@ class ParamCollection
     end
   end
 
+  # Do any of the contents of this ParamCollection require the task to stop
+  # @return [true, nil] should the values of this ParamCollection stop the task
+  def stop?
+    @collection.any?{ |param| param.stop }
+  end
+
   private :filter_contents, :check_classes
 end

data/lib/rototiller/version.rb

@@ -1,5 +1,5 @@
 module Rototiller
   module Version
-    STRING = '0.0.0.b'
+    STRING = '0.1.0'
   end
 end

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: rototiller
 version: !ruby/object:Gem::Version
-  version: 0.0.0.b
+  version: 0.1.0
 platform: ruby
 authors:
-- Puppetlabs
+- Puppet Labs
+- Zach Reichert
+- Eric Thompson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-28 00:00:00.000000000 Z
+date: 2016-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -16,15 +18,15 @@ dependencies:
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
-        version: '0'
-description: Puppetlabs tool for building rake tasks
+        version: 0.9.0
+description: Puppet Labs tool for building rake tasks
 email:
 - qa@puppetlabs.com
 executables: []
@@ -36,11 +38,14 @@ files:
 - LICENSE.md
 - README.md
 - Rakefile
+- Rakefile.bak
 - lib/rototiller.rb
 - lib/rototiller/rake/dsl/dsl_extention.rb
 - lib/rototiller/task/flags/cli_flags.rb
 - lib/rototiller/task/rototiller_task.rb
+- lib/rototiller/utilities/block_syntax_object.rb
 - lib/rototiller/utilities/color_text.rb
+- lib/rototiller/utilities/command.rb
 - lib/rototiller/utilities/command_flag.rb
 - lib/rototiller/utilities/env_collection.rb
 - lib/rototiller/utilities/env_var.rb
@@ -63,14 +68,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.2
 signing_key: 
 specification_version: 4
-summary: Puppetlabs rake tool
+summary: Puppet Labs rake tool
 test_files: []
 has_rdoc: