sprout 1.0.32.pre → 1.0.35.pre

data/lib/sprout/executable/boolean.rb

@@ -2,8 +2,51 @@ module Sprout
 
   module Executable
 
-    # Concrete param object for :boolean values
+    ##
+    # Concrete Sprout::Executable::Param object for Boolean values.
+    #
+    # By default Boolean parameters have their value set to false and
+    # :hidden_value set to true. This means that when they are serialized
+    # to the shell, they will usually be represented like:
+    #
+    #   --name
+    #
+    # Rather than:
+    #
+    #   --name=true
+    #
+    # The following example demonstrates a simple use of the Boolean
+    # parameter:
+    #
+    #   class Foo
+    #     include Sprout::Executable
+    #
+    #     add_param :visible, Boolean
+    #   end
+    #
+    # @see Sprout::Executable::Param
+    #
     class Boolean < Param
+
+      ##
+      # By default, the Boolean parameter will only
+      # be displayed when it's value is +true+.
+      #
+      # Set :show_on_false to true in order to reverse
+      # this rule.
+      #
+      #   add_param :visible, Boolean, :show_on_false => true
+      #
+      # Will make the following:
+      #
+      #   foo :name do |t|
+      #     t.visible = false
+      #   end
+      #
+      # Serialize to the shell with:
+      #
+      #   foo -visible=false
+      # 
       attr_accessor :show_on_false
 
       def initialize
@@ -15,6 +58,9 @@ module Sprout
         @hidden_value            = true
       end
 
+      ##
+      # Convert string representations of truthiness
+      # to something more Booley.
       def value=(value)
         value = (value == "true" || value === true) ? true : false 
         super value

data/lib/sprout/executable/collection_param.rb

@@ -1,6 +1,8 @@
 module Sprout
 
   module Executable
+
+    ##
     # Included by any parameters that represent
     # a collection of values, rather than a single
     # value.
@@ -8,6 +10,11 @@ module Sprout
     # Should only be included by classes that 
     # extend Sprout::Executable::Param.
     #
+    # @see Sprout::Executable::Files
+    # @see Sprout::Executable::Paths
+    # @see Sprout::Executable::Strings
+    # @see Sprout::Executable::Urls
+    #
     module CollectionParam
 
       def initialize
@@ -17,7 +24,30 @@ module Sprout
         @option_parser_type_name = 'a,b,c'
       end
 
-      # Assign the value and raise if 
+      ##
+      # Assign the value and raise if a collection wasn't provided.
+      #
+      # This customization was added so that Rake tasks could help
+      # users avoid accidentally clobbering a collection with equals assignments.
+      #
+      # The following example is incorrect and will raise an exception:
+      #
+      #   foo :name do |t|
+      #     t.collection = 'A'
+      #   end
+      #
+      # The following example is correct and should not raise an exception:
+      #
+      #   foo :name do |t|
+      #     t.collection << 'A'
+      #   end 
+      #
+      # The following example is also correct and should not raise an exception:
+      #
+      #   foo :name do |t|
+      #     t.collection = ['A']
+      #   end
+      #
       def value=(val)
         if(val.is_a?(String) || !val.is_a?(Enumerable))
           message = "The #{name} property is an Enumerable. It looks like you may have used the assignment operator (=) with (#{value.inspect}) where the append operator (<<) was expected."
@@ -26,12 +56,14 @@ module Sprout
         @value = val
       end
 
+      ##
       # Hide the collection param if no items
       # have been added to it.
       def visible?
         (!value.nil? && value.size > 0)
       end
 
+      ##
       # Returns a shell formatted string of the collection
       def to_shell
         prepare if !prepared?

data/lib/sprout/executable/file_param.rb

@@ -3,16 +3,29 @@ module Sprout
   module Executable
 
     ##
-    # Concrete param object for :file values
+    # Concrete Sprout::Executable::Param object for File values.
     #
-    # This class is actually referenced in Excecutables with:
+    # This class is used in Sprout::Excecutable s with:
     #
     #   add_param :some_name, File
     #
-    # @see Sprout::Executable::ParameterFactory
+    # This parameter is truly special in that whatever values
+    # are sent to the File parameter will be added to the underlying
+    # Rake task as prerequisites and must exist before +Sprout::Executable.execute+
+    # is called - _unless_ the parameter value
+    # matches the Sprout::Executable instance's +output+ value.
+    #
+    # Of course this will only be the case if there is a Rake
+    # task wrapper for the Executable, if the Sprout::Executable
+    # is being used to create a Ruby executable, then these File
+    # parameters will only be validated before execution.
+    #
+    # @see Sprout::Executable::Param
     #
     class FileParam < Param 
 
+      attr_accessor :file_task_name
+
       def initialize
         super
         @option_parser_type_name = 'FILE'

data/lib/sprout/executable/files.rb

@@ -4,6 +4,11 @@ module Sprout
 
     ##
     # Concrete param object for collections of files
+    #
+    # @see Sprout::Executable::FileParam
+    # @see Sprout::Executable::Param
+    # @see Sprout::Executable::CollectionParam
+    #
     class Files < Executable::Param
       include CollectionParam
 

data/lib/sprout/executable/number.rb

@@ -3,7 +3,11 @@ module Sprout
 
   module Executable
 
-    # Concrete param object for numberic values
+    ##
+    # Concrete Sprout::Executable::Param object for numeric values.
+    #
+    # @see Sprout::Executable::Param
+    #
     class Number < Param; end
   end
 end

data/lib/sprout/executable/param.rb

@@ -6,36 +6,175 @@ module Sprout
     ##
     # The abstract base class for all Executable parameters.
     #
+    # This class provides a variety of template methods and general
+    # functionality to the different executable parameter types.
+    #
+    # Many of these parameter attributes are exposed to Sprout::Executable
+    # concrete classes as the options hash like:
+    #
+    #   class Foo
+    #     include Sprout::Executable
+    #
+    #     add_param :name, String, :hidden_name => true
+    #   end
+    #
+    # @see Sprout::Executable::Boolean
+    # @see Sprout::Executable::FileParam
+    # @see Sprout::Executable::Files
+    # @see Sprout::Executable::Number
+    # @see Sprout::Executable::ParameterFactory
+    # @see Sprout::Executable::Path
+    # @see Sprout::Executable::Paths
+    # @see Sprout::Executable::StringParam
+    # @see Sprout::Executable::Strings
+    # @see Sprout::Executable::Url
+    # @see Sprout::Executable::Urls
+    #
     class Param
+
+      ##
+      # Default value for the delimiter that will
+      # separate parameter names from their values.
       DEFAULT_DELIMITER               = '='
+
+      ##
+      # Defaut TYPE assumed for parameters when
+      # creating documentation for the OptionParser.
       DEFAULT_OPTION_PARSER_TYPE_NAME = 'STRING'
 
-      # These values should usually be pulled
-      # from the 'belongs_to' executable:
+      ##
+      # Default value for the parameter prefix.
+      # Should usually be pulled from the 
+      # +belongs_to+ Sprout::Executable.
       DEFAULT_PREFIX                  = '--'
+
+      ## 
+      # Default prefix for truncated parameters.
+      # Should usually be pulled from the 
+      # +belongs_to+ Sprout::Executable.
       DEFAULT_SHORT_PREFIX            = '-'
 
+      ##
+      # The Sprout::Executable that this parameter
+      # instance belongs to.
       attr_accessor :belongs_to
+
+      ##
+      # Executable::Params join their name/value pair with an
+      # equals sign by default, this can be modified 
+      # To a space or whatever you wish.
+      attr_accessor :delimiter
+
+      ##
+      # The String description that will be used for
+      # RDoc documentation and user help.
       attr_accessor :description
+
+      ##
+      # Boolean value that hides the name parameter
+      # from the shell execution.
+      #
+      #    add_param :name, String, :hidden_name => true
+      #
+      # Without this option, the above parameter would 
+      # serialize to the process like:
+      #
+      #   foo --name=Value
+      #
+      # But with this option, the above parameter would
+      # serialize to the process like:
+      #
+      #   foo Value
+      #
       attr_accessor :hidden_name
+
+      ##
+      # Boolean value that hides the value parameter
+      # from the shell execution.
+      #
+      #   add_param :visible, Boolean, :hidden_value => true
+      #
+      # Without this option, the above parameter would
+      # serialize to the process like:
+      #
+      #   foo --visible=true
+      #
+      # But with this option, the above parameter would
+      # serialize to the process like:
+      #
+      #   foo --visible
+      #
       attr_accessor :hidden_value
-      attr_accessor :file_task_name
+
+      ##
+      # The String (or Symbol) name of the parameter.
       attr_accessor :name
+
+      ##
+      # The String prefix that should be in front of each
+      # command line parameter.
+      #
+      # If no value is set for this option, the 
+      # DEFAULT_PREFIX (--) will be used for regular parameters,
+      # and the DEFAULT_SHORT_PREFIX (-) will be used for short
+      # parameters.
       attr_accessor :prefix
+
+      ##
+      # A Symbol that refers to a custom attribute reader
+      # that is available to instance methods on the 
+      # Sprout::Executable that uses it.
+      #
+      #   add_param :visible, Boolean, :reader => :get_visible
+      #
+      #   def get_visible
+      #     return @visible
+      #   end
+      #
       attr_accessor :reader
+
+      ##
+      # Boolean value that will cause a Sprout::Errors::UsageError
+      # if the executable is invoked without this parameter first
+      # being set.
+      #
+      #   add_param :visible, Boolean :required => true
+      #
+      # Default false
+      #
       attr_accessor :required
+
+      ##
+      # An optional Proc that should be called when this parameter
+      # is serialized to shell output. The Proc should return a 
+      # String value that makes sense to the underlying process.
+      #
+      #   add_param :visible, Boolean, :to_shell_proc => Proc.new {|p| "---result" }
+      #
       attr_accessor :to_shell_proc
+
+      ##
+      # The data type of the parameter, used to generate more appropriate
+      # RDoc content for the concrete Sprout::Executable.
       attr_accessor :type
-      attr_accessor :validator
+      
+      ##
+      # The value that was assigned to this parameter when the 
+      # concrete Sprout::Executable was instantiated and configured.
       attr_accessor :value
-      attr_accessor :visible
-      attr_accessor :writer
 
       ##
-      # Executable::Params join their name/value pair with an
-      # equals sign by default, this can be modified 
-      # To a space or whatever you wish.
-      attr_accessor :delimiter
+      # A Symbol that refers to a custom attribute writer
+      # that is available to instance methods on the 
+      # Sprout::Executable that uses it.
+      #
+      #   add_param :visible, Boolean, :writer => :set_visible
+      #
+      #   def set_visible=(vis)
+      #     @visible = vis
+      #   end
+      #
+      attr_accessor :writer
 
       ##
       # Set the file_expression (blob) to append to each path
@@ -43,17 +182,48 @@ module Sprout
       #
       # Defaults to the parent Executable.default_file_expression
       #
-      # NOTE: We should add support for file_expressionS
+      # TODO: We should add support for file_expressionS
       # since these are really just blobs that are sent
       # to the FileList[expr] and that interface accepts
       # an array.
       attr_writer :file_expression
 
       ##
-      # Return the name with a single leading dash
-      # and underscores replaced with dashes
+      # Optional String value of the name of this parameter
+      # that should be returned to the shell.
+      #
+      # By default, this method will infer the name by
+      # prepending the +prefix+ and replacing underscores
+      # with dashes. For example:
+      #
+      #   add_param :some_name, String
+      #
+      # Would return '--some-name=value' to the shell.
+      #
+      # If this option is set, then the provided value
+      # will be used rather than inferred.
+      #
+      #   add_param :some_name, String, :shell_name => '--OtherName'
+      #
+      # Would return '--OtherName=value' when sent to the shell.
+      #
       attr_writer :shell_name
 
+      ##
+      # Optional String value that should be used for this
+      # parameter's short name. Generally only helpful
+      # for Sprout::Executable 's that are going to be exposed
+      # to Ruby OptionParser as Ruby applications.
+      #
+      # By default, this value will be the first letter
+      # of the parameter name, and when multiple parameters
+      # share the same first letter, the first one encountered
+      # will be used.
+      attr_writer :short_name
+      ##
+      # Default constructor for Params, if you create
+      # a new concrete type, be sure to call +super()+ in your
+      # own constructor.
       def initialize
         @description             = 'Default Description'
         @hidden_value            = false
@@ -70,14 +240,14 @@ module Sprout
       end
       
       ##
-      # Raise an exception if a required parameter is nil.
+      # Returns Boolean value if this parameter is required.
       def required?
         (required == true)
       end
       
       ##
-      # Ensure this parameter is in a valid state, raise an appropriate
-      # exception if it is not.
+      # Ensure this parameter is in a valid state, raise a Sprout::Errors::MissingArgumentError
+      # if it is not.
       def validate
         if(required? && value.nil?)
           raise Sprout::Errors::MissingArgumentError.new("#{name} is required and must not be nil")
@@ -86,11 +256,19 @@ module Sprout
 
       ##
       # Set the default value of the parameter.
+      # Using this option will ensure that required parameters
+      # are not nil, and default values can be overridden on 
+      # instances.
+      #
+      #   add_param :name, String, :default => 'Bob'
+      #
       def default=(value)
         self.value = value
         @default = value
       end
 
+      ##
+      # Return the default value or nil if none was provided.
       def default
         @default
       end
@@ -136,6 +314,9 @@ module Sprout
         @short_prefix ||= (belongs_to.nil?) ? DEFAULT_SHORT_PREFIX : belongs_to.default_short_prefix
       end
 
+      ##
+      # How this parameter is provided to the
+      # Ruby OptionParser when being exposed as a Ruby Executable.
       def option_parser_declaration
         declaration = [ prefix, option_parser_name ]
         # TODO: Need to figure out how to support hidden name inputs...
@@ -148,14 +329,30 @@ module Sprout
         declaration.join('')
       end
 
+      ##
+      # The Ruby OptionParser short name with prefix.
       def option_parser_short_name
         [ short_prefix, short_name ].join('')
       end
       
+      ##
+      # The short name for this parameter.
+      # If it's not explicitly, the first
+      # character of the parameter name will
+      # be used. When multiple parameters have
+      # the same first character, the first one
+      # encountered will win.
       def short_name
         @short_name ||= name.to_s.split('').shift
       end
 
+      ##
+      # The String representation of the value in
+      # a format that is appropriate for the terminal.
+      #
+      # For certain types of parameters, like File,
+      # spaces may be escaped on some platforms.
+      #
       def shell_value
         value.to_s
       end
@@ -168,6 +365,13 @@ module Sprout
         @shell_name ||= prefix + name.to_s.split('_').join('-')
       end
 
+      ##
+      # Prepare and serialize this parameter to a string
+      # that is appropriate for shell execution on the
+      # current platform.
+      #
+      # Calling +to_shell+ will first trigger a call to
+      # the +prepare+ template method unless +prepared?+ returns +true+.
       def to_shell
         prepare if !prepared?
         validate
@@ -208,10 +412,22 @@ module Sprout
       def prepare_prerequisites
       end
 
+      ##
+      # Clean the provided path using the current Sprout::System.
       def clean_path path
         Sprout::System.create.clean_path path
       end
 
+      ##
+      # Return true if the Sprout::Executable
+      # that this parameter +belongs_to+ has an +output+
+      # method (or parameter), and if the provided +file+
+      # matches the value of that parameter.
+      #
+      # This method (convention) is used to avoid creating circular
+      # prerequisites in Rake. For most types of File parameters
+      # we want to make them into prerequisites, but not if the
+      # File is the one being created by the outer Sprout::Executable.
       def file_is_output? file
         belongs_to.respond_to?(:output) && belongs_to.output.to_s == file
       end