html_tags 0.1.183

data/lib/html_tags/individual_tags/a.rb

@@ -0,0 +1,646 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'html_tags/individual_tags/a.rb'
+# =========================================================================== #
+module HtmlTags
+
+  require 'html_tags/closing_tag/closing_tag.rb'
+  require 'html_tags/toplevel_methods/add.rb'
+
+  # ========================================================================= #
+  # === HtmlTags.a                                                    (a tag)
+  #
+  # This tag will attempt to create a HTML link. It follows all other
+  # conventions as well. The first argument called `i` is the target
+  # URL to use.
+  #
+  # In plain HTML, this would be create a string such as the following one:
+  #
+  #   <a href="url">Test</a> 
+  #
+  # The first argument `i` is the hyperref-target.
+  #
+  # Usage examples:
+  #
+  #   a('connect')
+  #   a('connect', :make_newline)
+  #   a('connect', 'marl1em','great_link','color: blue')
+  #   a('LINUX_DESIGNING.cgi', :copy_description)
+  #   a('https://de.wikipedia.org/wiki/Lampensockel#Edisonsockel', 'SELF', :make_newline)
+  #   a('local_ruby_c', description: 'Ruby C Seite', css_style: 'margin-left: 2em')
+  #   a(
+  #     remote_url: remote_url,
+  #     text: title?.to_s,
+  #     css_style: 'font-weight: bold; color: darkblue'
+  #   )
+  #   HtmlTags.a('https://en.wikipedia.org/wiki/Gramicidin', { :remote_URL=>'gramicidin' })
+  #   HtmlTags.a('https://en.wikipedia.org/wiki/Gramicidin', { remote_URL: 'gramicidin', open_new_tab: true })
+  #
+  # ========================================================================= #
+  def self.a(
+      hyperref_target  = '',
+      link_description = :use_hyperref_as_the_target,
+      css_class        = '',
+      the_id           = '',
+      css_style        = '',
+      javascript       = ''
+    )
+    # ======================================================================= #
+    # The following Hash can be used to store data into, such as :tooltip.
+    # ======================================================================= #
+    internal_hash = {}
+    title = nil
+    # ======================================================================= #
+    # The next variable determines whether we will use target="_blank" or
+    # whether we will not.
+    # ======================================================================= #
+    target_is_blank = false
+    # ======================================================================= #
+    # Store the generated String in the local variable called result.
+    # ======================================================================= #
+    result = ''.dup
+    # ======================================================================= #
+    # If make_newline is set to true then we will append a <br> tag.
+    # ======================================================================= #
+    make_newline = false
+    close_me = close(__method__) # Default. Must come before case css_class.
+    # ======================================================================= #
+    # Since as of December 2015 we will check whether we have passed an
+    # Array.
+    #
+    # This may look like that way:
+    #
+    #   ["https://de.wikipedia.org/wiki/Lampensockel#Edisonsockel",
+    #   {:content=>"SELF", :css_class=>"mars2em"}]
+    #
+    # or
+    #
+    #   ["http://geizhals.at/philips-voice-tracer-dvt3600-digitales-diktiergeraet-a992644.html?hloc=at", "SELF", 1]
+    #
+    # So we have to stay flexible here.
+    # ======================================================================= #
+    if hyperref_target.is_a? Array
+      if hyperref_target.size > 1
+        hash = hyperref_target[1] # This may not have to be a Hash, though.
+        if hash.is_a? Hash
+          link_description = hash
+          hyperref_target = hyperref_target[0]
+        elsif hash.is_a? Array
+          if hash[1]
+            link_description = hash[1]
+          end
+          if hash[2] and (hash[2] == 1)
+            make_newline = true
+          end
+          # ================================================================= #
+          # Finally, assign the first entry to hyperref_target.
+          # ================================================================= #
+          hyperref_target = hyperref_target.first
+        end
+      end
+      if hyperref_target.is_a? Array
+        hyperref_target = hyperref_target.first
+      end
+    end
+    case css_class
+    # ======================================================================= #
+    # === :copy_description
+    # ======================================================================= #
+    when :copy_description
+      css_class = ''
+      link_description = hyperref_target
+    # ======================================================================= #
+    # === :make_newline
+    # ======================================================================= #
+    when :make_newline
+      css_class = ''
+      close_me  = close(__method__) {{ make_newline: true  }}
+    # ======================================================================= #
+    # === :no_newline
+    # ======================================================================= #
+    when :no_newline
+      css_class = ''
+      close_me  = close(__method__) {{ make_newline: false }}
+    else # Else do not make a newline, simply pass through..
+    end
+    # ======================================================================= #
+    # === Check for hyperref_target being a Hash
+    # ======================================================================= #
+    if hyperref_target.is_a? Hash
+      # ===================================================================== #
+      # === :open_new_tab
+      # ===================================================================== #
+      if hyperref_target.has_key? :open_new_tab
+        target_is_blank = hyperref_target.delete(:open_new_tab)
+      # ===================================================================== #
+      # === :new_tab
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :new_tab
+        target_is_blank = hyperref_target.delete(:new_tab)
+      # ===================================================================== #
+      # === :open_in_new_tab
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :open_in_new_tab
+        target_is_blank = hyperref_target.delete(:open_in_new_tab)
+      # ===================================================================== #
+      # === :open_in_a_new_tab
+      #
+      # This is an "alias" to the above entry point.
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :open_in_a_new_tab
+        target_is_blank = hyperref_target.delete(:open_in_a_new_tab)
+      # ===================================================================== #
+      # === :new_tab
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :new_tab
+        target_is_blank = hyperref_target.delete(:new_tab)
+      # ===================================================================== #
+      # === :open_new_tab
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :open_new_tab
+        target_is_blank = hyperref_target.delete(:open_new_tab)
+      end
+      # ===================================================================== #
+      # === :link_description
+      # ===================================================================== #
+      if hyperref_target.has_key? :link_description
+        link_description = hyperref_target.delete(:link_description)
+      # ===================================================================== #
+      # === :description
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :description
+        link_description = hyperref_target.delete(:description)
+      end
+      # ===================================================================== #
+      # === :id
+      # ===================================================================== #
+      if hyperref_target.has_key? :id
+        the_id = hyperref_target.delete(:id)
+      # ===================================================================== #
+      # === :the_id
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :the_id
+        the_id = hyperref_target.delete(:the_id)
+      end
+      # ===================================================================== #
+      # === :make_newline
+      # ===================================================================== #
+      if hyperref_target.has_key? :make_newline
+        make_newline = hyperref_target.delete(:make_newline)
+      # ===================================================================== #
+      # === :linebreak
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :linebreak
+        make_newline = hyperref_target.delete(:linebreak)
+      end
+      # ===================================================================== #
+      # === :css_class
+      #
+      # Handle :css_class early on, as it is a very unproblematic entry.
+      # ===================================================================== #
+      if hyperref_target.has_key? :css_class
+        css_class = hyperref_target.delete(:css_class)
+      end
+      # ===================================================================== #
+      # === :css_style
+      #
+      # This entry point allows us to handle css-styles for a given
+      # HTML tag.
+      # ===================================================================== #
+      if hyperref_target.has_key? :css_style
+        css_style = hyperref_target.delete(:css_style)
+      end
+      # ===================================================================== #
+      # === :content
+      #
+      # Rewrite :content to the more correctly named :link_description.
+      # ===================================================================== #
+      if hyperref_target.has_key? :content
+        link_description = hyperref_target.delete(:content)
+      # ===================================================================== #
+      # === :text
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :text
+        link_description = hyperref_target.delete(:text)
+      end
+      # ===================================================================== #
+      # === :link_description
+      #
+      # This entry point ought to come last.
+      # ===================================================================== #
+      if hyperref_target.has_key?(:link_description) and
+        (hyperref_target[:link_description] == 'SELF')
+        link_description = hyperref_target.delete(:link_description)
+      end
+      # ===================================================================== #
+      # The next four checks should come last, since they will modify
+      # hyperref_target.
+      # ===================================================================== #
+      # ===================================================================== #
+      # === :remote_url
+      # ===================================================================== #
+      if hyperref_target.has_key? :remote_url
+        hyperref_target = hyperref_target.delete(:remote_url)
+      # ===================================================================== #
+      # === :remote_URL
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :remote_URL
+        hyperref_target = hyperref_target.delete(:remote_URL)
+      # ===================================================================== #
+      # === :href
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :href
+        hyperref_target = hyperref_target.delete(:href)
+      # ===================================================================== #
+      # === :href_target
+      # ===================================================================== #
+      elsif hyperref_target.has_key? :href_target
+        hyperref_target = hyperref_target.delete(:href_target)
+      end if hyperref_target.is_a?(Hash)
+    end
+    # ======================================================================= #
+    # === Intercept Hash for the link_description variable
+    #
+    # The hash can contain entries such as linebreak: true, but also
+    # entries such as content: :self.
+    # ======================================================================= #
+    if link_description.is_a? Hash
+      # ===================================================================== #
+      # === :remote_url
+      # ===================================================================== #
+      if link_description.has_key? :remote_url
+        hyperref_target = link_description.delete(:remote_url)
+      # ===================================================================== #
+      # === :remote_URL
+      # ===================================================================== #
+      elsif link_description.has_key? :remote_URL
+        hyperref_target = link_description.delete(:remote_URL)
+      end
+      # ===================================================================== #
+      # === :tooltip
+      # ===================================================================== #
+      if link_description.has_key? :tooltip
+        internal_hash[:tooltip] = link_description.delete(:tooltip)
+      end
+      # ===================================================================== #
+      # === :onclick
+      #
+      # This may look like so:
+      #
+      #   onclick: 'change_the_colour_to()'
+      #
+      # ===================================================================== #
+      if link_description.has_key? :onclick
+        javascript = ' onclick="'+link_description.delete(:onclick)+'"'
+      end
+      # ===================================================================== #
+      # === :css_style
+      # ===================================================================== #
+      if link_description.has_key? :css_style
+        css_style = link_description.delete(:css_style)
+      end
+      # ===================================================================== #
+      # === :id
+      # ===================================================================== #
+      if link_description.has_key? :id
+        the_id = link_description.delete(:id)
+      # ===================================================================== #
+      # === :the_id
+      # ===================================================================== #
+      elsif link_description.has_key? :the_id
+        the_id = link_description.delete(:the_id)
+      end
+      # ===================================================================== #
+      # === :open_new_tab
+      # ===================================================================== #
+      if link_description.has_key? :open_new_tab
+        target_is_blank = link_description.delete(:open_new_tab)
+      # ===================================================================== #
+      # === :open_in_new_tab
+      # ===================================================================== #
+      elsif link_description.has_key? :open_in_new_tab
+        target_is_blank = link_description.delete(:open_in_new_tab)
+      # ===================================================================== #
+      # === :open_in_a_new_tab
+      #
+      # This is an "alias" to the above entry point.
+      # ===================================================================== #
+      elsif link_description.has_key? :open_in_a_new_tab
+        target_is_blank = link_description.delete(:open_in_a_new_tab)
+      # ===================================================================== #
+      # === :new_tab
+      # ===================================================================== #
+      elsif link_description.has_key? :new_tab
+        target_is_blank = link_description.delete(:new_tab)
+      # ===================================================================== #
+      # === :open_new_tab
+      # ===================================================================== #
+      elsif link_description.has_key? :open_new_tab
+        target_is_blank = link_description.delete(:open_new_tab)
+      end
+      # ===================================================================== #
+      # === css_class
+      # ===================================================================== #
+      if link_description.has_key? :css_class
+        css_class = link_description.delete(:css_class)
+      end
+      # ===================================================================== #
+      # === :css_style
+      # ===================================================================== #
+      if link_description.has_key? :css_style
+        css_style = link_description.delete(:css_style)
+      end
+      # ===================================================================== #
+      # === :title
+      #
+      # Support the :title attribute here.
+      #
+      # The :title attribute is to enable a short tooltip, on our
+      # <a> tag.
+      # ===================================================================== #
+      if link_description.has_key? :title
+        title = link_description.delete(:title)
+      end
+      # ===================================================================== #
+      # Rewrite :link_description into :description.
+      # ===================================================================== #
+      if link_description.has_key? :description
+        link_description = link_description.delete(:description)
+      # ===================================================================== #
+      # Rewrite :link_description into :text.
+      # ===================================================================== #
+      elsif link_description.has_key? :text
+        link_description = link_description.delete(:text)
+      # ===================================================================== #
+      # ==== :content
+      # ===================================================================== #
+      elsif link_description.has_key? :content
+        link_description = link_description.delete(:content)
+      # ===================================================================== #
+      # Rewrite :link_description into :link_description.
+      # ===================================================================== #
+      elsif link_description.has_key? :link_description
+        link_description = link_description.delete(:link_description)
+      # ===================================================================== #
+      # === :content
+      #
+      # Rewrite :content into :link_description.
+      #
+      # This entry point is for input such as:
+      #
+      #   a('http://rubyreports.org/', content: '<b>Link</b>')
+      #
+      # ===================================================================== #
+      elsif link_description.has_key? :content
+        link_description = link_description.delete(:content).to_s
+        hyperref_target = hyperref_target.to_s.dup
+        if link_description and link_description.start_with?('→ ')
+          hyperref_target.sub!(/^→ /,'')
+        end
+        # =================================================================== #
+        # Next, we must both check for 'SELF' 'self', second variant
+        # could also be the Symbol :self.
+        # =================================================================== #
+        if link_description.include?('SELF') or (link_description.to_s == 'self')
+          if link_description.frozen?
+            link_description = link_description.dup
+          end
+          # ================================================================= #
+          # Must replace it with the proper target next.
+          # ================================================================= #
+          link_description = link_description.to_s.sub( # Ensure we have a String.
+            /^SELF/i, hyperref_target
+          )
+        end
+      else
+        # =================================================================== #
+        # We don't have a link_description entry, so we will simply use
+        # the value from hyperref_target..
+        # =================================================================== #
+        if link_description.is_a?(Hash) and link_description.empty?
+          link_description = hyperref_target.to_s.dup
+        end
+      end
+    end
+    if link_description.empty?
+      link_description = hyperref_target # This simulates "abr_self".
+    end
+    # ======================================================================= #
+    # Work on link_description next, assuming it is a String at this point.
+    # ======================================================================= #
+    case link_description.to_s
+    when /^→ / # If it starts with a right-arrow.
+      if link_description.to_s == :self
+        link_description = hyperref_target.dup.sub(/^→ /,'')
+      end
+    when /^SELF$/i
+      link_description = link_description.dup if link_description.frozen?
+      link_description = link_description.to_s.sub!(
+        /^SELF/i, hyperref_target.dup # .sub(/^→ /,'')
+      )
+    end
+    case hyperref_target
+    # Remove leading right-arrows.
+    when /^→ /
+      hyperref_target = hyperref_target.dup if hyperref_target.frozen?
+      hyperref_target.sub!(/^→ /,'')
+    end
+    # ======================================================================= #
+    # === :make_newline is treated in a special manner, as the id.
+    #     Same for the number 1, which stands for newline too, due
+    #     to historic reasons.
+    # ======================================================================= #
+    case the_id
+    when :make_newline, 1
+      make_newline = true
+      the_id = '' # Reset it here in this case.
+    end
+    if css_class and css_class.is_a?(String) and (css_class == 'SELF')
+      css_class = ''.dup
+    end
+    if css_class.is_a? Hash
+      # ===================================================================== #
+      # === Intercept key :css_style next, on the css_class variable
+      #
+      # This entry point is for input such as:
+      #
+      #   a(@target, css_style: 'color:red; margin-left:2em')
+      #
+      # ===================================================================== #
+      if css_class.has_key? :css_style
+        css_style = css_class.delete :css_style
+      end if css_class.is_a? Hash # Must check again due to the earlier resetting.
+      # ===================================================================== #
+      # === Intercept key :css_class next
+      # ===================================================================== #
+      if css_class.has_key? :css_class
+        # =================================================================== #
+        # Must assign to css_class variable in this case:
+        # =================================================================== #
+        css_class = css_class.delete :css_class
+      end if css_class.is_a? Hash # See above explanation.
+      # ===================================================================== #
+      # === Intercept key :url next
+      # ===================================================================== #
+      if css_class.has_key? :url
+        i = css_class.delete :url
+      end if css_class.is_a? Hash # See above explanation.
+      # ===================================================================== #
+      # === Intercept key :linebreak next
+      # ===================================================================== #
+      if css_class.has_key? :linebreak
+        i = css_class.delete :linebreak
+        close_me = close(__method__) {{ make_newline: i  }}
+      end if css_class.is_a? Hash # See above explanation.
+      if css_class.is_a?(Hash) and css_class.empty?
+        css_class = ''
+      end
+    end
+    # ======================================================================= #
+    # === Handle blocks next
+    #
+    # Append a pre-defined content to it, unless we also use a block.
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded # Intercept some Symbols.
+      when :strip
+        hyperref_target.strip!
+        close_me.strip! if close_me
+      when :only_basename
+        if hyperref_target.has_key? :link_description
+          link_description = File.basename(hyperref_target[:link_description])
+        end
+      when :smaller
+        _ = link_description
+        link_description = '<span style="font-size:smaller">'+_+'</span>'
+      else
+        # =================================================================== #
+        # Assume that it could be a HTML colour, such as :slateblue:
+        # =================================================================== #
+        if yielded.is_a? Symbol
+          begin
+            require 'colours/html/html_colours.rb'
+            if Colours.is_this_html_colour_included?(yielded)
+              if css_style.nil?
+                css_style = ''.dup
+              end
+              css_style = css_style.dup if css_style.frozen?
+              css_style << " color: #{yielded};"
+            end
+          rescue LoadError
+          end
+        end
+      end
+      hyperref_target.merge!(yielded) unless yielded.is_a? Symbol
+    end
+    # ======================================================================= #
+    # === Copy the content of hyperref_target onto link_description
+    #
+    # This should come fairly late, though.
+    # ======================================================================= #
+    case link_description
+    when :use_hyperref_as_the_target
+      link_description = hyperref_target.dup
+    end
+    # ======================================================================= #
+    # Finally we will build-up the result-String next.
+    # ======================================================================= #
+    result = '<a'.dup
+    if hyperref_target.is_a?(Hash) and hyperref_target.empty? and
+      !link_description.empty?
+      hyperref_target = link_description.dup
+    end
+    hyperref_target = hyperref_target.to_s
+    result << ' href="'+hyperref_target+'"'
+    if css_class and !css_class.to_s.empty?
+      result << ' class="'+css_class.to_s+'"'
+    end
+    if the_id and !the_id.empty?
+      result << ' id="'+the_id.to_s+'"'
+    end
+    if css_style and !css_style.empty?
+      result << ' style="'+css_style.to_s+'"'
+    end
+    if javascript and !javascript.empty?
+      # The next lines exist to use "onclick" javascript directly.
+      unless javascript.lstrip.start_with? 'onclick'
+        result << ' javascript="'
+      end
+      result << javascript
+      unless javascript.lstrip.start_with? 'onclick'
+        result << '"'
+      end
+    end
+    # ======================================================================= #
+    # === Handle tooltips next, via data-tip
+    # ======================================================================= #
+    if internal_hash.is_a?(Hash) and internal_hash.has_key?(:tooltip)
+      result << " data-tip=\"#{internal_hash[:tooltip]}\""
+    end
+    if target_is_blank
+      result << ' target="_blank"'
+    end
+    if title
+      result << ' title="'+title.to_s+'"'
+    end
+    result << '>' # Close that tag here.
+    # result << N
+    result << link_description.to_s # Could be a Symbol after all.
+    result << close_me
+    if make_newline
+      result << '<br>'
+    end
+    # ======================================================================= #
+    # Must add it onto the main String too.
+    # ======================================================================= #
+    return HtmlTags.add(result)
+  end; self.instance_eval { alias slink a } # === HtmlTags.slink
+       self.instance_eval { alias link  a } # === HtmlTags.link
+
+  # ========================================================================= #
+  # === a
+  #
+  # Wrapper towards HtmlTags.a().
+  # ========================================================================= #
+  def a(
+      hyperref_target  = '',
+      link_description = :use_hyperref_as_the_target,
+      css_class        = '',
+      the_id           = '',
+      css_style        = '',
+      javascript       = '',
+      &block
+    )
+    HtmlTags.a(
+      hyperref_target,
+      link_description,
+      css_class,
+      the_id,
+      css_style,
+      javascript,
+      &block
+    )
+  end; alias slink a # === slink
+       alias link  a # === link
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  e HtmlTags.a(
+    'https://geizhals.at/diverse-cr2032-knopfzelle-a134716.html',
+    css_style: 'margin-left: 4em',
+    # The title attribute on an <a> tag adds a tooltip with title
+    # text to the anchor tag.
+    title:     'This is a tooltip.'
+  )
+  e
+  e HtmlTags.a(
+    'https://foobar.com',
+     css_style: 'font-size: 1.1em;',
+     description: 'https://foobar com'
+  )
+end

data/lib/html_tags/individual_tags/abbr.rb

@@ -0,0 +1,44 @@
+# =========================================================================== #
+# Documentation for the <abbr> tag can be found here:
+#   http://www.w3schools.com/tags/tag_abbr.asp
+# =========================================================================== #
+module HtmlTags
+
+  # ========================================================================= #
+  # === HtmlTags.abbr
+  #
+  # To test this method, try:
+  #
+  #   HtmlTags.abbr 'WHO','World Health Organization'
+  # ========================================================================= #
+  def self.abbr(abbreviation_to_use = '', long_name = '')
+    if long_name.empty? and !abbreviation_to_use.empty?
+      # ===================================================================== #
+      # In this case, we simply copy to the long name.
+      # ===================================================================== #
+      long_name = abbreviation_to_use.to_s.dup
+    end
+    if block_given?
+      return HtmlTags.add(
+        opening_tag(__method__, title: long_name.to_s)+
+        abbreviation_to_use+
+        yield+
+        close(__method__)
+      )
+    else
+      return HtmlTags.add(
+        opening_tag(__method__, title: long_name.to_s)+
+        abbreviation_to_use+
+        close(__method__)
+      )
+    end
+  end
+
+  # ========================================================================= #
+  # === abbr
+  # ========================================================================= #
+  def abbr(abbreviation_to_use = '', long_name = '')
+    HtmlTags.abbr(abbreviation_to_use, long_name)
+  end
+
+end