meta-tags 2.22.2 → 2.23.0

data/lib/meta_tags/meta_tags_collection.rb

@@ -1,42 +1,38 @@
 # frozen_string_literal: true
 
 module MetaTags
-  # Class represents a collection of meta tags. Basically a wrapper around
+  # This class represents a collection of meta tags. Basically a wrapper around
   # HashWithIndifferentAccess, with some additional helper methods.
   class MetaTagsCollection
     attr_reader :meta_tags
 
     # Initializes a new instance of MetaTagsCollection.
-    #
     def initialize
       @meta_tags = ActiveSupport::HashWithIndifferentAccess.new
     end
 
     # Returns meta tag value by name.
     #
-    # @param [String, Symbol] name meta tag name.
+    # @param name [String, Symbol] meta tag name.
     # @return meta tag value.
-    #
     def [](name)
       @meta_tags[name]
     end
 
     # Sets meta tag value by name.
     #
-    # @param [String, Symbol] name meta tag name.
+    # @param name [String, Symbol] meta tag name.
     # @param value meta tag value.
     # @return meta tag value.
-    #
     def []=(name, value)
       @meta_tags[name] = value
     end
 
-    # Recursively merges a Hash of meta tag attributes into current list.
+    # Recursively merges a Hash of meta tag attributes into the current list.
     #
-    # @param [Hash, #to_meta_tags] object Hash of meta tags (or object responding
+    # @param object [Hash, #to_meta_tags] Hash of meta tags (or object responding
     #   to #to_meta_tags and returning a hash) to merge into the current list.
     # @return [Hash] result of the merge.
-    #
     def update(object = {})
       meta_tags = if object.respond_to?(:to_meta_tags)
         # @type var object: _MetaTagish & Object
@@ -48,11 +44,10 @@ module MetaTags
       @meta_tags.deep_merge! normalize_open_graph(meta_tags)
     end
 
-    # Temporary merges defaults with current meta tags list and yields the block.
+    # Temporarily merges defaults with the current meta tags list and yields the block.
     #
-    # @param [Hash] defaults list of default meta tag attributes.
+    # @param defaults [Hash] list of default meta tag attributes.
     # @return result of the block call.
-    #
     def with_defaults(defaults = {})
       old_meta_tags = @meta_tags
       @meta_tags = normalize_open_graph(defaults).deep_merge!(@meta_tags)
@@ -63,9 +58,8 @@ module MetaTags
 
     # Constructs the full title as if it would be rendered in title meta tag.
     #
-    # @param [Hash] defaults list of default meta tag attributes.
+    # @param defaults [Hash] list of default meta tag attributes.
     # @return [String] page title.
-    #
     def full_title(defaults = {})
       with_defaults(defaults) { extract_full_title }
     end
@@ -73,30 +67,29 @@ module MetaTags
     # Constructs the title without site title (for normalized parameters). When title is empty,
     # use the site title instead.
     #
+    # @param defaults [Hash] list of default meta tag attributes.
     # @return [String] page title.
-    #
     def page_title(defaults = {})
+      had_site = @meta_tags.key?(:site)
       old_site = @meta_tags[:site]
-      @meta_tags[:site] = nil
+      @meta_tags[:site] = nil if had_site
       full_title = with_defaults(defaults) { extract_full_title }
       full_title.presence || old_site || ""
     ensure
-      @meta_tags[:site] = old_site
+      @meta_tags[:site] = old_site if had_site
     end
 
     # Deletes and returns a meta tag value by name.
     #
-    # @param [String, Symbol] name meta tag name.
+    # @param name [String, Symbol] meta tag name.
     # @return [Object] meta tag value.
-    #
     def extract(name)
       @meta_tags.delete(name)
     end
 
     # Deletes specified meta tags.
     #
-    # @param [Array<String, Symbol>] names a list of meta tags to delete.
-    #
+    # @param names [Array<String, Symbol>] list of meta tags to delete.
     def delete(*names)
       names.each { |name| @meta_tags.delete(name) }
     end
@@ -104,7 +97,6 @@ module MetaTags
     # Extracts full page title and deletes all related meta tags.
     #
     # @return [String] page title.
-    #
     def extract_full_title
       site_title = extract(:site) || ""
       title = extract_title
@@ -117,7 +109,6 @@ module MetaTags
     # Extracts page title as an array of segments without site title and separators.
     #
     # @return [Array<String>] segments of page title.
-    #
     def extract_title
       title = extract(:title).presence
       return [] unless title
@@ -132,7 +123,6 @@ module MetaTags
     # Extracts title separator as a string.
     #
     # @return [String] page title separator.
-    #
     def extract_separator
       if meta_tags[:separator] == false
         # Special case: if separator is hidden, do not display suffix/prefix
@@ -149,9 +139,9 @@ module MetaTags
 
     # Extracts noindex settings as a Hash mapping noindex tag name to value.
     #
-    # @return [Hash<String,String>] noindex attributes.
-    #
+    # @return [Hash{String => String}] noindex attributes.
     def extract_robots
+      # @type var result: Hash[String, Array[String]]
       result = Hash.new { |h, k| h[k] = [] }
 
       [
@@ -171,9 +161,8 @@ module MetaTags
 
     # Converts input hash to HashWithIndifferentAccess and renames :open_graph to :og.
     #
-    # @param [Hash] meta_tags list of meta tags.
+    # @param meta_tags [Hash] list of meta tags.
     # @return [ActiveSupport::HashWithIndifferentAccess] normalized meta tags list.
-    #
     def normalize_open_graph(meta_tags)
       meta_tags = meta_tags.with_indifferent_access
       meta_tags[:og] = meta_tags.delete(:open_graph) if meta_tags.key?(:open_graph)
@@ -181,21 +170,19 @@ module MetaTags
     end
 
     # Extracts separator segment without deleting it from meta tags list.
-    # If the value is false, empty string will be returned.
+    # If the value is false, an empty string will be returned.
     #
-    # @param [Symbol, String] name separator segment name.
-    # @param [String] default default value.
+    # @param name [Symbol, String] separator segment name.
+    # @param default [String] default value.
     # @return [String] separator segment value.
-    #
     def extract_separator_section(name, default)
       (meta_tags[name] == false) ? "" : (meta_tags[name] || default)
     end
 
-    # Extracts robots attribute (noindex, nofollow, etc) name and value.
-    #
-    # @param [String, Symbol] name noindex attribute name.
-    # @return [Array<String>] pair of noindex attribute name and value.
+    # Extracts a robots attribute name/value pair (noindex, nofollow, etc.).
     #
+    # @param name [String, Symbol] noindex attribute name.
+    # @return [Array<String>] noindex attribute name and value pair.
     def extract_robots_attribute(name)
       noindex = extract(name)
       noindex_name = (noindex.is_a?(String) || noindex.is_a?(Array)) ? noindex : "robots"
@@ -204,18 +191,32 @@ module MetaTags
       [noindex_name, noindex_value]
     end
 
+    # Appends resolved robots directives while preserving first-write priority.
+    #
+    # @param result [Hash{String => Array<String>}] robots directives grouped by tag name.
+    # @param attributes [Symbol, Array<Symbol>] robots attributes to resolve.
+    # @return [void]
     def calculate_robots_attributes(result, attributes)
       processed = Set.new
       Array(attributes).each do |attribute|
+        # @type var attribute: String | Symbol
         names, value = extract_robots_attribute(attribute)
         next unless value
 
         Array(names).each do |name|
+          # @type var name: String | Symbol
           apply_robots_value(result, name, value, processed)
         end
       end
     end
 
+    # Records a robots directive unless it has already been set for the same key.
+    #
+    # @param result [Hash{String => Array<String>}] robots directives grouped by tag name.
+    # @param name [String, Symbol] robots tag name.
+    # @param value [String] robots directive value.
+    # @param processed [Set<String>] names already recorded in this pass.
+    # @return [void]
     def apply_robots_value(result, name, value, processed)
       name = name.to_s
       return if processed.include?(name)

data/lib/meta_tags/railtie.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module MetaTags
+  # Hooks MetaTags helpers into Rails controllers and views.
   class Railtie < Rails::Railtie
     initializer "meta_tags.setup_action_controller" do
       ActiveSupport.on_load :action_controller do

data/lib/meta_tags/renderer.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 module MetaTags
-  # This class is used by MetaTags gems to render HTML meta tags into page.
+  # This class is used by the MetaTags gem to render HTML meta tags on a page.
   class Renderer
     attr_reader :meta_tags, :normalized_meta_tags
 
-    # Initialized a new instance of Renderer.
-    #
-    # @param [MetaTagsCollection] meta_tags meta tags object to render.
+    # Initializes a new instance of Renderer.
     #
+    # @param meta_tags [MetaTagsCollection] meta tags object to render.
     def initialize(meta_tags)
       @meta_tags = meta_tags
       @normalized_meta_tags = {}
@@ -16,7 +15,7 @@ module MetaTags
 
     # Renders meta tags on the page.
     #
-    # @param [ActionView::Base] view Rails view object.
+    # @param view [ActionView::Base] Rails view object.
     def render(view)
       tags = [] # : Array[Tag]
 
@@ -43,8 +42,7 @@ module MetaTags
 
     # Renders charset tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_charset(tags)
       charset = meta_tags.extract(:charset)
       tags << Tag.new(:meta, charset: charset) if charset.present?
@@ -52,8 +50,7 @@ module MetaTags
 
     # Renders title tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_title(tags)
       normalized_meta_tags[:title] = meta_tags.page_title
       normalized_meta_tags[:site] = meta_tags[:site]
@@ -68,8 +65,7 @@ module MetaTags
 
     # Renders icon(s) tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_icon(tags)
       icon = meta_tags.extract(:icon)
       return unless icon
@@ -88,9 +84,9 @@ module MetaTags
     # Renders meta tag with normalization (should have a corresponding normalize_
     # method in TextNormalizer).
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param name [Symbol] meta tag name to normalize and render.
     # @see TextNormalizer
-    #
     def render_with_normalization(tags, name)
       value = TextNormalizer.public_send(:"normalize_#{name}", meta_tags.extract(name))
       normalized_meta_tags[name] = value
@@ -99,8 +95,7 @@ module MetaTags
 
     # Renders noindex and nofollow meta tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_noindex(tags)
       meta_tags.extract_robots.each do |name, content|
         tags << Tag.new(:meta, name: name, content: content) if content.present?
@@ -109,8 +104,7 @@ module MetaTags
 
     # Renders refresh meta tag.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_refresh(tags)
       refresh = meta_tags.extract(:refresh)
       tags << Tag.new(:meta, "http-equiv" => "refresh", :content => refresh.to_s) if refresh.present?
@@ -118,8 +112,7 @@ module MetaTags
 
     # Renders alternate link tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_alternate(tags)
       alternate = meta_tags.extract(:alternate)
       return unless alternate
@@ -135,10 +128,9 @@ module MetaTags
       end
     end
 
-    # Renders open_search link tag.
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
+    # Renders the OpenSearch link tag.
     #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_open_search(tags)
       open_search = meta_tags.extract(:open_search)
       return unless open_search
@@ -152,8 +144,7 @@ module MetaTags
 
     # Renders links.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_links(tags)
       [:amphtml, :prev, :next, :image_src, :manifest].each do |tag_name|
         href = meta_tags.extract(tag_name)
@@ -164,12 +155,11 @@ module MetaTags
       end
     end
 
-    # Renders canonical link
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
+    # Renders the canonical link.
     #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_canonical_link(tags)
-      href = meta_tags.extract(:canonical) # extract, so its not used anywhere else
+      href = meta_tags.extract(:canonical) # extract, so it's not used anywhere else
       return if MetaTags.config.skip_canonical_links_on_noindex && meta_tags[:noindex]
       return if href.blank?
 
@@ -179,30 +169,28 @@ module MetaTags
 
     # Renders complex hash objects.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
-    def render_hashes(tags, **opts)
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    def render_hashes(tags)
       meta_tags.meta_tags.each_key do |property|
-        render_hash(tags, property, **opts)
+        render_hash(tags, property)
       end
     end
 
     # Renders a complex hash object by key.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
-    def render_hash(tags, key, **opts)
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param key [String, Symbol] top-level meta tag key.
+    def render_hash(tags, key)
       data = meta_tags.meta_tags[key]
       return unless data.is_a?(Hash)
 
-      process_hash(tags, key, data, **opts)
+      process_hash(tags, key, data)
       meta_tags.extract(key)
     end
 
     # Renders custom meta tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
     def render_custom(tags)
       meta_tags.meta_tags.each do |name, data|
         Array(data).each do |val|
@@ -212,40 +200,39 @@ module MetaTags
       end
     end
 
-    # Recursive method to process all the hashes and arrays on meta tags
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] property a Hash or a String to render as meta tag.
-    # @param [Hash, Array, String, Symbol] content text content or a symbol reference to
-    # top-level meta tag.
+    # Recursive method to process all hashes and arrays in meta tags.
     #
-    def process_tree(tags, property, content, itemprop: nil, **opts)
-      method = case content
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param property [String, Symbol] the meta tag property name.
+    # @param content [Hash, Array, String, Symbol] text content or a symbol
+    #   reference to a top-level meta tag.
+    # @param itemprop [String, Symbol, nil] value of the itemprop attribute.
+    def process_tree(tags, property, content, itemprop: nil)
+      case content
       when Hash
-        :process_hash
+        process_hash(tags, property, content, itemprop: itemprop)
       when Array
-        :process_array
+        process_array(tags, property, content, itemprop: itemprop)
       else
-        iprop = itemprop
-        :render_tag
+        render_tag(tags, property, content, itemprop: itemprop)
       end
-      __send__(method, tags, property, content, itemprop: iprop, **opts)
     end
 
-    # Recursive method to process a hash with meta tags
+    # Recursive method to process a hash of meta tags.
     #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] property a Hash or a String to render as meta tag.
-    # @param [Hash] content nested meta tag attributes.
-    #
-    def process_hash(tags, property, content, **opts)
-      itemprop = content.delete(:itemprop)
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param property [String, Symbol] the meta tag property name.
+    # @param content [Hash] nested meta tag attributes.
+    # @param itemprop [String, Symbol, nil] inherited itemprop value.
+    def process_hash(tags, property, content, itemprop: nil)
+      current_itemprop = content.delete(:itemprop)
       content.each do |key, value|
         if key.to_s == "_"
-          iprop = itemprop
           key = property
+          next_itemprop = current_itemprop
         else
           key = "#{property}:#{key}"
+          next_itemprop = nil
         end
 
         normalized_value = if value.is_a?(Symbol)
@@ -253,44 +240,59 @@ module MetaTags
         else
           value
         end
-        process_tree(tags, key, normalized_value, **opts.merge(itemprop: iprop))
+        process_tree(tags, key, normalized_value, itemprop: next_itemprop)
       end
     end
 
-    # Recursive method to process a hash with meta tags
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] property a Hash or a String to render as meta tag.
-    # @param [Array] content array of nested meta tag attributes or values.
+    # Recursive method to process an array of meta tags.
     #
-    def process_array(tags, property, content, **opts)
-      content.each { |v| process_tree(tags, property, v, **opts) }
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param property [String, Symbol] the meta tag property name.
+    # @param content [Array] array of nested meta tag attributes or values.
+    # @param itemprop [String, Symbol, nil] value of the itemprop attribute.
+    def process_array(tags, property, content, itemprop: nil)
+      content.each { |value| process_tree(tags, property, value, itemprop: itemprop) }
     end
 
-    # Recursive method to process a hash with meta tags
-    #
-    # @param [Array<Tag>] tags a buffer object to store tag in.
-    # @param [String, Symbol] name a Hash or a String to render as meta tag.
-    # @param [String, Symbol] value text content or a symbol reference to
-    # top-level meta tag.
-    # @param [String, Symbol] itemprop value of the itemprop attribute.
+    # Renders a single meta tag.
     #
+    # @param tags [Array<Tag>] a buffer object to store tags in.
+    # @param name [String, Symbol] the meta tag name.
+    # @param value [String, Symbol] text content or a symbol reference to a
+    #   top-level meta tag.
+    # @param itemprop [String, Symbol, nil] value of the itemprop attribute.
     def render_tag(tags, name, value, itemprop: nil)
       name_key ||= configured_name_key(name)
       tags << Tag.new(:meta, name_key => name.to_s, :content => value, :itemprop => itemprop) if value.present?
     end
 
-    # Returns meta tag property name for a give meta tag based on the
+    # Returns the meta tag property name for a given meta tag based on the
     # configured list of property tags in MetaTags::Configuration#property_tags.
     #
-    # @param [String, Symbol] name tag key.
+    # @param name [String, Symbol] tag key.
     # @return [Symbol] meta tag attribute name (:property or :name).
-    #
     def configured_name_key(name)
+      name = name.to_s
       is_property_tag = MetaTags.config.property_tags.any? do |tag_name|
-        name.to_s.match(/^#{Regexp.escape(tag_name.to_s)}\b/)
+        property_tag?(name, tag_name.to_s)
       end
       is_property_tag ? :property : :name
     end
+
+    # Returns true when a configured property tag matches the exact meta tag
+    # name or the start of a colon-delimited namespace.
+    #
+    # @param name [String] rendered meta tag name.
+    # @param tag_name [String] configured property tag name or namespace prefix.
+    # @return [Boolean]
+    def property_tag?(name, tag_name)
+      return false unless name.start_with?(tag_name)
+
+      tag_name_length = tag_name.bytesize
+      return true if name.bytesize == tag_name_length
+      return true if tag_name.getbyte(tag_name_length - 1) == 58
+
+      name.getbyte(tag_name_length) == 58
+    end
   end
 end

data/lib/meta_tags/tag.rb

@@ -7,26 +7,28 @@ module MetaTags
 
     # Initializes a new instance of Tag class.
     #
-    # @param [String, Symbol] name HTML tag name
-    # @param [Hash] attributes list of HTML tag attributes
-    #
+    # @param name [String, Symbol] HTML tag name.
+    # @param attributes [Hash] list of HTML tag attributes.
     def initialize(name, attributes = {})
       @name = name.to_s
       @attributes = attributes
     end
 
-    # Render tag into a Rails view.
+    # Renders the tag in a Rails view.
     #
-    # @param [ActionView::Base] view instance of a Rails view.
+    # @param view [ActionView::Base] instance of a Rails view.
     # @return [String] HTML string for the tag.
-    #
     def render(view)
-      view.tag(name, prepare_attributes(attributes), MetaTags.config.open_meta_tags?)
+      view.tag(name, serialize_iso8601_attributes(attributes), MetaTags.config.open_meta_tags?)
     end
 
     protected
 
-    def prepare_attributes(attributes)
+    # Serializes attribute values that support ISO 8601 formatting.
+    #
+    # @param attributes [Hash] HTML tag attributes.
+    # @return [Hash] normalized HTML tag attributes.
+    def serialize_iso8601_attributes(attributes)
       attributes.each do |key, value|
         attributes[key] = value.iso8601 if value.respond_to?(:iso8601)
       end