fiksu-af 1.1.0

data/lib/fiksu-af/option_parser/dsl.rb

@@ -0,0 +1,290 @@
+module Af::OptionParser
+  # Utility base class for executing Ruby scripts on the command line. Provides
+  # methods to define, gather, parse and cast command line options. Options are
+  # stored as class instance variables.
+  module Dsl
+    ### Class methods ###
+
+    @@opt_group_stack = []
+    def opt_get_top_of_stack
+      return (@@opt_group_stack[-1] || {}).clone
+    end
+
+    # Declare a command line options group.
+    #
+    # *Arguments*
+    #   * group_name - name of the group
+    #   * extra_stuff (Hash)
+    #     * :title - display title of the group (optional)
+    #     * :description - details about group
+    #     * :priority - order to show groups in help --?
+    #     * :hidden - true if this group's options should only be seen with --?
+    #     * :disabled - (default: false)
+    #     *  anything else in this hash can be passed to yield block as defaults for other opt/opt_group invocations
+    #   * yeilds to block if given with extra_stuff in a global space that opt/opt_group calls use as defaults
+
+    def opt_group(group_name, *extra_stuff)
+      # grab information from our yield scope
+      factory_hash = opt_get_top_of_stack
+
+      # update factory_hash with information in array area first (left parameters of the dsl)
+      maybe_title = extra_stuff.shift
+      if maybe_title.is_a? String
+        factory_hash[:title] = maybe_title
+      else
+        extra_stuff.unshift(maybe_title)
+      end
+
+      # then fold in the hash
+      maybe_hash = extra_stuff[-1] || {}
+      if maybe_hash.is_a? Hash
+        factory_hash.merge! maybe_hash
+      end
+
+      # Add group_name to OptionStore if it's not present. Otherwise, retrieve the value
+      # associated with that key and merge the value into factory_hash
+      OptionStore.factory(self).get_option_group(group_name).merge!(factory_hash)
+
+      # if a block is given, then let the yielded block
+      # have access to our scoped hash.
+      if block_given?
+        begin
+          @@opt_group_stack.push factory_hash.merge({ group: group_name })
+          yield
+        ensure
+          @@opt_group_stack.pop
+        end
+      end
+    end
+
+    # Declare a command line option switch.
+    #
+    # *Arguments*
+    #   * long_name - long version of the switch
+    #   * extra_stuff - hash with the following possible keys:
+    #     :type - (:option_type) the OptionType
+    #     :argument - (:requirements) is a parameter value requied (valid values: :required, :optional, :none)
+    #     :short - (:short_name) the single letter used for this option (i.e., :e = '-e')
+    #     :argument_note - used in --? as the typename of the parameter (e.g. ENGLISH_WORD)
+    #     :note - used in --? as the help text
+    #     :environment_variable - the name of the environment variable associated with this switch
+    #     :default - (:default_value) the default value of the parameter
+    #     :method - (:evaluation_method) called to evaluate argument: lambda{|argument,option| ... }
+    #     :group - (:option_group_name) name of group
+    #     :hidden - should option only be shown in --?
+    #     :disabled - (default: false)
+    #     :choices - array of valid choices, e.g: [:blue, :green, :red]
+    #     :set - (:value_to_set_target_variable) value to set if option specified (use for switches where --blue means set @color = 'blue')
+    #     :no_accessor - (:do_not_create_accessor) don't class_eval 'attr_accessor :#{target_variable}'
+    #     :var - (:target_variable) name of instance variable to set
+    #     :target_container - name of object to set instance value
+    #
+    # if block is passed it is used as :method
+    #
+    def opt(long_name, *extra_stuff, &b)
+      factory_hash = opt_get_top_of_stack
+
+      # Ensure long name is in the proper string format.
+      long_name = long_name.to_s
+      unless long_name.starts_with? "--"
+        long_name = "--#{long_name.gsub(/_/,'-')}"
+      end
+      factory_hash[:var] = long_name[2..-1].gsub(/-/, '_').gsub(/[^0-9a-zA-Z]/, '_')
+
+      # Create hash for processed options.
+      maybe_hash = extra_stuff[-1]
+      if maybe_hash.is_a? Hash
+        # if maybe_hash is a Hash, then the rest of extra_stuff is an array, which
+        # is expected to be:
+        #   NOTE (String)
+        # or:
+        #   TYPE (Symbol)
+        # or:
+        #   REQUIREMENT (Symbol)
+        extra_stuff.pop
+        factory_hash.merge! maybe_hash
+      end
+
+      # Iterate through and process all of the other arguments.
+      while extra_stuff.length > 0
+        extra = extra_stuff.shift
+        if extra.is_a? Symbol
+          if [:required, :optional, :none].include? extra
+            factory_hash[:argument] = extra
+          elsif OptionType.valid_option_type_names.include? extra
+            factory_hash[:type] = extra
+          else
+            raise MisconfiguredOptionError.new("#{long_name}: extra options: #{extra.inspect} are not understood")
+          end
+        elsif extra.is_a? String
+          factory_hash[:note] = extra
+        else
+          raise MisconfiguredOptionError.new("#{long_name}: extra options: #{extra.inspect} are not understood")
+        end
+      end
+
+      unless factory_hash[:type]
+        # If we are not just setting a switch, then we can use the default value
+        # and assume this switch has a required argument.
+        if factory_hash[:default].present? && factory_hash[:set].nil?
+          type = OptionType.find_by_value(factory_hash[:default]).try(:short_name)
+          factory_hash[:type] = type unless type.nil?
+        end
+      end
+
+      # Determine argument requirement type.
+      factory_hash[:argument] = if factory_hash[:argument] == :required
+                                  ::Af::OptionParser::GetOptions::REQUIRED_ARGUMENT
+                                elsif factory_hash[:argument] == :none
+                                  ::Af::OptionParser::GetOptions::NO_ARGUMENT
+                                elsif factory_hash[:argument] == :optional
+                                  ::Af::OptionParser::GetOptions::OPTIONAL_ARGUMENT
+                                elsif factory_hash[:argument] == nil
+                                  if factory_hash[:type]
+                                    if factory_hash[:type] == :switch
+                                      ::Af::OptionParser::GetOptions::OPTIONAL_ARGUMENT
+                                    else
+                                      ::Af::OptionParser::GetOptions::REQUIRED_ARGUMENT
+                                    end
+                                  else
+                                    factory_hash[:type] = :switch
+                                    ::Af::OptionParser::GetOptions::OPTIONAL_ARGUMENT
+                                  end
+                                else
+                                  factory_hash[:argument]
+                                end
+
+      # Determine argument type if it is not explictly given
+      unless factory_hash[:type]
+        if factory_hash[:set]
+          type = OptionType.find_by_value(factory_hash[:set]).try(:short_name)
+          factory_hash[:type] = type unless type.nil?
+        end
+      end
+
+      # Add the switch to the store, along with all of it's options.
+      if factory_hash[:short]
+        short = factory_hash[:short].to_s
+        unless short[0] == '-'
+          short = "-#{short}"
+        end
+        factory_hash[:short] = short
+      end
+
+      if factory_hash[:type]
+        type = OptionType.find_by_short_name(factory_hash[:type])
+        raise MisconfiguredOptionError.new("#{long_name}: option type #{factory_hash[:type].inspect} is not recognized. " +
+          "(valid option types: #{OptionType.valid_option_type_names.join(', ')})") unless type
+        factory_hash[:type]  = type
+      end
+
+      factory_hash[:method] = b if b
+
+      unless factory_hash[:argument_note]
+        unless type.argument_note.blank?
+          factory_hash[:argument_note] = type.argument_note
+        end
+      end
+
+      # rename keys in factory hash from the UI names to the API names
+
+      {
+        env: :environment_variable,
+        default: :default_value,
+        type: :option_type,
+        var: :target_variable,
+        set: :value_to_set_target_variable,
+        no_accessor: :do_not_create_accessor,
+        group: :option_group_name,
+        short: :short_name,
+        method: :evaluation_method,
+        argument: :requirements
+      }.each do |current_key_name, new_key_name|
+        if factory_hash.has_key? current_key_name
+          factory_hash[new_key_name] = factory_hash.delete(current_key_name)
+        end
+      end
+
+      # Add long_name to OptionStore if it's not present. Otherwise, retrieve the value
+      # associated with that key and merge the value into factory_hash
+      OptionStore.factory(self).get_option(long_name).merge!(factory_hash)
+    end
+
+    def opt_check(var_name, *extra_stuff, &b)
+      factory_hash = {}
+      factory_hash[:target_variable] = var_name[0..-1]
+      # Set the target_container when using an application component
+      if extra_stuff[0][:target_container].present?
+        factory_hash[:target_container] = extra_stuff[0][:target_container]
+      end
+
+      if extra_stuff[-1].is_a? Hash
+        action, targets = extra_stuff[-1].flatten
+
+        if [:requires, :excludes].include?(action)
+          factory_hash[:action] = action
+          if targets.is_a? Array
+            factory_hash[:targets] = targets
+          else
+            raise MisconfiguredOptionError.new("#{var_name}: check targets '#{targets.inspect}' must be Array")
+          end
+          raise MisconfiguredOptionError.new("#{var_name}: check action '#{action}' given block") unless b.nil?
+        elsif action == :check
+          raise MisconfiguredOptionError.new("#{var_name}: check action '#{action}' requires block") if b.nil?
+          factory_hash[:block] = b
+        else
+          raise MisconfiguredOptionError.new("unknown check action '#{action}' for #{var_name}")
+        end
+      else
+        raise MisconfiguredOptionError.new("check: #{var_name} must be given a hash")
+      end
+
+      # Add var_name to OptionStore if it's not present. Otherwise, retrieve the value
+      # associated with that key and merge the value into factory_hash
+      OptionStore.factory(self).get_option_check(var_name).merge!(factory_hash)
+    end
+
+    def opt_select(var_name, *extra_stuff, &b)
+      factory_hash = {}
+      factory_hash[:target_variable] = var_name[0..-1]
+      # Set the target_container when using an application component
+      if extra_stuff[0][:target_container].present?
+        factory_hash[:target_container] = extra_stuff[0][:target_container]
+      end
+
+      if extra_stuff[-1].is_a? Hash
+        action, targets = extra_stuff[-1].flatten
+
+        if [:one_of, :one_or_more_of, :none_or_one_of].include?(action)
+          factory_hash[:action] = action
+          if targets.is_a? Symbol
+            factory_hash[:targets] = [targets]
+          elsif targets.is_a? Array
+            factory_hash[:targets] = targets
+          else
+            raise MisconfiguredOptionError.new("#{var_name}: select targets '#{targets.inspect}' must be Symbol or Array")
+          end
+          raise MisconfiguredOptionError.new("#{var_name}: select action '#{action}' given block") unless b.nil?
+        else
+          raise MisconfiguredOptionError.new("unknown select action '#{action}' for #{var_name}")
+        end
+      else
+        raise MisconfiguredOptionError.new("select: #{var_name} must be given a hash")
+      end
+
+      # Add var_name to OptionStore if it's not present. Otherwise, retrieve the value
+      # associated with that key and merge the value into factory_hash
+      OptionStore.factory(self).get_option_select(var_name).merge!(factory_hash)
+    end
+
+    def opt_error(text)
+      puts "ERROR: #{text} (--? for help)"
+      exit 1
+    end
+
+    def usage
+      return "USAGE: rails runner #{self.name}.run [OPTIONS]"
+    end
+
+  end
+end

data/lib/fiksu-af/option_parser/get_options.rb

@@ -0,0 +1,65 @@
+require 'getoptlong'
+
+module Af::OptionParser
+  # Subclasses Getoptlong from the Ruby standard library.
+  # Docs: http://www.ruby-doc.org/stdlib-1.9.3/libdoc/getoptlong/rdoc/GetoptLong.html.
+  # Source: https://github.com/ruby/ruby/blob/trunk/lib/getoptlong.rb.
+  class GetOptions < GetoptLong
+
+    # Local constants which map to superclass argument types.
+    ARGUMENT_FLAGS = [
+      NO_ARGUMENT = GetoptLong::NO_ARGUMENT,
+      REQUIRED_ARGUMENT = GetoptLong::REQUIRED_ARGUMENT,
+      OPTIONAL_ARGUMENT = GetoptLong::OPTIONAL_ARGUMENT
+    ]
+
+    # Instantiate a new long command line option parser with a hash of switches.
+    #
+    # *Arguments*
+    #   * switches - optional hash of command line switches, with long switch as
+    #       key to a set of options:
+    #         :short => <optional short switch>
+    #         :argument => <constant arg type>
+    #         :environment_variable => <how do these work???>
+    #         :note => <arg description>
+    def initialize(declared_options = [])
+      getopt_options = []
+      argv_additions = []
+
+      # Iterate through all of the options.
+      declared_options.each do |option|
+        # Set aside
+        if option.environment_variable.present?
+          # Add enviroment variables to the front of ARGV.
+          if ENV[option.environment_variable]
+            argv_additions << option.long_name
+            unless ENV[option.environment_variable].empty?
+              # if the envvar is empty we assume this is a switch (no parameter)
+              argv_additions << ENV[option.environment_variable]
+            end
+          end
+        end
+
+        # Convert hash into array, in format expected by Getoptlong#new.
+        # Example: ['--foo', '-f', GetoptLong::NO_ARGUMENT]
+        options = []
+        options << option.long_name
+        if (option.short_name)
+          options << option.short_name
+        end
+        options << option.requirements
+        getopt_options << options
+      end
+
+      # add any ARGVs to our list
+      for arg in ARGV do
+        argv_additions << arg
+      end
+
+      # Rewrite ARGV with environment variable with the new list.
+      argv_additions.each_with_index { |v,i| ARGV[i] = v }
+
+      super(*getopt_options)
+    end
+  end
+end

data/lib/fiksu-af/option_parser/helper.rb

@@ -0,0 +1,80 @@
+module ::Af::OptionParser
+  class Helper
+    def initialize(af_opt_class_path)
+      option_finder = OptionFinder.new(af_opt_class_path)
+      @options = option_finder.all_options
+      @grouped_options = @options.group_by{|option| option.option_group_name || :basic}
+      @groups = option_finder.all_option_groups.sort{|a,b| (a.priority || 50) <=> (b.priority || 50)}
+    end
+
+    # Prints to stdout application usage and all command line options.
+    def help(command_line_usage, show_hidden = false)
+      # Print usage.
+      puts(command_line_usage)
+
+      # Array of strings to be printed to stdout.
+      output = []
+
+      # Iterate through all command groups  sorted by priority.
+      @groups.each do |group|
+        options_in_group = @grouped_options[group.group_name]
+        unless options_in_group.blank?
+          if group.hidden == true && show_hidden == false
+            # skipping hidden groups
+          else
+            output << "#{group.group_name}: #{group.title}"
+            unless group.description.blank?
+              output << " " + group.description.split("\n").map(&:strip).join("\n ")
+            end
+
+            rows = []
+
+            # Iterate trhough all commands in this group.
+            options_in_group.sort{|a,b| a.long_name <=> b.long_name}.each do |option|
+              if option.hidden == true && show_hidden == false
+                # skipping hidden commands
+              else
+                columns = []
+                switches = "#{option.long_name}"
+                if (option.short_name)
+                  switches << " | #{option.short_name}"
+                end
+                unless (option.requirements == ::Af::OptionParser::GetOptions::NO_ARGUMENT)
+                  if (option.argument_note)
+                    switches << " #{option.argument_note}"
+                  elsif (option.option_type)
+                    note = OptionType.find_by_short_name(option.option_type).try(:argument_note)
+                    switches << " #{note}" if note
+                  end
+                end
+                columns << switches
+                notes = []
+                unless (option.requirements == ::Af::OptionParser::GetOptions::NO_ARGUMENT)
+                  if option.default_value.present?
+                    if option.default_value.is_a? Array
+                      notes << "(default: #{option.default_value.join(',')})"
+                    elsif option.default_value.is_a? Hash
+                      notes << "(default: #{option.default_value.map{|k,v| k.to_s + '=>' + v.to_s}.join(',')}"
+                    else
+                      notes << "(default: #{option.default_value})"
+                    end
+                  end
+                end
+                notes << (option.note || "")
+                notes << "(choices: #{option.choices.map(&:to_s).join(', ')})" unless option.choices.blank?
+                if option.environment_variable
+                  notes << " [env: #{option.environment_variable}]"
+                end
+                columns << notes.join(' ')
+                rows << columns
+              end
+            end
+            output += Columnizer.new.columnized(rows)
+          end
+        end
+      end
+
+      puts output.join("\n")
+    end
+  end
+end

data/lib/fiksu-af/option_parser/instance_variable_setter.rb

@@ -0,0 +1,117 @@
+module ::Af::OptionParser
+  class InstanceVariableSetter
+    FACTORY_SETTABLES = [
+                          :evaluation_method,
+                          :hidden,
+                          :value_to_set_target_variable,
+                          :do_not_create_accessor,
+                          :target_variable,
+                          :target_container,
+                          :disabled
+                        ]
+    attr_accessor *FACTORY_SETTABLES
+
+    def initialize(parameters = {})
+      set_instance_variables(parameters)
+      @target_container ||= :af_application
+    end
+
+    #-------------------------
+    # *** Instance Methods ***
+    #+++++++++++++++++++++++++
+
+    def target_container
+      if @target_container == :af_application
+        @target_container = ::Af::Application.singleton
+      end
+      return @target_container
+    end
+
+    def target_class_variable
+      return "@@#{target_variable}"
+    end
+
+    def target_instance_variable
+      return "@#{target_variable}"
+    end
+
+    def has_value_to_set_target_variable?
+      return @has_value_to_set_target_variable || false
+    end
+
+    def evaluate_and_set_target(argument)
+      value = evaluate(argument)
+      set_target_variable(value)
+    end
+
+    def evaluate(argument)
+      if has_value_to_set_target_variable?
+        argument = @value_to_set_target_variable
+      else
+        if @requirements == ::Af::OptionParser::GetOptions::NO_ARGUMENT
+          argument = true
+        end
+      end
+
+      evaluator = @evaluation_method ||
+        @option_type ||
+        OptionType.find_by_value(argument) ||
+        OptionType.find_by_short_name(:switch)
+
+      if evaluator.nil?
+        raise UndeterminedArgumentTypeError.new(@long_name)
+      elsif evaluator.is_a? Proc
+        return evaluator.call(argument, self)
+      else
+        return evaluator.evaluate_argument(argument, self)
+      end
+    end
+
+    def instantiate_target_variable
+      if target_container.present? && target_variable.present?
+        set_target_variable(@default_value)
+        unless @do_not_create_accessor
+          if target_container.is_a? Class
+            target_container.class_eval "def self.#{target_variable}; return #{target_class_variable}; end"
+            target_container.class_eval "def self.#{target_variable}=(value); return #{target_class_variable} = value; end"
+          else
+            target_container.class.class_eval "attr_accessor :#{target_variable}"
+          end
+        end
+      end
+    end
+
+    def set_target_variable(value)
+      if target_container.present? && target_variable.present?
+        if target_container.is_a? Class
+          # this is a Class -- set @@foo
+          target_container.class_variable_set(target_class_variable, value)
+        else
+          # this is an instance -- set @foo
+          target_container.instance_variable_set(target_instance_variable, value)
+        end
+      end
+    end
+
+    def set_instance_variables(parameters = {}, other_settables = [])
+      parameters.select do |name, value|
+        (FACTORY_SETTABLES + other_settables).include? name
+      end.each do |name, value|
+        instance_variable_set("@#{name}", value)
+      end
+
+      if parameters[:value_to_set_target_variable]
+        @has_value_to_set_target_variable = true
+      end
+    end
+
+    def merge(that_option, other_settables = [])
+      (FACTORY_SETTABLES + other_settables).each do |name|
+        if that_option.instance_variable_defined?("@#{name}")
+          self.send("#{name}=", that_option.send(name))
+        end
+      end
+    end
+
+  end
+end

data/lib/fiksu-af/option_parser/interface.rb

@@ -0,0 +1,63 @@
+module Af::OptionParser
+  module Interface
+    # used by application code to note an error and exit
+    def opt_error(text)
+      self.class.opt_error(text)
+    end
+
+    # Returns a string detailing application usage.
+    def usage
+      return self.class.usage
+    end
+
+    # Update Options for the provided long switch option name.
+    # Just a helper to UI method "opt"
+    def opt(long_name, *extra_stuff, &b)
+      self.class.opt(long_name, *extra_stuff, &b)
+    end
+
+    # Update OptionGroups for the provided group option name.
+    # Just a helper to UI method "opt_group"
+    def opt_group(group_name, *extra_stuff, &b)
+      self.class.opt_group(group_name, *extra_stuff, &b)
+    end
+
+    # Update OptionChecks for the provided group option name.
+    # Just a helper to UI method "opt_check"
+    def opt_check(var_name, *extra_stuff, &b)
+      self.class.opt_check(var_name, *extra_stuff, &b)
+    end
+
+    # Update OptionSelects for the provided group option name.
+    # Just a helper to UI method "opt_select"
+    def opt_select(var_name, *extra_stuff, &b)
+      self.class.opt_select(var_name, *extra_stuff, &b)
+    end
+
+    # Collect and process all of the switches (values) on the command
+    # line, as previously configured.
+    def process_command_line_options(af_option_interests)
+      # Iterate through all options in the class heirachy.
+      # Create instance variables and accessor methods for each.
+
+      option_finder = OptionFinder.new(af_option_interests)
+
+      options = option_finder.all_options
+      options.each(&:instantiate_target_variable)
+
+      # Fetch the actual switches (and values) from the command line.
+      get_options = GetOptions.new(options)
+
+      # Iterate through the command line options. Print and exit if the switch
+      # is invalid, help or app version.  Otherwise, process and handle.
+      begin
+        get_options.each do |long_name, argument|
+          option_finder.find_option(long_name).evaluate_and_set_target(argument)
+        end
+      rescue GetoptLong::Error, Error => e
+        opt_error e.message
+      end
+    end
+
+  end
+end

data/lib/fiksu-af/option_parser/option.rb

@@ -0,0 +1,40 @@
+module ::Af::OptionParser
+  class Option < InstanceVariableSetter
+    FACTORY_SETTABLES = [
+                          :option_type,
+                          :requirements,
+                          :short_name,
+                          :argument_note,
+                          :note,
+                          :environment_variable,
+                          :default_value,
+                          :option_group_name,
+                          :choices
+                        ]
+    attr_accessor *FACTORY_SETTABLES
+    attr_accessor :long_name
+
+    def initialize(long_name, parameters = {})
+      super(parameters)
+      @long_name = long_name
+    end
+
+    #-------------------------
+    # *** Instance Methods ***
+    #+++++++++++++++++++++++++
+
+    def set_instance_variables(parameters = {})
+      super(parameters, FACTORY_SETTABLES)
+    end
+
+    def merge(that_option)
+      super(that_option, FACTORY_SETTABLES)
+    end
+
+    def error(text)
+      puts "ERROR: #{self.long_name}: #{text} (--? for help)"
+      exit 1
+    end
+
+  end
+end