micromicro 2.0.1 → 3.1.0

data/lib/micro_micro/item.rb

@@ -4,38 +4,47 @@ module MicroMicro
   class Item
     include Collectible
 
-    # Extract items from a context.
-    #
-    # @param context [Nokogiri::HTML::Document, Nokogiri::XML::NodeSet, Nokogiri::XML::Element]
-    # @return [Array<MicroMicro::Item>]
-    def self.from_context(context)
-      node_set_from(context).map { |node| new(node) }
-    end
+    class ItemNodeSearch
+      attr_reader :node_set
 
-    # Extract item nodes from a context.
-    #
-    # @param context [Nokogiri::XML::NodeSet, Nokogiri::XML::Element]
-    # @param node_set [Nokogiri::XML::NodeSet]
-    # @return [Nokogiri::XML::NodeSet]
-    # rubocop:disable Metrics
-    def self.node_set_from(context, node_set = Nokogiri::XML::NodeSet.new(context.document, []))
-      context.each { |node| node_set_from(node, node_set) } if context.is_a?(Nokogiri::XML::NodeSet)
-
-      if context.is_a?(Nokogiri::XML::Element) && !Helpers.ignore_node?(context)
-        if Helpers.item_node?(context)
-          node_set << context unless Helpers.item_nodes?(context.ancestors) && Helpers.property_node?(context)
-        else
-          node_set_from(context.element_children, node_set)
+      def initialize(document)
+        @node_set = Nokogiri::XML::NodeSet.new(document, [])
+      end
+
+      # rubocop:disable Metrics
+      def search(context)
+        context.each { |node| search(node) } if context.is_a?(Nokogiri::XML::NodeSet)
+
+        if context.is_a?(Nokogiri::XML::Element) && !Helpers.ignore_node?(context)
+          if Helpers.item_node?(context)
+            node_set << context unless Helpers.item_nodes?(context.ancestors) && Helpers.property_node?(context)
+          else
+            search(context.element_children)
+          end
         end
+
+        node_set
       end
+      # rubocop:enable Metrics
+    end
+
+    private_constant :ItemNodeSearch
 
-      node_set
+    # Extract {MicroMicro::Item}s from a context.
+    #
+    # @param context [Nokogiri::HTML::Document, Nokogiri::XML::NodeSet, Nokogiri::XML::Element]
+    # @return [Array<MicroMicro::Item>]
+    def self.from_context(context)
+      ItemNodeSearch
+        .new(context.document)
+        .search(context)
+        .map { |node| new(node) }
     end
-    # rubocop:enable Metrics
 
     # Parse a node for microformats2-encoded data.
     #
     # @param node [Nokogiri::XML::Element]
+    # @return [MicroMicro::Item]
     def initialize(node)
       @node = node
 
@@ -44,24 +53,40 @@ module MicroMicro
       properties << implied_url if implied_url?
     end
 
-    # A collection of child items parsed from the node.
+    # A collection of child {MicroMicro::Item}s parsed from the node.
     #
     # @see https://microformats.org/wiki/microformats2-parsing#parse_an_element_for_class_microformats
+    #   microformats.org: microformats2 parsing specification § Parse an element for class microformats
     #
     # @return [MicroMicro::Collections::ItemsCollection]
     def children
       @children ||= Collections::ItemsCollection.new(self.class.from_context(node.element_children))
     end
 
-    # The value of the node's `id` attribute, if present.
+    # Does this {MicroMicro::Item} contain any child {MicroMicro::Item}s?
+    #
+    # @return [Boolean]
+    def children?
+      children.any?
+    end
+
+    # The value of the node's +id+ attribute, if present.
     #
     # @return [String, nil]
     def id
       @id ||= node['id']&.strip
     end
 
-    # :nocov:
+    # Does this {MicroMicro::Item} have an +id+ attribute value?
+    #
+    # @return [Boolean]
+    def id?
+      id.present?
+    end
+
     # @return [String]
+    #
+    # :nocov:
     def inspect
       "#<#{self.class}:#{format('%#0x', object_id)} " \
         "types: #{types.inspect}, " \
@@ -70,23 +95,23 @@ module MicroMicro
     end
     # :nocov:
 
-    # A collection of plain text properties parsed from the node.
-    #
-    # @return [MicroMicro::Collections::PropertiesCollection]
-    def plain_text_properties
-      @plain_text_properties ||= properties.plain_text_properties
-    end
-
-    # A collection of properties parsed from the node.
+    # A collection of {MicroMicro::Property}s parsed from the node.
     #
     # @return [MicroMicro::Collections::PropertiesCollection]
     def properties
       @properties ||= Collections::PropertiesCollection.new(Property.from_context(node.element_children))
     end
 
-    # Return the parsed item as a Hash.
+    # Return the parsed {MicroMicro::Item} as a Hash.
     #
     # @see https://microformats.org/wiki/microformats2-parsing#parse_an_element_for_class_microformats
+    #   microformats.org: microformats2 parsing specification § Parse an element for class microformats
+    #
+    # @see MicroMicro::Item#children
+    # @see MicroMicro::Item#id
+    # @see MicroMicro::Item#properties
+    # @see MicroMicro::Item#types
+    # @see MicroMicro::Collections::PropertiesCollection#to_h
     #
     # @return [Hash]
     def to_h
@@ -95,28 +120,22 @@ module MicroMicro
         properties: properties.to_h
       }
 
-      hash[:id] = id if id.present?
-      hash[:children] = children.to_a if children.any?
+      hash[:id] = id if id?
+      hash[:children] = children.to_a if children?
 
       hash
     end
 
-    # An array of root class names parsed from the node's `class` attribute.
+    # An Array of root class names parsed from the node's +class+ attribute.
     #
     # @return [Array<String>]
     def types
       @types ||= Helpers.root_class_names_from(node)
     end
 
-    # A collection of url properties parsed from the node.
-    #
-    # @return [MicroMicro::Collections::PropertiesCollection]
-    def url_properties
-      @url_properties ||= properties.url_properties
-    end
-
     private
 
+    # @return [Nokogiri::XML::Element]
     attr_reader :node
 
     # @return [MicroMicro::ImpliedProperty]
@@ -173,7 +192,7 @@ module MicroMicro
 
     # @return [Boolean]
     def nested_items?
-      @nested_items ||= properties.find(&:item_node?) || children.any?
+      @nested_items ||= properties.find(&:item_node?) || children?
     end
   end
 end

data/lib/micro_micro/parsers/base_property_parser.rb

@@ -10,7 +10,9 @@ module MicroMicro
       end
 
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_a_p-_property
+      #   microformats.org: microformats2 parsing specification § Parsing a +p-+ property
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_an_e-_property
+      #   microformats.org: microformats2 parsing specification § Parsing an +e-+ property
       #
       # @return [String]
       def value

data/lib/micro_micro/parsers/date_time_parser.rb

@@ -30,6 +30,7 @@ module MicroMicro
       # Value Class Pattern date and time parsing specification.
       #
       # @see https://microformats.org/wiki/value-class-pattern#Date_and_time_parsing
+      #   microformats.org: Value Class Pattern § Date and time parsing
       #
       # @param string [String, #to_s]
       def initialize(string)
@@ -89,17 +90,14 @@ module MicroMicro
 
       # @return [String, nil]
       def value
-        @value ||=
-          if normalized_date || normalized_time || normalized_timezone
-            "#{normalized_date} #{normalized_time}#{normalized_timezone}".strip
-          end
+        @value ||= "#{normalized_date} #{normalized_time}#{normalized_timezone}".strip.presence
       end
 
       # @return [Hash{Symbol => String, nil}]
       def values
         @values ||=
           if string.match?(DATE_TIME_TIMEZONE_REGEXP)
-            string.match(DATE_TIME_TIMEZONE_REGEXP).named_captures.symbolize_keys
+            string.match(DATE_TIME_TIMEZONE_REGEXP).named_captures.transform_keys(&:to_sym)
           else
             {}
           end

data/lib/micro_micro/parsers/date_time_property_parser.rb

@@ -10,6 +10,7 @@ module MicroMicro
       }.freeze
 
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_a_dt-_property
+      #   microformats.org: microformats2 parsing specification § Parsing a +dt-+ property
       #
       # @return [String]
       def value
@@ -19,6 +20,7 @@ module MicroMicro
       private
 
       # @see https://microformats.org/wiki/value-class-pattern#microformats2_parsers_implied_date
+      #   microformats.org: Value Class Pattern § microformats2 parsers implied date
       #
       # @return [MicroMicro::Parsers::DateTimeParser, nil]
       def adopted_date_time_parser
@@ -39,6 +41,7 @@ module MicroMicro
       end
 
       # @see https://microformats.org/wiki/value-class-pattern#microformats2_parsers_implied_date
+      #   microformats.org: Value Class Pattern § microformats2 parsers implied date
       #
       # @return [Boolean]
       def imply_date?

data/lib/micro_micro/parsers/embedded_markup_property_parser.rb

@@ -4,6 +4,7 @@ module MicroMicro
   module Parsers
     class EmbeddedMarkupPropertyParser < BasePropertyParser
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_an_e-_property
+      #   microformats.org: microformats2 parsing specification § Parsing an +e-+ property
       #
       # @return [Hash{Symbol => String}]
       def value

data/lib/micro_micro/parsers/image_element_parser.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module MicroMicro
+  module Parsers
+    class ImageElementParser
+      # @return [String]
+      attr_reader :value
+
+      # @param node [Nokogiri::XML::Element]
+      # @param value [String]
+      def initialize(node, value)
+        @node = node
+        @value = value
+      end
+
+      # @return [String, nil]
+      def alt
+        @alt ||= node['alt']&.strip
+      end
+
+      # @return [Boolean]
+      def alt?
+        !alt.nil?
+      end
+
+      # @return [Hash{Symbol => String}, nil]
+      def srcset
+        @srcset ||= image_candidates if node['srcset']
+      end
+
+      # @return [Boolean]
+      def srcset?
+        srcset.present?
+      end
+
+      # @return [Hash{Symbol => String, Hash{Symbol => String}}]
+      def to_h
+        hash = { value: value }
+
+        hash[:srcset] = srcset if srcset?
+        hash[:alt] = alt if alt?
+
+        hash
+      end
+
+      private
+
+      # @return [Nokogiri::XML::Element]
+      attr_reader :node
+
+      # @return [Hash{Symbol => String}]
+      #
+      # rubocop:disable Style/PerlBackrefs
+      def image_candidates
+        node['srcset']
+          .split(',')
+          .each_with_object({}) do |candidate, hash|
+            candidate.strip.match(/^(.+?)(\s+.+)?$/) do
+              key = ($2 || '1x').strip.to_sym
+
+              hash[key] = $1 unless hash[key]
+            end
+          end
+      end
+      # rubocop:enable Style/PerlBackrefs
+    end
+  end
+end

data/lib/micro_micro/parsers/implied_name_property_parser.rb

@@ -10,6 +10,7 @@ module MicroMicro
       }.freeze
 
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_for_implied_properties
+      #   microformats.org: microformats2 parsing specification § Parsing for implied properties
       #
       # @return [String]
       def value

data/lib/micro_micro/parsers/implied_photo_property_parser.rb

@@ -11,18 +11,19 @@ module MicroMicro
       }.freeze
 
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_for_implied_properties
+      #   microformats.org: microformats2 parsing specification § Parsing for implied properties
       # @see https://microformats.org/wiki/microformats2-parsing#parse_an_img_element_for_src_and_alt
+      #   microformats.org: microformats2 parsing specification § Parse an img element for src and alt
       #
       # @return [String, Hash{Symbol => String}, nil]
       def value
         @value ||=
           if attribute_value
-            return attribute_value unless candidate_node.matches?('img[alt]')
-
-            {
-              value: attribute_value,
-              alt: candidate_node['alt'].strip
-            }
+            if candidate_node.matches?('img[alt], img[srcset]')
+              ImageElementParser.new(candidate_node, attribute_value).to_h
+            else
+              attribute_value
+            end
           end
       end
 

data/lib/micro_micro/parsers/implied_url_property_parser.rb

@@ -11,6 +11,7 @@ module MicroMicro
       }.freeze
 
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_for_implied_properties
+      #   microformats.org: microformats2 parsing specification § Parsing for implied properties
       #
       # @return [String, nil]
       def value

data/lib/micro_micro/parsers/plain_text_property_parser.rb

@@ -10,6 +10,7 @@ module MicroMicro
       }.freeze
 
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_a_p-_property
+      #   microformats.org: microformats2 parsing specification § Parsing a +p-+ property
       #
       # @return [String]
       def value

data/lib/micro_micro/parsers/url_property_parser.rb

@@ -16,16 +16,15 @@ module MicroMicro
       }.freeze
 
       # @see https://microformats.org/wiki/microformats2-parsing#parsing_a_u-_property
+      #   microformats.org: microformats2 parsing specification § Parsing a +u-+ property
       # @see https://microformats.org/wiki/microformats2-parsing#parse_an_img_element_for_src_and_alt
+      #   microformats.org: microformats2 parsing specification § Parse an img element for src and alt
       #
       # @return [String, Hash{Symbol => String}]
       def value
         @value ||=
-          if node.matches?('img[alt]')
-            {
-              value: resolved_value,
-              alt: node['alt'].strip
-            }
+          if node.matches?('img[alt], img[srcset]')
+            ImageElementParser.new(node, resolved_value).to_h
           else
             resolved_value
           end

data/lib/micro_micro/parsers/value_class_pattern_parser.rb

@@ -4,7 +4,9 @@ module MicroMicro
   module Parsers
     class ValueClassPatternParser
       # @see https://microformats.org/wiki/value-class-pattern#Basic_Parsing
+      #   microformats.org: Value Class Pattern § Basic Parsing
       # @see https://microformats.org/wiki/value-class-pattern#Date_and_time_values
+      #   microformats.org: Value Class Pattern § Date and time values
       HTML_ATTRIBUTES_MAP = {
         'alt'      => %w[area img],
         'value'    => %w[data],
@@ -37,7 +39,7 @@ module MicroMicro
         Helpers.attribute_value_from(node, HTML_ATTRIBUTES_MAP) || node.text
       end
 
-      # @param context [Nokogiri::XML::Element]
+      # @param node [Nokogiri::XML::Element]
       # @param separator [String]
       def initialize(node, separator = '')
         @node = node
@@ -55,7 +57,7 @@ module MicroMicro
           self.class
               .node_set_from(node)
               .map { |value_node| self.class.value_from(value_node) }
-              .select(&:present?)
+              .compact_blank!
       end
 
       private

data/lib/micro_micro/property.rb

@@ -11,55 +11,95 @@ module MicroMicro
       'u'  => Parsers::UrlPropertyParser
     }.freeze
 
-    attr_reader :name, :node, :prefix
+    private_constant :PROPERTY_PARSERS_MAP
 
-    # @param context [Nokogiri::XML::NodeSet, Nokogiri::XML::Element]
-    # @return [Array<MicroMicro::Property>]
-    def self.from_context(context)
-      node_set_from(context).flat_map do |node|
-        Helpers.property_class_names_from(node).map { |token| new(node, token) }
+    class PropertyNodeSearch
+      attr_reader :node_set
+
+      def initialize(document)
+        @node_set = Nokogiri::XML::NodeSet.new(document, [])
       end
-    end
 
-    # @param context [Nokogiri::XML::NodeSet, Nokogiri::XML::Element]
-    # @param node_set [Nokogiri::XML::NodeSet]
-    # @return [Nokogiri::XML::NodeSet]
-    def self.node_set_from(context, node_set = Nokogiri::XML::NodeSet.new(context.document, []))
-      context.each { |node| node_set_from(node, node_set) } if context.is_a?(Nokogiri::XML::NodeSet)
+      def search(context)
+        context.each { |node| search(node) } if context.is_a?(Nokogiri::XML::NodeSet)
+
+        if context.is_a?(Nokogiri::XML::Element) && !Helpers.ignore_node?(context)
+          node_set << context if Helpers.property_node?(context)
 
-      if context.is_a?(Nokogiri::XML::Element) && !Helpers.ignore_node?(context)
-        node_set << context if Helpers.property_node?(context)
+          search(context.element_children) unless Helpers.item_node?(context)
+        end
 
-        node_set_from(context.element_children, node_set) unless Helpers.item_node?(context)
+        node_set
       end
+    end
+
+    private_constant :PropertyNodeSearch
 
-      node_set
+    # This {MicroMicro::Property}'s +name+ value.
+    #
+    # @return [String]
+    attr_reader :name
+
+    # This {MicroMicro::Property}'s node.
+    #
+    # @return [Nokogiri::XML::Element]
+    attr_reader :node
+
+    # This {MicroMicro::Property}'s +prefix+ value.
+    #
+    # @return [String] One of +dt+, +e+, +p+, or +u+.
+    attr_reader :prefix
+
+    # Extract {MicroMicro::Property}s from a context.
+    #
+    # @param context [Nokogiri::XML::NodeSet, Nokogiri::XML::Element]
+    # @return [Array<MicroMicro::Property>]
+    def self.from_context(context)
+      PropertyNodeSearch
+        .new(context.document)
+        .search(context)
+        .flat_map do |node|
+          Helpers.property_class_names_from(node).map { |token| new(node, token) }
+        end
     end
 
+    # Parse a node for property data.
+    #
     # @param node [Nokogiri::XML::Element]
-    # @param token [String]
+    # @param token [String] A hyphen-separated token representing a microformats2
+    #   property value (e.g. +p-name+, +u-url+).
     def initialize(node, token)
       @node = node
       @prefix, @name = token.split(/-/, 2)
     end
 
+    # Is this {MicroMicro::Property} a datetime property?
+    #
     # @return [Boolean]
     def date_time_property?
       prefix == 'dt'
     end
 
+    # Is this {MicroMicro::Property} an embedded markup property?
+    #
     # @return [Boolean]
     def embedded_markup_property?
       prefix == 'e'
     end
 
+    # Always return +false+ when asked if this {MicroMicro::Property} is an
+    # implied property.
+    #
+    # @see MicroMicro::ImpliedProperty#implied?
+    #
     # @return [Boolean]
     def implied?
       false
     end
 
-    # :nocov:
     # @return [String]
+    #
+    # :nocov:
     def inspect
       "#<#{self.class}:#{format('%#0x', object_id)} " \
         "name: #{name.inspect}, " \
@@ -68,27 +108,42 @@ module MicroMicro
     end
     # :nocov:
 
+    # Parse this {MicroMicro::Property}'s node as a {MicroMicro::Item}, if
+    # applicable.
+    #
     # @return [MicroMicro::Item, nil]
     def item
       @item ||= Item.new(node) if item_node?
     end
 
+    # Should this {MicroMicro::Property}'s node be parsed as a
+    # {MicroMicro::Item}?
+    #
+    # @see MicroMicro::Helpers.item_node?
+    #
     # @return [Boolean]
     def item_node?
       @item_node ||= Helpers.item_node?(node)
     end
 
+    # Is this {MicroMicro::Property} a plain text property?
+    #
     # @return [Boolean]
     def plain_text_property?
       prefix == 'p'
     end
 
+    # Is this {MicroMicro::Property} a url property?
+    #
     # @return [Boolean]
     def url_property?
       prefix == 'u'
     end
 
+    # Return this {MicroMicro::Property}'s parsed value.
+    #
     # @return [String, Hash]
+    #
     # rubocop:disable Metrics
     def value
       @value ||=
@@ -97,8 +152,8 @@ module MicroMicro
 
           return hash.merge(parser.value) if embedded_markup_property?
 
-          p_property = item.properties.find { |property| property.name == 'name' } if plain_text_property?
-          u_property = item.properties.find { |property| property.name == 'url' } if url_property?
+          p_property = item.properties.find_by(name: 'name') if plain_text_property?
+          u_property = item.properties.find_by(name: 'url') if url_property?
 
           hash.merge(value: (p_property || u_property || parser).value)
         else
@@ -107,6 +162,9 @@ module MicroMicro
     end
     # rubocop:enable Metrics
 
+    # Returns +true+ if this {MicroMicro::Property}'s +value+ is anything other
+    # than blank or +nil+.
+    #
     # @return [Boolean]
     def value?
       value.present?