micromicro 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9c965d277e7c87c68de6ce7a12aff28da257d813573de2519bfe36943df1f4f
-  data.tar.gz: a62d02a8fe962b060c36a9c615445f586fe76ea1c570d71f05175d140d631d32
+  metadata.gz: 6734c4d9cbd071d3288a5f8c72de07095fc6db2915224f97684a0577362bcdb0
+  data.tar.gz: 9225043ef91161f2a92fa338bc874771dc55d9e81ffe969fe7b005c9dbc28403
 SHA512:
-  metadata.gz: 8ee19e4ca072c36137746dd54e435405a9a749761c9b735d75ff9f97a5c28f8e5367f79c3a7ad45c83039eb8cb54f1043cac2dd7ddcd1bfd2d4fbbad0d218ad6
-  data.tar.gz: f5f88370b3fc92e2d467c8e358798c6266b5fb9dbfe50fb13e74b2235572e9adfbfeb4f171b1df3d5bf474cc549bac7adfe3fa7c2a59b6830d2bacc3cab3d500
+  metadata.gz: 58824c1699a2aff5e22d906cbb449f95f55a665d7374ba62e26ddfa3fd6986ae952e22965446e4bbe973d2e17a1f05cba32e74f7d30e1e327fbc262ebce7b1f1
+  data.tar.gz: aa9db8c15e10ecc08fa65db0cf6964914681ef72b552a300c4b95899b4a837835c1c69baff9b8e48586df34eefb7bb4156e55a5c81582deda4a9948554224f48

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v3.0.0 / 2022-08-28
+
+- Improved YARD documentation
+- New `Item` instance methods (8105d6f):
+  - `MicroMicro::Item#children?`
+  - `MicroMicro::Item#id?`
+- **Breaking change:** Remove property-centric methods from `MicroMicro::Item` (926dedb):
+  - `MicroMicro::Item#plain_text_properties`
+  - `MicroMicro::Item#url_properties`
+- Add predicate methods to `MicroMicro::Collections::PropertiesCollection` (82e91c8):
+  - `MicroMicro::Collections::PropertiesCollection#plain_text_properties?`
+  - `MicroMicro::Collections::PropertiesCollection#url_properties?`
+- Add collections search methods `#where` and `#find_by` (847cb77)
+- **Breaking change:** Refactor `.node_set_from` class methods into private classes (b18a714)
+
 ## 2.0.1 / 2022-08-20
 
 - Use ruby/debug instead of pry-byebug (2965b2e)

data/README.md

@@ -18,15 +18,9 @@
 
 <small>¹ …with some exceptions until [this pull request](https://github.com/microformats/tests/pull/112) is merged.</small>
 
-## Getting Started
-
-Before installing and using MicroMicro, you'll want to have [Ruby](https://www.ruby-lang.org) 2.7 (or newer) installed. It's recommended that you use a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm).
-
-MicroMicro is developed using Ruby 2.7.6 and is additionally tested against Ruby 3.0 and 3.1 using [GitHub Actions](https://github.com/jgarber623/micromicro/actions).
-
 ## Installation
 
-If you're using [Bundler](https://bundler.io) to manage gem dependencies, add MicroMicro to your project's Gemfile:
+Before installing and using MicroMicro, you'll want to have [Ruby](https://www.ruby-lang.org) 2.7 (or newer) installed. If you're using [Bundler](https://bundler.io) to manage gem dependencies, add MicroMicro to your project's Gemfile:
 
 ```ruby
 gem 'micromicro'
@@ -42,13 +36,7 @@ gem install micromicro
 
 ## Usage
 
-### Basic Usage
-
-MicroMicro's `parse` method accepts two arguments: a `String` of markup and a `String` representing the URL associated with that markup.
-
-The markup (typically HTML) can be retrieved from the Web using a library of your choosing or provided inline as a simple `String` (e.g. `<div class="h-card">Jason Garber</div>`) The URL provided is used to resolve relative URLs in accordance with the document's language rules.
-
-An example using a simple `String` of HTML as input:
+MicroMicro's `parse` method accepts two arguments: a `String` of markup and a `String` representing the URL associated with that markup. The resulting `MicroMicro::Document` may be converted to a `Hash` which may be further manipulated using conventional Ruby tooling.
 
 ```ruby
 require 'micromicro'
@@ -60,88 +48,7 @@ doc.to_h
 #=> { :items => [{ :type => ["h-card"], :properties => { :name => ["Jason Garber"] } }], :rels => {}, :"rel-urls" => {} }
 ```
 
-The `Hash` produced by calling `doc.to_h` may be converted to JSON (e.g. `doc.to_h.to_json`) for storage, additional manipulation, or use with other tools.
-
-Another example pulling the source HTML from [Tantek](https://tantek.com)'s website:
-
-```ruby
-require 'net/http'
-require 'micromicro'
-
-url = 'https://tantek.com'
-rsp = Net::HTTP.get(URI.parse(url))
-
-doc = MicroMicro.parse(rsp, url)
-#=> #<MicroMicro::Document items: #<MicroMicro::Collections::ItemsCollection count: 1, members: […]>, relationships: #<MicroMicro::Collections::RelationshipsCollection count: 31, members: […]>>
-
-doc.to_h
-#=> { :items => [{ :type => ["h-card"], :properties => {…}, :children => […]}], :rels => {…}, :'rel-urls' => {…} }
-```
-
-### Advanced Usage
-
-Building on the example above, a MicroMicro-parsed document is navigable and manipulable using a familiar `Enumerable`-esque interface.
-
-#### Items
-
-```ruby
-doc.items.first
-#=> #<MicroMicro::Item types: ["h-card"], properties: 42, children: 6>
-
-# 🆕 in v1.0.0
-doc.items.types
-#=> ["h-card"]
-
-doc.items.first.children
-#=> #<MicroMicro::Collections::ItemsCollection count: 6, members: […]>
-```
-
-#### Properties
-
-```ruby
-doc.items.first.properties
-#=> #<MicroMicro::Collections::PropertiesCollection count: 42, members: […]>
-
-# 🆕 in v1.0.0
-doc.items.first.plain_text_properties
-#=> #<MicroMicro::Collections::PropertiesCollection count: 34, members: […]>
-
-# 🆕 in v1.0.0
-doc.items.first.url_properties
-#=> #<MicroMicro::Collections::PropertiesCollection count: 11, members: […]>
-
-# 🆕 in v1.0.0
-doc.items.first.properties.names
-#=> ["category", "name", "note", "org", "photo", "pronoun", "pronouns", "role", "uid", "url"]
-
-# 🆕 in v1.0.0
-doc.items.first.properties.values
-#=> [{:value=>"https://tantek.com/photo.jpg", :alt=>""}, "https://tantek.com/", "Tantek Çelik", "Inventor, writer, teacher, runner, coder, more.", "Inventor", "writer", "teacher", "runner", "coder", …]
-
-doc.items.first.properties[7]
-#=> #<MicroMicro::Property name: "category", prefix: "p", value: "teacher">
-
-doc.items.first.properties.take(5).map { |property| [property.name, property.value] }
-#=> [["photo", { :value => "https://tantek.com/photo.jpg", :alt => "" }], ["url", "https://tantek.com/"], ["uid", "https://tantek.com/"], ["name", "Tantek Çelik"], ["role", "Inventor, writer, teacher, runner, coder, more."]]
-```
-
-#### Relationships
-
-```ruby
-doc.relationships.first
-#=> #<MicroMicro::Relationship href: "https://tantek.com/", rels: ["canonical"]>
-
-# 🆕 in v1.0.0
-doc.relationships.rels
-#=> ["alternate", "apple-touch-icon-precomposed", "author", "authorization_endpoint", "bookmark", "canonical", "hub", "icon", "me", "microsub", …]
-
-# 🆕 in v1.0.0
-doc.relationships.urls
-#=> ["http://dribbble.com/tantek/", "http://last.fm/user/tantekc", "https://aperture.p3k.io/microsub/277", "https://en.wikipedia.org/wiki/User:Tantek", "https://github.com/tantek", "https://indieauth.com/auth", "https://indieauth.com/openid", "https://micro.blog/t", "https://pubsubhubbub.superfeedr.com/", "https://tantek.com/", …]
-
-doc.relationships.find { |relationship| relationship.rels.include?('webmention') }
-# => #<MicroMicro::Relationship href: "https://webmention.io/tantek.com/webmention", rels: ["webmention"]>
-```
+See [USAGE.md](https://github.com/jgarber623/micromicro/blob/main/USAGE.md) for detailed examples of MicroMicro's features.
 
 ## Contributing
 

data/lib/micro_micro/collections/base_collection.rb

@@ -14,8 +14,9 @@ module MicroMicro
         members.each { |member| push(member) }
       end
 
-      # :nocov:
       # @return [String]
+      #
+      # :nocov:
       def inspect
         "#<#{self.class}:#{format('%#0x', object_id)} " \
           "count: #{count}, " \

data/lib/micro_micro/collections/items_collection.rb

@@ -3,15 +3,96 @@
 module MicroMicro
   module Collections
     class ItemsCollection < BaseCollection
+      class ItemsCollectionSearch
+        attr_reader :results
+
+        def initialize
+          @results = []
+        end
+
+        def search(items, **args, &block)
+          items.each do |item|
+            results << item if item_matches_conditions?(item, **args, &block)
+
+            search(item.properties.filter_map { |property| property.item if property.item_node? }, **args, &block)
+            search(item.children, **args, &block)
+          end
+
+          results
+        end
+
+        private
+
+        def item_matches_conditions?(item, **args)
+          return yield(item) if args.none?
+
+          args.all? { |key, value| (Array(item.public_send(key.to_sym)) & Array(value)).any? }
+        end
+      end
+
+      private_constant :ItemsCollectionSearch
+
+      # Return the first {MicroMicro::Item} from a search.
+      #
+      # @see #where
+      #
+      # @param (see #where)
+      # @yieldparam (see #where))
+      # @return [MicroMicro::Item, nil]
+      def find_by(**args, &block)
+        where(**args, &block).first
+      end
+
+      # Return an Array of this collection's {MicroMicro::Item}s as Hashes.
+      #
+      # @see MicroMicro::Item#to_h
+      #
       # @return [Array<Hash{Symbol => Array<String, Hash>}>]
       def to_a
         map(&:to_h)
       end
 
+      # Retrieve an Array of this collection's unique {MicroMicro::Item} types.
+      #
+      # @see MicroMicro::Item#types
+      #
       # @return [Array<String>]
       def types
         @types ||= flat_map(&:types).uniq.sort
       end
+
+      # Recursively search this collection for {MicroMicro::Item}s matching the
+      # given conditions.
+      #
+      # If a Hash is supplied, the returned collection will include
+      # {MicroMicro::Item}s matching _all_ conditions. Keys must be Symbols
+      # matching an instance method on {MicroMicro::Item} and values may be
+      # either a String or an Array of Strings.
+      #
+      # @example Search using a Hash with a String value
+      #   MicroMicro.parse(markup, url).items.where(types: 'h-card')
+      #
+      # @example Search using a Hash with an Array value
+      #   MicroMicro.parse(markup, url).items.where(types: ['h-card', 'h-entry'])
+      #
+      # When passing a block, each {MicroMicro::Item} in this collection is
+      # yielded to the block and the returned collection will include
+      # {MicroMicro::Item}s that cause the block to return a value other than
+      # +false+ or +nil+.
+      #
+      # @example Search using a block
+      #   MicroMicro.parse(markup, url).items.where do |item|
+      #     item.properties.names.include?('email')
+      #   end
+      #
+      # @param args [Hash{Symbol => String, Array<String>}]
+      # @yieldparam item [MicroMicro::Item]
+      # @return [MicroMicro::Collections::ItemsCollection]
+      def where(**args, &block)
+        return self if args.none? && !block
+
+        self.class.new(ItemsCollectionSearch.new.search(self, **args, &block))
+      end
     end
   end
 end

data/lib/micro_micro/collections/properties_collection.rb

@@ -3,30 +3,129 @@
 module MicroMicro
   module Collections
     class PropertiesCollection < BaseCollection
+      class PropertiesCollectionSearch
+        def search(properties, **args, &block)
+          properties.select { |property| property_matches_conditions?(property, **args, &block) }
+        end
+
+        private
+
+        def property_matches_conditions?(property, **args)
+          return yield(property) if args.none?
+
+          args.all? { |key, value| (Array(property.public_send(key.to_sym)) & Array(value)).any? }
+        end
+      end
+
+      private_constant :PropertiesCollectionSearch
+
+      # Return the first {MicroMicro::Property} from a search.
+      #
+      # @see #where
+      #
+      # @param (see #where)
+      # @yieldparam (see #where))
+      # @return [MicroMicro::Property, nil]
+      def find_by(**args, &block)
+        where(**args, &block).first
+      end
+
+      # Retrieve an Array of this collection's unique {MicroMicro::Property}
+      # names.
+      #
+      # @see MicroMicro::Property#name
+      #
       # @return [Array<String>]
       def names
         @names ||= map(&:name).uniq.sort
       end
 
+      # A collection of plain text {MicroMicro::Property}s parsed from the node.
+      #
+      # @see MicroMicro::Property#plain_text_property?
+      #
       # @return [MicroMicro::Collections::PropertiesCollection]
       def plain_text_properties
-        self.class.new(select(&:plain_text_property?))
+        @plain_text_properties ||= self.class.new(select(&:plain_text_property?))
       end
 
+      # Does this {MicroMicro::Collections::PropertiesCollection} include any
+      # plain text {MicroMicro::Property}s?
+      #
+      # @return [Boolean]
+      def plain_text_properties?
+        plain_text_properties.any?
+      end
+
+      # Return a Hash of this collection's {MicroMicro::Property}s as Arrays.
+      #
+      # @see MicroMicro::Property#name
+      # @see MicroMicro::Property#value
+      #
       # @return [Hash{Symbol => Array<String, Hash>}]
       def to_h
         group_by(&:name).symbolize_keys.deep_transform_values(&:value)
       end
 
+      # A collection of url {MicroMicro::Property}s parsed from the node.
+      #
+      # @see MicroMicro::Property#url_property?
+      #
       # @return [MicroMicro::Collections::PropertiesCollection]
       def url_properties
-        self.class.new(select(&:url_property?))
+        @url_properties ||= self.class.new(select(&:url_property?))
+      end
+
+      # Does this {MicroMicro::Collections::PropertiesCollection} include any
+      # url {MicroMicro::Property}s?
+      #
+      # @return [Boolean]
+      def url_properties?
+        url_properties.any?
       end
 
+      # Return an Array of this collection's unique {MicroMicro::Property}
+      # values.
+      #
+      # @see MicroMicro::Property#value
+      #
       # @return [Array<String, Hash>]
       def values
         @values ||= map(&:value).uniq
       end
+
+      # Search this collection for {MicroMicro::Property}s matching the given
+      # conditions.
+      #
+      # If a Hash is supplied, the returned collection will include
+      # {MicroMicro::Property}s matching _all_ conditions. Keys must be Symbols
+      # matching an instance method on {MicroMicro::Property} and values may be
+      # either a String or an Array of Strings.
+      #
+      # @example Search using a Hash with a String value
+      #   MicroMicro.parse(markup, url).properties.where(name: 'url')
+      #
+      # @example Search using a Hash with an Array value
+      #   MicroMicro.parse(markup, url).properties.where(name: ['name', 'url'])
+      #
+      # When passing a block, each {MicroMicro::Property} in this collection
+      # is yielded to the block and the returned collection will include
+      # {MicroMicro::Property}s that cause the block to return a value other
+      # than +false+ or +nil+.
+      #
+      # @example Search using a block
+      #   MicroMicro.parse(markup, url).properties.where do |property|
+      #     property.value.is_a?(Hash)
+      #   end
+      #
+      # @param args [Hash{Symbol => String, Array<String>}]
+      # @yieldparam property [MicroMicro::Property]
+      # @return [MicroMicro::Collections::PropertiesCollection]
+      def where(**args, &block)
+        return self if args.none? && !block
+
+        self.class.new(PropertiesCollectionSearch.new.search(self, **args, &block))
+      end
     end
   end
 end

data/lib/micro_micro/collections/relationships_collection.rb

@@ -3,7 +3,38 @@
 module MicroMicro
   module Collections
     class RelationshipsCollection < BaseCollection
+      class RelationshipsCollectionSearch
+        def search(relationships, **args, &block)
+          relationships.select { |relationship| relationship_matches_conditions?(relationship, **args, &block) }
+        end
+
+        private
+
+        def relationship_matches_conditions?(relationship, **args)
+          return yield(relationship) if args.none?
+
+          args.all? { |key, value| (Array(relationship.public_send(key.to_sym)) & Array(value)).any? }
+        end
+      end
+
+      private_constant :RelationshipsCollectionSearch
+
+      # Return the first {MicroMicro::Relationship} from a search.
+      #
+      # @see #where
+      #
+      # @param (see #where)
+      # @yieldparam (see #where))
+      # @return [MicroMicro::Relationship, nil]
+      def find_by(**args, &block)
+        where(**args, &block).first
+      end
+
+      # Return a Hash of this collection's {MicroMicro::Relationship}s grouped
+      # by their +rel+ attribute value.
+      #
       # @see https://microformats.org/wiki/microformats2-parsing#parse_a_hyperlink_element_for_rel_microformats
+      #   microformats.org: microformats2 parsing specification § Parse a hyperlink element for rel microformats
       #
       # @return [Hash{Symbol => Array<String>}]
       def group_by_rel
@@ -12,22 +43,69 @@ module MicroMicro
         end.symbolize_keys.transform_values(&:uniq)
       end
 
+      # Return a Hash of this collection's {MicroMicro::Relationship}s grouped
+      # by their +href+ attribute value.
+      #
       # @see https://microformats.org/wiki/microformats2-parsing#parse_a_hyperlink_element_for_rel_microformats
+      #   microformats.org: microformats2 parsing specification § Parse a hyperlink element for rel microformats
       #
       # @return [Hash{Symbol => Hash{Symbol => Array, String}}]
       def group_by_url
         group_by(&:href).symbolize_keys.transform_values { |relationships| relationships.first.to_h.slice!(:href) }
       end
 
+      # Retrieve an Array of this collection's unique {MicroMicro::Relationship}
+      # +rel+ attrivute values.
+      #
+      # @see MicroMicro::Relationship#rels
+      #
       # @return [Array<String>]
       def rels
         @rels ||= flat_map(&:rels).uniq.sort
       end
 
+      # Retrieve an Array of this collection's unique {MicroMicro::Relationship}
+      # +href+ attribute values.
+      #
+      # @see MicroMicro::Relationship#urls
+      #
       # @return [Array<String>]
       def urls
         @urls ||= map(&:href).uniq.sort
       end
+
+      # Search this collection for {MicroMicro::Relationship}s matching the
+      # given conditions.
+      #
+      # If a Hash is supplied, the returned collection will include
+      # {MicroMicro::Relationship}s matching _all_ conditions. Keys must be
+      # Symbols matching an instance method on {MicroMicro::Relationship} and
+      # values may be either a String or an Array of Strings.
+      #
+      # @example Search using a Hash with a String value
+      #   MicroMicro.parse(markup, url).relationships.where(rels: 'webmention')
+      #
+      # @example Search using a Hash with an Array value
+      #   MicroMicro.parse(markup, url).relationships.where(rels: ['me', 'webmention'])
+      #
+      # When passing a block, each {MicroMicro::Relationship} in this collection
+      # is yielded to the block and the returned collection will include
+      # {MicroMicro::Relationship}s that cause the block to return a value other
+      # than +false+ or +nil+.
+      #
+      # @example Search using a block
+      #   MicroMicro.parse(markup, url).relationships.where do |relationship|
+      #     relationship.href.match?(%r{https://webmention.io/.+})
+      #   end
+      #
+      # @param args [Hash{Symbol => String, Array<String>}]
+      # @yieldparam relationship [MicroMicro::Relationship]
+      # @return [MicroMicro::Collections::RelationshipsCollection]
+      def where(**args, &block)
+        return self if args.none? && !block
+
+        self.class.new(RelationshipsCollectionSearch.new.search(self, **args, &block))
+      end
     end
   end
 end

data/lib/micro_micro/document.rb

@@ -4,10 +4,10 @@ module MicroMicro
   class Document
     # Parse a string of HTML for microformats2-encoded data.
     #
+    # @example Parse a String of markup
     #   MicroMicro::Document.new('<a href="/" class="h-card" rel="me">Jason Garber</a>', 'https://sixtwothree.org')
     #
-    # Or, pull the source HTML of a page on the Web:
-    #
+    # @example Parse a String of markup from a URL
     #   url = 'https://tantek.com'
     #   markup = Net::HTTP.get(URI.parse(url))
     #
@@ -19,8 +19,9 @@ module MicroMicro
       @document = Nokogiri::HTML(markup, base_url).resolve_relative_urls!
     end
 
-    # :nocov:
     # @return [String]
+    #
+    # :nocov:
     def inspect
       "#<#{self.class}:#{format('%#0x', object_id)} " \
         "items: #{items.inspect}, " \
@@ -28,23 +29,28 @@ module MicroMicro
     end
     # :nocov:
 
-    # A collection of items parsed from the provided markup.
+    # A collection of {MicroMicro::Item}s parsed from the provided markup.
     #
     # @return [MicroMicro::Collections::ItemsCollection]
     def items
       @items ||= Collections::ItemsCollection.new(Item.from_context(document.element_children))
     end
 
-    # A collection of relationships parsed from the provided markup.
+    # A collection of {MicroMicro::Relationship}s parsed from the provided markup.
     #
     # @return [MicroMicro::Collections::RelationshipsCollection]
     def relationships
-      @relationships ||= Collections::RelationshipsCollection.new(Relationship.relationships_from(document))
+      @relationships ||= Collections::RelationshipsCollection.new(Relationship.from_context(document))
     end
 
     # Return the parsed document as a Hash.
     #
     # @see https://microformats.org/wiki/microformats2-parsing#parse_a_document_for_microformats
+    #   microformats.org: Parse a document for microformats
+    #
+    # @see MicroMicro::Collections::ItemsCollection#to_a
+    # @see MicroMicro::Collections::RelationshipsCollection#group_by_rel
+    # @see MicroMicro::Collections::RelationshipsCollection#group_by_url
     #
     # @return [Hash{Symbol => Array, Hash}]
     def to_h

data/lib/micro_micro/helpers.rb

@@ -4,6 +4,8 @@ module MicroMicro
   module Helpers
     IGNORED_NODE_NAMES = %w[script style template].freeze
 
+    private_constant :IGNORED_NODE_NAMES
+
     # @param node [Nokogiri::XML::Element]
     # @param attributes_map [Hash{String => Array}]
     # @return [String, nil]
@@ -56,7 +58,9 @@ module MicroMicro
     end
 
     # @see https://microformats.org/wiki/microformats2-parsing#parse_an_element_for_properties
+    #   microformats.org: microformats2 parsing specification § Parse an element for properties
     # @see https://microformats.org/wiki/microformats2-parsing#parsing_for_implied_properties
+    #   microformats.org: microformats2 parsing specification § Parsing for implied properties
     #
     # @param context [Nokogiri::HTML::Document, Nokogiri::XML::NodeSet, Nokogiri::XML::Element]
     # @yield [context]
@@ -70,6 +74,7 @@ module MicroMicro
     end
 
     # @see https://microformats.org/wiki/value-class-pattern#Basic_Parsing
+    #   microformats.org: Value Class Pattern § Basic Parsing
     #
     # @param node [Nokogiri::XML::Element]
     # @return [Boolean]
@@ -78,6 +83,7 @@ module MicroMicro
     end
 
     # @see https://microformats.org/wiki/value-class-pattern#Parsing_value_from_a_title_attribute
+    #   microformats.org: Value Class Pattern § Parsing value from a title attribute
     #
     # @param node [Nokogiri::XML::Element]
     # @return [Boolean]

data/lib/micro_micro/implied_property.rb

@@ -8,11 +8,24 @@ module MicroMicro
       'url'   => Parsers::ImpliedUrlPropertyParser
     }.freeze
 
+    private_constant :IMPLIED_PROPERTY_PARSERS_MAP
+
+    # Always return +true+ when asked if this {MicroMicro::ImpliedProperty} is
+    # an implied property.
+    #
+    # @see https://microformats.org/wiki/microformats2-parsing#parsing_for_implied_properties
+    #   microformats.org: microformats2 parsing specification § Parsing for implied properties
+    #
+    # @see MicroMicro::Property#implied?
+    #
     # @return [Boolean]
     def implied?
       true
     end
 
+    # Always return +false+ when asked if this {MicroMicro::ImpliedProperty} is
+    # a {MicroMicro::Item} node.
+    #
     # @return [Boolean]
     def item_node?
       false

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)

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/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,7 +11,9 @@ 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

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,7 +16,9 @@ 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

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

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 ||=
@@ -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?

data/lib/micro_micro/relationship.rb

@@ -4,31 +4,41 @@ module MicroMicro
   class Relationship
     include Collectible
 
+    # Extract {MicroMicro::Relationship}s from a context.
+    #
     # @param context [Nokogiri::HTML::Document, Nokogiri::XML::Element]
     # @return [Array<MicroMicro::Relationship>]
-    def self.relationships_from(context)
+    def self.from_context(context)
       context.css('[href][rel]:not([rel=""])')
              .reject { |node| Helpers.ignore_nodes?(node.ancestors) }
              .map { |node| new(node) }
     end
 
+    # Parse a node for relationship data.
+    #
     # @param node [Nokogiri::XML::Element]
+    # @return [MicroMicro::Relationship]
     def initialize(node)
       @node = node
     end
 
+    # The value of the node's +href+ attribute.
+    #
     # @return [String]
     def href
       @href ||= node['href']
     end
 
+    # The value of the node's +hreflang+ attribute, if present.
+    #
     # @return [String, nil]
     def hreflang
       @hreflang ||= node['hreflang']&.strip
     end
 
-    # :nocov:
     # @return [String]
+    #
+    # :nocov:
     def inspect
       "#<#{self.class}:#{format('%#0x', object_id)} " \
         "href: #{href.inspect}, " \
@@ -36,11 +46,15 @@ module MicroMicro
     end
     # :nocov:
 
+    # The value of the node's +media+ attribute, if present.
+    #
     # @return [String, nil]
     def media
       @media ||= node['media']&.strip
     end
 
+    # Return the parsed {MicroMicro::Relationship} as a Hash.
+    #
     # @return [Hash{Symbol => String}]
     def to_h
       {
@@ -54,21 +68,29 @@ module MicroMicro
       }.select { |_, value| value.present? }
     end
 
+    # An Array of unique values from node's +rel+ attribute.
+    #
     # @return [Array<String>]
     def rels
       @rels ||= node['rel'].split.uniq.sort
     end
 
+    # The node's text content.
+    #
     # @return [String]
     def text
       @text ||= node.text
     end
 
+    # The value of the node's +title+ attribute, if present.
+    #
     # @return [String, nil]
     def title
       @title ||= node['title']&.strip
     end
 
+    # The value of the node's +type+ attribute, if present.
+    #
     # @return [String, nil]
     def type
       @type ||= node['type']&.strip
@@ -76,6 +98,7 @@ module MicroMicro
 
     private
 
+    # @return [Nokogiri::XML::Element]
     attr_reader :node
   end
 end

data/lib/micro_micro/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MicroMicro
-  VERSION = '2.0.1'
+  VERSION = '3.0.0'
 end

data/lib/micromicro.rb

@@ -41,13 +41,14 @@ require_relative 'micro_micro/collections/relationships_collection'
 
 module MicroMicro
   # Parse a string of HTML for microformats2-encoded data.
-  # Convenience method for MicroMicro::Document.new.
   #
+  # Convenience method for {MicroMicro::Document#initialize}.
+  #
+  # @example
   #   MicroMicro.parse('<a href="/" class="h-card" rel="me">Jason Garber</a>', 'https://sixtwothree.org')
   #
-  # @param markup [String] The HTML to parse for microformats2-encoded data.
-  # @param base_url [String] The URL associated with markup. Used for relative URL resolution.
-  # @return [MicroMicro::Document]
+  # @param (see MicroMicro::Document#initialize)
+  # @return (see MicroMicro::Document#initialize)
   def self.parse(markup, base_url)
     Document.new(markup, base_url)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: micromicro
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Jason Garber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-21 00:00:00.000000000 Z
+date: 2022-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -93,7 +93,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jgarber623/micromicro/issues
-  changelog_uri: https://github.com/jgarber623/micromicro/blob/v2.0.1/CHANGELOG.md
+  changelog_uri: https://github.com/jgarber623/micromicro/blob/v3.0.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []