rototiller 0.1.0 → 1.0.0

data/lib/rototiller/task/collections/command_collection.rb

@@ -0,0 +1,15 @@
+require 'rototiller/task/collections/param_collection'
+require 'rototiller/task/params/command'
+
+module Rototiller
+  module Task
+
+    class CommandCollection < ParamCollection
+      # @return [Type] allowed class for this collection (Command)
+      def allowed_class
+        Command
+      end
+    end
+
+  end
+end

data/lib/rototiller/task/collections/env_collection.rb

@@ -0,0 +1,27 @@
+require 'rototiller/task/collections/param_collection'
+require 'rototiller/task/params/env_var'
+
+module Rototiller
+  module Task
+
+    class EnvCollection < ParamCollection
+
+      # @return [Type] allowed class for this collection (EnvVar)
+      def allowed_class
+        EnvVar
+      end
+
+      # remove the nils and return the last known value
+      # @return [String] last set environment variable or default
+      def last
+        if self.any?
+          last_known_env_var = self.map{|x| x.value}.compact.last
+          # ruby converts nil to "", so guard against single non-set env vars here
+          last_known_env_var.to_s if last_known_env_var
+        end
+      end
+
+    end
+
+  end
+end

data/lib/rototiller/task/collections/option_collection.rb

@@ -0,0 +1,20 @@
+require 'rototiller/task/collections/param_collection'
+require 'rototiller/task/params/option'
+
+module Rototiller
+  module Task
+
+    # The OptionCollection class to collect more than one option for a Command
+    #   delegates to Array via inheritance from ParamCollection
+    # @since v1.0.0
+    class OptionCollection < ParamCollection
+
+      # set allowed classes to be inserted into this Collection/Array
+      # @return [Option] the collection's allowed class
+      def allowed_class
+        Option
+      end
+
+    end
+  end
+end

data/lib/rototiller/task/collections/param_collection.rb

@@ -0,0 +1,66 @@
+require 'forwardable'
+
+module Rototiller
+  module Task
+
+    # The base ParamCollection class to collect more than one parameter for a task, or other parameters
+    #   delegates to Array for most of Array's methods
+    # @since v0.1.0
+    class ParamCollection
+
+      extend Forwardable
+
+      def_delegators :@collection, :clear, :delete_if, :include?, :include, :inspect, :each, :[], :map, :any?, :compact
+
+      # setup the collection as a composed Array
+      # @return the collection
+      def initialize
+        @collection = []
+      end
+
+      # push to the collection
+      # @param [Param] args instances of the child classes allowed_class
+      # @return the new collection
+      def push(*args)
+        check_classes(allowed_class, *args)
+        @collection.push(*args)
+      end
+
+      # format the messages inside this ParamCollection
+      # @return [String] messages from the contents of this ParamCollection
+      def messages
+        @collection.map { |param| param.message }.join('')
+      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
+
+      # convert a ParamCollection to a string
+      #   the value sent by author, or overridden by any EnvVar
+      # @return [String] the Param's value
+      def to_str
+        @collection.join(' ') unless @collection.empty?
+      end
+      alias :to_s :to_str
+
+      private
+
+      #@private
+      def check_classes(allowed_klass, *args)
+
+        args.each do |arg|
+
+          unless arg.is_a?(allowed_klass)
+            argument_error = "Argument was of class #{arg.class}, Can only be of class #{allowed_klass}"
+            raise(ArgumentError, argument_error)
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/rototiller/task/collections/switch_collection.rb

@@ -0,0 +1,20 @@
+require 'rototiller/task/collections/param_collection'
+require 'rototiller/task/params/switch'
+
+module Rototiller
+  module Task
+
+    # The SwitchCollection class to collect more than one switch for a Command
+    #   delegates to Array via inheritance from ParamCollection
+    # @since v1.0.0
+    class SwitchCollection < ParamCollection
+
+      # set allowed classes to be inserted into this Collection/Array
+      # @return [Switch] the collection's allowed class
+      def allowed_class
+        Switch
+      end
+
+    end
+  end
+end

data/lib/rototiller/task/hash_handling.rb

@@ -0,0 +1,30 @@
+module Rototiller
+  module Task
+    module HashHandling
+
+      # equates methods to keys inside a hash or an array of hashes
+      # @param [Hash] hash attempt to use keys as setter or getter methods on self
+      # @raise [ArgumentError] if a key is not a valid method on self
+      def send_hash_keys_as_methods_to_self(hash)
+
+        hash = [hash].flatten
+        hash.each do |h|
+          raise ArgumentError unless h.is_a?(Hash)
+          h.each do |k, v|
+
+            method_list = self.methods
+
+            if method_list.include?(k) && method_list.include?("#{k}=".to_sym)
+              # methods that have attr_accesors
+              self.send("#{k}=", v)
+            elsif method_list.include?(k)
+              self.send(k,v)
+            else
+              raise ArgumentError.new("'#{k}' is not a valid key: #{self.class}")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rototiller/task/params.rb

@@ -0,0 +1,24 @@
+require 'rototiller/task/hash_handling'
+
+module Rototiller
+  module Task
+
+    # The base class for creating rototiller task params (commands, envs, etc)
+    # @since v0.1.0
+    # @attr [String] name The name of the param
+    # @attr [String] message The param message (for debugging/informing/logging)
+    class RototillerParam
+      include HashHandling
+
+      attr_accessor :name
+      attr_accessor :message
+
+      # we must always have a message that can be aggregated via the parent params
+      # @return [String] <empty string>
+      def message
+        return ''
+      end
+    end
+
+  end
+end

data/lib/rototiller/task/params/argument.rb

@@ -0,0 +1,9 @@
+require 'rototiller/task/params'
+
+module Rototiller
+  module Task
+
+    Argument = Switch
+
+  end
+end

data/lib/rototiller/task/params/command.rb

@@ -0,0 +1,209 @@
+require 'open3'
+require 'rototiller/task/collections/env_collection'
+require 'rototiller/task/collections/switch_collection'
+require 'rototiller/task/collections/option_collection'
+require 'rototiller/task/collections/argument_collection'
+
+module Rototiller
+  module Task
+
+    # The Command class to implement rototiller command handling
+    #   via a RototillerTask's #add_command
+    # @since v0.1.0
+    # @attr [String] name The name of the command to run
+    # @attr_reader [Struct] result A structured command result
+    #    contains members: output, exit_code and pid (from Open3.popen2e)
+    class Command < RototillerParam
+
+      # @return [String] the command to be used, could be considered a default
+      attr_accessor :name
+
+      # @return [Struct] the command results, if run
+      attr_reader :result
+
+      # Creates a new instance of Command, holds information about desired state of a command
+      # @param [Hash,Array<Hash>] args hashes of information about the command
+      # for block { |b| ... }
+      # @yield Command object with attributes matching method calls supported by Command
+      # @return Command object
+      def initialize(args={}, &block)
+        # the env_vars that override the command name
+        @env_vars      = EnvCollection.new
+        @switches      = SwitchCollection.new
+        @options       = OptionCollection.new
+        @arguments     = ArgumentCollection.new
+
+        block_given? ? (yield self) : send_hash_keys_as_methods_to_self(args)
+        # @name is the default unless @env_vars returns something truthy
+        (@name = @env_vars.last) if @env_vars.last
+      end
+
+      # adds environment variables to be tracked, messaged.
+      #   In the Command context this env_var overrides the command "name"
+      # @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
+      #                                  this is optional and defaults to the parent's `:name`
+      # @option args [String] :message A message describing the use of this variable
+      #
+      # for block {|a| ... }
+      # @yield [a] Optional block syntax allows you to specify information about the environment variable, available methods match hash keys described above
+      def add_env(*args, &block)
+        raise ArgumentError.new("#{__method__} takes a block or a hash") if !args.empty? && block_given?
+        # this is kinda annoying we have to do this for all params? (not DRY)
+        #   have to do it this way so EnvVar doesn't become a collection
+        #   but if this gets moved to a mixin, it might be more tolerable
+        if block_given?
+          # send in the name of this Param, so it can be used when no default is given to add_env
+          @env_vars.push(EnvVar.new({:parent_name => @name},&block))
+        else
+          #TODO: test this with array and non-array single hash
+          args.each do |arg| # we can accept an array of hashes, each of which defines a param
+            error_string = "#{__method__} takes an Array of Hashes. Received Array of: '#{arg.class}'"
+            raise ArgumentError.new(error_string) unless arg.is_a?(Hash)
+            # send in the name of this Param, so it can be used when no default is given to add_env
+            arg[:parent_name] = @name
+            @env_vars.push(EnvVar.new(arg))
+          end
+        end
+        @name = @env_vars.last if @env_vars.last
+      end
+
+      # adds switch(es) (binary option flags) to this Command instance with optional env_var overrides
+      # @param [Hash] args hashes of information about the switch
+      # @option args [String] :name The switch string, including any '-', '--', etc
+      # @option args [String] :message A message describing the use of this variable
+      #
+      # for block {|a| ... }
+      # @yield [a] Optional block syntax allows you to specify information about the environment variable, available methods match hash keys described above
+      def add_switch(*args, &block)
+        raise ArgumentError.new("#{__method__} takes a block or a hash") if !args.empty? && block_given?
+        # this is kinda annoying we have to do this for all params? (not DRY)
+        #   have to do it this way so EnvVar doesn't become a collection
+        #   but if this gets moved to a mixin, it might be more tolerable
+        if block_given?
+          @switches.push(Switch.new(&block))
+        else
+          #TODO: test this with array and non-array single hash
+          args.each do |arg| # we can accept an array of hashes, each of which defines a param
+            error_string = "#{__method__} takes an Array of Hashes. Received Array of: '#{arg.class}'"
+            raise ArgumentError.new(error_string) unless arg.is_a?(Hash)
+            @switches.push(Switch.new(arg))
+          end
+        end
+      end
+
+      # adds option to append to command (a switch with an argument)
+      #   add_option creates an option object which has its own `#add_env`, `#add_argument` methods
+      # @param [Hash] args hashes of information about the option
+      # @option args [String] :name The value to be used as the option
+      # @option args [String] :message A message describing the use of option
+      #
+      # for block {|a| ... }
+      # @yield [a] Optional block syntax allows you to specify information about the option, available methods match hash keys
+      def add_option(*args, &block)
+        raise ArgumentError.new("#{__method__} takes a block or a hash") if !args.empty? && block_given?
+        # this is kinda annoying we have to do this for all params? (not DRY)
+        #   have to do it this way so EnvVar doesn't become a collection
+        #   but if this gets moved to a mixin, it might be more tolerable
+        if block_given?
+          @options.push(Option.new(&block))
+        else
+          #TODO: test this with array and non-array single hash
+          args.each do |arg| # we can accept an array of hashes, each of which defines a param
+            error_string = "#{__method__} takes an Array of Hashes. Received Array of: '#{arg.class}'"
+            raise ArgumentError.new(error_string) unless arg.is_a?(Hash)
+            @options.push(Option.new(arg))
+          end
+        end
+      end
+
+      # adds argument to append to command.
+      #   In the Command context this Argument is added to the end of the command string
+      # @param [Hash] args hashes of information about the argument
+      # @option args [String] :name The value to be used as the argument
+      # @option args [String] :message A message describing the use of argument
+      #
+      # for block {|a| ... }
+      # @yield [a] Optional block syntax allows you to specify information about the option, available methods match hash keys
+      def add_argument(*args, &block)
+        raise ArgumentError.new("#{__method__} takes a block or a hash") if !args.empty? && block_given?
+        if block_given?
+          @arguments.push(Argument.new(&block))
+        else
+          args.each do |arg| # we can accept an array of hashes, each of which defines a param
+            error_string = "#{__method__} takes an Array of Hashes. Received Array of: '#{arg.class}'"
+            raise ArgumentError.new(error_string) unless arg.is_a?(Hash)
+            @arguments.push(Argument.new(arg))
+          end
+        end
+      end
+
+      # convert a Command object to a string (runable command string)
+      # @return [String] the current value of the command string as built from its params
+      # TODO make private method? so that it will throw an error if yielded to?
+      def to_str
+        delete_nil_empty_false([
+          (name if name),
+          @switches.to_s,
+          @options.to_s,
+          @arguments.to_s
+        ]).join(' ').to_s
+      end
+      alias :to_s :to_str
+
+      Result = Struct.new(:output, :exit_code, :pid)
+      # run Command locally, capture relevent result data
+      # @return [Struct<Result>] a Result Struct with stdout, stderr, exit_code members
+      # TODO make private method? so that it will throw an error if yielded to?
+      def run
+        # make this look a bit like beaker's result class
+        #   we may have to convert this to a class if it gets complex
+        @result = Result.new
+        @result.output = ''
+        # add ';' to command string as it is a metacharacter that forces open3
+        #   to send the command to the shell. This returns the correct
+        #   exit_code and stderr, etc when the command is not found
+        Open3.popen2e(self.to_str + ";"){|stdin, stdout_err, wait_thr|
+          stdout_err.each { |line| puts line
+                            @result.output << line }
+          @result.pid    = wait_thr.pid # pid of the started process.
+          @result.exit_code = wait_thr.value.exitstatus # Process::Status object returned.
+        }
+
+        if block_given? # if block, send result to the block
+          yield @result
+        end
+        @result
+      end
+
+      # Does this param require the task to stop
+      # Determined by the interactions between @name, @env_vars, @options, @switches, @arguments
+      # @return [true|nil] if this param requires a stop
+      # TODO make private method? so that it will throw an error if yielded to?
+      def stop
+        return true if [@switches, @options, @arguments].any?{ |collection| collection.stop? }
+        return true unless @name
+      end
+
+      # @return [String] formatted messages from all of Command's pieces
+      #   itself, env_vars, switches, options, arguments
+      # TODO make private method? so that it will throw an error if yielded to?
+      def message
+        return [@message,
+                @env_vars.messages,
+                @switches.messages,
+                @options.messages,
+                @arguments.messages,
+        ].join('')
+      end
+
+      private
+      # @private
+      def delete_nil_empty_false(arg)
+        arg.delete_if{ |i| ([nil, '', false].include?(i)) }
+      end
+    end
+
+  end
+end

data/lib/rototiller/task/params/env_var.rb

@@ -0,0 +1,118 @@
+require 'rototiller/task/params'
+require 'rototiller/utilities/color_text'
+
+module Rototiller
+  module Task
+
+    # The main EnvVar type to implement envrironment variable handling
+    #   contains its messaging, status, and whether it is required.
+    #   The rototiller Param using it knows what to do with its value.
+    # @since v0.1.0
+    # @attr [String]         default  The default value of this env_var to use. if we have a default and
+    #   the system ENV does not have a value this implies the env_var is not required. If not default is specified but the parent parameter has a `#name` then that name is used as the default.
+    #   Used internally by CommandFlag, ignored for standalone EnvVar.
+    # @attr_reader [Boolean] stop     Whether the state of the EnvVar requires the task to stop
+    # @attr_reader [Boolean] value    The value of the ENV based on specified default and environment state
+    class EnvVar < RototillerParam
+      include Rototiller::ColorText
+      STATUS = {:nodefault_noexist=>0, :nodefault_exist=>1, :default_noexist=>2, :default_exist=>3}
+
+      attr_accessor :name
+      attr_accessor :default
+      attr_accessor :message
+      attr_reader   :value
+      attr_reader   :stop
+
+      # Creates a new instance of EnvVar, holds information about the ENV in the environment
+      # @param [Hash, Array<Hash>] args hash 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
+      # for block { |b| ... }
+      # @yield EnvVar object with attributes matching method calls supported by EnvVar
+      # @return EnvVar object
+      def initialize(args={}, &block)
+        @parent_name = args[:parent_name]
+        args.delete(:parent_name)
+        block_given? ? (yield self) : send_hash_keys_as_methods_to_self(args)
+
+        raise(ArgumentError, 'A name must be supplied to add_env') unless @name
+        @env_value_set_by_us = false
+        reset
+      end
+
+      # The formatted messages about this EnvVar's status 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
+        this_message = String.new
+
+        if env_status    == STATUS[:nodefault_noexist]
+          this_message << red_text('ERROR: environment-variable not set and no default provided: ')
+          this_message << "'#{@name}': '#{@message}'\n"
+        elsif env_status == STATUS[:nodefault_exist]
+          this_message << yellow_text('INFO: using system environment-variable value, no default provided: ')
+          this_message << "'#{@name}': '#{@value}': '#{@message}'\n"
+        elsif env_status == STATUS[:default_noexist]
+          this_message << green_text('INFO: no system environment-variable value, using default provided: ')
+          this_message << "'#{@name}': '#{@value}': '#{@message}'\n"
+        elsif env_status == STATUS[:default_exist]
+          this_message << yellow_text('INFO: environment-variable overridden from system, not using default: ')
+          this_message << "'#{@name}': default: '#{@default}' using: '#{@value}': '#{@message}'\n"
+        end
+
+      end
+
+      # The string representation of this EnvVar; the value on the system, or nil
+      # @return [String] the EnvVar's value
+      def to_str
+        @value
+      end
+      alias :to_s :to_str
+
+      # Sets the name of the EnvVar
+      # @raise [ArgumentError] if name contains an illegal character for bash environment variable
+      def name=(name)
+        name.each_char do |char|
+          message = "You have defined an environment variable with an illegal character: #{char}"
+          raise ArgumentError.new(message) unless char =~ /[a-zA-Z]|\d|_/
+        end
+        @name = name
+      end
+
+      private
+
+      # @private
+      def reset
+        # if no default given, use parent param's name
+        @default ||= @parent_name
+        (env_value_provided_by_user? || @default) ? @stop = false : @stop = true
+
+        if @name
+          @value = ENV[@name] || @default
+          unless env_value_provided_by_user?
+            ENV[@name] = @value
+            @env_value_set_by_us = true
+          end
+        else
+          @value = @default
+        end
+      end
+
+      # @private
+      def env_value_provided_by_user?
+        # its possible that name could not be set
+        (ENV.key?(@name) if @name) ? true : false
+      end
+
+      # @private
+      def env_status
+        return STATUS[:nodefault_noexist] if !@default &&  @env_value_set_by_us
+        return STATUS[:nodefault_exist]   if !@default && !@env_value_set_by_us
+        return STATUS[:default_noexist]   if  @default &&  @env_value_set_by_us
+        return STATUS[:default_exist]     if  @default && !@env_value_set_by_us
+      end
+
+    end
+
+  end
+end