kalimba 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 51492726fdd0d0303d00af8376c1bef0af951d48
+  data.tar.gz: c4bdf88223e9efd0591d447a152b9f16896d0626
+SHA512:
+  metadata.gz: 1543ecdd70a064ca87f4328d5e6729297d28cc93174917c2907911512191746b28c0bff95bcff08fe190956522bb6926c515231541e986ce0bc6ccb04af5304e
+  data.tar.gz: 61c0b9a9a146b8da73499ea763b21a02e2405fda113c2dd8ba589479f126d61ea9bffaadda60e17fffe0bf71768732f85a64ddff88b653f86be84ae3278cecc7

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.rspec
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+TAGS
+*~
+.*~
+bin/

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec name: "kalimba"
+gemspec name: "kalimba-redlander"
+
+gem "rake"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Slava Kravchenko
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# Kalimba
+
+Kalimba is an clone of ActiveRecord, based on ActiveModel framework.
+Combined with the raw power of Redlander gem, it introduces the world of Ruby on Rails
+to the world of RDF, triple storages, LinkedData and Semantic Web.
+The resources of semantic graph storages become accessible in a customary form of "models".
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'kalimba'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kalimba
+
+
+## Backends
+
+You won't be able to do much without a backend to handle your RDF statements.
+Please add "kalimba-redlander" gem dependency to your Gemfile, and make sure
+to "require 'kalimba-redlander'" before invoking "require 'kalimba'".
+
+For now, the backends are developed as a part of Kalimba gem for convenience.
+However, you are free to develop your own backend as a separate gem.
+
+
+### Kalimba::Persistence::Redlander
+
+Redlander adapter for [Kalimba](https://github.com/cordawyn/kalimba). It provides the RDF storage backend for Kalimba.
+
+
+## Usage
+
+Your model must be inherited from Kalimba::Resource:
+
+    class Person < Kalimba::Resource
+      # Note that type is *not* inherited,
+      # it must be explicitly declared for every subclass.
+      # And types better be unique!
+      type "http://schema.org/Person"
+
+      # Define base URI for the instances of this resource
+      base_uri "http://example.org/people"
+
+      property :name, :predicate => NS::FOAF["name"], :datatype => NS:XMLSchema["string"]
+
+      has_many :friends, :predicate => "http://schema.org/Person", :datatype => :Person
+    end
+
+From this point on, you may treat your model just like
+any fully-fledged clone of ActiveModel (i.e. ActiveRecord model)
+
+    $ alice = Person.new(:name => "Alice")
+    $ alice.valid?
+    $ alice.save!
+    ...
+    $ alice.friends << bob
+
+> Note that Kalimba associations are not fully API-compliant with ActiveRecord associations (yet?).
+> One major feature missing is "association proxy" which would enable tricks like
+> `alice.friends.destroy_all`. Presently, Kalimba "associations" return a simple collection (Array).
+
+For other details refer to YARD documentation for Kalimba::Resource module.
+
+
+## Regarding RDFS/OWL features
+
+It should be also noted that "special" features of RDFS/OWL like inverse properties or
+transitive properties and so on, are *not* specifically handled by Kalimba (or Redlander backend).
+Availability of any "virtual" data which is supposed to be available as a product of reasoning,
+is up to the graph storage that you use with the *backend*.
+
+So (provided that "hasFriend" is "owl:inverseOf" "isFriendOf") you may end with something like this:
+
+    alice.has_friend  # => bob
+    bob.is_friend_of  # => nil
+
+... unless your graph storage provides reasoning by default.
+
+That said, certain graph storages that are said to have reasoning capabilities,
+do not have reasoning enabled by default (e.g. [Virtuoso](http://virtuoso.openlinksw.com/)),
+and require that you explicitly enable it using special options or a custom SPARQL syntax.
+While it is possible to "hack" and modify the options or SPARQL queries that are generated
+by Kalimba (or its backend), this is not currently available.
+
+
+## Validations
+
+For details, refer to ActionModel::Validations documentation.
+
+    class Human < Kalimba::Resource
+      base_uri "http://example.com/people/"
+      property :name, :predicate => NS::FOAF["name"], :datatype => NS:XMLSchema["string"]
+
+      validates_presence_of :name
+    end
+
+    $ bob = Human.create  # => bob will have an error on :name
+
+## Callbacks
+
+Kalimba supports :before, :after and :around callbacks for :save, :create, :update and
+:destroy actions.
+
+    class Human < Kalimba::Resource
+      base_uri "http://example.com/people/"
+
+      before_save :shout
+
+      private
+
+      def shout
+        puts "Hey!"
+      end
+    end
+
+For details, refer to ActionModel::Callbacks documentation.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+
+require 'bundler/gem_helper'
+Bundler::GemHelper.install_tasks(name: "kalimba")
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new

data/kalimba-redlander.gemspec

@@ -0,0 +1,19 @@
+require File.expand_path('../lib/kalimba/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "kalimba-redlander"
+  gem.version       = Kalimba::VERSION
+  gem.authors       = ["Slava Kravchenko"]
+  gem.email         = ["slava.kravchenko@gmail.com"]
+  gem.description   = %q{Redlander adapter for Kalimba. It provides the RDF storage backend for Kalimba.}
+  gem.summary       = %q{Redlander adapter for Kalimba}
+  gem.homepage      = "https://github.com/cordawyn/kalimba-redlander"
+
+  gem.files         = ["lib/kalimba/persistence/redlander.rb"]
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_runtime_dependency "kalimba"
+  gem.add_runtime_dependency "redlander", "~> 0.6.0"
+end

data/kalimba.gemspec

@@ -0,0 +1,22 @@
+require File.expand_path('../lib/kalimba/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Slava Kravchenko"]
+  gem.email         = ["slava.kravchenko@gmail.com"]
+  gem.description   = %q{ActiveModel-based framework, which allows the developer to combine RDF resources into ActiveRecord-like models.}
+  gem.summary       = %q{Kalimba provides ActiveRecord-like capabilities for RDF resources.}
+  gem.homepage      = "https://github.com/cordawyn/kalimba"
+
+  gem.files         = `git ls-files`.split($\) - ["lib/kalimba/persistence/redlander.rb"]
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "kalimba"
+  gem.require_paths = ["lib"]
+  gem.version       = Kalimba::VERSION
+
+  gem.add_runtime_dependency "activemodel", "~> 3.2"
+  gem.add_runtime_dependency "activesupport", "~> 3.2"
+
+  gem.add_development_dependency "rspec", "~> 2.11.0"
+  gem.add_development_dependency "kalimba-redlander"
+end

data/lib/kalimba.rb

@@ -0,0 +1,24 @@
+require "set"
+require "active_model" # TODO: not all is required?
+
+require "kalimba/version"
+require "kalimba/exceptions"
+require "kalimba/resource"
+
+module Kalimba
+  class << self
+    def repository
+      @repository ||= Persistence.repository(@repository_options || {})
+    end
+
+    # Set repository options
+    #
+    # @param [Hash] options options to be passed to the repository constructor
+    # @return [void]
+    def set_repository_options(options = {})
+      @repository_options = options
+    end
+  end
+end
+
+require "kalimba/railtie" if defined?(Rails)

data/lib/kalimba/attribute_assignment.rb

@@ -0,0 +1,148 @@
+module Kalimba
+  module AttributeAssignment
+    # Assign attributes from the given hash
+    #
+    # @param [Hash<[Symbol, String] => Any>] new_attributes
+    # @param [Hash] options
+    # @return [void]
+    def assign_attributes(new_attributes = {}, options = {})
+      return if new_attributes.blank?
+
+      attributes = new_attributes.stringify_keys
+      multi_parameter_attributes = []
+      nested_parameter_attributes = []
+
+      attributes.each do |k, v|
+        if k.include?("(")
+          multi_parameter_attributes << [ k, v ]
+        elsif respond_to?("#{k}=")
+          if v.is_a?(Hash)
+            nested_parameter_attributes << [ k, v ]
+          else
+            send("#{k}=", v)
+          end
+        else
+          raise UnknownAttributeError, "unknown attribute: #{k}"
+        end
+      end
+
+      # assign any deferred nested attributes after the base attributes have been set
+      nested_parameter_attributes.each do |k,v|
+        send("#{k}=", v)
+      end
+
+      assign_multiparameter_attributes(multi_parameter_attributes)
+    end
+
+    private
+
+    # Instantiates objects for all attribute classes that needs more than one constructor parameter. This is done
+    # by calling new on the column type or aggregation type (through composed_of) object with these parameters.
+    # So having the pairs written_on(1) = "2004", written_on(2) = "6", written_on(3) = "24", will instantiate
+    # written_on (a date type) with Date.new("2004", "6", "24"). You can also specify a typecast character in the
+    # parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum,
+    # f for Float, s for String, and a for Array. If all the values for a given attribute are empty, the
+    # attribute will be set to nil.
+    def assign_multiparameter_attributes(pairs)
+      execute_callstack_for_multiparameter_attributes(
+        extract_callstack_for_multiparameter_attributes(pairs)
+      )
+    end
+
+    def execute_callstack_for_multiparameter_attributes(callstack)
+      errors = []
+      callstack.each do |name, values_with_empty_parameters|
+        begin
+          send(name + "=", read_value_from_parameter(name, values_with_empty_parameters))
+        rescue => ex
+          errors << AttributeAssignmentError.new("error on assignment #{values_with_empty_parameters.values.inspect} to #{name}", ex, name)
+        end
+      end
+      unless errors.empty?
+        raise MultiparameterAssignmentErrors.new(errors), "#{errors.size} error(s) on assignment of multiparameter attributes"
+      end
+    end
+
+    def read_value_from_parameter(name, values_hash_from_param)
+      case self.class.properties[name][:datatype]
+      when NS::XMLSchema["string"]
+        read_other_parameter_value(LocalizedString, name, values_hash_from_param)
+      when NS::XMLSchema["dateTime"], NS::XMLSchema["time"]
+        read_time_parameter_value(name, values_hash_from_param)
+      when NS::XMLSchema["date"]
+        read_date_parameter_value(name, values_hash_from_param)
+      else
+        values_hash_from_param
+      end
+    end
+
+    def read_other_parameter_value(klass, name, values_hash_from_param)
+      max_position = extract_max_param_for_multiparameter_attributes(values_hash_from_param)
+      values = (1..max_position).collect do |position|
+        raise "Missing Parameter" if !values_hash_from_param.has_key?(position)
+        values_hash_from_param[position]
+      end
+      klass.new(*values)
+    end
+
+    def extract_max_param_for_multiparameter_attributes(values_hash_from_param, upper_cap = 100)
+      [values_hash_from_param.keys.max,upper_cap].min
+    end
+
+    def extract_callstack_for_multiparameter_attributes(pairs)
+      pairs.inject({}) do |attributes, (multiparameter_name, value)|
+        attribute_name = multiparameter_name.split("(").first
+        attributes[attribute_name] = {} unless attributes.include?(attribute_name)
+
+        parameter_value = value.empty? ? nil : type_cast_attribute_value(multiparameter_name, value)
+        attributes[attribute_name][find_parameter_position(multiparameter_name)] ||= parameter_value
+        attributes
+      end
+    end
+
+    def type_cast_attribute_value(multiparameter_name, value)
+      multiparameter_name =~ /\([0-9]*([if])\)/ ? value.send("to_" + $1) : value
+    end
+
+    def find_parameter_position(multiparameter_name)
+      multiparameter_name.scan(/\(([0-9]*).*\)/).first.first.to_i
+    end
+
+    def read_time_parameter_value(name, values_hash_from_param)
+      if values_hash_from_param.size == 2
+        instantiate_time_using_two_fields(name, values_hash_from_param)
+      else
+        instantiate_time_using_many_fields(name, values_hash_from_param)
+      end
+    end
+
+    def read_date_parameter_value(name, values_hash_from_param)
+      return nil if (1..3).any? {|position| values_hash_from_param[position].blank?}
+      set_values = [values_hash_from_param[1], values_hash_from_param[2], values_hash_from_param[3]]
+      begin
+        Date.new(*set_values)
+      rescue ArgumentError # if Date.new raises an exception on an invalid date
+        # we instantiate Time object and convert it back to a date thus using Time's logic in handling invalid dates
+        Time.new(*set_values).to_date
+      end
+    end
+
+    def instantiate_time_using_two_fields(name, values_hash_from_param)
+      value = [values_hash_from_param[1], values_hash_from_param[2]].join(" ")
+      Time.parse(value) rescue nil
+    end
+
+    def instantiate_time_using_many_fields(name, values_hash_from_param)
+      # If Date bits were not provided, error
+      raise "Missing Parameter" if [1,2,3].any?{|position| !values_hash_from_param.has_key?(position)}
+      max_position = extract_max_param_for_multiparameter_attributes(values_hash_from_param, 6)
+      # If Date bits were provided but blank, then return nil
+      return nil if (1..3).any? {|position| values_hash_from_param[position].blank?}
+
+      set_values = (1..max_position).collect{|position| values_hash_from_param[position] }
+      # If Time bits are not there, then default to 0
+      (3..5).each {|i| set_values[i] = set_values[i].blank? ? 0 : set_values[i]}
+      Time.new(*set_values)
+    end
+  end
+end

data/lib/kalimba/callbacks.rb

@@ -0,0 +1,30 @@
+require "active_model/callbacks"
+
+module Kalimba
+  module Callbacks
+    def destroy
+      run_callbacks :destroy do
+        super
+      end
+    end
+
+    def save(options = {})
+      run_callbacks :save do
+        persistence_callback_type = new_record? ? :create : :update
+        run_callbacks persistence_callback_type do
+          super
+        end
+      end
+    end
+
+    private
+
+    def self.included(klass)
+      super
+      klass.class_eval do
+        extend ActiveModel::Callbacks
+        define_model_callbacks :create, :update, :destroy, :save
+      end
+    end
+  end
+end