cliutils 1.4.2 → 2.0.0

data/lib/cliutils/messaging.rb

@@ -13,6 +13,11 @@ module CLIUtils
       k.extend(self)
     end
 
+    # Empty method so that Messaging doesn't freak
+    # out when passed a debug message.
+    # @return [void]
+    def debug(m); end
+
     # Returns a default instance of LoggerDelegator that
     # delegates to STDOUT only.
     # @return [LoggerDelegator]
@@ -25,11 +30,118 @@ module CLIUtils
       LoggerDelegator.new(STDOUT: stdout_logger)
     end
 
+    # Outputs a formatted-red error message.
+    # @param [String] m The message to output
+    # @return [void]
+    def error(m)
+      puts _word_wrap(m, '# ').red
+    end
+
+    # Outputs a formatted-blue informational message.
+    # @param [String] m The message to output
+    # @return [void]
+    def info(m)
+      puts _word_wrap(m, '# ').blue
+    end
+
+    # Wraps a block in an opening and closing info message.
+    # @param [String] m1 The opening message to output
+    # @param [String] m2 The closing message to output
+    # @param [<True, False>] multiline Whether the message should be multiline
+    # @yield
+    # @return [void]
+    def info_block(m1, m2 = 'Done.', multiline = false)
+      if block_given?
+        if multiline
+          info(m1)
+        else
+          print _word_wrap(m1, '# ').blue
+        end
+
+        yield
+
+        if multiline
+          info(m2)
+        else
+          puts _word_wrap(m2, '# ').blue
+        end
+      else
+        fail 'Did not specify a valid block'
+      end
+    end
+
+    # Empty method so that Messaging doesn't freak
+    # out when passed a log message.
+    # @return [void]
+    def log(m); end
+
     # Singleton method to return (or initialize, if needed)
     # a LoggerDelegator.
     # @return [LoggerDelegator]
     def messenger
       @@messenger ||= default_instance
     end
+
+    # Outputs a prompt, collects the user's response, and
+    # returns it.
+    # @param [String] prompt The prompt to output
+    # @param [String] default The default option
+    # @param [String] start_dir The directory to start from for autocompletion
+    # @return [String]
+    def prompt(prompt, default = nil, start_dir = '')
+      Readline.completion_append_character = nil
+      Readline.completion_proc = lambda do |prefix|
+        files = Dir["#{start_dir}#{prefix}*"]
+        files.map { |f| File.expand_path(f) }
+             .map { |f| File.directory?(f) ? "#{ f }/" : f }
+      end
+      p = "# #{ prompt }#{ default.nil? ? ':' : " [default: #{ default }]:" } "
+      choice = Readline.readline(p.cyan)
+      if choice.empty?
+        default
+      else
+        choice
+      end
+    end
+
+    # Outputs a formatted-purple section message.
+    # @param [String] m The message to output
+    # @return [void]
+    def section(m)
+      puts _word_wrap(m, '---> ').purple
+    end
+
+    # Wraps a block in an opening and closing section message.
+    # @param [String] m The opening message to output
+    # @param [<True, False>] multiline Whether the message should be multiline
+    # @yield
+    # @return [void]
+    def section_block(m, multiline = true)
+      if block_given?
+        if multiline
+          section(m)
+        else
+          print _word_wrap(m, '---> ').purple
+        end
+
+        yield
+      else
+        fail 'Did not specify a valid block'
+      end
+    end
+
+    # Outputs a formatted-green success message.
+    # @param [String] m The message to output
+    # @return [void]
+    def success(m)
+      puts _word_wrap(m, '# ').green
+    end
+
+    # Outputs a formatted-yellow warning message.
+    # @param [String] m The message to output
+    # @return [void]
+    def warn(m)
+      puts _word_wrap(m, '# ').yellow
+    end
   end
 end

data/lib/cliutils/prefs/pref.rb

@@ -1,17 +1,35 @@
-require 'cliutils/messaging'
-require 'cliutils/prefs/pref_behavior'
-require 'cliutils/prefs/pref_validation'
-
 module CLIUtils
   # Pref Class
   # An individual preference
   class Pref
     include Messaging
 
+    # Constant defining an Action
+    ASSET_TYPE_ACTION = 0
+
+    # Constant defining a Behavior
+    ASSET_TYPE_BEHAVIOR = 1
+
+    # Constant defining a Validator
+    ASSET_TYPE_VALIDATOR = 2
+
+    # Contains a listing of asset names for classes and
+    # file suffixes.
+    # @return [Array]
+    @@asset_labels = [
+      { class_suffix: 'Action',    file_suffix: 'action'    },
+      { class_suffix: 'Behavior',  file_suffix: 'behavior'  },
+      { class_suffix: 'Validator', file_suffix: 'validator' }
+    ]
+
     # Stores the answer to this Pref.
     # @return [String, Symbol]
     attr_accessor :answer
 
+    # Stores instantiated Behavior objects.
+    # @return [Array]
+    attr_accessor :behavior_objects
+
     # Stores the behaviors that this Pref conforms to.
     # @return [Array]
     attr_accessor :behaviors
@@ -54,17 +72,29 @@ module CLIUtils
     # @return [String]
     attr_accessor :prompt_text
 
+    # Stores instantiated Validators
+    # @return [Array]
+    attr_accessor :validator_objects
+
     # Stores key/value combinations required to show this Pref.
     # @return [Hash]
     attr_accessor :validators
 
-    # Initializes a new Pref via passed-in parameters.
+    # Initializes a new Pref via passed-in parameters. Also
+    # initializes objects for each Validator and Behavior on
+    # this Pref.
     # @param [Hash] params Parameters to initialize
     # @return [void]
     def initialize(params = {})
+      @behavior_objects = []
+      @validator_objects = []
+
+      # Assign all of the passed params as instance variables.
       params.each { |key, value| send("#{ key }=", value) }
-      
-      # _load_validators if @validators
+
+      # Instantiate any listed Behaviors or Validators.
+      @behaviors.each { |b| _init_and_add_behavior(b) } if @behaviors
+      @validators.each { |v| _init_and_add_validator(v) } if @validators
     end
 
     # Custom equality operator for this class.
@@ -105,25 +135,13 @@ module CLIUtils
     # @param [String] text The text to evaluate
     # @return [String]
     def evaluate_behaviors(text)
-      if @behaviors
-        modified_text = text
-        @behaviors.each do |method|
-          if method.is_a?(Hash)
-            parameter = method.values[0]
-            method = method.keys[0]
-          end
-
-          args = [modified_text, parameter]
-          if PrefBehavior.respond_to?(method)
-            modified_text = PrefBehavior.send(method, *args)
-          else
-            messenger.warn("Skipping undefined Pref Behavior: #{ b }")
-          end
+      modified_text = text
+      if @behavior_objects
+        @behavior_objects.each do |b|
+          modified_text = b.evaluate(modified_text)
         end
-        modified_text
-      else
-        text
       end
+      modified_text
     end
 
     # Validates a text against this pref's options and
@@ -131,8 +149,8 @@ module CLIUtils
     # @param [String] text The text to validate
     # @return [Boolean]
     def validate(text)
-      _confirm_options(text) &&
-      _confirm_validators(text)
+      _check_options(text) &&
+      _check_validators(text)
     end
 
     private
@@ -140,7 +158,7 @@ module CLIUtils
     # Validates a text against the options for this Pref
     # @param [String] text The text to validate
     # @return [Boolean]
-    def _confirm_options(text)
+    def _check_options(text)
       ret = true
       if @options
         unless @options.include?(text)
@@ -155,18 +173,14 @@ module CLIUtils
     # Validates a text against the validators for this Pref
     # @param [String] text The text to validate
     # @return [Boolean]
-    def _confirm_validators(text)
+    def _check_validators(text)
       ret = true
-      if @validators
-        @validators.each do |v|
-          if PrefValidation.respond_to?(v)
-            validator = PrefValidation.send(v, text)
-            unless validator.code
-              @last_error_message = validator.message
-              ret = false
-            end
-          else
-            messenger.warn("Skipping undefined Pref Validator: #{ v }")
+      if @validator_objects
+        @validator_objects.each do |v|
+          v.validate(text)
+          unless v.is_valid
+            @last_error_message = v.message
+            ret = false
           end
         end
       end
@@ -178,11 +192,10 @@ module CLIUtils
     def _eval_pre
       info(@pre[:message])
       prompt('Press enter to continue')
-      
+
       if (@pre[:action])
-        action_obj = _load_action(@pre[:action])
-        action_obj.pref = self
-        action_obj.run(@pre[:action_parameters][0])
+        action_obj = _init_action(@pre[:action][:name])
+        action_obj.run
       end
     end
 
@@ -192,45 +205,79 @@ module CLIUtils
       info(@post[:message])
 
       if (@post[:action])
-        action_obj = _load_action(@post[:action])
-        action_obj.pref = self
-        action_obj.run(@post[:action_parameters][0])
+        action_obj = _init_action(@post[:action][:name])
+        action_obj.run
+      end
+    end
+
+    # Attempts to instantiate a Pre or Post Action based on name; if
+    # successful, the new object gets placed in @validator_objects
+    # @param [String] path_or_name The path to or name of the Action
+    # @return [void]
+    def _init_action(path_or_name)
+      obj = _load_asset(ASSET_TYPE_ACTION, path_or_name)
+      unless obj.nil?
+        obj.pref = self
+        obj.parameters = @pre[:action][:parameters]
       end
+      obj
     end
 
-    # Loads a Pref Action, instantiates it (if it exists),
-    # and returns that instance. Note that the passed
-    # String can be a name (thus translating to an included
-    # Action) or a filepath to a user-defined Action.
-    # @param [String] path_or_name The name of or path to an Action
-    # @return [Object]
-    def _load_action(path_or_name)
+    # Attempts to instantiate a Behavior based on name; if
+    # successful, the new object gets placed in @behavior_objects
+    # @param [Hash] behavior_hash The Behavior attributes
+    # @return [void]
+    def _init_and_add_behavior(behavior_hash)
+      obj = _load_asset(ASSET_TYPE_BEHAVIOR, behavior_hash[:name])
+      unless obj.nil?
+        obj.pref = self
+        obj.parameters = behavior_hash[:parameters]
+        @behavior_objects << obj
+      end
+    end
+
+    # Attempts to instantiate a Validator based on name; if
+    # successful, the new object gets placed in @validator_objects
+    # @param [String] path_or_name The path to or name of the Validator
+    # @return [void]
+    def _init_and_add_validator(path_or_name)
+      obj = _load_asset(ASSET_TYPE_VALIDATOR, path_or_name)
+      unless obj.nil?
+        obj.pref = self
+        @validator_objects << obj
+      end
+    end
+
+    # General function to load an asset (a Validator or Behavior).
+    # Note that if an asset isn't found, the user is warned, but
+    # execution continues.
+    # @param [Integer] type ASSET_TYPE_BEHAVIOR or ASSET_TYPE_VALIDATOR
+    # @param [String] path_or_name The path to or name of the asset
+    # @return [Object] 
+    def _load_asset(type, path_or_name)
       if File.exist?(path_or_name)
         # If the file exists, we're assuming that the user
         # passed a filepath.
-        action_path = File.expand_path(path_or_name) if path_or_name.start_with?('~') 
-        action_path = "#{ path_or_name }_action"
-        action_name = File.basename(path_or_name, '.*').camelize
+        asset_path = File.expand_path(path_or_name) if path_or_name.start_with?('~') 
+        asset_path = "#{ path_or_name }_#{ @@asset_labels[type][:file_suffix] }"
+        asset_name = File.basename(path_or_name, '.*').camelize
       else
         # If it doesn't, we're assuming that the user
         # passed a class name.
-        _default =  File.join(File.dirname(__FILE__), 'pref_actions')
-        action_path = File.join(_default, "#{ path_or_name }_action")
-        action_name = path_or_name.camelize
+        _default =  File.join(File.dirname(__FILE__), "pref_#{ @@asset_labels[type][:file_suffix] }s")
+        asset_path = File.join(_default, "#{ path_or_name }_#{ @@asset_labels[type][:file_suffix] }")
+        asset_name = path_or_name.camelize
       end
 
       # Try to load and instantiate the Action. If that fails, warn
       # the user with a message and skip over it.
       begin
-        require action_path
-        Object.const_get("CLIUtils::#{ action_name }Action").new
-      rescue
-        messenger.warn("Skipping undefined Pref Action: #{ path_or_name }")
+        require asset_path
+        Object.const_get("CLIUtils::#{ asset_name }#{ @@asset_labels[type][:class_suffix] }").new
+      rescue LoadError
+        messenger.warn("Skipping undefined Pref #{ @@asset_labels[type][:class_suffix] }: #{ path_or_name }")
+        nil
       end
     end
-
-    def _load_validators
-      
-    end
   end
 end

data/lib/cliutils/prefs/pref_actions/open_url_action.rb

@@ -1,7 +1,11 @@
 module CLIUtils
+  # Pref Action to open a URL in the default
+  # browser.
   class OpenUrlAction < PrefAction
-    def run(parameters)
-      `open #{ parameters[:url] }`
+    # Runs the action.
+    # @return [void]
+    def run
+      `open #{ @parameters[:url] }`
     end
   end
 end

data/lib/cliutils/prefs/pref_actions/pref_action.rb

@@ -1,23 +1,32 @@
 module CLIUtils
   # The generic base class for a Pref
-  # action.
+  # Action.
   class PrefAction
     include Messaging
 
+    # Holds the parameters that apply to
+    # this Action.
+    # @!attribute parameters
+    # @return [Hash]
+    attr_accessor :parameters
+
     # Holds a reference to the pref that
-    # is implementing this action.
+    # is implementing this Action.
+    # @!attribute pref
     # @return [Pref]
     attr_accessor :pref
 
-    # Runs the plugin. Note that the
-    # method implemented here shows
-    # an error (indicating that it
-    # needs to be implemented in a
-    # subclass).
+    # Runs the Action. Note that the
+    # method implemented here will throw
+    # an exception by default, meaning that
+    # the user's subclass *needs* to
+    # implement it.
     # @parameter [Hash] parameters
+    # @raise [StandardError] if the subclass
+    #   doesn't implement this method.
     # @return [void]
-    def run(parameters = {})
-      messenger.error("`run` method not implemented on caller: #{ self.class }")
+    def run
+      fail "`run` method not implemented on caller: #{ self.class }"
     end
   end
 end

data/lib/cliutils/prefs/pref_behaviors/capitalize_behavior.rb

@@ -0,0 +1,11 @@
+module CLIUtils
+  # A Behavior to capitalize a Pref answer
+  class CapitalizeBehavior < PrefBehavior
+    # Evaluates the behavior against the text.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def evaluate(text)
+      text.to_s.capitalize
+    end
+  end
+end

data/lib/cliutils/prefs/pref_behaviors/expand_filepath_behavior.rb

@@ -0,0 +1,12 @@
+module CLIUtils
+  # A Behavior to run File.expand_path on a
+  # Pref answer
+  class ExpandFilepathBehavior < PrefBehavior
+    # Evaluates the behavior against the text.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def evaluate(text)
+      File.expand_path(text.to_s)
+    end
+  end
+end

data/lib/cliutils/prefs/pref_behaviors/lowercase_behavior.rb

@@ -0,0 +1,11 @@
+module CLIUtils
+  # A Behavior to lowecase a Pref answer
+  class LowercaseBehavior < PrefBehavior
+    # Evaluates the behavior against the text.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def evaluate(text)
+      text.to_s.downcase
+    end
+  end
+end

data/lib/cliutils/prefs/pref_behaviors/pref_behavior.rb

@@ -0,0 +1,26 @@
+module CLIUtils
+  # The generic base class for a Pref
+  # Behavior.
+  class PrefBehavior
+    include Messaging
+
+    # Holds the parameters associated with
+    # this behavior.
+    # @return [Hash]
+    attr_accessor :parameters
+
+    # Holds a reference to the Pref that
+    # is applying this Behavior.
+    # @return [Pref]
+    attr_accessor :pref
+
+    # Evaluate the Behavior!
+    # @parameter [Hash] parameters
+    # @raise [StandardError] if the subclass
+    #   doesn't implement this method.
+    # @return [void]
+    def evaluate(text = '')
+      fail "`evaluate` method not implemented on caller: #{ self.class }"
+    end
+  end
+end

data/lib/cliutils/prefs/pref_behaviors/prefix_behavior.rb

@@ -0,0 +1,11 @@
+module CLIUtils
+  # A Behavior to prefix a Pref answer with a string
+  class PrefixBehavior < PrefBehavior
+    # Evaluates the behavior against the text.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def evaluate(text)
+      @parameters[:prefix] + text.to_s
+    end
+  end
+end

data/lib/cliutils/prefs/pref_behaviors/suffix_behavior.rb

@@ -0,0 +1,11 @@
+module CLIUtils
+  # A Behavior to suffix a Pref answer with a string
+  class SuffixBehavior < PrefBehavior
+    # Evaluates the behavior against the text.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def evaluate(text)
+      text.to_s + @parameters[:suffix]
+    end
+  end
+end

data/lib/cliutils/prefs/pref_behaviors/titlecase_behavior.rb

@@ -0,0 +1,11 @@
+module CLIUtils
+  # A Behavior to titlecase a Pref answer
+  class TitlecaseBehavior < PrefBehavior
+    # Evaluates the behavior against the text.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def evaluate(text)
+      text.to_s.split.map(&:capitalize).join(' ')
+    end
+  end
+end

data/lib/cliutils/prefs/pref_behaviors/uppercase_behavior.rb

@@ -0,0 +1,11 @@
+module CLIUtils
+  # A Behavior to uppercase a Pref answer
+  class UppercaseBehavior < PrefBehavior
+    # Evaluates the behavior against the text.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def evaluate(text)
+      text.to_s.upcase
+    end
+  end
+end

data/lib/cliutils/prefs/pref_validators/alphabetic_validator.rb

@@ -0,0 +1,13 @@
+module CLIUtils
+  # A Validator to verify whether a Pref answer
+  # is alphabetic (made up of letters and spaces).
+  class AlphabeticValidator < PrefValidator
+    # Runs the Validator against the answer.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def validate(text)
+      @is_valid = text.to_s =~ /\A[A-Za-z\s]+\z/
+      @message = "Response is not alphabetic: #{ text }"
+    end
+  end
+end

data/lib/cliutils/prefs/pref_validators/alphanumeric_validator.rb

@@ -0,0 +1,14 @@
+module CLIUtils
+  # A Validator to verify whether a Pref answer
+  # is alphanumeric (made up of letters, numbers
+  # and spaces).
+  class AlphanumericValidator < PrefValidator
+    # Runs the Validator against the answer.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def validate(text)
+      @is_valid = text.to_s =~ /\A[A-Za-z0-9\s]+\z/
+      @message = "Response is not alphanumeric: #{ text }"
+    end
+  end
+end

data/lib/cliutils/prefs/pref_validators/date_validator.rb

@@ -0,0 +1,13 @@
+module CLIUtils
+  # A Validator to verify whether a Pref answer
+  # is a date.
+  class DateValidator < PrefValidator
+    # Runs the Validator against the answer.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def validate(text)
+      @is_valid = !(Date.parse(text) rescue nil).nil?
+      @message = "Response is not a date: #{ text }"
+    end
+  end
+end

data/lib/cliutils/prefs/pref_validators/datetime_validator.rb

@@ -0,0 +1,13 @@
+module CLIUtils
+  # A Validator to verify whether a Pref answer
+  # is a datetime.
+  class DatetimeValidator < PrefValidator
+    # Runs the Validator against the answer.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def validate(text)
+      @is_valid = !(DateTime.parse(text) rescue nil).nil?
+      @message = "Response is not a datetime: #{ text }"
+    end 
+  end
+end

data/lib/cliutils/prefs/pref_validators/filepath_exists_validator.rb

@@ -0,0 +1,13 @@
+module CLIUtils
+  # A Validator to verify whether a Pref answer
+  # is a local filepath that exists.
+  class FilepathExistsValidator < PrefValidator
+    # Runs the Validator against the answer.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def validate(text)
+      @is_valid = Pathname.new(text.to_s).exist?
+      @message = "Path does not exist locally: #{ text }"
+    end
+  end
+end

data/lib/cliutils/prefs/pref_validators/non_nil_validator.rb

@@ -0,0 +1,13 @@
+module CLIUtils
+  # A Validator to verify whether a Pref answer
+  # is not empty or nil.
+  class NonNilValidator < PrefValidator
+    # Runs the Validator against the answer.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def validate(text)
+      @is_valid = !text.nil? && !text.empty?
+      @message = 'Nil text not allowed'
+    end
+  end
+end

data/lib/cliutils/prefs/pref_validators/number_validator.rb

@@ -0,0 +1,13 @@
+module CLIUtils
+  # A Validator to verify whether a Pref answer
+  # is not a number.
+  class NumberValidator < PrefValidator
+    # Runs the Validator against the answer.
+    # @param [Object] text The "text" to evaluate
+    # @return [String]
+    def validate(text)
+      @is_valid = text.to_s =~ /\A[-+]?\d*\.?\d+\z/
+      @message = "Response is not a number: #{ text }"
+    end
+  end
+end