hanami-utils 0.0.0 → 0.7.0

data/lib/hanami/logger.rb

@@ -0,0 +1,141 @@
+require 'logger'
+require 'hanami/utils/string'
+
+module Hanami
+  # Hanami logger
+  #
+  # Implement with the same interface of Ruby std lib `Logger`.
+  # It uses `STDOUT` as output device.
+  #
+  #
+  #
+  # When a Hanami application is initialized, it creates a logger for that specific application.
+  # For instance for a `Bookshelf::Application` a `Bookshelf::Logger` will be available.
+  #
+  # This is useful for auto-tagging the output. Eg (`[Booshelf]`).
+  #
+  # When used stand alone (eg. `Hanami::Logger.info`), it tags lines with `[Shared]`.
+  #
+  #
+  #
+  # The available severity levels are the same of `Logger`:
+  #
+  #   * debug
+  #   * error
+  #   * fatal
+  #   * info
+  #   * unknown
+  #   * warn
+  #
+  # Those levels are available both as class and instance methods.
+  #
+  # @since 0.5.0
+  #
+  # @see http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html
+  # @see http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger/Severity.html
+  #
+  # @example Basic usage
+  #   require 'hanami'
+  #
+  #   module Bookshelf
+  #     class Application < Hanami::Application
+  #     end
+  #   end
+  #
+  #   # Initialize the application with the following code:
+  #   Bookshelf::Application.load!
+  #   # or
+  #   Bookshelf::Application.new
+  #
+  #   Bookshelf::Logger.info('Hello')
+  #   # => I, [2015-01-10T21:55:12.727259 #80487]  INFO -- [Bookshelf] : Hello
+  #
+  #   Bookshelf::Logger.new.info('Hello')
+  #   # => I, [2015-01-10T21:55:12.727259 #80487]  INFO -- [Bookshelf] : Hello
+  #
+  # @example Standalone usage
+  #   require 'hanami'
+  #
+  #   Hanami::Logger.info('Hello')
+  #   # => I, [2015-01-10T21:55:12.727259 #80487]  INFO -- [Hanami] : Hello
+  #
+  #   Hanami::Logger.new.info('Hello')
+  #   # => I, [2015-01-10T21:55:12.727259 #80487]  INFO -- [Hanami] : Hello
+  #
+  # @example Custom tagging
+  #   require 'hanami'
+  #
+  #   Hanami::Logger.new('FOO').info('Hello')
+  #   # => I, [2015-01-10T21:55:12.727259 #80487]  INFO -- [FOO] : Hello
+  class Logger < ::Logger
+    # Hanami::Logger default formatter
+    #
+    # @since 0.5.0
+    # @api private
+    #
+    # @see http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger/Formatter.html
+    class Formatter < ::Logger::Formatter
+      # @since 0.5.0
+      # @api private
+      attr_writer :application_name
+
+      # @since 0.5.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger/Formatter.html#method-i-call
+      def call(severity, time, progname, msg)
+        progname = "[#{@application_name}] #{progname}"
+        super(severity, time.utc, progname, msg)
+      end
+    end
+
+    # Default application name.
+    # This is used as a fallback for tagging purposes.
+    #
+    # @since 0.5.0
+    # @api private
+    DEFAULT_APPLICATION_NAME = 'Hanami'.freeze
+
+    # @since 0.5.0
+    # @api private
+    attr_writer :application_name
+
+    # Initialize a logger
+    #
+    # @param application_name [String] an optional application name used for
+    #   tagging purposes
+    #
+    # @since 0.5.0
+    def initialize(application_name = nil)
+      super(STDOUT)
+
+      @application_name = application_name
+      @formatter        = Hanami::Logger::Formatter.new.tap { |f| f.application_name = self.application_name }
+    end
+
+    # Returns the current application name, this is used for tagging purposes
+    #
+    # @return [String] the application name
+    #
+    # @since 0.5.0
+    def application_name
+      @application_name || _application_name_from_namespace || _default_application_name
+    end
+
+    private
+    # @since 0.5.0
+    # @api private
+    def _application_name_from_namespace
+      class_name = self.class.name
+      namespace  = Utils::String.new(class_name).namespace
+
+      class_name != namespace and return namespace
+    end
+
+    # @since 0.5.0
+    # @api private
+    def _default_application_name
+      DEFAULT_APPLICATION_NAME
+    end
+  end
+end

data/lib/hanami/utils.rb

@@ -1,7 +1,36 @@
-require "hanami/utils/version"
+require 'hanami/utils/version'
 
 module Hanami
+  # Ruby core extentions and Hanami utilities
+  #
+  # @since 0.1.0
   module Utils
-    # Your code goes here...
+    # @since 0.3.1
+    # @api private
+    HANAMI_JRUBY = 'java'.freeze
+
+    # @since 0.3.1
+    # @api private
+    HANAMI_RUBINIUS = 'rbx'.freeze
+
+    # Checks if the current VM is JRuby
+    #
+    # @return [TrueClass,FalseClass] return if the VM is JRuby or not
+    #
+    # @since 0.3.1
+    # @api private
+    def self.jruby?
+      RUBY_PLATFORM == HANAMI_JRUBY
+    end
+
+    # Checks if the current VM is Rubinius
+    #
+    # @return [TrueClass,FalseClass] return if the VM is Rubinius or not
+    #
+    # @since 0.3.1
+    # @api private
+    def self.rubinius?
+      RUBY_ENGINE == HANAMI_RUBINIUS
+    end
   end
 end

data/lib/hanami/utils/attributes.rb

@@ -0,0 +1,132 @@
+require 'hanami/utils/hash'
+
+module Hanami
+  module Utils
+    # A set of attributes.
+    #
+    # It internally stores the data as a Hash.
+    #
+    # All the operations convert keys to strings.
+    # This strategy avoids memory attacks due to Symbol abuses when parsing
+    # untrusted input.
+    #
+    # At the same time, this allows to get/set data with the original key or
+    # with the string representation. See the examples below.
+    #
+    # @since 0.3.2
+    class Attributes
+      # Initialize a set of attributes
+      # All the keys of the given Hash are recursively converted to strings.
+      #
+      # @param hash [#to_h] a Hash or any object that implements #to_h
+      #
+      # @return [Hanami::Utils::Attributes] self
+      #
+      # @since 0.3.2
+      #
+      # @example
+      #   require 'hanami/utils/attributes'
+      #
+      #   attributes = Hanami::Utils::Attributes.new(a: 1, b: { 2 => [3, 4] })
+      #   attributes.to_h # => { "a" => 1, "b" => { "2" => [3, 4] } }
+      def initialize(hash = {})
+        @attributes = Utils::Hash.new(hash, &nil).stringify!
+      end
+
+      # Get the value associated with the given attribute
+      #
+      # @param attribute [#to_s] a String or any object that implements #to_s
+      #
+      # @return [Object,NilClass] the associated value, if present
+      #
+      # @since 0.3.2
+      #
+      # @example
+      #   require 'hanami/utils/attributes'
+      #
+      #   attributes = Hanami::Utils::Attributes.new(a: 1, 'b' => 2, 23 => 'foo')
+      #
+      #   attributes.get(:a)  # => 1
+      #   attributes.get('a') # => 1
+      #   attributes[:a]      # => 1
+      #   attributes['a']     # => 1
+      #
+      #   attributes.get(:b)  # => 2
+      #   attributes.get('b') # => 2
+      #   attributes[:b]      # => 2
+      #   attributes['b']     # => 2
+      #
+      #   attributes.get(23)   # => "foo"
+      #   attributes.get('23') # => "foo"
+      #   attributes[23]       # => "foo"
+      #   attributes['23']     # => "foo"
+      #
+      #   attributes.get(:unknown)  # => nil
+      #   attributes.get('unknown') # => nil
+      #   attributes[:unknown]      # => nil
+      #   attributes['unknown']     # => nil
+      def get(attribute)
+        @attributes[attribute.to_s]
+      end
+
+      # @since 0.3.4
+      alias_method :[], :get
+
+      # Set the given value for the given attribute
+      #
+      # @param attribute [#to_s] a String or any object that implements #to_s
+      # @param value [Object] any value
+      #
+      # @return [NilClass]
+      #
+      # @since 0.3.2
+      #
+      # @example
+      #   require 'hanami/utils/attributes'
+      #
+      #   attributes = Hanami::Utils::Attributes.new
+      #
+      #   attributes.set(:a, 1)
+      #   attributes.get(:a)  # => 1
+      #   attributes.get('a') # => 1
+      #
+      #   attributes.set('b', 2)
+      #   attributes.get(:b)  # => 2
+      #   attributes.get('b') # => 2
+      #
+      #   attributes.set(23, 'foo')
+      #   attributes.get(23)   # => "foo"
+      #   attributes.get('23') # => "foo"
+      def set(attribute, value)
+        @attributes[attribute.to_s] = value
+        nil
+      end
+
+      # Returns a deep duplicated copy of the attributes as a Hash
+      #
+      # @return [::Hash]
+      #
+      # @since 0.3.2
+      def to_h
+        ::Hash[].tap do |result|
+          @attributes.each do |k, v|
+            result[k] = _read_value(v)
+          end
+        end
+      end
+
+      private
+
+      # @since 0.4.1
+      # @api private
+      def _read_value(value)
+        case val = value
+        when ::Hash, ::Hanami::Utils::Hash, ->(v) { v.respond_to?(:hanami_nested_attributes?) }
+          val.to_h
+        else
+          val
+        end
+      end
+    end
+  end
+end

data/lib/hanami/utils/basic_object.rb

@@ -0,0 +1,53 @@
+module Hanami
+  module Utils
+    # BasicObject
+    #
+    # @since 0.3.5
+    class BasicObject < ::BasicObject
+      # Return the class for debugging purposes.
+      #
+      # @since 0.3.5
+      #
+      # @see http://ruby-doc.org/core/Object.html#method-i-class
+      def class
+        (class << self; self end).superclass
+      end
+
+      # Bare minimum inspect for debugging purposes.
+      #
+      # @return [String] the inspect string
+      #
+      # @since 0.3.5
+      #
+      # @see http://ruby-doc.org/core/Object.html#method-i-inspect
+      def inspect
+        "#<#{ self.class }:#{'%x' % (__id__ << 1)}#{ __inspect }>"
+      end
+
+      # Returns true if responds to the given method.
+      #
+      # @return [TrueClass,FalseClass] the result of the check
+      #
+      # @since 0.3.5
+      #
+      # @see http://ruby-doc.org/core-2.2.1/Object.html#method-i-respond_to-3F
+      def respond_to?(method_name, include_all = false)
+        respond_to_missing?(method_name, include_all)
+      end
+
+      private
+      # Must be overridden by descendants
+      #
+      # @since 0.3.5
+      # @api private
+      def respond_to_missing?(method_name, include_all)
+        ::Kernel.raise ::NotImplementedError
+      end
+
+      # @since 0.3.5
+      # @api private
+      def __inspect
+      end
+    end
+  end
+end

data/lib/hanami/utils/callbacks.rb

@@ -0,0 +1,286 @@
+module Hanami
+  module Utils
+    # Before and After callbacks
+    #
+    # @since 0.1.0
+    # @private
+    module Callbacks
+      # Series of callbacks to be executed
+      #
+      # @since 0.1.0
+      # @private
+      class Chain
+        # Return a new chain
+        #
+        # @return [Hanami::Utils::Callbacks::Chain]
+        #
+        # @since 0.2.0
+        def initialize
+          @chain = Array.new
+        end
+
+        # Appends the given callbacks to the end of the chain.
+        #
+        # @param callbacks [Array] one or multiple callbacks to append
+        # @param block [Proc] an optional block to be appended
+        #
+        # @return [void]
+        #
+        # @raise [RuntimeError] if the object was previously frozen
+        #
+        # @see #prepend
+        # @see #run
+        # @see Hanami::Utils::Callbacks::Callback
+        # @see Hanami::Utils::Callbacks::MethodCallback
+        # @see Hanami::Utils::Callbacks::Chain#freeze
+        #
+        # @since 0.3.4
+        #
+        # @example
+        #   require 'hanami/utils/callbacks'
+        #
+        #   chain = Hanami::Utils::Callbacks::Chain.new
+        #
+        #   # Append a Proc to be used as a callback, it will be wrapped by `Callback`
+        #   # The optional argument(s) correspond to the one passed when invoked the chain with `run`.
+        #   chain.append { Authenticator.authenticate! }
+        #   chain.append { |params| ArticleRepository.find(params[:id]) }
+        #
+        #   # Append a Symbol as a reference to a method name that will be used as a callback.
+        #   # It will wrapped by `MethodCallback`
+        #   # If the #notificate method accepts some argument(s) they should be passed when `run` is invoked.
+        #   chain.append :notificate
+        def append(*callbacks, &block)
+          callables(callbacks, block).each do |c|
+            @chain.push(c)
+          end
+
+          @chain.uniq!
+        end
+
+        # Prepends the given callbacks to the beginning of the chain.
+        #
+        # @param callbacks [Array] one or multiple callbacks to add
+        # @param block [Proc] an optional block to be added
+        #
+        # @return [void]
+        #
+        # @raise [RuntimeError] if the object was previously frozen
+        #
+        # @see #append
+        # @see #run
+        # @see Hanami::Utils::Callbacks::Callback
+        # @see Hanami::Utils::Callbacks::MethodCallback
+        # @see Hanami::Utils::Callbacks::Chain#freeze
+        #
+        # @since 0.3.4
+        #
+        # @example
+        #   require 'hanami/utils/callbacks'
+        #
+        #   chain = Hanami::Utils::Callbacks::Chain.new
+        #
+        #   # Add a Proc to be used as a callback, it will be wrapped by `Callback`
+        #   # The optional argument(s) correspond to the one passed when invoked the chain with `run`.
+        #   chain.prepend { Authenticator.authenticate! }
+        #   chain.prepend { |params| ArticleRepository.find(params[:id]) }
+        #
+        #   # Add a Symbol as a reference to a method name that will be used as a callback.
+        #   # It will wrapped by `MethodCallback`
+        #   # If the #notificate method accepts some argument(s) they should be passed when `run` is invoked.
+        #   chain.prepend :notificate
+        def prepend(*callbacks, &block)
+          callables(callbacks, block).each do |c|
+            @chain.unshift(c)
+          end
+
+          @chain.uniq!
+        end
+
+        # Runs all the callbacks in the chain.
+        # The only two ways to stop the execution are: `raise` or `throw`.
+        #
+        # @param context [Object] the context where we want the chain to be invoked.
+        # @param args [Array] the arguments that we want to pass to each single callback.
+        #
+        # @since 0.1.0
+        #
+        # @example
+        #   require 'hanami/utils/callbacks'
+        #
+        #   class Action
+        #     private
+        #     def authenticate!
+        #     end
+        #
+        #     def set_article(params)
+        #     end
+        #   end
+        #
+        #   action = Action.new
+        #   params = Hash[id: 23]
+        #
+        #   chain = Hanami::Utils::Callbacks::Chain.new
+        #   chain.append :authenticate!, :set_article
+        #
+        #   chain.run(action, params)
+        #
+        #   # `params` will only be passed as #set_article argument, because it has an arity greater than zero
+        #
+        #
+        #
+        #   chain = Hanami::Utils::Callbacks::Chain.new
+        #
+        #   chain.append do
+        #     # some authentication logic
+        #   end
+        #
+        #   chain.append do |params|
+        #     # some other logic that requires `params`
+        #   end
+        #
+        #   chain.run(action, params)
+        #
+        #   Those callbacks will be invoked within the context of `action`.
+        def run(context, *args)
+          @chain.each do |callback|
+            callback.call(context, *args)
+          end
+        end
+
+        # It freezes the object by preventing further modifications.
+        #
+        # @since 0.2.0
+        #
+        # @see http://ruby-doc.org/core/Object.html#method-i-freeze
+        #
+        # @example
+        #   require 'hanami/utils/callbacks'
+        #
+        #   chain = Hanami::Utils::Callbacks::Chain.new
+        #   chain.freeze
+        #
+        #   chain.frozen?  # => true
+        #
+        #   chain.append :authenticate! # => RuntimeError
+        def freeze
+          super
+          @chain.freeze
+        end
+
+
+        private
+
+        def callables(callbacks, block)
+          callbacks.push(block) if block
+          callbacks.map { |c| Factory.fabricate(c) }
+        end
+
+      end
+
+      # Callback factory
+      #
+      # @since 0.1.0
+      # @private
+      class Factory
+        # Instantiates a `Callback` according to if it responds to #call.
+        #
+        # @param callback [Object] the object that needs to be wrapped
+        #
+        # @return [Callback, MethodCallback]
+        #
+        # @since 0.1.0
+        #
+        # @example
+        #   require 'hanami/utils/callbacks'
+        #
+        #   callable = Proc.new{} # it responds to #call
+        #   method   = :upcase    # it doesn't responds to #call
+        #
+        #   Hanami::Utils::Callbacks::Factory.fabricate(callable).class
+        #     # => Hanami::Utils::Callbacks::Callback
+        #
+        #   Hanami::Utils::Callbacks::Factory.fabricate(method).class
+        #     # => Hanami::Utils::Callbacks::MethodCallback
+        def self.fabricate(callback)
+          if callback.respond_to?(:call)
+            Callback.new(callback)
+          else
+            MethodCallback.new(callback)
+          end
+        end
+      end
+
+      # Proc callback
+      # It wraps an object that responds to #call
+      #
+      # @since 0.1.0
+      # @private
+      class Callback
+        attr_reader :callback
+
+        # Initialize by wrapping the given callback
+        #
+        # @param callback [Object] the original callback that needs to be wrapped
+        #
+        # @return [Callback] self
+        #
+        # @since 0.1.0
+        #
+        def initialize(callback)
+          @callback = callback
+        end
+
+        # Executes the callback within the given context and passing the given arguments.
+        #
+        # @param context [Object] the context within we want to execute the callback.
+        # @param args [Array] an array of arguments that will be available within the execution.
+        #
+        # @return [void, Object] It may return a value, it depends on the callback.
+        #
+        # @since 0.1.0
+        #
+        # @see Hanami::Utils::Callbacks::Chain#run
+        def call(context, *args)
+          context.instance_exec(*args, &callback)
+        end
+      end
+
+      # Method callback
+      # It wraps a symbol or a string representing a method name that is implemented by the context within it will be called.
+      #
+      # @since 0.1.0
+      # @private
+      class MethodCallback < Callback
+        # Executes the callback within the given context and eventually passing the given arguments.
+        # Those arguments will be passed according to the arity of the target method.
+        #
+        # @param context [Object] the context within we want to execute the callback.
+        # @param args [Array] an array of arguments that will be available within the execution.
+        #
+        # @return [void, Object] It may return a value, it depends on the callback.
+        #
+        # @since 0.1.0
+        #
+        # @see Hanami::Utils::Callbacks::Chain#run
+        def call(context, *args)
+          method = context.method(callback)
+
+          if method.parameters.any?
+            method.call(*args)
+          else
+            method.call
+          end
+        end
+
+        def hash
+          callback.hash
+        end
+
+        def eql?(other)
+          hash == other.hash
+        end
+      end
+    end
+  end
+end