ki-repo 0.1.0 → 0.1.1

data/lib/util/attr_chain.rb

@@ -0,0 +1,258 @@
+# encoding: UTF-8
+
+# Copyright 2012 Mikko Apo
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Attaches configurable behaviour to accessor methods
+#
+#   class Foo
+#      attr_chain :name, :require
+#      attr_chain :email, -> {""}
+#      attr_chain :birth_day, :immutable, :valid => lambda { |i| (1870..Time.now.year+1).include?(i) }, :require => true
+#      attr_chain :children, :convert => lambda {|s| s.to_i}
+#   end
+#
+# Sets up public methods variable_name and variable_name= which both can be used to access the fields. Giving any parameters
+# for the method makes it a "set" operation and giving no parameters makes it a "get" operation. "Set" stores the value
+# and returns self, so set calls can be chained. "Get" returns the stored value.
+#
+#    foo.email("test@email.com").name("test")
+#    foo.email => "test@email.com"
+#    foo.name => "test"
+#
+# Parameters can be given in short and long format. Short format works by identifying parameter types,
+# long format works by given the name and value as hash parameters:
+# * <tt>:require=>"You need to define xxx first"</tt>, <tt>:require=>true</tt>, short: <tt>:require</tt> - an exception is thrown if target field is not defined
+# * <tt>:default=> -> {true}</tt>, short: <tt>-> {Array.new}</tt> - if target field has not been defined, executes proc and stores value. proc is executed using object.instance_exec: object's fields & methds are available
+# * <tt>:immutable=>true</tt>, short: <tt>:immutable</tt> - an exception is thrown if target field is defined a second time
+# * <tt>:valid=>[1,2,3,"a", lambda {|s| s.include?("b")}]</tt>, <tt>:valid => lambda {|s| s.include?("b")}</tt>, short: <tt>[1,2,3,"a"]</tt> - List of valid values. If any matches, sets value. If none matches, raises exception. Long form wraps single arguments to a list.
+# * <tt>:convert=> ->(s) { s+1 }</tt> - Converts input value using the defined proc
+# * <tt>:accessor=>InstanceVariableAccessor.new</tt> - Makes it possible to set values in other source, for example a hash. By default uses InstanceVariableAccessor
+#
+# Advantages for using attr_chain
+# * attr_chain has a compact syntax for many important programming concepts -> less manually written boilerplate code is needed
+# * :default makes it easy to isolate functionality to a default value while still making it easy to override the default behaviour
+# * :default adds easy lazy evalution and memoization to the attribute, default value is evaluated only if needed
+# * Testing becomes easier when objects have more exposed fields
+# * :require converts tricky nil exceptions in to useful errors. Instead of the "undefined method `bar' for nil:NilClass" you get a good error message that states which field was not defined
+#      foo.name.bar # if name has not been defined, raises "'name' has not been set" exception
+# * :immutable, :valid and :convert make complex validations and converts easy
+#
+# Warnings about attr_chain
+# * Performance has not been measured and attr_chain is probably not efficient. If there are tight inner loops, it's better to cache the value and store it afterwards
+# * There has not been tests for memory leaks. It's plain ruby so GC should take care of everything
+# * Excessive attr_chain usage makes classes a mess. Try to keep your classes short and attr_chain count below 10.
+# @see InstanceVariableAccessor
+# @see Object.attr_chain
+# @see Module#attr_chain
+class AttrChain
+  # Parses parameters with parse_short_syntax and set_parameters and configures class methods
+  # * each attr_chain definition uses one instance of AttrChain which holds the configuration for the definition
+  # * Object::define_method is used to add two methods to target class and when called both of these methods call attr_chain with their parameters
+  # @see Object.attr_chain
+  # @see Module#attr_chain
+  def initialize(clazz, variable_name, attr_configs)
+    @variable_name = variable_name
+    @accessor = InstanceVariableAccess
+    set_parameters(variable_name, parse_short_syntax(variable_name, attr_configs))
+    me = self
+    attr_call = lambda { |*args| me.attr_chain(self, args) }
+    [variable_name, "#{variable_name}="].each do |method_name|
+      if clazz.method_defined?(method_name)
+        clazz.send(:undef_method, method_name)
+      end
+      clazz.send(:define_method, method_name, attr_call)
+    end
+  end
+
+  # Converts short syntax entries in attr_configs to long syntax
+  # * warns about not supported values and already defined values
+  def parse_short_syntax(variable_name, attr_configs)
+    params = {}
+    attr_configs.each do |attr_config|
+      key_values = if [:require, :immutable].include?(attr_config)
+                     [[attr_config, true]]
+                   elsif attr_config.kind_of?(Proc)
+                     [[:default, attr_config]]
+                   elsif attr_config.kind_of?(Array)
+                     [[:valid, attr_config]]
+                   elsif attr_config.kind_of?(Hash)
+                     all = []
+                     attr_config.each_pair do |pair|
+                       all << pair
+                     end
+                     all
+                   else
+                     raise "attr_chain :#{variable_name} unsupported parameter: '#{attr_config.inspect}'"
+                   end
+      key_values.each do |key, value|
+        if params.include?(key)
+          raise "attr_chain :#{variable_name}, :#{key} was already defined to '#{params[key]}' (new value: '#{value}')"
+        end
+        params[key]=value
+      end
+    end
+    params
+  end
+
+  # Parses long syntax values and sets configuration for this field
+  def set_parameters(variable_name, params)
+    params.each_pair do |key, value|
+      case key
+        when :require
+          @require = value
+        when :default
+          if !value.kind_of?(Proc)
+            raise "attr_chain :#{variable_name}, :default needs to be a Proc, not '#{value.inspect}'"
+          end
+          @default = value
+        when :immutable
+          @immutable = value
+        when :valid
+          if !value.kind_of?(Array)
+            value = [value]
+          end
+          value.each do |valid|
+            if valid.kind_of?(Proc)
+              @valid_procs ||= []
+              @valid_procs << valid
+            else
+              @valid_items ||= {}
+              @valid_items[valid]=valid
+            end
+          end
+        when :convert
+          if !value.kind_of?(Proc)
+            raise "attr_chain :#{variable_name}, :convert needs to be a Proc, not '#{value.inspect}'"
+          end
+          @convert = value
+        when :accessor
+          @accessor = value
+        else
+          raise "attr_chain :#{variable_name} unsupported parameter: '#{key.inspect}'"
+      end
+    end
+  end
+
+  # Handles incoming methods for "get" and "set"
+  # * called by methods defined to class
+  # * configuration is stored as instance variables, the class knows which variable is being handled
+  # * method call parameters come as list of parameters
+  def attr_chain(object, args)
+    if args.empty?
+      if !@accessor.defined?(object, @variable_name)
+        if defined? @default
+          @accessor.set(object, @variable_name, object.instance_exec(&@default))
+        elsif defined? @require
+          if @require.kind_of?(String)
+            raise "'#{@variable_name}' has not been set: #{@require}"
+          else
+            raise "'#{@variable_name}' has not been set"
+          end
+        end
+      end
+      @accessor.get(object, @variable_name)
+    else
+      if defined?(@immutable) && @accessor.defined?(object, @variable_name)
+        raise "'#{@variable_name}' has been set once already"
+      end
+      value_to_set = if args.size == 1
+                       args.first
+                     else
+                       args
+                     end
+      if defined? @convert
+        value_to_set = object.instance_exec(value_to_set, &@convert)
+      end
+      if defined?(@valid_items) || defined?(@valid_procs)
+        is_valid = false
+        if defined?(@valid_items) && @valid_items.include?(value_to_set)
+          is_valid = true
+        end
+        if is_valid == false && defined?(@valid_procs)
+          @valid_procs.each do |valid_proc|
+            if is_valid=object.instance_exec(value_to_set, &valid_proc)
+              break
+            end
+          end
+        end
+        if is_valid == false
+          raise "invalid value for '#{@variable_name}'"
+        end
+      end
+      @accessor.set(object, @variable_name, value_to_set)
+      object
+    end
+  end
+
+  # Wrapper for Object::instance_variable_get, Object::instance_variable_set and Object::instance_variable_defined?
+  class InstanceVariableAccessor
+    def edit_name(variable_name)
+      "@#{variable_name}".to_sym
+    end
+
+    def get(object, name)
+      n = edit_name(name)
+      if object.instance_variable_defined?(n)
+        object.instance_variable_get(n)
+      else
+        nil
+      end
+    end
+
+    def set(object, name, value)
+      object.instance_variable_set(edit_name(name), value)
+    end
+
+    def defined?(object, name)
+      object.instance_variable_defined?(edit_name(name))
+    end
+  end
+
+  InstanceVariableAccess = InstanceVariableAccessor.new
+
+  class HashAccessor
+    def get(object, name)
+      object[name.to_s]
+    end
+
+    def set(object, name, value)
+      object[name.to_s] = value
+    end
+
+    def defined?(object, name)
+      object.include?(name.to_s)
+    end
+  end
+
+  HashAccess = HashAccessor.new
+end
+
+class Object
+  # Configurable accessor methods
+  # @see AttrChain
+  # @return [void]
+  def self.attr_chain(variable_name, *attr_configs)
+    AttrChain.new(self, variable_name, attr_configs)
+  end
+end
+
+class Module
+  # When a module defines an attr_chain, the attr_chain methods are available to all classes that are extended with the module
+  # @see AttrChain
+  # @return [void]
+  def attr_chain(variable_name, *attr_configs)
+    AttrChain.new(self, variable_name, attr_configs)
+  end
+end

data/lib/util/exception_catcher.rb

@@ -0,0 +1,118 @@
+# encoding: UTF-8
+
+# Copyright 2012 Mikko Apo
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'thread'
+
+# ExceptionCatcher makes it easy to execute multiple operations even though any might fail with exception
+# * executed tasks can be named to make it easier to identify which tasks failed
+# * collects result and exceptions for each executed task
+# * raises a {MultipleExceptions} exception if there were more than one exception
+#
+#    catcher = ExceptionCatcher.new
+#    catcher.catch(1){raise "1"}
+#    catcher.catch(2){raise "2"}
+#    catcher.catch(3){"ok!"}
+#    catcher.exception(1) # -> exception object raised by the task 1
+#    catcher.exception(2) # -> exception object raise by the task 2
+#    catcher.result(3) # -> "ok!"
+#    catcher.check # raises a MultipleExceptions exception
+#
+class ExceptionCatcher
+  attr_reader :tasks, :results, :exceptions, :mutex
+
+  def initialize
+    @mutex = Mutex.new
+    @results = {}
+    @exceptions = {}
+    @tasks = []
+  end
+
+  # Catches exceptions thrown by block
+  # @param [Object, nil] task if task is defined, results can be checked per task
+  # @param [Proc] block, block which is executed
+  # @return [Object, nil] returns block's result or nil if block raised an exception
+  def catch(task=nil, &block)
+    if task.nil?
+      task = block
+    end
+    @mutex.synchronize do
+      @tasks << task
+    end
+    begin
+      result = block.call
+      @mutex.synchronize do
+        @results[task]=result
+      end
+      result
+    rescue Exception => e
+      @mutex.synchronize do
+        @exceptions[task]=e
+      end
+      nil
+    end
+  end
+
+  # @param [Object] task identifies the executed task
+  # @return [Object,nil] result for the named block or nil if the block ended in exception
+  def result(task)
+    @mutex.synchronize do
+      @results[task]
+    end
+  end
+
+  # @param [Object] task identifies the executed task
+  # @return [Object,nil] block's exception or nil if the block did not raise an exception
+  def exception(task)
+    @mutex.synchronize do
+      @exceptions[task]
+    end
+  end
+
+  # @return [bool] exceptions? returns true if there has been exceptions
+  def exceptions?
+    @exceptions.size > 0
+  end
+
+  # Checks if there has been exceptions and raises the original exception if there has been one exception and {MultipleExceptions} if there has been many exceptions
+  def check
+    @mutex.synchronize do
+      if @exceptions.size == 1
+        e = @exceptions.values.first
+        raise e.class, e.message, e.backtrace
+      elsif @exceptions.size > 1
+        raise MultipleExceptions.new("Caught #{@exceptions.size} exceptions!").catcher(self)
+      end
+    end
+  end
+
+  # {ExceptionCatcher} raises MultipleExceptions if it has caught multiple exceptions.
+  # MultipleExceptions makes the {ExceptionCatcher} and its results available
+  class MultipleExceptions < RuntimeError
+    include Enumerable
+    # Reference to original {#ExceptionCatcher}
+    attr_chain :catcher, :require
+    # Map of exceptions
+    attr_chain :exceptions, -> { catcher.exceptions }
+    # Map of tasks that have been scheduled
+    attr_chain :tasks, -> { catcher.tasks }
+
+    def each(&block)
+      exceptions.values.each(&block)
+    end
+  end
+end
+
+

data/lib/util/hash.rb

@@ -0,0 +1,46 @@
+# encoding: UTF-8
+
+# Copyright 2012 Mikko Apo
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'digest/sha1'
+require 'digest/sha2'
+require 'digest/md5'
+
+module Ki
+
+# SHA1, uses standard Ruby library
+  class SHA1
+    # SHA1, uses standard Ruby library
+    def SHA1.digest
+      Digest::SHA1.new
+    end
+  end
+
+# SHA2, uses standard Ruby library
+  class SHA2
+    # SHA2, uses standard Ruby library
+    def SHA2.digest
+      Digest::SHA2.new
+    end
+  end
+
+# MD5, uses standard Ruby library
+  class MD5
+    # MD5, uses standard Ruby library
+    def MD5.digest
+      Digest::MD5.new
+    end
+  end
+end

data/lib/util/hash_cache.rb

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+
+# Copyright 2012 Mikko Apo
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Ki
+# Caching Hash, resolves values at request time
+  class HashCache < Hash
+    # If key has not been defined, uses block to resolve the value. Value is stored and returned
+    # @param key Key
+    # @param [Proc] block Block which is evaluated if the key does not have value yet. Block's value is stored to hash
+    # @return Existing value or one resolved with the block
+    def cache(key, &block)
+      if !include?(key)
+        store(key, block.call)
+      end
+      self[key]
+    end
+  end
+end

data/lib/util/ruby_extensions.rb

@@ -0,0 +1,137 @@
+# encoding: UTF-8
+
+# Copyright 2012 Mikko Apo
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Ki
+  module KiEnumerable
+    def size!(*args)
+      args.each do |valid_size|
+        if valid_size.kind_of?(Range)
+          if valid_size.include?(size)
+            return self
+          end
+        elsif valid_size.respond_to?(:to_i)
+          if Integer(valid_size) == size
+            return self
+          end
+        else
+          raise "'#{valid_size.inspect}' not supported, needs to be either Range or have .to_i method"
+        end
+      end
+      raise "size #{size} does not match '#{args.map { |s| s.to_s }.join("', '")}'"
+    end
+
+    def any_matches?(value)
+      each do |pattern|
+        if value.match(pattern)
+          return pattern
+        end
+      end
+      false
+    end
+
+    def find_first(count=1, &block)
+      ret = []
+      each do |item|
+        if block.nil? || block.call(item)
+          ret << item
+          if ret.size == count
+            break
+          end
+        end
+      end
+      if count==1
+        ret.at(0)
+      else
+        ret
+      end
+    end
+
+    def to_h(separator=nil, &block)
+      ret = {}
+      each do |item|
+        if separator
+          key, *values = item.split(separator)
+          if values.size > 0 || item.include?(separator)
+            ret[key]=values.join(separator)
+          else
+            ret[key]=true
+          end
+        elsif block
+          key, value = block.call(item)
+          ret[key]=value
+        end
+      end
+      ret
+    end
+
+  end
+end
+
+class Array
+  include Ki::KiEnumerable
+
+  def Array.wrap(maybe_arr)
+    if maybe_arr.kind_of?(Array)
+      maybe_arr
+    else
+      [maybe_arr]
+    end
+  end
+end
+
+module Enumerable
+  include Ki::KiEnumerable
+end
+
+require 'fileutils'
+class File
+  def File.safe_write(dest, txt=nil, &block)
+    tmp = dest + "-" + rand(9999).to_s
+    begin
+      File.open(tmp, "w") do |file|
+        if block
+          block.call(file)
+        elsif txt
+          file.write(txt)
+        end
+      end
+      FileUtils.mv(tmp, dest)
+    rescue Exception => e
+      FileUtils.remove_entry_secure(tmp)
+      raise
+    end
+  end
+end
+
+class Hash
+  original_get = self.instance_method(:[])
+
+  define_method(:[]) do |key, default=nil|
+    value = original_get.bind(self).call(key)
+    if value || include?(key)
+      value
+    else
+      default
+    end
+  end
+
+  def require(key)
+    if !include?(key)
+      raise "'#{key}' is not defined!"
+    end
+    self[key]
+  end
+end

data/lib/util/service_registry.rb

@@ -0,0 +1,88 @@
+# encoding: UTF-8
+
+# Copyright 2012 Mikko Apo
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'monitor'
+
+module Ki
+  class ServiceRegistry < Hash
+    attr_reader :by_parent
+
+    def initialize
+      @monitor = Monitor.new
+      @by_parent = {}
+    end
+
+    def register(*args)
+      @monitor.synchronize do
+        case args.size
+          when 1
+            args.first.each_pair do |url, clazz|
+              register(url, clazz)
+            end
+          when 2
+            url, clazz = args
+            self[url]=clazz
+            (@by_parent[File.dirname(url)]||=Array.new) << args
+          else
+            raise "Not supported '#{args.inspect}'"
+        end
+      end
+      self
+    end
+
+    def find(url, value=nil)
+      @monitor.synchronize do
+        if include?(url)
+          self[url]
+        elsif @by_parent.include?(url)
+          services = @by_parent[url]
+          if services
+            if value
+              services = services.select { |id, service| service.supports?(value) }
+            end
+            services = ServiceList.new.concat(services)
+          end
+          services
+        end
+      end
+    end
+
+    def find!(url, value=nil)
+      found = find(url, value)
+      if found.nil?
+        raise "Could not resolve '#{url}'"
+      end
+      found
+    end
+
+    def clear
+      @monitor.synchronize do
+        @by_parent.clear
+        super
+      end
+    end
+
+    class ServiceList < Array
+      def services
+        map { |url, service| service }
+      end
+
+      def service_names
+        map { |url, service| File.basename(url) }
+      end
+    end
+  end
+end