mbrao 1.5.0 → 1.6.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 Sun May 11 18:17:16 2014 by
+  Generated on Tue Mar 29 12:47:22 2016 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.8.7.4 (ruby-2.1.0).
+  0.8.7.6 (ruby-2.3.0).
 </div>
 
   </body>

data/lib/mbrao/author.rb

@@ -39,7 +39,7 @@ module Mbrao
       @email = Mbrao::Parser.email?(email) ? email : nil
       @website = Mbrao::Parser.url?(website) ? website : nil
       @image = Mbrao::Parser.url?(image) ? image : nil
-      @metadata = metadata.ensure_hash(:indifferent)
+      @metadata = metadata.ensure_hash(accesses: :indifferent)
     end
 
     # Returns the author as an Hash.

data/lib/mbrao/content.rb

@@ -56,7 +56,7 @@ module Mbrao
     #
     # @param value [Array] The new value for the attribute. A empty or "*" will be the default value.
     def locales=(value)
-      @locales = value.ensure_array(nil, true, true, true) { |l| l.ensure_string.strip }
+      @locales = value.ensure_array(no_duplicates: true, compact: true, flatten: true) { |l| l.ensure_string.strip }
     end
 
     # Sets the `title` attribute.
@@ -64,7 +64,7 @@ module Mbrao
     # @param new_title [String|Hash] The new value for the attribute. If an Hash, keys must be a string with one or locale separated by commas.
     #   A empty or "*" will be the default value.
     def title=(new_title)
-      @title = hash?(new_title) ? new_title.ensure_hash(:indifferent, nil, :ensure_string) : new_title.ensure_string
+      @title = hash?(new_title) ? new_title.ensure_hash(accesses: :indifferent, default: nil, sanitizer: :ensure_string) : new_title.ensure_string
     end
 
     # Sets the `summary` attribute.
@@ -72,7 +72,7 @@ module Mbrao
     # @param new_summary [String|Hash] The new value for the attribute. If an Hash, keys must be a string with one or locale separated by commas.
     #   A empty or "*" will be the default value.
     def summary=(new_summary)
-      @summary = hash?(new_summary) ? new_summary.ensure_hash(:indifferent, nil, :ensure_string) : new_summary.ensure_string
+      @summary = hash?(new_summary) ? new_summary.ensure_hash(accesses: :indifferent, default: nil, sanitizer: :ensure_string) : new_summary.ensure_string
     end
 
     # Sets the `body` attribute.
@@ -87,7 +87,7 @@ module Mbrao
     # @param new_tags [Array|Hash] The new value for the attribute. If an Hash, keys must be a string with one or locale separated by commas.
     #   A empty or "*" will be the default value. Tags can also be comma-separated.
     def tags=(new_tags)
-      @tags = hash?(new_tags) ? new_tags.ensure_hash(:indifferent) { |v| parse_tags(v) } : parse_tags(new_tags)
+      @tags = hash?(new_tags) ? new_tags.ensure_hash(accesses: :indifferent) { |v| parse_tags(v) } : parse_tags(new_tags)
     end
 
     # Sets the `more` attribute.
@@ -95,7 +95,7 @@ module Mbrao
     # @param new_more [String|Hash] The new value for the attribute. If an Hash, keys must be a string with one or locale separated by commas.
     #   A empty or "*" will be the default value.
     def more=(new_more)
-      @more = hash?(new_more) ? new_more.ensure_hash(:indifferent, nil, :ensure_string) : new_more.ensure_string
+      @more = hash?(new_more) ? new_more.ensure_hash(accesses: :indifferent, default: nil, sanitizer: :ensure_string) : new_more.ensure_string
     end
 
     # Sets the `author` attribute.
@@ -105,8 +105,8 @@ module Mbrao
       @author =
         if new_author.is_a?(Mbrao::Author)
           new_author
-        elsif hash?(new_author) then
-          Mbrao::Author.create(new_author.ensure_hash(:indifferent))
+        elsif hash?(new_author)
+          Mbrao::Author.create(new_author.ensure_hash(accesses: :indifferent))
         else
           new_author ? Mbrao::Author.new(new_author.ensure_string) : nil
         end
@@ -130,15 +130,44 @@ module Mbrao
     #
     # @param new_metadata [Hash] The new value for the attribute.
     def metadata=(new_metadata)
-      @metadata = hash?(new_metadata) ? new_metadata.ensure_hash(:indifferent) : @metadata = HashWithIndifferentAccess.new({raw: new_metadata})
+      @metadata = hash?(new_metadata) ? new_metadata.ensure_hash(accesses: :indifferent) : @metadata = HashWithIndifferentAccess.new({raw: new_metadata})
     end
 
-    private
+    # Assigns metadata to a content
+    #
+    # @param content [Content] The content to manipulate.
+    # @param metadata [Hash] The metadata to assign.
+    # @return [Content] The content with metadata.
+    def self.assign_metadata(content, metadata)
+      [:uid, :title, :summary, :tags, :more, :created_at, :updated_at].each do |field|
+        content.send("#{field}=", metadata.delete(field))
+      end
 
-    # Extracts a date and time from a value.
+      content.author = Mbrao::Author.create(metadata.delete(:author))
+      content.locales = extract_locales(metadata.delete(:locales))
+      content.metadata = metadata
+    end
+
+    # Extracts locales from metadata.
     #
-    # @param value [String|DateTime|Fixnum] The value to parse.
-    # @return [DateTime] The extracted value.
+    # @param locales [String] The list of locales.
+    # @return [Array] The locales.
+    def self.extract_locales(locales)
+      locales = locales.ensure_string.split(/\s*,\s*/) unless locales.is_a?(::Array)
+      normalize_locales(locales)
+    end
+
+    # Normalizes locales for further usage.
+    #
+    # @param locales [Array] The locales to normalize.
+    # @return [Array] The normalized locales.
+    def self.normalize_locales(locales)
+      locales.flatten.map(&:ensure_string).map(&:strip).uniq
+    end
+
+    private
+
+    # :nodoc:
     def extract_datetime(value)
       value = parse_datetime(value) if value
       value ? value.utc : nil
@@ -146,10 +175,7 @@ module Mbrao
       raise Mbrao::Exceptions::InvalidDate
     end
 
-    # Parses a datetime.
-    #
-    # @param value [String|DateTime|Fixnum] The value to parse.
-    # @return [DateTime] The extracted value.
+    # :nodoc:
     def parse_datetime(value)
       rv =
         case value.class.to_s
@@ -163,19 +189,13 @@ module Mbrao
       rv
     end
 
-    # Parses a datetime from a number.
-    #
-    # @param value [String] The value to parse.
-    # @return [Float|Fixnum] The extracted value.
+    # :nodoc:
     def parse_datetime_number(value)
       number = value.to_float
       number > 0 ? Time.at(number).to_datetime : nil
     end
 
-    # Parses a datetime from a string.
-    #
-    # @param value [String] The value to parse.
-    # @return [DateTime] The extracted value.
+    # :nodoc:
     def parse_datetime_string(value)
       value = value.ensure_string
 
@@ -190,52 +210,14 @@ module Mbrao
       end
     end
 
-    # Extracts tags from an array, making sure all the comma separated strings are evaluated.
-    #
-    # @param value [String|Array] The string or array to parse.
-    # @return [Array] The list of tags.
+    # :nodoc:
     def parse_tags(value)
-      value.ensure_array(nil, true, true, true) { |v| v.ensure_string.split(/\s*,\s*/) }
+      value.ensure_array(no_duplicates: true, compact: true, flatten: true) { |v| v.ensure_string.split(/\s*,\s*/) }
     end
 
-    # Check if value is an Hash.
-    #
-    # @param value [Object] The object to check.
-    # @return [Boolean] `true` if value is an Hash, `false` otherwise
+    # :nodoc:
     def hash?(value)
       value.is_a?(Hash)
     end
-
-    # Assigns metadata to a content
-    #
-    # @param content [Content] The content to manipulate.
-    # @param metadata [Hash] The metadata to assign.
-    # @return [Content] The content with metadata.
-    def self.assign_metadata(content, metadata)
-      [:uid, :title, :summary, :tags, :more, :created_at, :updated_at].each do |field|
-        content.send("#{field}=", metadata.delete(field))
-      end
-
-      content.author = Mbrao::Author.create(metadata.delete(:author))
-      content.locales = extract_locales(metadata.delete(:locales))
-      content.metadata = metadata
-    end
-
-    # Extracts locales from metadata.
-    #
-    # @param locales [String] The list of locales.
-    # @return [Array] The locales.
-    def self.extract_locales(locales)
-      locales = locales.ensure_string.split(/\s*,\s*/) unless locales.is_a?(::Array)
-      normalize_locales(locales)
-    end
-
-    # Normalizes locales for further usage.
-    #
-    # @param locales [Array] The locales to normalize.
-    # @return [Array] The normalized locales.
-    def self.normalize_locales(locales)
-      locales.flatten.map(&:ensure_string).map(&:strip).uniq
-    end
   end
 end

data/lib/mbrao/content_interface.rb

@@ -19,7 +19,7 @@ module Mbrao
 
       "%F %T.%L", "%F %T", "%F %H:%M", "%F",
       "%d/%m/%Y %T.%L", "%d/%m/%Y %T", "%d/%m/%Y %H:%M", "%d/%m/%Y"
-    ]
+    ].freeze
 
     # Class methods.
     module ClassMethods
@@ -30,7 +30,7 @@ module Mbrao
       # @param content [Content|nil] An optional content to check for availability
       # @return [Array] The validated list of locales.
       def validate_locales(locales, content = nil)
-        locales = locales.ensure_array(nil, true, true, true) { |l| l.ensure_string.strip }
+        locales = locales.ensure_array(no_duplicates: true, compact: true, flatten: true) { |l| l.ensure_string.strip }
         locales = (locales.empty? ? [Mbrao::Parser.locale] : locales)
         raise Mbrao::Exceptions::UnavailableLocalization if content && !content.enabled_for_locales?(locales)
         locales
@@ -54,7 +54,7 @@ module Mbrao
     # @param locales [Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
     # @return [Boolean] `true` if the content is available for at least one of the desired locales, `false` otherwise.
     def enabled_for_locales?(*locales)
-      locales = locales.flatten.ensure_array(nil, false, false, true) { |l| l.ensure_string.strip }.reject { |l| l == "*" }
+      locales = locales.flatten.ensure_array(flatten: true) { |l| l.ensure_string.strip }.reject { |l| l == "*" }
       @locales.blank? || locales.blank? || (@locales & locales).present?
     end
 
@@ -110,12 +110,7 @@ module Mbrao
 
     private
 
-    # Filters an attribute basing a set of locales.
-    #
-    # @param attribute [Object|HashWithIndifferentAccess] The desired attribute.
-    # @param locales [String|Array] The desired locales. Can include `*` to match all. If none are specified, the default mbrao locale will be used.
-    # @return [String|HashWithIndifferentAccess] Return the object for desired locales. If only one locale is available, then only a object is returned,
-    #   else a `HashWithIndifferentAccess` with locales as keys.
+    # :nodoc:
     def filter_attribute_for_locales(attribute, locales)
       locales = ::Mbrao::Content.validate_locales(locales, self)
 
@@ -127,14 +122,7 @@ module Mbrao
       end
     end
 
-    # Adds an value on a hash if enable for requested locales.
-    #
-    # @param hash [Hash] The hash to handle.
-    # @param locale [String] The list of locale (separated by commas) for which the value is available.
-    # @param locales [Array] The list of locale for which this value is requested. Can include `*` to match all. If none are specified, the default mbrao
-    #   locale will be used.
-    # @param value [Object] The value to add.
-    # @return [Hash] Return the original hash.
+    # :nodoc:
     def append_value_for_locale(hash, locale, locales, value)
       locale.split(/\s*,\s*/).map(&:strip).each do |l|
         hash[l] = value if locales.include?("*") || locales.include?(l)

data/lib/mbrao/parser.rb

@@ -35,12 +35,9 @@ module Mbrao
 
     private
 
-    # Sanitizes options for parsing.
-    #
-    # @param options [Hash] The options to sanitize.
-    # @return [HashWithIndifferentAccess] The sanitized options.
+    # :nodoc:
     def sanitize_parsing_options(options)
-      options = options.ensure_hash(:symbols)
+      options = options.ensure_hash(accesses: :symbols)
 
       options[:engine] ||= Mbrao::Parser.parsing_engine
       options[:metadata] = options.fetch(:metadata, true).to_boolean
@@ -49,12 +46,9 @@ module Mbrao
       HashWithIndifferentAccess.new(options)
     end
 
-    # Sanitizes options for rendering.
-    #
-    # @param options [Hash] The options to sanitize.
-    # @return [HashWithIndifferentAccess] The sanitized options.
+    # :nodoc:
     def sanitize_rendering_options(options)
-      options = options.ensure_hash(:symbols)
+      options = options.ensure_hash(accesses: :symbols)
 
       options[:engine] ||= Mbrao::Parser.rendering_engine
 

data/lib/mbrao/parser_interface.rb

@@ -75,8 +75,8 @@ module Mbrao
       # @return [Hash] An hash with all attributes.
       def as_json(target, keys, options = {})
         include_empty = !options[:exclude_empty].to_boolean
-        exclude = options[:exclude].ensure_array(nil, true, true, true, :ensure_string)
-        keys = keys.ensure_array(nil, true, true, true, :ensure_string)
+        exclude = options[:exclude].ensure_array(no_duplicates: true, compact: true, flatten: true, sanitizer: :ensure_string)
+        keys = keys.ensure_array(no_duplicates: true, compact: true, flatten: true, sanitizer: :ensure_string)
 
         map_to_json(target, (keys - exclude), include_empty)
       end
@@ -104,35 +104,25 @@ module Mbrao
 
       private
 
-      # Returns an attribute or a default value.
-      #
-      # @param attr [Object ]The attribute to return.
-      # @param default_value [Object] The value to return if `attr` is blank.
-      # @param sanitizer [Symbol] An optional method to sanitize the returned value.
+      # :nodoc:
       def attribute_or_default(attr, default_value = nil, sanitizer = :ensure_string)
         rv = attr.present? ? attr : default_value
         rv = rv.send(sanitizer) if sanitizer
         rv
       end
 
-      # Perform the mapping to JSON.
-      #
-      # @param target [Object] The target to serialize.
-      # @param keys [Array] The attributes to include in the serialization.
-      # @param include_empty [Boolean], if to include nil values.
-      # @return [Hash] An hash with all attributes.
+      # :nodoc:
       def map_to_json(target, keys, include_empty)
-        keys.reduce({}) { |rv, key|
+        json = keys.reduce({}) do |rv, key|
           value = get_json_field(target, key)
           rv[key] = value if include_empty || value.present?
           rv
-        }.deep_stringify_keys
+        end
+
+        json.deep_stringify_keys
       end
 
-      # Get a field as JSON.
-      #
-      # @param target [Object] The object containing the value.
-      # @param method [Symbol] The method containing the value.
+      # :nodoc:
       def get_json_field(target, method)
         value = target.send(method)
         value = value.as_json if value && value.respond_to?(:as_json) && !value.is_a?(Symbol)

data/lib/mbrao/parsing_engines/plain_text.rb

@@ -40,11 +40,8 @@ module Mbrao
         raise ArgumentError unless rv.is_a?(Hash)
         rv
       rescue => e
-        if options[:default]
-          options[:default]
-        else
-          raise ::Mbrao::Exceptions::InvalidMetadata, e.to_s
-        end
+        raise(::Mbrao::Exceptions::InvalidMetadata, e.to_s) unless options[:default]
+        options[:default]
       end
 
       # Filters content of a post by locale.
@@ -68,11 +65,7 @@ module Mbrao
 
       private
 
-      # Prepare arguments for separation.
-      #
-      # @param content [String] The content to separate.
-      # @param options [Hash] The options to sanitize.
-      # @return [Array] The sanitized arguments.
+      # :nodoc:
       def prepare_for_separation(content, options)
         content = content.ensure_string.strip
         meta_tags = sanitize_tags(options[:meta_tags], ["{{metadata}}", "{{/metadata}}"])
@@ -80,21 +73,13 @@ module Mbrao
         [nil, content.ensure_string.strip, StringScanner.new(content), meta_tags.first, meta_tags.last]
       end
 
-      # Sanitizes tag markers.
-      #
-      # @param tag [Array|String] The tag to sanitize.
-      # @return [Array] Sanitized tags.
+      # :nodoc:
       def sanitize_tags(tag, default = ["---"])
         tag = tag.ensure_string.split(/\s*,\s*/).map(&:strip) if tag && !tag.is_a?(Array)
         (tag.present? ? tag : default).slice(0, 2).map { |t| /#{Regexp.quote(t).gsub("%ARGS%", "\\s*(?<args>[^\\n\\}]+,?)*")}/ }
       end
 
-      # Scans a text and content section.
-      #
-      # @param content [String] The string to scan
-      # @param start_tag [Regexp] The tag to match for starting section.
-      # @param end_tag [Regexp] The tag to match for ending section.
-      # @return [String] The result of the scan.
+      # :nodoc:
       def scan_content(content, start_tag, end_tag)
         rv = []
         scanner = StringScanner.new(content)
@@ -105,12 +90,7 @@ module Mbrao
         rv
       end
 
-      # Perform a scan on the text and content.
-      #
-      # @param rv [String] The string where to put the results.
-      # @param scanner [StringScanner] The scanner to use.
-      # @param start_tag [Regexp] The tag to match for starting section.
-      # @param end_tag [Regexp] The tag to match for ending section.
+      # :nodoc:
       def perform_scan(rv, scanner, start_tag, end_tag)
         if scanner.exist?(start_tag) # It may start an embedded content
           # Scan until the start tag, remove the tag from the match and then store to results.
@@ -130,24 +110,13 @@ module Mbrao
         end
       end
 
-      # Gets results for an embedded content.
-      #
-      # @param [String] starting The match starting expression.
-      # @param [String] embedded The embedded contents.
-      # @param start_tag [Regexp] The tag to match for starting section.
-      # @param end_tag [Regexp] The tag to match for ending section.
-      # @return [Array] An array which the first element is the list of valid contents and second is the list of valid locales.
+      # :nodoc:
       def get_embedded_content(starting, embedded, start_tag, end_tag)
         # Either we have some content or the content was not closed and therefore we ignore this tag.
         embedded.present? ? [scan_content(embedded, start_tag, end_tag), starting.match(start_tag)["args"]] : [starting, "*"]
       end
 
-      # Parses embedded content of a tag
-      #
-      # @param scanner [StringScanner] The scanner to use.
-      # @param start_tag [Regexp] The tag to match for starting section.
-      # @param end_tag [Regexp] The tag to match for ending section.
-      # @return [String] The embedded content or `nil`, if the content was never closed.
+      # :nodoc:
       def parse_embedded_content(scanner, start_tag, end_tag)
         rv = ""
         balance = 1
@@ -155,7 +124,7 @@ module Mbrao
 
         while balance > 0 && embedded_part
           balance += embedded_part.scan(start_tag).count - 1 # -1 Because there is a closure
-          embedded_part = embedded_part.partition(end_tag).first if balance == 0 || !scanner.exist?(end_tag) # This is the last occurrence.
+          embedded_part = extract_embedded_part(scanner, embedded_part, end_tag, balance) # This is the last occurrence.
           rv << embedded_part
           embedded_part = scanner.scan_until(end_tag) if balance > 0
         end
@@ -163,28 +132,27 @@ module Mbrao
         rv
       end
 
-      # Filters content by locale.
-      #
-      # @param content [Array] The content to filter. @see #scan_content.
-      # @param locales [Array] The desired locales. Can include `*` to match all.
-      # @return [String|nil] Return the filtered content or `nil` if the content must be hidden.
+      # :nodoc:
+      def extract_embedded_part(scanner, embedded_part, end_tag, balance)
+        embedded_part = embedded_part.partition(end_tag).first if balance == 0 || !scanner.exist?(end_tag)
+        embedded_part
+      end
+
+      # :nodoc:
       def perform_filter_content(content, locales)
-        content.map { |part|
+        rv = content.map do |part|
           part_content = part[0]
           part_locales = parse_locales(part[1])
 
           if locales_valid?(locales, part_locales)
             part_content.is_a?(Array) ? perform_filter_content(part_content, locales) : part_content
-          else
-            nil
           end
-        }.compact.join("")
+        end
+
+        rv.compact.join("")
       end
 
-      # Parses locales of a content.
-      #
-      # @param locales [String] The desired locales. Can include `*` to match all. Note that `!*` is ignored.
-      # @return [Hash] An hash with valid and invalid locales.
+      # :nodoc:
       def parse_locales(locales)
         types = locales.split(/\s*,\s*/).map(&:strip).group_by { |l| l !~ /^!/ ? "valid" : "invalid" }
         types["valid"] ||= []
@@ -192,11 +160,7 @@ module Mbrao
         types
       end
 
-      # Checks if all locales in a list are valid for a part.
-      #
-      # @param locales [Array] The desired locales. Can include `*` to match all.
-      # @param part_locales[Hash] An hash with valid and invalid locales.
-      # @return [Boolean] `true` if the locales are valid, `false` otherwise.
+      # :nodoc:
       def locales_valid?(locales, part_locales)
         valid = part_locales["valid"]
         invalid = part_locales["invalid"]