lazier 4.1.0 → 4.2.0

data/doc/top-level-namespace.html

@@ -6,7 +6,7 @@
 <title>
   Top Level Namespace
   
-    &mdash; Documentation by YARD 0.8.7.4
+    &mdash; Documentation by YARD 0.8.7.6
   
 </title>
 
@@ -103,9 +103,9 @@
 </div>
 
     <div id="footer">
-  Generated on Thu Oct  2 10:38:44 2014 by
+  Generated on Sun Nov  2 11:08:44 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.8.7.4 (ruby-2.1.3).
+  0.8.7.6 (ruby-2.1.3).
 </div>
 
   </body>

data/lib/lazier.rb

@@ -3,6 +3,8 @@
 # Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
 #
 
+# PI: Ignore flog on this file.
+
 require(RUBY_ENGINE != "jruby" ? "oj" : "json")
 require "English"
 require "tzinfo"
@@ -43,15 +45,14 @@ module Lazier
   # Loads the extensions.
   #
   # @param what [Array] The modules to load. Valid values are:
-  #
-  #   @option object Extensions for all objects.
-  #   @option boolean Extensions for boolean values.
-  #   @option string Extensions for strings.
-  #   @option hash Extensions for hashs.
-  #   @option hash_method_access Extensions for hash to allow method access. Not included by default.
-  #   @option datetime Extensions date and time objects.
-  #   @option math Extensions for Math module.
-  #   @option pathname Extensions for path objects.
+  # @option object Extensions for all objects.
+  # @option boolean Extensions for boolean values.
+  # @option string Extensions for strings.
+  # @option hash Extensions for hashs.
+  # @option hash_method_access Extensions for hash to allow method access. Not included by default.
+  # @option datetime Extensions date and time objects.
+  # @option math Extensions for Math module.
+  # @option pathname Extensions for path objects.
   # @return [Settings] The settings for the extensions.
   def self.load!(*what)
     valid_modules = [:object, :boolean, :string, :hash, :datetime, :math, :pathname]
@@ -62,13 +63,13 @@ module Lazier
     ::Lazier::Settings.instance
   end
 
-  # Loads Object extensions.
+  # Loads `Object` extensions.
   def self.load_object
     Lazier.load_boolean
     perform_load(:object, ::Object, ::Lazier::Object)
   end
 
-  # Loads Boolean extensions.
+  # Loads `Boolean` extensions.
   def self.load_boolean
     perform_load(:boolean) do
       [::TrueClass, ::FalseClass].each do |klass|
@@ -80,12 +81,12 @@ module Lazier
     end
   end
 
-  # Loads String extensions.
+  # Loads `String` extensions.
   def self.load_string
     perform_load(:string, ::String, ::Lazier::String)
   end
 
-  # Loads Hash extensions.
+  # Loads `Hash` extensions.
   def self.load_hash
     Lazier.load_object
 
@@ -95,7 +96,7 @@ module Lazier
     end
   end
 
-  # Loads DateTime extensions.
+  # Loads `DateTime` extensions.
   def self.load_datetime
     Lazier.load_object
 
@@ -108,13 +109,13 @@ module Lazier
     end
   end
 
-  # Loads Math extensions.
+  # Loads `Math` extensions.
   def self.load_math
     Lazier.load_object
     perform_load(:math, ::Math, ::Lazier::Math)
   end
 
-  # Loads Pathname extensions.
+  # Loads `Pathname` extensions.
   def self.load_pathname
     perform_load(:pathname, ::Pathname, ::Lazier::Pathname)
   end
@@ -153,7 +154,7 @@ module Lazier
   # Measure the time in milliseconds required to execute the given block.
   #
   # @param message [String|NilClass] An optional message (see return value).
-  # @param precision [Fixnum] The precision for the message (see return value)..
+  # @param precision [Fixnum] The precision for the message (see return value).
   # @param block [Proc] The block to evaluate.
   # @return [Float|String] If a `message` is provided, then the message itself plus the duration under parenthesis will be returned,
   #   otherwise the duration alone as a number.

data/lib/lazier/boolean.rb

@@ -8,7 +8,7 @@ module Lazier
   module Boolean
     extend ::ActiveSupport::Concern
 
-    # Converts the boolean to an integer.
+    # Converts the boolean to a integer.
     #
     # @return [Fixnum] `1` for `true`, `0` for `false`.
     def to_i

data/lib/lazier/configuration.rb

@@ -7,22 +7,22 @@ module Lazier
   # A configuration class to set properties.
   class Configuration < Hashie::Dash
     # Initializes a new configuration object.
+    # @see Hash#initialize
     #
     # @param attributes [Hash] The initial values of properties of this configuration.
+    # @param block [Proc] A block to use for default values.
     def initialize(attributes = {}, &block)
       @i18n = Lazier::I18n.instance
       super(attributes, &block)
     end
 
     # Defines a property on the configuration.
-    # Options are as follows:
-    #
-    # * :default - Specify a default value for this property.
-    # * :required - Specify the value as required for this property, to raise an error if a value is unset in a new or existing configuration.
-    # * :readonly - Specify if the property is readonly, which means that it can only defined during creation of the configuration.
-    #
+
     # @param name [String|Symbol] The new property name.
     # @param options [Hash] The options for the property.
+    # @option options [Boolean] :default Specify a default value for this property.
+    # @option options [Boolean] :required Specify the value as required for this property, to raise an error if a value is unset in a new or existing configuration.
+    # @option options [Boolean] :readonly Specify if the property is readonly, which means that it can only defined during creation of the configuration.
     def self.property(name, options = {})
       super(name, options)
 

data/lib/lazier/datetime.rb

@@ -47,8 +47,8 @@ module Lazier
       #
       # @param offset [Fixnum] The width of the range.
       # @param also_future [Boolean] If return also future years.
-      # @param reference [Fixnum] The ending (or middle, if `also_future` is `true`) value of the range. Defaults to the current year.
-      # @param as_objects [Boolean] If to return years in hashes with `:value` and `label` keys.
+      # @param reference [Fixnum|NilClass] The ending (or middle, if `also_future` is `true`) value of the range. Defaults to the current year.
+      # @param as_objects [Boolean] Whether to return years in hashes with `:value` and `label` keys.
       # @return [Array] A range of years. Every entry is
       def years(offset: 10, also_future: true, reference: nil, as_objects: false)
         y = reference || ::Date.today.year
@@ -80,7 +80,7 @@ module Lazier
       # Returns the Easter (according to Gregorian calendar) date for the year.
       # @see http://en.wikipedia.org/wiki/Computus#Anonymous_Gregorian_algorithm
       #
-      # @param year [Fixnum] The year to compute the date for. Defaults to the current year.
+      # @param year [Fixnum|NilClass] The year to compute the date for. Defaults to the current year.
       # @return [Date] The Easter date for the year.
       def easter(year = nil)
         year = ::Date.today.year unless year.integer?
@@ -138,20 +138,20 @@ module Lazier
 
     # Returns the number of months passed between the beginning of the base year and the current date.
     #
-    # ```ruby
-    # DateTime.civil(2013, 6, 1).in_months(2011)
-    # # => 18
-    # ```
+    # Example:
     #
-    # @param base [DateTime] The base year to start computation from. Default to current year.
+    #     DateTime.civil(2013, 6, 1).in_months(2011)
+    #     # => 18
+    #
+    # @param base [DateTime|NilClass] The base year to start computation from. Default to current year.
     # @return [Fixnum] Returns the number of months passed between the beginning of the base year and the current date.
     def months_since_year(base = nil)
       (year - (base || ::Date.today.year)) * 12 + month
     end
 
-    # Returns the current month number with leading 0.
+    # Returns the current month number with a leading zero if needed.
     #
-    # @return [String] The current month number with leading 0.
+    # @return [String] The current month number with leading zero if needed.
     def padded_month
       month.indexize
     end
@@ -159,7 +159,7 @@ module Lazier
     # Formats a datetime, eventually looking up also custom formats and/or moving to the current timezone.
     # @see Settings#setup_date_formats
     #
-    # @param format [String] A format or a custom format name to use for formatting.
+    # @param format [String|NilClass] A format or a custom format name to use for formatting.
     # @param custom [Boolean] Whether to use custom formats.
     # @param change_time_zone [Boolean] Whether to move the date to the current timezone.
     # @return [String] The formatted date.

data/lib/lazier/exceptions.rb

@@ -12,7 +12,12 @@ module Lazier
 
     # This is the handler for the core I18n gem.
     class TranslationExceptionHandler < ::I18n::ExceptionHandler
-      # :nodoc:
+      # Implements the ExceptionHandler interface for I18n.
+      #
+      # @param exception [Exception] The error to raise.
+      # @param locale [String|Symbol] The locale that was requested.
+      # @param key [String|Symbol] The key that was requested.
+      # @param options [Hash] The options passed to the translation.
       def call(exception, locale, key, options)
         exception.is_a?(::I18n::MissingTranslation) ? raise(exception.to_exception) : super
       end
@@ -23,7 +28,7 @@ module Lazier
       # Creates a new missing translation exception.
       #
       # @param locale [Array] The locale that was requested to use.
-      # @param message [String] The message that was requested to translate.
+      # @param message [String|NilClass] The message that was requested to translate.
       def initialize(locale, message = nil)
         locale, message = locale if message.nil?
         super("Unable to load the translation \"#{message}\" for the locale \"#{locale}\".")

data/lib/lazier/hash.rb

@@ -4,7 +4,7 @@
 #
 
 module Lazier
-  # Extensions for Hash objects.
+  # Extensions for `Hash` objects.
   module Hash
     # The supported accesses for #ensure_access
     VALID_ACCESSES = {
@@ -18,7 +18,7 @@ module Lazier
 
     # Returns a new hash, removing all keys which values are blank.
     #
-    # @param validator [Proc], if present all the keys which evaluates to true will be removed. Otherwise all blank values will be removed.
+    # @param validator [Proc] If present all the keys which evaluates to true will be removed. Otherwise all blank values will be removed.
     # @return [Hash] The hash with all blank values removed.
     def compact(&validator)
       dup.compact!(&validator)
@@ -26,7 +26,7 @@ module Lazier
 
     # Compacts the current hash, removing all keys which values are blank.
     #
-    # @param validator [Proc], if present all the keys which evaluates to true will be removed. Otherwise all blank values will be removed.
+    # @param validator [Proc] If present all the keys which evaluates to true will be removed. Otherwise all blank values will be removed.
     def compact!(&validator)
       validator ||= ->(_, v) { v.blank? }
       reject!(&validator)
@@ -34,7 +34,7 @@ module Lazier
 
     # Makes sure that the keys of the hash are accessible in the desired way.
     #
-    # @param accesses [Array] The requested access for the keys. Can be `:strings`, `:symbols` or `:indifferent`. If `nil` the keys are not modified.
+    # @param accesses [Array] The requested access for the keys. Can be `:dotted`, `:strings`, `:symbols` or `:indifferent`. If `nil` the keys are not modified.
     # @return [Hash] The current hash with keys modified.
     def ensure_access(*accesses)
       methods = accesses.ensure_array(compact: true, no_duplicates: true, flatten: true) { |m| VALID_ACCESSES[m.ensure_string.to_sym] }.compact

data/lib/lazier/i18n.rb

@@ -23,10 +23,10 @@ module Lazier
 
     # Returns the singleton instance of the settings.
     #
-    # @param locale [Symbol] The locale to use for translations. Default is the current system locale.
+    # @param locale [Symbol|NilClass] The locale to use for translations. Default is the current system locale.
     # @param root [Symbol] The root level of the translation.
-    # @param path [String] The path where the translations are stored.
-    # @param force [Boolean] If to force recreation of the instance.
+    # @param path [String|NilClass] The path where the translations are stored.
+    # @param force [Boolean] Whether to force recreation of the instance.
     # @return [I18n] The singleton instance of the i18n.
     def self.instance(locale = nil, root: :lazier, path: nil, force: false)
       @instance = nil if force
@@ -35,9 +35,9 @@ module Lazier
 
     # Creates a new I18n object.
     #
-    # @param locale [Symbol] The locale to use. Defaults to the current locale.
+    # @param locale [Symbol|NilClass] The locale to use. Defaults to the current locale.
     # @param root [Symbol] The root level of the translation.
-    # @param path [String] The path where the translations are stored.
+    # @param path [String|NilClass] The path where the translations are stored.
     def initialize(locale = nil, root: :lazier, path: nil)
       Lazier.load_object
       path ||= Lazier::ROOT + "/locales"
@@ -57,7 +57,7 @@ module Lazier
 
     # Gets the list of available translation for a locale.
     #
-    # @param locale [Symbol] The locale to list. Defaults to the current locale.
+    # @param locale [Symbol|NilClass] The locale to list. Defaults to the current locale.
     # @return [Hash] The available translations for the specified locale.
     def translations(locale = nil)
       locale ||= @locale
@@ -98,8 +98,8 @@ module Lazier
 
     # Localize a message in a specific locale.
     #
-    # @param message [String|Symbol] The message to localize.
     # @param locale [String|Symbol] The new locale to use for localization.
+    # @param message [String|Symbol] The message to localize.
     # @param args [Array] Optional arguments to localize the message.
     # @return [String] The localized message.
     def translate_in_locale(locale, message, *args)

data/lib/lazier/math.rb

@@ -4,13 +4,13 @@
 #
 
 module Lazier
-  # Utility methods for Math module.
+  # Utility methods for `Math` module.
   module Math
     extend ::ActiveSupport::Concern
 
     # General methods.
     module ClassMethods
-      # Returns the minimum value in the arguments
+      # Returns the minimum value between the arguments.
       #
       # @param args [Array] A list of objects to compare (with the `<` operator).
       # @return [Object] The minimum value or `nil` (if the list is empty).
@@ -18,7 +18,7 @@ module Lazier
         args.ensure_array(default: [], no_duplicates: true, compact: true, flatten: true).min
       end
 
-      # Returns the maximum value in the arguments
+      # Returns the maximum value between the arguments.
       #
       # @param args [Array] A list of objects to compare (with the `>` operator).
       # @return [Object] The maximum value or `nil` (if the list is empty).

data/lib/lazier/object.rb

@@ -93,10 +93,10 @@ module Lazier
     # Makes sure that the object is an array. For non array objects, return a single element array containing the object.
     #
     # @param default [Array|NilClass] The default array to use. If not specified, an array containing the object is returned.
-    # @param no_duplicates [Boolean] If to remove duplicates from the array before sanitizing.
-    # @param compact [Boolean] If to compact the array before sanitizing.
-    # @param flatten [Boolean] If to flatten the array before sanitizing.
-    # @param sanitizer [Symbol|nil] If not `nil`, the method to use to sanitize entries of the array. *Ignored if a block is present.*
+    # @param no_duplicates [Boolean] Whether to remove duplicates from the array before sanitizing.
+    # @param compact [Boolean] Whether to compact the array before sanitizing.
+    # @param flatten [Boolean] Whether to flatten the array before sanitizing.
+    # @param sanitizer [Symbol|NilClass] If not `nil`, the method to use to sanitize entries of the array. *Ignored if a block is present.*
     # @param block [Proc] A block to sanitize entries. It must accept the value as unique argument.
     # @return [Array] If the object is an array, then the object itself, a single element array containing the object otherwise.
     def ensure_array(default: nil, no_duplicates: false, compact: false, flatten: false, sanitizer: nil, &block)
@@ -119,7 +119,7 @@ module Lazier
     # @param default [Hash|String|Symbol|NilClass] The default value to use. If it is an `Hash`, it is returned as value otherwise it is used to build
     #   as a key to build an hash with the current object as only value (everything but strings and symbols are mapped to `key`).
     #   Passing `nil` is equal to pass an empty Hash.
-    # @param sanitizer [Symbol|nil] If not `nil`, the method to use to sanitize values of the hash. *Ignored if `block` is present.*
+    # @param sanitizer [Symbol|NilClass] If not `nil`, the method to use to sanitize values of the hash. *Ignored if `block` is present.*
     # @param block [Proc] A block to sanitize entries. It must accept the value as unique argument.
     # @return [Hash] If the object is an hash, then the object itself, a hash with the object as single value otherwise.
     def ensure_hash(accesses: nil, default: {}, sanitizer: nil, &block)
@@ -184,11 +184,11 @@ module Lazier
     # Formats a number.
     # @see Settings#setup_format_number
     #
-    # @param precision [Fixnum] The precision to show.
-    # @param decimal_separator [String] The string to use as decimal separator.
-    # @param add_string [String] The string to append to the number.
-    # @param k_separator [String] The string to use as thousands separator.
-    # @return [String] The string representation of the object.
+    # @param precision [Fixnum|NilClass] The precision to show.
+    # @param decimal_separator [String|NilClass] The string to use as decimal separator.
+    # @param add_string [String|NilClass] The string to append to the number.
+    # @param k_separator [String|NilClass] The string to use as thousands separator.
+    # @return [String|NilClass] The string representation of the object or `nil`, if the object is not a number.
     def format_number(precision: nil, decimal_separator: nil, add_string: nil, k_separator: nil)
       if number?
         settings = ::Lazier.settings.format_number
@@ -206,19 +206,21 @@ module Lazier
     # Formats a boolean.
     # @see Settings#setup_boolean_names
     #
-    # @param true_name [String] The string representation of `true`. Defaults to `Yes`.
-    # @param false_name [String] The string representation of `false`. Defaults to `No`.
+    # @param true_name [String|NilClass] The string representation of `true`. Defaults to `Yes`.
+    # @param false_name [String|NilClass] The string representation of `false`. Defaults to `No`.
     # @return [String] The string representation of the object.
     def format_boolean(true_name: nil, false_name: nil)
       settings = ::Lazier.settings.boolean_names
       to_boolean ? (true_name || settings[true]) : (false_name || settings[false])
     end
 
-    # Prepares an object to be printed in list summaries, like `[01/04] Opening this...`.
+    # Prepares an object to be printed in list summaries, like
+    #
+    #     [01/04] Opening this...
     #
     # @param length [Fixnum] The minimum length of the label.
-    # @param filler [String] The minimum length of the label.
-    # @param formatter [Symbol] The method to use to format the label. Must accept the `length` and the `filler arguments.
+    # @param filler [String] The character to use to fill the label.
+    # @param formatter [Symbol] The method to use to format the label. Must accept the `length` and the `filler` arguments.
     # @return [String] The object inspected and formatted.
     def indexize(length: 2, filler: "0", formatter: :rjust)
       ensure_string.send(formatter, length, filler)

data/lib/lazier/pathname.rb

@@ -4,16 +4,14 @@
 #
 
 module Lazier
-  # Extensions for the Pathname class.
+  # Extensions for the `Pathname` class.
   module Pathname
     extend ::ActiveSupport::Concern
 
     # Returns all the components that are included in this path.
     #
-    # ```ruby
-    # Pathname.new("/usr/bin/ruby").components
-    # # => ["usr", "bin", "ruby"]
-    # ```
+    #     Pathname.new("/usr/bin/ruby").components
+    #     # => ["usr", "bin", "ruby"]
     #
     # @return [Array] A list of all components that are included in this path.
     def components

data/lib/lazier/settings.rb

@@ -21,7 +21,7 @@ module Lazier
 
     # Returns the singleton instance of the settings.
     #
-    # @param force [Boolean] If to force recreation of the instance.
+    # @param force [Boolean] Whether to force recreation of the instance.
     # @return [Settings] The singleton instance of the settings.
     def self.instance(force = false)
       @instance = nil if force
@@ -60,8 +60,8 @@ module Lazier
     # Setups strings representation of booleans.
     # @see Object#format_boolean
     #
-    # @param true_name [String] The string representation of `true`. Defaults to `Yes`.
-    # @param false_name [String] The string representation of `false`. Defaults to `No`.
+    # @param true_name [String|NilClass] The string representation of `true`. Defaults to `Yes`.
+    # @param false_name [String|NilClass] The string representation of `false`. Defaults to `No`.
     # @return [Hash] The new representations.
     def setup_boolean_names(true_name: nil, false_name: nil)
       names = i18n.translate("boolean")
@@ -71,8 +71,8 @@ module Lazier
     # Setups custom formats for dates and times.
     # @see DateTime#lstrftime
     #
-    # @param formats [Hash] The format to add or replace.
-    # @param replace [Boolean] If to discard current formats.
+    # @param formats [Hash|NilClass] The format to add or replace.
+    # @param replace [Boolean] Whether to discard current formats.
     # @return [Hash] The new formats.
     def setup_date_formats(formats = nil, replace = false)
       @date_formats = HashWithIndifferentAccess.new if replace || !@date_formats
@@ -87,12 +87,12 @@ module Lazier
     # Setups strings representation of days and months.
     # @see DateTime::ClassMethods#days
     # @see DateTime::ClassMethods#months
-    # @see DateTime#lstrftime
+    # @see Lazier::DateTime#format
     #
-    # @param long_months [Array] The string representation of months.
-    # @param short_months [Array] The abbreviated string representation of months.
-    # @param long_days [Array] The string representation of days.
-    # @param short_days [Array] The abbreviated string representation of days.
+    # @param long_months [Array|NilClass] The string representation of months.
+    # @param short_months [Array|NilClass] The abbreviated string representation of months.
+    # @param long_days [Array|NilClass] The string representation of days.
+    # @param short_days [Array|NilClass] The abbreviated string representation of days.
     # @return [Hash] The new representations.
     def setup_date_names(long_months: nil, short_months: nil, long_days: nil, short_days: nil)
       definitions = prepare_definitions