@@ -17,16 +17,12 @@ class Plow # 4. Start a new `Plow::Generator` while handling any library specific exceptions raised. # # @return [Number] Success will return 0, while failure will most likely return a number > 0. - # @overload launch(user_name, site_name) - # Only the user_name and site_name are provided by the user. - # @param [String] user_name Name of a Linux system account user (e.g. steve) - # @param [String] site_name Name of the web-site (e.g. www.apple.com) # @overload launch(user_name, site_name, *site_aliases) # In addition to the user_name and site_aliases, an array of n site_aliases are also # provided by the user. # @param [String] user_name Name of a Linux system account user (e.g. steve) # @param [String] site_name Name of the web-site (e.g. www.apple.com) - # @param [Array] *site_aliases (Optional) List of alias names of the web-site + # @param [splat] *site_aliases (Optional) List of alias names of the web-site # (e.g. apple.com) def launch(*arguments) puts version_stamp lib/plow/application.rb @@ -1,30 +1,48 @@ # encoding: UTF-8 class Plow - # A small class that provides Struct-like access to instance variables, but in in a far more simple internal implementation. - # useful for ERB templates. + # `BindingStruct` is an **adapter** between the friendly declarative-style of `Hash` key/value + # pairs and the built-in, `ERB` (i.e. embedded ruby) class, which takes an optional `Binding` + # object for the scope of template evaluation. + # + # This class is very similar to Ruby's built-in `OpenStruct` class. It differs internally as + # `BindingStruct` converts each element of the `Hash` object into an instance variable during + # initialization. Once initialized, an instance of `BindingStruct` is able to return a + # reference to it's internal `Binding` object. This object can be further passed along to an + # `ERB` object for evaluation within a template. + # + # @example Sample template file at /path/to/a/template/file.txt' + # My hero is <%= @first_name %> <%= @last_name %>. + # + # @example Evaluating an `ERB` template file with a `BindingStruct` context + # template = ERB.new(File.read('/path/to/a/template/file.txt')) + # context = Plow::BindingStruct.new({ first_name: 'Carl', last_name: 'Sagan' }) + # result = template.result(context.get_binding) #=> My hero is Carl Sagan. # # @see http://www.ruby-doc.org/ruby-1.9/classes/Binding.html # @see http://www.ruby-doc.org/ruby-1.9/classes/ERB.html - # @see http://www.ruby-doc.org/ruby-1.9/classes/Struct.html + # @see http://www.ruby-doc.org/ruby-1.9/classes/OpenStruct.html class BindingStruct - # Creates a new `BindingStruct` from a `Hash` object where each key/value pair is an instance variable within the object. + # Creates a new `BindingStruct` from a `Hash` where each key/value pair is converted to an + # instance variable. # - # @param [Hash] hash A basic `Hash` object - # @example Usage + # @param [Hash] source A source of data + # @example A peek into the internals of an instance post initialization # bstruct = Plow::BindingStruct.new({first_name: 'Carl', last_name: 'Sagan'}) - # bstruct.instance_variable_get("@first_name") #=> 'Carl' - # bstruct.instance_variable_get("@last_name") #=> 'Sagan' - def initialize(hash) - hash.each_pair do |name, val| + # bstruct.instance_variables.sort #=> [:@first_name, :@last_name] + # bstruct.instance_variable_get(:@first_name) #=> 'Carl' + # bstruct.instance_variable_get(:@last_name) #=> 'Sagan' + def initialize(source) + source.each_pair do |name, val| instance_variable_set("@#{name}".to_sym, val) end end - # Returns an internal `Binding` object + # Returns a reference to its internal `Binding` which can be used in conjunction with `ERB` + # template evaluation. # - # @return [Binding] An internal `Binding` object + # @return [Binding] An reference to its internal `Binding` # @see http://www.ruby-doc.org/ruby-1.9/classes/Binding.html def get_binding binding lib/plow/binding_struct.rb @@ -1,7 +1,15 @@ # encoding: UTF-8 +# Carefully adding methods the the base `Object` class. class Object - # See http://api.rubyonrails.org/classes/Object.html#M000279 + # An object is blank if it‘s false, empty, or a whitespace string. + # For example, "", " ", nil, [], and {} are blank. + # + # @example This simplifies + # if !address.nil? && !address.empty? + # @example to + # if !address.blank? + # @see http://api.rubyonrails.org/classes/Object.html#M000279 def blank? respond_to?(:empty?) ? empty? : !self end lib/plow/core_ext/object.rb 0fbf1c202de9aae045791c692d9d6e5e2d0a2d94 Ryan Sobol code@ryansobol.com http://github.com/ryansobol/plow/commit/54a44b08185eee6e9d14bd9a2f9b3fdd32f55c58 54a44b08185eee6e9d14bd9a2f9b3fdd32f55c58 2009-10-29T19:59:21-07:00 2009-10-29T19:59:21-07:00 * lib/plow/application.rb * removed duplicate @overload explanation * renamed @param [Array] *site_aliases to @param [splat] *site_aliases for clarity * lib/plow/binding_struct.rb * significantly improved sustainability with yardoc * lib/plow/core_ext/object.rb * significantly improved sustainability with yardoc dbf6adcdf4ecca51e966decb9f35a9a70277d7bf Ryan Sobol code@ryansobol.com