RubyGems - roda-tags - Versions diffs - 0.1.1 → 0.2.0 - Mend

roda-tags 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

checksums.yaml +5 -5
data/.github/dependabot.yml +24 -0
data/.github/workflows/ruby.yml +45 -0
data/.gitignore +1 -1
data/.rubocop.yml +33 -0
data/.rubocop_todo.yml +7 -0
data/CODE_OF_CONDUCT.md +22 -16
data/Gemfile +86 -0
data/Guardfile +25 -0
data/README.md +234 -236
data/Rakefile +14 -11
data/lib/core_ext/blank.rb +37 -36
data/lib/core_ext/hash.rb +39 -16
data/lib/core_ext/object.rb +2 -2
data/lib/core_ext/string.rb +290 -116
data/lib/roda/plugins/tag_helpers.rb +795 -575
data/lib/roda/plugins/tags.rb +532 -276
data/lib/roda/tags/version.rb +2 -3
data/lib/roda/tags.rb +2 -0
data/roda-tags.gemspec +30 -32
metadata +44 -128
data/.travis.yml +0 -4

data/lib/roda/plugins/tags.rb CHANGED Viewed

@@ -1,18 +1,17 @@
+# frozen_string_literal: false
 require 'roda'
 require_relative '../../core_ext/hash'   unless {}.respond_to?(:to_html_attributes)
 require_relative '../../core_ext/blank'  unless Object.new.respond_to?(:blank?)
 class Roda
-  #
+  # add module documentation
   module RodaPlugins
     # TODO: Add documentation here
     #
     #
     module RodaTags
       # default options
       OPTS = {
         # toggle for XHTML formatted output in case of legacy
@@ -20,433 +19,690 @@ class Roda
         # toggle for adding newlines after output
         tag_add_newlines_after_tags: true
       }.freeze
       # Tags that should be rendered in multiple lines, like...
-      #
+      #
       #   <body>
       #     <snip...>
       #   </body>
       #
-      MULTI_LINE_TAGS = %w(
-        a address applet bdo big blockquote body button caption center
-        colgroup dd dir div dl dt fieldset form frameset head html iframe
-        map noframes noscript object ol optgroup pre script section select small
-        style table tbody td tfoot th thead title tr tt ul
-      )
+      MULTI_LINE_TAGS = %w[
+        a address applet bdo big blockquote body button caption center colgroup dd dir div dl dt
+        fieldset form frameset head html iframe map noframes noscript object ol optgroup pre
+        script section select small style table tbody td tfoot th thead title tr tt ul
+      ].freeze
       # Self closing tags, like...
-      #
+      #
       #   <hr> or <hr />
       #
-      SELF_CLOSING_TAGS = %w( area base br col frame hr img input link meta param )
+      SELF_CLOSING_TAGS = %w[
+        area base br col frame hr img input link meta param
+      ].freeze
       # Tags that should be rendered in a single line, like...
-      #
+      #
       #   <h1>Header</h1>
       #
-      SINGLE_LINE_TAGS = %w(
-        abbr acronym b cite code del dfn em h1 h2 h3 h4 h5 h6 i kbd
+      SINGLE_LINE_TAGS = %w[
+        abbr acronym b cite code del dfn em h1 h2 h3 h4 h5 h6 i kbd
         label legend li option p q samp span strong sub sup var
-      )
+      ].freeze
       # Boolean attributes, ie: attributes like...
-      #
+      #
       #   <option value="a" selected="selected">A</option>
       #
-      BOOLEAN_ATTRIBUTES = %w(autofocus checked disabled multiple readonly required selected)
+      BOOLEAN_ATTRIBUTES = %w[
+        autofocus checked disabled multiple readonly required selected
+      ].freeze
       # Depend on the render plugin, since this plugin only makes
       # sense when the render plugin is used.
-      def self.load_dependencies(app, opts = OPTS)
+      def self.load_dependencies(app, _opts = OPTS)
         app.plugin :render
       end
       def self.configure(app, opts = {})
-        if app.opts[:tags]
-          opts = app.opts[:tags][:orig_opts].merge(opts)
-        else
-          opts = OPTS.merge(opts)
-        end
+        opts = if app.opts[:tags]
+                 app.opts[:tags][:orig_opts].merge(opts)
+               else
+                 OPTS.merge(opts)
+               end
         app.opts[:tags]             = opts.dup
         app.opts[:tags][:orig_opts] = opts
       end
-      #
+      # add module documentation
       module ClassMethods
-        # Return the uitags options for this class.
+        # Returns the tags options hash for the current Roda class instance.
+        #
+        # @example
+        #   tags_opts
+        #     #=> { tag_output_format_is_xhtml: false, tag_add_newlines_after_tags: true }
+        #
         def tags_opts
           opts[:tags]
         end
       end
-      #
+      # add module documentation
+      # rubocop:disable Metrics/ModuleLength
       module InstanceMethods
-        # Returns markup for tag _name_.
-        #
-        # Optionally _contents_ may be passed, which is literal content for spanning tags such as
-        # <tt>textarea</tt>, etc.
-        #
-        # A hash of _attrs_ may be passed as the *second* or *third* argument.
-        #
-        # Self closing tags such as <tt><br/></tt>, <tt><input/></tt>, etc are automatically closed
-        # depending on output format, HTML vs XHTML.
-        #
-        # Boolean attributes like "<tt>selected</tt>", "<tt>checked</tt>" etc, are mirrored or
-        # removed when <tt>true</tt> or <tt>false</tt>.
-        #
-        # ==== Examples
-        #
-        # Self closing tags:
-        #
-        #   tag(:br)
-        #   # => <br> or <br/> if XHTML
-        #
-        #   tag(:hr, class: "space")
-        #   # => <hr class="space">
-        #
-        # Multi line tags:
-        #
-        #   tag(:div)
-        #   # => <div></div>
-        #
-        #   tag(:div, 'content')
-        #   # => <div>content</div>
+        # Generates HTML tag markup based on the given name, content, and attributes
+        #
+        # @param name [String,Symbol] The tag name to generate (e.g. 'div', :span)
+        # @param content [String,nil] Optional content for the tag (ignored if block given)
+        # @param attrs [Hash] Optional HTML attributes hash that may include :newline toggle
+        # @yield Optional block providing content for the tag
+        #
+        # @return [String] The generated HTML tag markup
+        #
+        # @example Basic tag
+        #   tag(:div)  #=> <div></div>
+        #
+        # @example Tag with content
+        #   tag(:p, "Hello")  #=> <p>Hello</p>
+        #
+        # @example Tag with attributes
+        #   tag(:div, class: 'btn', id: 'submit')
+        #     #=> <div class="btn" id="submit"></div>
+        #
+        # @example Self closing tags:
+        #   tag(:br)  # => <br> / <br/>
+        #
+        #   tag(:hr, class: "space")  # => <hr class="space">
+        #
+        # @example Multi line tags:
+        #   tag(:div, 'content')  # => <div>content</div>
         #
         #   tag(:div, 'content', id: 'comment')
-        #   # => <div id="comment">content</div>
+        #     # => <div id="comment">content</div>
         #
         #   tag(:div, id: 'comment')  # NB! no content
-        #   # => <div id="comment"></div>
+        #     # => <div id="comment"></div>
         #
-        # Single line tags:
-        #
+        # @example Single line tags:
         #   tag(:h1,'Header')
-        #   # => <h1>Header</h1>
-        #
+        #     # => <h1>Header</h1>
+        #
         #   tag(:abbr, 'WHO', :title => "World Health Organization")
-        #   # => <abbr title="World Health Organization">WHO</abbr>
-        #
-        # Working with blocks
-        #
+        #     # => <abbr title="World Health Organization">WHO</abbr>
+        #
+        # @example Tag with block
+        #   tag(:div) { tag(:p, "Content") }  #=> "<div><p>Content</p></div>"
+        #
+        # @example Working with blocks
         #   tag(:div) do
         #     tag(:p, 'Hello World')
         #   end
-        #   # => <div><p>Hello World</p></div>
-        #
+        #     # => <div><p>Hello World</p></div>
+        #
         #   <% tag(:div) do %>
         #     <p>Paragraph 1</p>
         #     <%= tag(:p, 'Paragraph 2') %>
         #     <p>Paragraph 3</p>
         #   <% end %>
-        #   # =>
-        #     <div>
-        #       <p>Paragraph 1</p>
-        #       <p>Paragraph 2</p>
-        #       <p>Paragraph 3</p>
-        #     </div>
-        #
-        #
-        #   # NB! ignored tag contents if given a block
+        #     # => <div>
+        #     #      <p>Paragraph 1</p>
+        #     #      <p>Paragraph 2</p>
+        #     #      <p>Paragraph 3</p>
+        #     #    </div>
+        #
+        # NOTE! ignored tag contents if given a block
+        #
         #   <% tag(:div, 'ignored tag-content') do  %>
         #     <%= tag(:label, 'Comments:', for: :comments)  %>
         #     <%= tag(:textarea,'textarea contents', id: :comments) %>
         #   <% end  %>
-        #   # =>
-        #     <div>
-        #       <label for="comments">Comments:</label>
-        #       <textarea id="comments">
-        #         textarea contents
-        #       </textarea>
-        #     </div>
-        #
-        #
-        #
-        # Boolean attributes:
-        #
+        #     # => <div>
+        #     #      <label for="comments">Comments:</label>
+        #     #      <textarea id="comments">
+        #     #        textarea contents
+        #     #      </textarea>
+        #     #    </div>
+        #
+        # @example Boolean attributes
         #   tag(:input, type: :checkbox, checked: true)
-        #   # => <input type="checkbox" checked="checked">
-        #
+        #     # => <input type="checkbox" checked="checked">
+        #
         #   tag(:option, 'Sinatra', value: "1", selected: true)
-        #   # => <option value="1" selected>Sinatra</option>
-        #
+        #     # => <option value="1" selected>Sinatra</option>
+        #
         #   tag(:option, 'PHP', value: "0", selected: false)
-        #   # => <option value="0">PHP</option>
-        #
+        #     # => <option value="0">PHP</option>
+        #
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
         def tag(*args, &block)
           name = args.first
           attrs = args.last.is_a?(Hash) ? args.pop : {}
           newline = attrs[:newline] # save before it gets tainted
-          tag_content = block_given? ? capture_html(&block) : args[1]  # content
+          tag_content = block_given? ? capture_html(&block) : args[1] # content
           if self_closing_tag?(name)
             tag_html = self_closing_tag(name, attrs)
           else
-            tag_html = "#{open_tag(name, attrs)}#{tag_contents_for(name, tag_content, newline)}"
+            tag_html = "#{open_tag(name, attrs)}#{tag_contents_for(name, tag_content, newline)}"
             tag_html << closing_tag(name)
           end
           block_is_template?(block) ? concat_content(tag_html) : tag_html
         end
-        # Update the +:class+ entry in the +attr+ hash with the given +classes+ and returns +attr+.
-        #
-        #   attr = { class: 'alert', id: :idval }
-        #
-        #   merge_attr_classes(attr, 'alert-info')  #=> { class: 'alert alert-info', id: :idval }
-        #
-        #   merge_attr_classes(attr, [:alert, 'alert-info'])
-        #     #=> { class: 'alert alert-info', id: :idval }
-        #
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+        # Updates the :class attribute in the given hash with additional class values.
+        # Takes a hash and any number of class values as arguments.
+        # Returns the modified hash with merged class values.
+        #
+        # @param attr [Hash] The attributes hash to modify
+        # @param classes [Array<String,Symbol,Array>] Additional class values to merge
+        #
+        # @return [Hash] The modified attributes hash
+        #
+        # @example
+        #   attr = { class: 'btn', id: 'submit' }
+        #   merge_attr_classes(attr, 'primary', 'large')
+        #     #=> { class: 'btn large primary', id: 'submit' }
+        #
+        #   attr = { id: 'submit' }
+        #   merge_attr_classes(attr, ['btn', 'primary'])
+        #     #=> { class: 'btn primary', id: 'submit' }
+        #
         def merge_attr_classes(attr, *classes)
           attr[:class] = [] if attr[:class].blank?
           attr[:class] = merge_classes(attr[:class], *classes)
           attr[:class] = nil if attr[:class] == '' # set to nil to remove from tag output
           attr
         end
-        # Return an alphabetized string that includes all given class values.
-        #
-        # Handles a combination of arrays, strings & symbols being passed in.
-        #
+        # Merges class values from multiple sources into a single sorted string
+        #
+        # @param classes [Array<String,Symbol,Array>] Class values to merge, which can be:
+        #   - Symbols: Converted directly to strings
+        #   - Strings: Split on whitespace into multiple classes
+        #   - Arrays: Each element converted to string
+        #
+        # @return [String] Space-separated string of unique, sorted class names
+        #
+        # @example Passing a hash
         #   attr = { class: 'alert', id: :idval }
-        #
         #   merge_classes(attr[:class], ['alert', 'alert-info'])  #=> 'alert alert-info'
-        #
+        #
         #   merge_classes(attr[:class], :text)  #=> 'alert text'
-        #
-        #   merge_classes(attr[:class], [:text, :'alert-info'])  #=> 'alert alert-info text'
-        #
-        #
+        #
+        # @example Passing a string, an array & symbol
+        #   merge_classes('btn', ['primary', 'large'], :active)  #=> "active btn large primary"
+        #
+        # @example Passing a string & :symbol
+        #   merge_classes('alert alert-info', :text)  #=> "alert alert-info text"
+        #
+        # rubocop:disable Metrics/AbcSize
         def merge_classes(*classes)
           klasses = []
           classes.each do |c|
             klasses << c.to_s if c.is_a?(Symbol)
-            c.split(/\s+/).each { |x| klasses << x.to_s  } if c.is_a?(String)
+            c.split(/\s+/).each { |x| klasses << x.to_s } if c.is_a?(String)
             c.each { |i| klasses << i.to_s } if c.is_a?(Array)
           end
           klasses.compact.uniq.sort.join(' ').strip
         end
+        # rubocop:enable Metrics/AbcSize
         ## HELPERS
-        #
+        # Captures the content of a block with proper buffer handling
+        #
+        # @param block [String, Proc] The block to capture, defaults to empty string
+        #
+        # @return The captured content from the block
+        #
+        # @example Capturing a block's content
+        #   capture { tag(:div, "content") }  # => <div>content</div>
+        #
+        # @example Capturing with explicit block parameter
+        #   capture(some_block) { yield }  # => captured block content
+        #
         def capture(block = '') # :nodoc:
           buf_was = @output
-          @output = block.is_a?(Proc) ? (eval('@_out_buf', block.binding) || @output) : block
+          @output = if block.is_a?(Proc)
+                      eval('@_out_buf', block.binding, __FILE__, __LINE__ - 1) || @output
+                    else
+                      block
+                    end
           yield
           ret = @output
           @output = buf_was
           ret
         end
-        # Captures the html from a block of template code for erb or haml
-        #
-        # ==== Examples
-        #
-        #   capture_html(&block) => "...html..."
-        #
-        def capture_html(*args, &block)
-          if self.respond_to?(:is_haml?) && is_haml?
-            block_is_haml?(block) ? capture_haml(*args, &block) : block.call
+        # Captures the content of a template block for Haml or ERB templates,
+        # returning the captured HTML
+        #
+        # @param args [Array] Arguments to pass to the block
+        # @param block [Proc] The template block to capture
+        #
+        # @return [String] The captured HTML content
+        #
+        # @example Capturing Haml content
+        #   capture_html { tag :div, "Content" }  # => <div>Content</div>
+        #
+        # @example Capturing ERB content
+        #   capture_html { tag :p, "Content" }  # => <p>Content</p>\n
+        #
+        # @example Direct block yield
+        #   capture_html { "Content" }  # => Content
+        #
+        def capture_html(*args, &block)
+          if respond_to?(:is_haml?) && is_haml?
+            block_is_haml?(block) ? capture_haml(*args, &block) : yield
           elsif erb_buffer?
             result_text = capture_block(*args, &block)
-            result_text.present? ? result_text : (block_given? && block.call(*args))
+            result_text.present? ? result_text : (block_given? && yield(*args))
           else # theres no template to capture, invoke the block directly
-            block.call(*args)
+            yield(*args)
           end
         end
-        # Outputs the given text to the templates buffer directly.
-        #
-        # ==== Examples
-        #
-        #   concat_content("This will be output to the template buffer in erb or haml")
-        #
-        def concat_content(text = '')
-          if self.respond_to?(:is_haml?) && is_haml?
-            haml_concat(text)
-          elsif :erb_buffer?
-            buffer_concat(text)
+        # Outputs the given text to the template buffer based on the template engine in use.
+        # For Haml templates, uses `haml_concat`. For ERB templates, uses `buffer_concat`.
+        # If no template engine is active, returns the text directly.
+        #
+        # @param text [String] The text to output, defaults to empty string
+        #
+        # @return [String] The text if no template engine is active
+        #
+        # @example With Haml template
+        #   concat_content("Hello")  # => Outputs "Hello" to Haml buffer
+        #
+        # @example With ERB template
+        #   concat_content("World")  # => Outputs "World" to ERB buffer
+        #
+        # @example With no template
+        #   concat_content("Test")  # => Returns "Test" string
+        #
+        def concat_content(text = '')
+          if respond_to?(:is_haml?) && is_haml?
+            haml_concat(text.to_s)
+          elsif erb_buffer?
+            buffer_concat(text.to_s)
           else # theres no template to concat, return the text directly
-            text
+            text.to_s
           end
         end
-        # Returns true if the block is from an ERB or HAML template; false otherwise.
-        # Used to determine if html should be returned or concatenated to a view.
-        #
-        # ==== Examples
-        #
-        #   block_is_template?(block)
-        #
-        def block_is_template?(block)
-           block && (erb_block?(block) ||
-             (self.respond_to?(:block_is_haml?) && block_is_haml?(block)))
+        # Returns true if the given block is from an ERB or HAML template
+        #
+        # @param block [Proc] The block to check
+        #
+        # @return [Boolean] true if block is from an ERB/HAML template, false otherwise
+        #
+        # @example
+        #   # if block is from ERB template
+        #   block_is_template?(some_block)  #=> true
+        #
+        #   # if block is from HAML template
+        #   block_is_template?(some_block)  #=> true
+        #
+        #   block_is_template?(regular_block)  #=> false
+        #
+        def block_is_template?(block)
+          block && (erb_block?(block) || (respond_to?(:block_is_haml?) && block_is_haml?(block)))
         end
-        #
+        # Returns whether the current output format is XHTML based on tag configuration
+        #
+        # @return [Boolean] true if XHTML output is enabled, false for HTML output
+        #
+        # @example
+        #   # if :tag_output_format_is_xhtml is true in config
+        #   output_is_xhtml?  #=> true
+        #
+        #   # if :tag_output_format_is_xhtml is false in config
+        #   output_is_xhtml?  #=> false
+        #
         def output_is_xhtml?
           opts[:tags][:tag_output_format_is_xhtml]
         end
         private
-        # Return an opening tag of _name_, with _attrs_.
-        def open_tag(name, attrs = {})
+        # Returns an opening HTML tag string with the given name and optional attributes
+        #
+        # @param name [String,Symbol] The tag name (e.g. 'div', :span)
+        # @param attrs [Hash] Optional HTML attributes hash (e.g. {class: 'btn'})
+        #
+        # @return [String] The opening tag string (e.g. '<div class="btn">')
+        #
+        # @example Basic tag
+        #   open_tag(:div)  #=> "<div>"
+        #
+        # @example Tag with attributes
+        #   open_tag(:div, class: 'btn', id: 'submit')
+        #     #=> <div class="btn" id="submit">
+        #
+        def open_tag(name, attrs = {})
           "<#{name}#{normalize_html_attributes(attrs)}>"
         end
-        # Return closing tag of _name_.
-        def closing_tag(name)
+        # Returns a closing HTML tag string for the given tag name
+        #
+        # @param name [String,Symbol] The tag name to close (e.g. 'div', :span)
+        #
+        # @return [String] The closing tag string with optional newline
+        #
+        # @example Basic closing tag
+        #   closing_tag(:div)  #=> "</div>\n" # with newlines enabled
+        #
+        # @example Without newlines
+        #   closing_tag(:span)  #=> "</span>" # with newlines disabled
+        #
+        def closing_tag(name)
           "</#{name}>#{add_newline?}"
         end
-        # Creates a self closing tag.  Like <br/> or <img src="..."/>
-        #
-        # ==== Options
-        # +name+ : the name of the tag to create
-        # +attrs+ : a hash where all members will be mapped to key="value"
-        #
-        def self_closing_tag(name, attrs = {})
-          newline = (attrs[:newline].nil?) ? nil : attrs.delete(:newline)
+        # Creates a self-closing HTML tag with optional attributes and newlines
+        #
+        # @param name [String,Symbol] The tag name (e.g. 'br', :img)
+        # @param attrs [Hash] Optional attrs hash including `{ newline: true } toggle
+        #
+        # @return [String] The self-closing tag string (e.g. '<br>' or '<br />' for XHTML)
+        #
+        # @example Basic self-closing tag
+        #   self_closing_tag(:br)  #=> "<br>" / "<br />" in XHTML
+        #
+        # @example With attributes and newlines
+        #   self_closing_tag(:img, src: 'test.jpg', newline: true)
+        #     #=> '<img src="test.jpg">\n' / '<img src="test.jpg" />\n'
+        #
+        def self_closing_tag(name, attrs = {})
+          newline = attrs[:newline].nil? ? nil : attrs.delete(:newline)
           "<#{name}#{normalize_html_attributes(attrs)}#{is_xhtml?}#{add_newline?(newline)}"
         end
-        # Based upon the context, wraps the tag content in '\n' (newlines)
-        #
-        # ==== Examples
-        #
-        #   tag_contents_for(:div, 'content', nil)
-        #   # => <div>content</div>
-        #
-        #   tag_contents_for(:div, 'content', false)
-        #   # => <div>content</div>
-        #
-        # Single line tag
-        #   tag_contents_for(:option, 'content', true)
-        #   # => <option...>\ncontent\n</option>
-        #
+        # Formats tag contents with appropriate newlines based on tag type and options
+        #
+        # @param name [String,Symbol] The tag name to check format rules against
+        # @param content [String] The content to be wrapped in the tag
+        # @param newline [Boolean,nil] Override flag for newline insertion, nil uses default
+        #
+        # @return [String] The formatted content with appropriate newlines
+        #
+        # @example Multi-line tag
+        #   tag_contents_for(:div, 'content')  #=> "\ncontent\n"
+        #
+        # @example Single-line tag with newlines
+        #   tag_contents_for(:span, 'text', true)  #=> "\ntext\n"
+        #
+        # @example Basic content
+        #   tag_contents_for(:p, 'text')  #=> "text"
+        #
         def tag_contents_for(name, content, newline = nil)
           if multi_line_tag?(name)
-            "#{add_newline?(newline)}#{content}#{add_newline?(newline)}".gsub(/\n\n/, "\n")
+            "#{add_newline?(newline)}#{content}#{add_newline?(newline)}".gsub("\n\n", "\n")
           elsif single_line_tag?(name) && newline == true
             "#{add_newline?(newline)}#{content}#{add_newline?(newline)}"
           else
             content.to_s
           end
         end
-        # Normalize _attrs_, replacing boolean keys with their mirrored values.
-        def normalize_html_attributes(attrs = {})
+        # Normalizes HTML attributes handling special cases like data-* attributes
+        # and boolean attributes
+        #
+        # @param attrs [Hash] Hash of HTML attributes to normalize
+        #
+        # @return [String, nil] Normalized attributes string with leading space, nil if attrs empty
+        #
+        # @example Basic attributes
+        #   normalize_html_attributes(class: 'btn', id: 'submit')  #=> ' class="btn" id="submit"'
+        #
+        # @example Data attributes
+        #   normalize_html_attributes(data: { value: 123 })  #=> ' data-value="123"'
+        #
+        # @example Boolean attributes
+        #   normalize_html_attributes(checked: true, disabled: false)  #=> ' checked="checked"'
+        #
+        # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+        def normalize_html_attributes(attrs = {})
           return if attrs.blank?
           attrs.delete(:newline) # remove newline from attributes
           # look for data attrs
-          if value = attrs.delete(:data)
+          if (value = attrs.delete(:data))
             # NB!! convert key to symbol for [].sort
-            value.each { |k, v| attrs[:"data-#{k.to_s}"] = v }
+            value.each { |k, v| attrs[:"data-#{k}"] = v }
           end
           attrs.each do |name, val|
             if boolean_attribute?(name)
               val == true ? attrs[name] = name : attrs.delete(name)
             end
           end
-          return attrs.empty? ? '' : ' ' + attrs.to_html_attributes
+          attrs.empty? ? '' : " #{attrs.to_html_attributes}"
         end
-        # Check if _name_ is a boolean attribute.
-        def boolean_attribute?(name)
+        # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+        # Checks if the given attribute name is a boolean HTML attribute like checked, disabled, etc
+        #
+        # @param name [String,Symbol] The attribute name to check
+        #
+        # @return [Boolean] true if attribute is boolean, false otherwise
+        #
+        # @example Boolean attribute
+        #   boolean_attribute?(:checked)  #=> true
+        #
+        # @example Regular attribute
+        #   boolean_attribute?(:class)  #=> false
+        #
+        def boolean_attribute?(name)
           BOOLEAN_ATTRIBUTES.include?(name.to_s)
         end
-        # Check if tag _name_ is a self-closing tag.
-        def self_closing_tag?(name)
+        # Checks if the given tag name is a self-closing tag like <br>, <img>, etc
+        #
+        # @param name [String,Symbol] The tag name to check
+        #
+        # @return [Boolean] true if tag is self-closing, false otherwise
+        #
+        # @example Self-closing tag
+        #   self_closing_tag?(:br)  #=> true
+        #
+        # @example Regular tag
+        #   self_closing_tag?(:div)  #=> false
+        #
+        def self_closing_tag?(name)
           SELF_CLOSING_TAGS.include?(name.to_s)
         end
-        # Check if tag _name_ is a single line tag.
-        def single_line_tag?(name)
+        # Checks if the given tag name is a single-line tag that should be rendered without newlines
+        #
+        # @param name [String,Symbol] The tag name to check
+        #
+        # @return [Boolean] true if tag should be rendered on a single line, false otherwise
+        #
+        # @example Single-line tag
+        #   single_line_tag?(:span)  #=> true
+        #
+        # @example Multi-line tag
+        #   single_line_tag?(:div)  #=> false
+        #
+        def single_line_tag?(name)
           SINGLE_LINE_TAGS.include?(name.to_s)
         end
-        # Check if tag _name_ is a multi line tag.
-        def multi_line_tag?(name)
+        # Checks if the given tag name is a multi-line tag that should be rendered with newlines
+        #
+        # @param name [String,Symbol] The tag name to check
+        #
+        # @return [Boolean] true if tag should be rendered with multiple lines, false otherwise
+        #
+        # @example Multi-line tag
+        #   multi_line_tag?(:div)  #=> true
+        #
+        # @example Single-line tag
+        #   multi_line_tag?(:span)  #=> false
+        #
+        def multi_line_tag?(name)
           MULTI_LINE_TAGS.include?(name.to_s)
         end
-        # Returns a '>' or ' />' string based on the output format used, ie: HTML vs XHTML
-        def xhtml?
+        # Returns a string for closing self-closing tags based on HTML/XHTML format setting
+        #
+        # @return [String] Returns ' />' for XHTML format, '>' for HTML format
+        #
+        # @example With XHTML format
+        #   # When tag_output_format_is_xhtml is true
+        #   xhtml?  #=> ' />'
+        #
+        # @example With HTML format
+        #   # When tag_output_format_is_xhtml is false
+        #   xhtml?  #=> '>'
+        #
+        def xhtml?
           opts[:tags][:tag_output_format_is_xhtml] ? ' />' : '>'
         end
-        alias_method :is_xhtml?, :xhtml?
-        #
-        def add_newline?(add_override = nil)
-          add = (add_override.nil?) ? opts[:tags][:tag_add_newlines_after_tags] : add_override
+        alias is_xhtml? xhtml?
+        # Determines whether to add a newline based on override flag or default configuration
+        #
+        # @param add_override [Boolean, nil] Optional flag to override default newline behavior
+        #   - When nil: Uses configured :tag_add_newlines_after_tags setting
+        #   - When true/false: Uses override value directly
+        #
+        # @return [String] Returns "\n" for true, empty string for false
+        #
+        # @example Using default configuration
+        #   add_newline?  #=> "\n" # When tag_add_newlines_after_tags is true
+        #
+        # @example With override
+        #   add_newline?(false)  #=> "" # Forces no newline
+        #
+        def add_newline?(add_override = nil)
+          add = add_override.nil? ? opts[:tags][:tag_add_newlines_after_tags] : add_override
           add == true ? "\n" : ''
         end
-        # concat contents to the buffer if present
-        #
-        # ==== Examples
-        #
-        #   buffer_concat("Direct to buffer")
-        #
+        # Appends text to the ERB output buffer if one exists
+        #
+        # @param txt [String] The text to append to the buffer
+        #
+        # @return [String, nil] The appended text if buffer exists, nil otherwise
+        #
+        # @example With active buffer
+        #   buffer_concat("Hello")  #=> "Hello" # Added to @_out_buf
+        #
+        # @example With no buffer
+        #   buffer_concat("Hello")  #=> nil # No buffer to append to
+        #
         def buffer_concat(txt)
           @_out_buf << txt if buffer?
         end
-        alias_method :erb_concat, :buffer_concat
-        # Used to capture the contents of html/ERB block
-        #
-        # ==== Examples
-        #
-        #   capture_block(&block) => '...html...'
-        #
-        def capture_block(*args, &block)
-          with_output_buffer { block_given? && block.call(*args) }
+        alias erb_concat buffer_concat
+        # Captures the contents of a given block by executing it with a temporary output buffer
+        #
+        # @param args [Array] Arguments to pass through to the yielded block
+        # @yield [*args] The block to capture contents from
+        #
+        # @return [String] The captured contents of the block, or nil if no block given
+        #
+        # @example Basic capture
+        #   capture_block { "<div>content</div>" }
+        #     #=> "<div>content</div>"
+        #
+        # @example With arguments
+        #   capture_block("arg1", "arg2") { |a,b| "#{a} #{b}" }
+        #     #=> "arg1 arg2"
+        #
+        def capture_block(*args)
+          with_output_buffer { block_given? && yield(*args) }
         end
-        alias_method :capture_erb, :capture_block
-        # Used to direct the buffer for the erb capture
+        alias capture_erb capture_block
+        # Temporarily swaps the output buffer with a new one during block execution
+        #
+        # @param buf [String] The new buffer to use temporarily, defaults to empty string
+        # @yield The block to execute with the temporary buffer
+        #
+        # @return [String] The contents of the temporary buffer after block execution
+        #
+        # @example Using temporary buffer
+        #   with_output_buffer { @_out_buf << "content" }  #=> "content"
+        #
+        # @example Restoring original buffer
+        #   old_buf = @_out_buf
+        #   with_output_buffer { "content" }
+        #   @_out_buf == old_buf #=> true
+        #
         def with_output_buffer(buf = '')
-          @_out_buf, old_buffer = buf, @_out_buf
+          old_buffer = @_out_buf
+          @_out_buf = buf
           yield
           @_out_buf
         ensure
           @_out_buf = old_buffer
         end
-        alias_method :erb_with_output_buffer, :with_output_buffer
+        alias erb_with_output_buffer with_output_buffer
-        # returns true if the buffer is not empty
-        def buffer?
+        # Checks if an output buffer exists for template rendering
+        #
+        # @return [Boolean] true if @_out_buf is not nil, false otherwise
+        #
+        # @example With active buffer
+        #   buffer?  #=> true # when @_out_buf exists
+        #
+        # @example With no buffer
+        #   buffer?  #=> false # when @_out_buf is nil
+        #
+        def buffer?
           !@_out_buf.nil?
         end
-        alias_method :have_buffer?, :buffer?
-        alias_method :erb_buffer?,  :buffer?
+        alias have_buffer? buffer?
+        alias erb_buffer? buffer?
+        # Checks if the given block is from an ERB template
+        #
+        # @param block [Proc] The block to check
+        #
+        # @return [Boolean] true if block is from ERB template or buffer exists, false otherwise
+        #
+        # @example With ERB template block
+        #   erb_block?(erb_block)  #=> true
+        #
+        # @example With regular block
+        #   erb_block?(regular_block)  #=> false
         #
         def erb_block?(block)
-          have_buffer? || block && eval('defined? __in_erb_template', block.binding)
+          have_buffer? ||
+            (block && eval('defined? __in_erb_template', block.binding, __FILE__, __LINE__ - 1))
         end
-        alias_method :is_erb_block?, :erb_block?
-        alias_method :is_erb_template?, :erb_block?
-      end # /InstanceMethods
-    end # /RodaTags
+        alias is_erb_block? erb_block?
+        alias is_erb_template? erb_block?
+        # Checks if the given block is from a HAML template
+        #
+        # @param block [Proc] The block to check
+        #
+        # @return [Boolean] true if block is from HAML template, false otherwise
+        #
+        # @example With HAML template block
+        #   haml_block?(haml_block)  #=> true
+        #
+        # @example With regular block
+        #   haml_block?(regular_block)  #=> false
+        #
+        def haml_block?(block)
+          block && eval('defined? _hamlout', block.binding, __FILE__, __LINE__ - 1)
+        end
+        alias is_haml_block? haml_block?
+        alias is_haml_template? haml_block?
+      end
+      # rubocop:enable Metrics/ModuleLength
+      # /InstanceMethods
+    end
+    # /RodaTags
     register_plugin(:tags, RodaTags)
-  end # /RodaPlugins
+  end
+  # /RodaPlugins
 end