lotus-utils 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 635f90690f0d715100766bedfc746f1ee9a977e9
-  data.tar.gz: 6517b4075a02732076484155950e8f177269ba88
+  metadata.gz: ab1fa641a480652c1773fc1808f2f920e10e0ffa
+  data.tar.gz: 6c59b62ec336ef0a4e13c64a0e8f71f45dded958
 SHA512:
-  metadata.gz: d4b96ccd1aaffb8a3cddad8a96cf56b9b3ef899b1779b35fc09c3dee302e1f25539ab912eeeaf0cc3b5d8e60f8c2d347bfab07b52eafe1d610d80a8e019e8049
-  data.tar.gz: 829dfd916801ed046c0bf08071dacbdfd9a6dc61e08f7baf00232d27ec07270795dfd2ed9117ab227fc4778b8d7a2997b93c322ad7881e883d88452fca78a3db
+  metadata.gz: 7dd6940ce3dbebec5d04ae5f05ecb67e2c41cca40579d09d637f0c5a1c64cad083408bff258ec815cfce93480b17d871662e23bc85ae7b7b88a986e115a36978
+  data.tar.gz: 17686034d0c2003a2e42dc1d386b5cd22dc55ebb45cce29707e4283c47a05036b0aefb13e3ad00a34a43547e0efb9dca2f8369ad716b65d24838efd3e6cbe42d

data/.coveralls.yml

@@ -0,0 +1,2 @@
+service_name: travis-pro
+repo_token: xXwDghSC1DjiaetDmdYbITJam1xJOGIRZ

data/.gitignore

@@ -2,6 +2,7 @@
 *.rbc
 .bundle
 .config
+.greenbar
 .yardoc
 Gemfile.lock
 InstalledFiles

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+script: 'bundle exec rake'
+rvm:
+  - 2.0.0
+  - 2.1.0

data/.yardopts

@@ -0,0 +1,3 @@
+-
+LICENSE.txt
+lib/**/*.rb

data/Gemfile

@@ -1,4 +1,10 @@
 source 'https://rubygems.org'
-
-# Specify your gem's dependencies in lotus-utils.gemspec
 gemspec
+
+unless ENV['TRAVIS']
+  gem 'debugger',  require: false, platforms: :ruby
+  gem 'yard',      require: false
+  gem 'simplecov', require: false
+end
+
+gem 'coveralls', require: false

data/README.md

@@ -1,6 +1,26 @@
 # Lotus::Utils
 
-TODO: Write a gem description
+Ruby core extentions and class utilities for [Lotus](http://lotusrb.org)
+
+## Status
+
+[![Gem Version](https://badge.fury.io/rb/lotus-utils.png)](http://badge.fury.io/rb/lotus-utils)
+[![Build Status](https://secure.travis-ci.org/lotus/utils.png?branch=master)](http://travis-ci.org/lotus/utils?branch=master)
+[![Test Coverage](https://coveralls.io/repos/lotus/utils/badge.png?branch=master)](https://coveralls.io/r/lotus/utils)
+[![Code quality](https://codeclimate.com/github/lotus/utils.png)](https://codeclimate.com/github/lotus/utils)
+[![Dependencies](https://gemnasium.com/lotus/utils.png)](https://gemnasium.com/lotus/utils)
+
+## Contact
+
+* Home page: http://lotusrb.org
+* Mailing List: http://lotusrb.org/mailing-list
+* API Doc: http://rdoc.info/gems/lotus-utils
+* Bugs/Issues: https://github.com/lotus/utils/issues
+* Support: http://stackoverflow.com/questions/tagged/lotusrb
+
+## Rubies
+
+__Lotus::Utils__ supports Ruby (MRI) 2+
 
 ## Installation
 
@@ -18,12 +38,24 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+__Lotus::Utils__ is designed to enhance Ruby's code and stdlib.
+By default this gem doesn't load any code, require yourself what you need.
+
+Please read the documentation of each module, in order to understand how to use
+each feature.
+
+## Versioning
+
+__Lotus::Utils__ uses [Semantic Versioning 2.0.0](http://semver.org)
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/lotus-utils/fork )
+1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## Copyright
+
+Copyright 2014 Luca Guidi – Released under MIT License

data/Rakefile

@@ -1 +1,10 @@
-require "bundler/gem_tasks"
+require 'rake'
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.libs.push 'test'
+end
+
+task default: :test

data/lib/lotus/utils/callbacks.rb

@@ -0,0 +1,207 @@
+module Lotus
+  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 < ::Array
+        # Adds the given callbacks to the chain
+        #
+        # @param callbacks [Array] one or multiple callbacks to add
+        # @param blk [Proc] an optional block to be added
+        #
+        # @return [void]
+        #
+        # @see #run
+        # @see Lotus::Utils::Callbacks::Callback
+        # @see Lotus::Utils::Callbacks::MethodCallback
+        #
+        # @since 0.1.0
+        #
+        # @example
+        #   require 'lotus/utils/callbacks'
+        #
+        #   chain = Lotus::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.add { Authenticator.authenticate! }
+        #   chain.add {|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.add :notificate
+        def add(*callbacks, &blk)
+          callbacks.push blk if block_given?
+          callbacks.each do |c|
+            push Factory.fabricate(c)
+          end
+
+          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 'lotus/utils/callbacks'
+        #
+        #   class Action
+        #     private
+        #     def authenticate!
+        #     end
+        #
+        #     def set_article(params)
+        #     end
+        #   end
+        #
+        #   action = Action.new
+        #   params = Hash[id: 23]
+        #
+        #   chain = Lotus::Utils::Callbacks::Chain.new
+        #   chain.add :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 = Lotus::Utils::Callbacks::Chain.new
+        #
+        #   chain.add do
+        #     # some authentication logic
+        #   end
+        #
+        #   chain.add 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)
+          each do |callback|
+            callback.call(context, *args)
+          end
+        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 'lotus/utils/callbacks'
+        #
+        #   callable = Proc.new{} # it responds to #call
+        #   method   = :upcase    # it doesn't responds to #call
+        #
+        #   Lotus::Utils::Callbacks::Factory.fabricate(callable).class
+        #     # => Lotus::Utils::Callbacks::Callback
+        #
+        #   Lotus::Utils::Callbacks::Factory.fabricate(method).class
+        #     # => Lotus::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 Lotus::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 Lotus::Utils::Callbacks::Chain#run
+        def call(context, *args)
+          method = context.method(callback)
+
+          if method.parameters.any?
+            method.call(*args)
+          else
+            method.call
+          end
+        end
+
+        protected
+        def hash
+          callback.hash
+        end
+
+        def eql?(other)
+          hash == other.hash
+        end
+      end
+    end
+  end
+end

data/lib/lotus/utils/class.rb

@@ -0,0 +1,59 @@
+require 'lotus/utils/string'
+
+module Lotus
+  module Utils
+    # Class utilities
+    # @since 0.1.0
+    class Class
+      # Loads a class for the given string or pattern.
+      #
+      # @param name [String] the specific class name or pattern for the class that we want to load
+      #
+      # @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
+      #
+      # @see Lotus::Utils::String#tokenize
+      #
+      # @example
+      #   require 'lotus/utils/class'
+      #
+      #   module App
+      #     module Service
+      #       class Endpoint
+      #       end
+      #     end
+      #
+      #     class ServiceEndpoint
+      #     end
+      #   end
+      #
+      #   # basic usage
+      #   Lotus::Utils::Class.load!('App::Service') # => App::Service
+      #
+      #   # with explicit namespace
+      #   Lotus::Utils::Class.load!('Service', App) # => App::Service
+      #
+      #   # with pattern
+      #   Lotus::Utils::Class.load!('App::Service(::Endpoint|Endpoint)') # => App::Service::Endpoint
+      #   Lotus::Utils::Class.load!('App::Service(Endpoint|::Endpoint)') # => App::ServiceEndpoint
+      #
+      #   # with missing constant
+      #   Lotus::Utils::Class.load!('Unknown') # => raises NameError
+      def self.load!(name, namespace = Object)
+        String.new(name).tokenize do |token|
+          begin
+            return namespace.const_get(token)
+          rescue NameError
+          end
+        end
+
+        raise NameError.new(name)
+      end
+    end
+  end
+end

data/lib/lotus/utils/class_attribute.rb

@@ -0,0 +1,94 @@
+module Lotus
+  module Utils
+    # Inheritable class level variable accessors.
+    # @since 0.1.0
+    #
+    # @see Lotus::Utils::ClassAttribute::ClassMethods
+    module ClassAttribute
+      def self.included(base)
+        base.class_eval do
+          extend ClassMethods
+        end
+      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 'lotus/utils/class_attribute'
+        #
+        #   class Vehicle
+        #     include Lotus::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)
+          (class << self; self; end).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 = value.dup rescue 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/lotus/utils/hash.rb

@@ -0,0 +1,43 @@
+module Lotus
+  module Utils
+    # Hash on steroids
+    # @since 0.1.0
+    class Hash < ::Hash
+      # Initialize the hash
+      #
+      # @param hash [::Hash, Hash] the value we want to use to initialize this instance
+      #
+      # @return [Hash] self
+      #
+      # @since 0.1.0
+      def initialize(hash = {})
+        merge! hash
+      end
+
+      # Convert in-place all the keys to Symbol instances, nested hashes are converted too.
+      #
+      # @return [Hash] self
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/utils/hash'
+      #
+      #   hash = Lotus::Utils::Hash.new 'a' => 23, 'b' => { 'c' => ['x','y','z'] }
+      #   hash.symbolize!
+      #
+      #   hash.keys    # => [:a, :b]
+      #   hash.inspect # => {:a=>23, :b=>{:c=>["x", "y", "z"]}}
+      def symbolize!
+        keys.each do |k|
+          v = delete(k)
+          v = Hash.new(v).symbolize! if v.is_a?(::Hash)
+
+          self[k.to_sym] = v
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/lotus/utils/io.rb

@@ -0,0 +1,37 @@
+module Lotus
+  module Utils
+    # IO utils
+    #
+    # @since 0.1.0
+    class IO
+      # Decreases the level of verbosity, during the execution of the given block.
+      #
+      # Revised version of ActiveSupport's `Kernel.with_warnings` implementation
+      # @see https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/kernel/reporting.rb#L25
+      #
+      # @param blk [Proc] the block of code that generates warnings.
+      #
+      # @return [void]
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/utils/io'
+      #
+      #   class Test
+      #     TEST_VALUE = 'initial'
+      #   end
+      #
+      #   Lotus::Utils::IO.silence_warnings do
+      #     Test::TEST_VALUE = 'redefined'
+      #   end
+      def self.silence_warnings(&blk)
+        old_verbose, $VERBOSE = $VERBOSE, nil
+        blk.call
+      ensure
+        $VERBOSE = old_verbose
+      end
+    end
+  end
+end
+

data/lib/lotus/utils/path_prefix.rb

@@ -0,0 +1,84 @@
+module Lotus
+  module Utils
+    # Prefixed string
+    #
+    # @since 0.1.0
+    class PathPrefix < ::String
+      # Initialize the path prefix
+      #
+      # @param string [::String] the prefix value
+      # @param separator [::String] the separator used between tokens
+      #
+      # @return [PathPrefix] self
+      #
+      # @since 0.1.0
+      def initialize(string = nil, separator = '/')
+        @separator = separator
+        super(string.to_s)
+      end
+
+      # Joins self with the given token.
+      # It cleanups the all the `separator` repetitions.
+      #
+      # @param string [::String] the token we want to join
+      #
+      # @return [::String] the joined string
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/utils/path_prefix'
+      #
+      #   path_prefix = Lotus::Utils::PathPrefix.new '/posts'
+      #   path_prefix.join 'new'  # => '/posts/new'
+      #   path_prefix.join '/new' # => '/posts/new'
+      #
+      #   path_prefix = Lotus::Utils::PathPrefix.new 'posts'
+      #   path_prefix.join 'new'  # => '/posts/new'
+      #   path_prefix.join '/new' # => '/posts/new'
+      def join(string)
+        absolutize relative_join(string)
+      end
+
+      # Joins self with the given token, without prefixing it with `separator`.
+      # It cleanups the all the `separator` repetitions.
+      #
+      # @param string [::String] the token we want to join
+      # @param separator [::String] the separator used between tokens
+      #
+      # @return [::String] the joined string
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/utils/path_prefix'
+      #
+      #   path_prefix = Lotus::Utils::PathPrefix.new 'posts'
+      #   path_prefix.relative_join 'new'      # => 'posts/new'
+      #   path_prefix.relative_join 'new', '_' # => 'posts_new'
+      def relative_join(string, separator = @separator)
+        separator = separator || @separator
+        relativize [self, string].join(separator), separator
+      end
+
+      private
+      attr_reader :separator
+
+      def absolutize(string)
+        string.tap do |s|
+          s.insert(0, separator) unless absolute?(s)
+        end
+      end
+
+      def absolute?(string)
+        string.start_with?(separator)
+      end
+
+      def relativize(string, separator = @separator)
+        string.
+          gsub(%r{(?<!:)#{ separator * 2 }}, separator).
+          gsub(%r{\A#{ separator }}, '')
+      end
+    end
+  end
+end