hanami-utils 0.0.0 → 0.7.0

data/lib/hanami/utils/class.rb

@@ -0,0 +1,94 @@
+require 'hanami/utils/string'
+
+module Hanami
+  module Utils
+    # Class utilities
+    # @since 0.1.0
+    class Class
+      # Loads a class for the given name.
+      #
+      # @param name [String, Class] the specific class name
+      # @param namespace [Class, Module] the Ruby namespace where we want to perform the lookup.
+      # @return [Class, Module] the found Ruby constant.
+      #
+      # @raise [NameError] if no constant can be found.
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'hanami/utils/class'
+      #
+      #   module App
+      #     module Service
+      #       class Endpoint
+      #       end
+      #     end
+      #
+      #     class ServiceEndpoint
+      #     end
+      #   end
+      #
+      #   # basic usage
+      #   Hanami::Utils::Class.load!('App::Service') # => App::Service
+      #   Hanami::Utils::Class.load!(App::Service)   # => App::Service
+      #
+      #   # with explicit namespace
+      #   Hanami::Utils::Class.load!('Service', App) # => App::Service
+      #
+      #   # with missing constant
+      #   Hanami::Utils::Class.load!('Unknown') # => raises NameError
+      def self.load!(name, namespace = Object)
+        namespace.const_get(name.to_s)
+      end
+
+      # Loads a class from the given pattern name and namespace
+      #
+      # @param pattern [String] the class name pattern
+      # @param namespace [Class, Module] the Ruby namespace where we want to perform the lookup.
+      # @return [Class, Module] the found Ruby constant.
+      #
+      # @raise [NameError] if no constant can be found.
+      #
+      # @since 0.3.1
+      #
+      # @see Hanami::Utils::String#tokenize
+      #
+      # @example
+      #   require 'hanami/utils/class'
+      #
+      #   module App
+      #     module Service
+      #       class Endpoint
+      #       end
+      #     end
+      #
+      #     class ServiceEndpoint
+      #     end
+      #   end
+      #
+      #   # basic usage
+      #   Hanami::Utils::Class.load_from_pattern!('App::Service') # => App::Service
+      #
+      #   # with explicit namespace
+      #   Hanami::Utils::Class.load_from_pattern!('Service', App) # => App::Service
+      #
+      #   # with pattern
+      #   Hanami::Utils::Class.load_from_pattern!('App::Service(::Endpoint|Endpoint)') # => App::Service::Endpoint
+      #   Hanami::Utils::Class.load_from_pattern!('App::Service(Endpoint|::Endpoint)') # => App::ServiceEndpoint
+      #
+      #   # with missing constant
+      #   Hanami::Utils::Class.load_from_pattern!('Unknown') # => raises NameError
+      def self.load_from_pattern!(pattern, namespace = Object)
+        String.new(pattern).tokenize do |token|
+          begin
+            return namespace.const_get(token)
+          rescue NameError
+          end
+        end
+
+        full_name = [ (namespace == Object ? nil : namespace), pattern ].compact.join('::')
+        raise NameError.new("uninitialized constant #{ full_name }")
+      end
+    end
+  end
+end

data/lib/hanami/utils/class_attribute.rb

@@ -0,0 +1,95 @@
+require 'set'
+require 'hanami/utils/duplicable'
+
+module Hanami
+  module Utils
+    # Inheritable class level variable accessors.
+    # @since 0.1.0
+    #
+    # @see Hanami::Utils::ClassAttribute::ClassMethods
+    module ClassAttribute
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Defines a class level accessor for the given attribute(s).
+        #
+        # A value set for a superclass is automatically available by their
+        # subclasses, unless a different value is explicitely set within the
+        # inheritance chain.
+        #
+        # @param attributes [Array<Symbol>] a single or multiple attribute name(s)
+        #
+        # @return [void]
+        #
+        # @since 0.1.0
+        #
+        # @example
+        #   require 'hanami/utils/class_attribute'
+        #
+        #   class Vehicle
+        #     include Hanami::Utils::ClassAttribute
+        #     class_attribute :engines, :wheels
+        #
+        #     self.engines = 0
+        #     self.wheels  = 0
+        #   end
+        #
+        #   class Car < Vehicle
+        #     self.engines = 1
+        #     self.wheels  = 4
+        #   end
+        #
+        #   class Airplane < Vehicle
+        #     self.engines = 4
+        #     self.wheels  = 16
+        #   end
+        #
+        #   class SmallAirplane < Airplane
+        #     self.engines = 2
+        #     self.wheels  = 8
+        #   end
+        #
+        #   Vehicle.engines # => 0
+        #   Vehicle.wheels  # => 0
+        #
+        #   Car.engines # => 1
+        #   Car.wheels  # => 4
+        #
+        #   Airplane.engines # => 4
+        #   Airplane.wheels  # => 16
+        #
+        #   SmallAirplane.engines # => 2
+        #   SmallAirplane.wheels  # => 8
+        def class_attribute(*attributes)
+          singleton_class.class_eval do
+            attr_accessor *attributes
+          end
+
+          class_attributes.merge(attributes)
+        end
+
+        protected
+        # @see Class#inherited
+        def inherited(subclass)
+          class_attributes.each do |attr|
+            value = send(attr)
+            value = Duplicable.dup(value)
+            subclass.class_attribute attr
+            subclass.send("#{attr}=", value)
+          end
+
+          super
+        end
+
+        private
+        # Class accessor for class attributes.
+        # @private
+        def class_attributes
+          @class_attributes ||= Set.new
+        end
+      end
+    end
+  end
+end

data/lib/hanami/utils/deprecation.rb

@@ -0,0 +1,70 @@
+require 'hanami/utils'
+
+module Hanami
+  module Utils
+    # Prints a deprecation warning when initialized
+    #
+    # @since 0.3.1
+    class Deprecation
+      # Initialize a deprecation message and prints it to standard error.
+      #
+      # @param message [#to_s] a deprecation message
+      #
+      # @since 0.3.1
+      #
+      # @example Direct usage
+      #   require 'hanami/utils/deprecation'
+      #
+      #   class Engine
+      #     def old_method
+      #       Hanami::Utils::Deprecation.new('old_method is deprecated, please use new_method')
+      #       new_method
+      #     end
+      #
+      #     def new_method
+      #       puts 'started'
+      #     end
+      #   end
+      #
+      #   Engine.new.old_method
+      #     # => old_method is deprecated, please use new_method - called from: test.rb:14:in `<main>'.
+      #     # => started
+      #
+      # @example Indirect usage
+      #   require 'hanami/utils/deprecation'
+      #
+      #   class Engine
+      #     def old_method
+      #       Hanami::Utils::Deprecation.new('old_method is deprecated, please use new_method')
+      #       new_method
+      #     end
+      #
+      #     def new_method
+      #       puts 'started'
+      #     end
+      #   end
+      #
+      #   class Car
+      #     def initialize
+      #       @engine = Engine.new
+      #     end
+      #
+      #     def start
+      #       @engine.old_method
+      #     end
+      #   end
+      #
+      #   Car.new.start
+      #     # => old_method is deprecated, please use new_method - called from: test.rb:20:in `start'.
+      #     # => started
+      def initialize(message)
+        ::Kernel.warn("#{ message } - called from: #{ caller[caller_index] }.")
+      end
+
+      private
+      def caller_index
+        Utils.jruby? || Utils.rubinius? ? 1 : 2
+      end
+    end
+  end
+end

data/lib/hanami/utils/duplicable.rb

@@ -0,0 +1,80 @@
+module Hanami
+  module Utils
+    # Safe dup logic
+    #
+    # @since 0.6.0
+    module Duplicable
+      # Duplicates the given value.
+      #
+      # It accepts a block to customize the logic.
+      #
+      # The following types aren't duped:
+      #
+      #   * <tt>NilClass</tt>
+      #   * <tt>FalseClass</tt>
+      #   * <tt>TrueClass</tt>
+      #   * <tt>Symbol</tt>
+      #   * <tt>Numeric</tt>
+      #
+      # All the other types are duped via <tt>#dup</tt>
+      #
+      # @param value [Object] the value to duplicate
+      # @param blk [Proc] the optional block to customize the logic
+      #
+      # @return [Object] the duped value
+      #
+      # @since 0.6.0
+      #
+      # @example Basic Usage With Types That Can't Be Duped
+      #   require 'hanami/utils/duplicable'
+      #
+      #   object = 23
+      #   puts object.object_id # => 47
+      #
+      #   result = Hanami::Utils::Duplicable.dup(object)
+      #
+      #   puts result           # => 23
+      #   puts result.object_id # => 47 - Same object, because numbers can't be duped
+      #
+      # @example Basic Usage With Types That Can Be Duped
+      #   require 'hanami/utils/duplicable'
+      #
+      #   object = "hello"
+      #   puts object.object_id # => 70172661782360
+      #
+      #   result = Hanami::Utils::Duplicable.dup(object)
+      #
+      #   puts result           # => "hello"
+      #   puts result.object_id # => 70172671467020 – Different object
+      #
+      # @example Custom Logic
+      #   require 'hanami/utils/duplicable'
+      #   require 'hanami/utils/hash'
+      #
+      #   hash = { a: 1 }
+      #   puts hash.object_id # => 70207105061680
+      #
+      #   result = Hanami::Utils::Duplicable.dup(hash) do |value|
+      #     case value
+      #     when Hanami::Utils::Hash
+      #       value.deep_dup
+      #     when ::Hash
+      #       Hanami::Utils::Hash.new(value).deep_dup.to_h
+      #     end
+      #   end
+      #
+      #   puts result           # => "{:a=>1}"
+      #   puts result.object_id # => 70207105185500 – Different object
+      def self.dup(value, &blk)
+        case value
+        when NilClass, FalseClass, TrueClass, Symbol, Numeric
+          value
+        when v = blk && blk.call(value)
+          v
+        else
+          value.dup
+        end
+      end
+    end
+  end
+end

data/lib/hanami/utils/escape.rb

@@ -0,0 +1,577 @@
+module Hanami
+  module Utils
+    # HTML escape utilities
+    #
+    # Based on OWASP research and OWASP ESAPI code
+    #
+    # @since 0.4.0
+    #
+    # @see https://www.owasp.org
+    # @see https://www.owasp.org/index.php/Cross-site_Scripting_%28XSS%29
+    # @see https://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet
+    # @see https://www.owasp.org/index.php/ESAPI
+    # @see https://github.com/ESAPI/esapi-java-legacy
+    module Escape
+      # Hex base for base 10 integer conversion
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/core/Fixnum.html#method-i-to_s
+      HEX_BASE           = 16
+
+      # Limit for non printable chars
+      #
+      # @since 0.4.0
+      # @api private
+      LOW_HEX_CODE_LIMIT = 0xff
+
+      # Replacement hex for non printable characters
+      #
+      # @since 0.4.0
+      # @api private
+      REPLACEMENT_HEX  = "fffd".freeze
+
+      # Low hex codes lookup table
+      #
+      # @since 0.4.0
+      # @api private
+      HEX_CODES = (0..255).each_with_object({}) do |c, codes|
+        if (c >= 0x30 && c <= 0x39) || (c >= 0x41 && c <= 0x5A) || (c >= 0x61 && c <= 0x7A)
+          codes[c] = nil
+        else
+          codes[c] = c.to_s(HEX_BASE)
+        end
+      end.freeze
+
+      # Non printable chars
+      #
+      # This is a Hash instead of a Set, to make lookup faster.
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see https://gist.github.com/jodosha/ac5dd54416de744b9600
+      NON_PRINTABLE_CHARS = {
+        0x0  => true, 0x1  => true, 0x2  => true, 0x3  => true, 0x4  => true,
+        0x5  => true, 0x6  => true, 0x7  => true, 0x8  => true, 0x11 => true,
+        0x12 => true, 0x14 => true, 0x15 => true, 0x16 => true, 0x17 => true,
+        0x18 => true, 0x19 => true, 0x1a => true, 0x1b => true, 0x1c => true,
+        0x1d => true, 0x1e => true, 0x1f => true, 0x7f => true, 0x80 => true,
+        0x81 => true, 0x82 => true, 0x83 => true, 0x84 => true, 0x85 => true,
+        0x86 => true, 0x87 => true, 0x88 => true, 0x89 => true, 0x8a => true,
+        0x8b => true, 0x8c => true, 0x8d => true, 0x8e => true, 0x8f => true,
+        0x90 => true, 0x91 => true, 0x92 => true, 0x93 => true, 0x94 => true,
+        0x95 => true, 0x96 => true, 0x97 => true, 0x98 => true, 0x99 => true,
+        0x9a => true, 0x9b => true, 0x9c => true, 0x9d => true, 0x9e => true,
+        0x9f => true
+      }.freeze
+
+      # Lookup table for HTML escape
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see Hanami::Utils::Escape.html
+      HTML_CHARS = {
+        '&' => '&amp;',
+        '<' => '&lt;',
+        '>' => '&gt;',
+        '"' => '&quot;',
+        "'" => '&apos;',
+        '/' => '&#x2F;'
+      }.freeze
+
+      # Lookup table for safe chars for HTML attributes.
+      #
+      # This is a Hash instead of a Set, to make lookup faster.
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see Lookup::Utils::Escape.html_attribute
+      # @see https://gist.github.com/jodosha/ac5dd54416de744b9600
+      HTML_ATTRIBUTE_SAFE_CHARS = {
+        ',' => true, '.' => true, '-' => true, '_' => true
+      }.freeze
+
+      # Lookup table for HTML attribute escape
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see Hanami::Utils::Escape.html_attribute
+      HTML_ENTITIES = {
+        34   => 'quot',     # quotation mark
+        38   => 'amp',      # ampersand
+        60   => 'lt',       # less-than sign
+        62   => 'gt',       # greater-than sign
+        160  => 'nbsp',     # no-break space
+        161  => 'iexcl',    # inverted exclamation mark
+        162  => 'cent',     # cent sign
+        163  => 'pound',    # pound sign
+        164  => 'curren',   # currency sign
+        165  => 'yen',      # yen sign
+        166  => 'brvbar',   # broken bar
+        167  => 'sect',     # section sign
+        168  => 'uml',      # diaeresis
+        169  => 'copy',     # copyright sign
+        170  => 'ordf',     # feminine ordinal indicator
+        171  => 'laquo',    # left-pointing double angle quotation mark
+        172  => 'not',      # not sign
+        173  => 'shy',      # soft hyphen
+        174  => 'reg',      # registered sign
+        175  => 'macr',     # macron
+        176  => 'deg',      # degree sign
+        177  => 'plusmn',   # plus-minus sign
+        178  => 'sup2',     # superscript two
+        179  => 'sup3',     # superscript three
+        180  => 'acute',    # acute accent
+        181  => 'micro',    # micro sign
+        182  => 'para',     # pilcrow sign
+        183  => 'middot',   # middle dot
+        184  => 'cedil',    # cedilla
+        185  => 'sup1',     # superscript one
+        186  => 'ordm',     # masculine ordinal indicator
+        187  => 'raquo',    # right-pointing double angle quotation mark
+        188  => 'frac14',   # vulgar fraction one quarter
+        189  => 'frac12',   # vulgar fraction one half
+        190  => 'frac34',   # vulgar fraction three quarters
+        191  => 'iquest',   # inverted question mark
+        192  => 'Agrave',   # Latin capital letter a with grave
+        193  => 'Aacute',   # Latin capital letter a with acute
+        194  => 'Acirc',    # Latin capital letter a with circumflex
+        195  => 'Atilde',   # Latin capital letter a with tilde
+        196  => 'Auml',     # Latin capital letter a with diaeresis
+        197  => 'Aring',    # Latin capital letter a with ring above
+        198  => 'AElig',    # Latin capital letter ae
+        199  => 'Ccedil',   # Latin capital letter c with cedilla
+        200  => 'Egrave',   # Latin capital letter e with grave
+        201  => 'Eacute',   # Latin capital letter e with acute
+        202  => 'Ecirc',    # Latin capital letter e with circumflex
+        203  => 'Euml',     # Latin capital letter e with diaeresis
+        204  => 'Igrave',   # Latin capital letter i with grave
+        205  => 'Iacute',   # Latin capital letter i with acute
+        206  => 'Icirc',    # Latin capital letter i with circumflex
+        207  => 'Iuml',     # Latin capital letter i with diaeresis
+        208  => 'ETH',      # Latin capital letter eth
+        209  => 'Ntilde',   # Latin capital letter n with tilde
+        210  => 'Ograve',   # Latin capital letter o with grave
+        211  => 'Oacute',   # Latin capital letter o with acute
+        212  => 'Ocirc',    # Latin capital letter o with circumflex
+        213  => 'Otilde',   # Latin capital letter o with tilde
+        214  => 'Ouml',     # Latin capital letter o with diaeresis
+        215  => 'times',    # multiplication sign
+        216  => 'Oslash',   # Latin capital letter o with stroke
+        217  => 'Ugrave',   # Latin capital letter u with grave
+        218  => 'Uacute',   # Latin capital letter u with acute
+        219  => 'Ucirc',    # Latin capital letter u with circumflex
+        220  => 'Uuml',     # Latin capital letter u with diaeresis
+        221  => 'Yacute',   # Latin capital letter y with acute
+        222  => 'THORN',    # Latin capital letter thorn
+        223  => 'szlig',    # Latin small letter sharp sXCOMMAX German Eszett
+        224  => 'agrave',   # Latin small letter a with grave
+        225  => 'aacute',   # Latin small letter a with acute
+        226  => 'acirc',    # Latin small letter a with circumflex
+        227  => 'atilde',   # Latin small letter a with tilde
+        228  => 'auml',     # Latin small letter a with diaeresis
+        229  => 'aring',    # Latin small letter a with ring above
+        230  => 'aelig',    # Latin lowercase ligature ae
+        231  => 'ccedil',   # Latin small letter c with cedilla
+        232  => 'egrave',   # Latin small letter e with grave
+        233  => 'eacute',   # Latin small letter e with acute
+        234  => 'ecirc',    # Latin small letter e with circumflex
+        235  => 'euml',     # Latin small letter e with diaeresis
+        236  => 'igrave',   # Latin small letter i with grave
+        237  => 'iacute',   # Latin small letter i with acute
+        238  => 'icirc',    # Latin small letter i with circumflex
+        239  => 'iuml',     # Latin small letter i with diaeresis
+        240  => 'eth',      # Latin small letter eth
+        241  => 'ntilde',   # Latin small letter n with tilde
+        242  => 'ograve',   # Latin small letter o with grave
+        243  => 'oacute',   # Latin small letter o with acute
+        244  => 'ocirc',    # Latin small letter o with circumflex
+        245  => 'otilde',   # Latin small letter o with tilde
+        246  => 'ouml',     # Latin small letter o with diaeresis
+        247  => 'divide',   # division sign
+        248  => 'oslash',   # Latin small letter o with stroke
+        249  => 'ugrave',   # Latin small letter u with grave
+        250  => 'uacute',   # Latin small letter u with acute
+        251  => 'ucirc',    # Latin small letter u with circumflex
+        252  => 'uuml',     # Latin small letter u with diaeresis
+        253  => 'yacute',   # Latin small letter y with acute
+        254  => 'thorn',    # Latin small letter thorn
+        255  => 'yuml',     # Latin small letter y with diaeresis
+        338  => 'OElig',    # Latin capital ligature oe
+        339  => 'oelig',    # Latin small ligature oe
+        352  => 'Scaron',   # Latin capital letter s with caron
+        353  => 'scaron',   # Latin small letter s with caron
+        376  => 'Yuml',     # Latin capital letter y with diaeresis
+        402  => 'fnof',     # Latin small letter f with hook
+        710  => 'circ',     # modifier letter circumflex accent
+        732  => 'tilde',    # small tilde
+        913  => 'Alpha',    # Greek capital letter alpha
+        914  => 'Beta',     # Greek capital letter beta
+        915  => 'Gamma',    # Greek capital letter gamma
+        916  => 'Delta',    # Greek capital letter delta
+        917  => 'Epsilon',  # Greek capital letter epsilon
+        918  => 'Zeta',     # Greek capital letter zeta
+        919  => 'Eta',      # Greek capital letter eta
+        920  => 'Theta',    # Greek capital letter theta
+        921  => 'Iota',     # Greek capital letter iota
+        922  => 'Kappa',    # Greek capital letter kappa
+        923  => 'Lambda',   # Greek capital letter lambda
+        924  => 'Mu',       # Greek capital letter mu
+        925  => 'Nu',       # Greek capital letter nu
+        926  => 'Xi',       # Greek capital letter xi
+        927  => 'Omicron',  # Greek capital letter omicron
+        928  => 'Pi',       # Greek capital letter pi
+        929  => 'Rho',      # Greek capital letter rho
+        931  => 'Sigma',    # Greek capital letter sigma
+        932  => 'Tau',      # Greek capital letter tau
+        933  => 'Upsilon',  # Greek capital letter upsilon
+        934  => 'Phi',      # Greek capital letter phi
+        935  => 'Chi',      # Greek capital letter chi
+        936  => 'Psi',      # Greek capital letter psi
+        937  => 'Omega',    # Greek capital letter omega
+        945  => 'alpha',    # Greek small letter alpha
+        946  => 'beta',     # Greek small letter beta
+        947  => 'gamma',    # Greek small letter gamma
+        948  => 'delta',    # Greek small letter delta
+        949  => 'epsilon',  # Greek small letter epsilon
+        950  => 'zeta',     # Greek small letter zeta
+        951  => 'eta',      # Greek small letter eta
+        952  => 'theta',    # Greek small letter theta
+        953  => 'iota',     # Greek small letter iota
+        954  => 'kappa',    # Greek small letter kappa
+        955  => 'lambda',   # Greek small letter lambda
+        956  => 'mu',       # Greek small letter mu
+        957  => 'nu',       # Greek small letter nu
+        958  => 'xi',       # Greek small letter xi
+        959  => 'omicron',  # Greek small letter omicron
+        960  => 'pi',       # Greek small letter pi
+        961  => 'rho',      # Greek small letter rho
+        962  => 'sigmaf',   # Greek small letter final sigma
+        963  => 'sigma',    # Greek small letter sigma
+        964  => 'tau',      # Greek small letter tau
+        965  => 'upsilon',  # Greek small letter upsilon
+        966  => 'phi',      # Greek small letter phi
+        967  => 'chi',      # Greek small letter chi
+        968  => 'psi',      # Greek small letter psi
+        969  => 'omega',    # Greek small letter omega
+        977  => 'thetasym', # Greek theta symbol
+        978  => 'upsih',    # Greek upsilon with hook symbol
+        982  => 'piv',      # Greek pi symbol
+        8194 => 'ensp',     # en space
+        8195 => 'emsp',     # em space
+        8201 => 'thinsp',   # thin space
+        8204 => 'zwnj',     # zero width non-joiner
+        8205 => 'zwj',      # zero width joiner
+        8206 => 'lrm',      # left-to-right mark
+        8207 => 'rlm',      # right-to-left mark
+        8211 => 'ndash',    # en dash
+        8212 => 'mdash',    # em dash
+        8216 => 'lsquo',    # left single quotation mark
+        8217 => 'rsquo',    # right single quotation mark
+        8218 => 'sbquo',    # single low-9 quotation mark
+        8220 => 'ldquo',    # left double quotation mark
+        8221 => 'rdquo',    # right double quotation mark
+        8222 => 'bdquo',    # double low-9 quotation mark
+        8224 => 'dagger',   # dagger
+        8225 => 'Dagger',   # double dagger
+        8226 => 'bull',     # bullet
+        8230 => 'hellip',   # horizontal ellipsis
+        8240 => 'permil',   # per mille sign
+        8242 => 'prime',    # prime
+        8243 => 'Prime',    # double prime
+        8249 => 'lsaquo',   # single left-pointing angle quotation mark
+        8250 => 'rsaquo',   # single right-pointing angle quotation mark
+        8254 => 'oline',    # overline
+        8260 => 'frasl',    # fraction slash
+        8364 => 'euro',     # euro sign
+        8465 => 'image',    # black-letter capital i
+        8472 => 'weierp',   # script capital pXCOMMAX Weierstrass p
+        8476 => 'real',     # black-letter capital r
+        8482 => 'trade',    # trademark sign
+        8501 => 'alefsym',  # alef symbol
+        8592 => 'larr',     # leftwards arrow
+        8593 => 'uarr',     # upwards arrow
+        8594 => 'rarr',     # rightwards arrow
+        8595 => 'darr',     # downwards arrow
+        8596 => 'harr',     # left right arrow
+        8629 => 'crarr',    # downwards arrow with corner leftwards
+        8656 => 'lArr',     # leftwards double arrow
+        8657 => 'uArr',     # upwards double arrow
+        8658 => 'rArr',     # rightwards double arrow
+        8659 => 'dArr',     # downwards double arrow
+        8660 => 'hArr',     # left right double arrow
+        8704 => 'forall',   # for all
+        8706 => 'part',     # partial differential
+        8707 => 'exist',    # there exists
+        8709 => 'empty',    # empty set
+        8711 => 'nabla',    # nabla
+        8712 => 'isin',     # element of
+        8713 => 'notin',    # not an element of
+        8715 => 'ni',       # contains as member
+        8719 => 'prod',     # n-ary product
+        8721 => 'sum',      # n-ary summation
+        8722 => 'minus',    # minus sign
+        8727 => 'lowast',   # asterisk operator
+        8730 => 'radic',    # square root
+        8733 => 'prop',     # proportional to
+        8734 => 'infin',    # infinity
+        8736 => 'ang',      # angle
+        8743 => 'and',      # logical and
+        8744 => 'or',       # logical or
+        8745 => 'cap',      # intersection
+        8746 => 'cup',      # union
+        8747 => 'int',      # integral
+        8756 => 'there4',   # therefore
+        8764 => 'sim',      # tilde operator
+        8773 => 'cong',     # congruent to
+        8776 => 'asymp',    # almost equal to
+        8800 => 'ne',       # not equal to
+        8801 => 'equiv',    # identical toXCOMMAX equivalent to
+        8804 => 'le',       # less-than or equal to
+        8805 => 'ge',       # greater-than or equal to
+        8834 => 'sub',      # subset of
+        8835 => 'sup',      # superset of
+        8836 => 'nsub',     # not a subset of
+        8838 => 'sube',     # subset of or equal to
+        8839 => 'supe',     # superset of or equal to
+        8853 => 'oplus',    # circled plus
+        8855 => 'otimes',   # circled times
+        8869 => 'perp',     # up tack
+        8901 => 'sdot',     # dot operator
+        8968 => 'lceil',    # left ceiling
+        8969 => 'rceil',    # right ceiling
+        8970 => 'lfloor',   # left floor
+        8971 => 'rfloor',   # right floor
+        9001 => 'lang',     # left-pointing angle bracket
+        9002 => 'rang',     # right-pointing angle bracket
+        9674 => 'loz',      # lozenge
+        9824 => 'spades',   # black spade suit
+        9827 => 'clubs',    # black club suit
+        9829 => 'hearts',   # black heart suit
+        9830 => 'diams',    # black diamond suit
+      }.freeze
+
+      # Allowed URL schemes
+      #
+      # @since 0.4.0
+      # @api private
+      #
+      # @see Hanami::Utils::Escape.url
+      DEFAULT_URL_SCHEMES = ['http', 'https', 'mailto'].freeze
+
+      # The output of an escape.
+      #
+      # It's marked with this special class for two reasons:
+      #
+      #   * Don't double escape the same string (this is for `Hanami::Helpers` compatibility)
+      #   * Leave open the possibility to developers to mark a string as safe with an higher API (eg. `#raw` in `Hanami::View` or `Hanami::Helpers`)
+      #
+      # @since 0.4.0
+      # @api private
+      class SafeString < ::String
+        # @return [SafeString] the duped string
+        #
+        # @since 0.4.0
+        # @api private
+        #
+        # @see http://www.ruby-doc.org/core/String.html#method-i-to_s
+        def to_s
+          dup
+        end
+
+        # Encode the string the given encoding
+        #
+        # @return [SafeString] an encoded SafeString
+        #
+        # @since 0.4.0
+        # @api private
+        #
+        # @see http://www.ruby-doc.org/core/String.html#method-i-encode
+        def encode(*args)
+          self.class.new super
+        end
+      end
+
+      # Escape HTML contents
+      #
+      # This MUST be used only for tag contents.
+      # Please use `html_attribute` for escaping HTML attributes.
+      #
+      # @param input [String] the input
+      #
+      # @return [String] the escaped string
+      #
+      # @since 0.4.0
+      #
+      # @see https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet OWASP XSS Cheat Sheet Rule #1
+      #
+      # @example Good practice
+      #   <div><%= Hanami::Utils::Escape.html('<script>alert(1);</script>') %></div>
+      #   <div>&lt;script&gt;alert(1);&lt;&#x2F;script&gt;</div>
+      #
+      # @example Bad practice
+      #   # WRONG Use Escape.html_attribute
+      #   <a title="<%= Hanami::Utils::Escape.html('...') %>">link</a>
+      def self.html(input)
+        input = encode(input)
+        return input if input.is_a?(SafeString)
+
+        result = SafeString.new
+
+        input.chars do |chr|
+          result << HTML_CHARS.fetch(chr, chr)
+        end
+
+        result
+      end
+
+      # Escape HTML attributes
+      #
+      # This can be used both for HTML attributes and contents.
+      # Please note that this is more computational expensive.
+      # If you need to escape only HTML contents, please use `.html`.
+      #
+      # @param input [String] the input
+      #
+      # @return [String] the escaped string
+      #
+      # @since 0.4.0
+      #
+      # @see https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet OWASP XSS Cheat Sheet Rule #2
+      #
+      # @example Good practice
+      #   <a title="<%= Hanami::Utils::Escape.html_attribute('...') %>">link</a>
+      #
+      # @example Good but expensive practice
+      #   # Alternatively you can use Escape.html
+      #   <p><%= Hanami::Utils::Escape.html_attribute('...') %></p>
+      def self.html_attribute(input)
+        input = encode(input)
+        return input if input.is_a?(SafeString)
+
+        result = SafeString.new
+
+        input.chars do |chr|
+          result << encode_char(chr, HTML_ATTRIBUTE_SAFE_CHARS)
+        end
+
+        result
+      end
+
+      # Escape URL for HTML attributes (href, src, etc..).
+      #
+      # It extracts from the given input the first valid URL that matches the
+      # whitelisted schemes (default: http, https and mailto).
+      #
+      # It's possible to pass a second optional argument to specify different
+      # schemes.
+      #
+      # @param input [String] the input
+      # @param schemes [Array<String>] an array of whitelisted schemes
+      #
+      # @return [String] the escaped string
+      #
+      # @since 0.4.0
+      #
+      # @see Hanami::Utils::Escape::DEFAULT_URL_SCHEMES
+      # @see http://www.ruby-doc.org/stdlib/libdoc/uri/rdoc/URI.html#method-c-extract
+      #
+      # @example Basic usage
+      #   <%
+      #     good_input = "http://hanamirb.org"
+      #     evil_input = "javascript:alert('xss')"
+      #
+      #     escaped_good_input = Hanami::Utils::Escape.url(good_input) # => "http://hanamirb.org"
+      #     escaped_evil_input = Hanami::Utils::Escape.url(evil_input) # => ""
+      #   %>
+      #
+      #   <a href="<%= escaped_good_input %>">personal website</a>
+      #   <a href="<%= escaped_evil_input %>">personal website</a>
+      #
+      # @example Custom scheme
+      #   <%
+      #     schemes  = ['ftp', 'ftps']
+      #
+      #     accepted = "ftps://ftp.example.org"
+      #     rejected = "http://www.example.org"
+      #
+      #     escaped_accepted = Hanami::Utils::Escape.url(accepted) # => "ftps://ftp.example.org"
+      #     escaped_rejected = Hanami::Utils::Escape.url(rejected) # => ""
+      #   %>
+      #
+      #   <a href="<%= escaped_accepted %>">FTP</a>
+      #   <a href="<%= escaped_rejected %>">FTP</a>
+      def self.url(input, schemes = DEFAULT_URL_SCHEMES)
+        input = encode(input)
+        return input if input.is_a?(SafeString)
+
+        SafeString.new(
+          URI.extract(
+            URI.decode(input),
+            schemes
+          ).first.to_s
+        )
+      end
+
+      private
+      # Encode the given string into UTF-8
+      #
+      # @param input [String] the input
+      #
+      # @return [String] an UTF-8 encoded string
+      #
+      # @since 0.4.0
+      # @api private
+      def self.encode(input)
+        return '' if input.nil?
+        input.encode(Encoding::UTF_8)
+      rescue Encoding::UndefinedConversionError
+        input.dup.force_encoding(Encoding::UTF_8)
+      end
+
+      # Encode the given UTF-8 char.
+      #
+      # @param char [String] an UTF-8 char
+      # @param safe_chars [Hash] a table of safe chars
+      #
+      # @return [String] an HTML encoded string
+      #
+      # @since 0.4.0
+      # @api private
+      def self.encode_char(char, safe_chars = {})
+        return char if safe_chars[char]
+
+        code = char.ord
+        hex  = hex_for_non_alphanumeric_code(code)
+        return char if hex.nil?
+
+        if NON_PRINTABLE_CHARS[code]
+          hex = REPLACEMENT_HEX
+        end
+
+        if entity = HTML_ENTITIES[code]
+          "&#{ entity };"
+        else
+          "&#x#{ hex };"
+        end
+      end
+
+      # Transforms the given char code
+      #
+      # @since 0.4.0
+      # @api private
+      def self.hex_for_non_alphanumeric_code(input)
+        if input < LOW_HEX_CODE_LIMIT
+          HEX_CODES[input]
+        else
+          input.to_s(HEX_BASE)
+        end
+      end
+    end
+  end
+end