veritas 0.0.5 → 0.0.6

data/.travis.yml

@@ -3,8 +3,9 @@ script: "bundle exec rake spec"
 rvm:
   - 1.8.7
   - 1.9.2
-  - rbx
-  # - rbx-2.0
-  - ree
-  # - jruby
+  - 1.9.3
   - ruby-head
+  - ree
+  - jruby
+  - rbx
+  - rbx-2.0

data/Gemfile

@@ -11,10 +11,9 @@ group :development do
 end
 
 group :guard do
-  gem 'guard',         '~> 0.5.1'
+  gem 'guard',         '~> 0.7.0'
   gem 'guard-bundler', '~> 0.1.3'
-  gem 'guard-ego',     '~> 0.0.1'
-  gem 'guard-rspec',   '~> 0.4.0'
+  gem 'guard-rspec',   '~> 0.4.5'
 end
 
 group :benchmarks do
@@ -29,16 +28,19 @@ end
 
 platforms :mri_18 do
   group :metrics do
-    gem 'flay',      '~> 1.4.2'
-    gem 'flog',      '~> 2.5.1'
-    gem 'heckle',    '~> 1.4.3'
-    gem 'json',      '~> 1.5.3'
-    gem 'metric_fu', '~> 2.1.1'
-    gem 'mspec',     '~> 1.5.17'
-    gem 'rcov',      '~> 0.9.9'
-    gem 'reek',      '~> 1.2.8', :git => 'git://github.com/dkubb/reek.git'
-    gem 'roodi',     '~> 2.1.0'
-    gem 'ruby2ruby', '=  1.2.2'
-    gem 'yardstick', '~> 0.4.0'
+    gem 'arrayfields', '~> 4.7.4'
+    gem 'fattr',       '~> 2.2.0'
+    gem 'flay',        '~> 1.4.2'
+    gem 'flog',        '~> 2.5.3'
+    gem 'heckle',      '~> 1.4.3'
+    gem 'json',        '~> 1.6.1'
+    gem 'map',         '~> 4.4.0'
+    gem 'metric_fu',   '~> 2.1.1'
+    gem 'mspec',       '~> 1.5.17'
+    gem 'rcov',        '~> 0.9.9'
+    gem 'reek',        '~> 1.2.8', :git => 'git://github.com/dkubb/reek.git'
+    gem 'roodi',       '~> 2.1.0'
+    gem 'ruby2ruby',   '=  1.2.2'
+    gem 'yardstick',   '~> 0.4.0'
   end
 end

data/Guardfile

@@ -1,9 +1,5 @@
 # encoding: utf-8
 
-guard 'ego' do
-  watch('Guardfile')
-end
-
 guard 'bundler' do
   watch('Gemfile')
 end

data/README.md

@@ -0,0 +1,188 @@
+# Veritas
+
+Simplifies querying of structured data using relational algebra
+
+[![Build Status](https://secure.travis-ci.org/dkubb/veritas.png)](http://travis-ci.org/dkubb/veritas)
+
+## Installation
+
+With Rubygems:
+
+```bash
+$ gem install veritas
+$ irb -rubygems
+>> require 'veritas'
+=> true
+```
+
+With git and local working copy:
+
+```bash
+$ git clone git://github.com/dkubb/veritas.git
+$ cd veritas
+$ rake install
+$ irb -rubygems
+>> require 'veritas'
+=> true
+```
+
+NOTE: This gem works best with ruby 1.9, however if you are using ruby 1.8 you must also install [backports](https://rubygems.org/gems/backports), then require backports and backports/basic_object, eg:
+
+```bash
+$ ruby -e 'puts RUBY_VERSION'
+=> 1.8.7
+$ gem install backports
+$ irb -rubygems
+>> require 'backports'
+=> true
+>> require 'backports/basic_object'
+=> true
+>> require 'veritas'  # assuming it was installed by one of the two methods above
+=> true
+```
+
+## Usage
+
+```ruby
+relation = Veritas::Relation.new(
+  [ [ :id, String ], [ :name, String ], [ :color, String ], [ :weight, Float ], [ :city, String ] ],
+  [
+    [ 'P1', 'Nut',   'Red',   12.0, 'London' ],
+    [ 'P2', 'Bolt',  'Green', 17.0, 'Paris'  ],
+    [ 'P3', 'Screw', 'Blue',  17.0, 'Oslo'   ],
+    [ 'P4', 'Screw', 'Red',   14.0, 'London' ],
+    [ 'P5', 'Cam',   'Blue',  12.0, 'Paris'  ],
+    [ 'P6', 'Cog',   'Red',   19.0, 'London' ],
+  ]
+)
+
+# Relational Operators
+# --------------------
+
+# projection
+new_relation = relation.project([ :id ])
+
+# removal
+new_relation = relation.remove([ :name ])
+
+# rename
+new_relation = relation.rename(id: :other_id, name: :other_name)
+
+# restriction
+new_relation = relation.restrict { |r| r.name.eq('Screw').or(r.city.eq('London')) }
+
+# natural join
+new_relation = relation.join(other)        # OR relation + other
+
+# product
+new_relation = relation.product(other)     # OR relation * other
+
+# intersection
+new_relation = relation.intersect(other)   # OR relation & other
+
+# union
+new_relation = relation.union(other)       # OR relation | other
+
+# difference
+new_relation = relation.difference(other)  # OR relation - other
+
+# theta-join
+new_relation = relation.join(other) { |r| r.id.gte(r.other_id) }
+
+# NOTE: theta-join is effectively restricting a product of the relations
+
+# extend
+new_relation = relation.extend { |r| r.add(:pounds, r.weight * 2.2) }
+new_relation = relation.extend { |r| r.add(:pounds) { |t| t[:weight] * 2.2 } }
+
+# summarize
+new_relation = relation.summarize(relation.project([ :city ])) { |r| r.add(:count, r.id.count) }
+new_relation = relation.summarize(relation.project([ :city ])) { |r| r.add(:count) { |acc, t| acc.to_i + 1 } }
+
+# Non-Relational Operators
+# ------------------------
+
+# returns a set that represents the relation header
+header = relation.header
+
+# a relation is Enumerable
+relation = relation.each { |tuple| ... }
+
+# order by attribute and direction
+ordered = relation.sort_by { |r| [ r.city.desc, r.name, r.color, r.id, r.weight ] }
+
+# reverse the relation (only allowed if ordered)
+new_relation = ordered.reverse
+
+# offset (only allowed if ordered)
+new_relation = ordered.drop(5)
+
+# limiting (only allowed if ordered)
+new_relation = ordered.take(10)
+
+# get the first n tuples (only allowed if ordered)
+new_relation = ordered.first     # default is 1
+new_relation = ordered.first(5)
+
+# get the last n tuples (only allowed if ordered)
+new_relation = ordered.last      # default is 1
+new_relation = ordered.last(5)
+```
+
+## Goals
+
+The purpose of this project is to expand my knowledge of relational algebra by attempting to implement a simple query system using the primitive operations defined in relational algebra.
+
+Most of the design is heavily inspired from [koios](https://github.com/carllerche/koios) and [arel](https://github.com/rails/arel). The reason I decided to write my own and not just build on top of those systems was not so much because I don't like the code/API in those projects, it's more because I wanted to gain a depth of understanding that can only be earned by trying to solve the problem myself.
+
+I should note though that I don't plan to just re-implement those systems with a different API, or different internals, I plan to make something that surpasses them in several areas. For example, I want to be able to join information from multiple datastores and represent it as a single relation. I want to be able to insert, update or delete from that relation and have those changes propagated back to the right datastore. This is not an easy feat, since it is basically the writable view problem that RDBMS' struggle with. While I do think there are some cases where relations will become read-only, I think it will be possible to propagate writes properly in this manner. I certainly think for the current use cases in DataMapper this should work quite well.
+
+The ability to join data from multiple datastores and have it presented in a consistent manner will solve one of the longest standing problems in DataMapper, namely how do we do cross repository joins. It should be possible to construct one query for one datastore, and then another query for another datastore and then join them. Since they are using different engines veritas will know to perform each query *natively* and then join the results in-memory seamlessly. It should also be possible to reorganize the queries so that as much work as possible is done natively as opposed to in-memory, which is considered the last resort.
+
+Not only does this work nicely with associations, but it will allow DataMapper to perform mapping in a more powerful way. You'll be able to construct a join from multiple datastores, and set that as the base for your model. Each DM Resource would work as normal, but again writes could be propagated back to the appropriate datastore. You'd be able to split your data up between different datastores, but assemble it into one coherent view.
+
+### Phase 1: In-Memory Operations
+
+The first phase of this project will be to implement all the operations listed below using in-memory data structures. I'm focusing on the API, and making sure the specs ensure the desired results are obtained from each operation.
+
+This is 100% complete.
+
+### Phase 2: RDBMS Engines
+
+The second phase of this project will be to add a RDBMS based engine, and move the in-memory matching to it's own engine. I'll also be working on a system where if the primary engine cannot carry out some operation, that it first look at alternate forms (eg. using a join instead of an intersection), and then fall-back to in-memory matching. I also want to look at re-arranging queries so that all the operations that can be performed natively are "pushed down" the hierarchy and then the in-memory matching is performed last.
+
+This is 95% complete. I have completed a first pass on [veritas-sql-generator](https://github.com/dkubb/veritas-sql-generator) which is a visitor that walks the AST and produces SQL for every operatione. More work is needed to write adapters that use the veritas-sql-generator and manage database connections/execution.
+
+### Phase 3: DataMapper Integration
+
+The third phase of this project will be to add a few NoSQL engines (like [MongoDB](http://www.mongodb.org/) and [CouchDB](http://couchdb.org/)) and then look at writing a DataMapper adapter that translates Query objects into Veritas relations. I want to make sure all the DM specs pass with this adapter and each engine, and if everything goes well I will look at updating DM to work directly on top of Veritas.
+
+## Related Projects
+
+* [veritas-optimizer](https://github.com/dkubb/veritas-optimizer)
+
+This is an optimizer that takes a veritas relation, scalar or aggregate function and will transform it into something equivalent but simpler in structure to the original.
+
+* [veritas-sql-generator](https://github.com/dkubb/veritas-sql-generator)
+
+This is a visitor class that takes a veritas relation and generates valid SQL from it.
+
+* [veritas-do-adapter](https://github.com/dkubb/veritas-do-adapter)
+
+This is a system that manages the database connections and executes the SQL generated fom the relations.
+
+## Note on Patches/Pull Requests
+
+* If you want your code merged into the mainline, please discuss the proposed changes with me before doing any work on it. This library is still in early development, and it may not always be clear the direction it is going. Some features may not be appropriate yet, may need to be deferred until later when the foundation for them is laid, or may be more applicable in a plugin.
+* Fork the project.
+* Make your feature addition or bug fix.
+  * Follow this [style guide](https://github.com/dkubb/styleguide).
+* Add specs for it. This is important so I don't break it in a future version unintentionally. Tests must cover all branches within the code, and code must be fully covered.
+* Commit, do not mess with Rakefile, version, or history.  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Run "rake ci". This must pass and not show any regressions in the
+  metrics for the code to be merged.
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright © 2009-2011 Dan Kubb. See LICENSE for details.

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake'
 require File.expand_path('../lib/veritas/version', __FILE__)
 
 begin
-  gem('jeweler', '~> 1.6.2') if respond_to?(:gem, true)
+  gem('jeweler', '~> 1.6.4') if respond_to?(:gem, true)
   require 'jeweler'
 
   Jeweler::Tasks.new do |gem|
@@ -23,5 +23,5 @@ begin
 
   FileList['tasks/**/*.rake'].each { |task| import task }
 rescue LoadError
-  puts 'Jeweler (or a dependency) not available. Install it with: gem install jeweler -v 1.6.2'
+  puts 'Jeweler (or a dependency) not available. Install it with: gem install jeweler -v 1.6.4'
 end

data/TODO

@@ -1,8 +1,3 @@
-* Materialized relations need to hold a reference to the original relation.
-  * Especially "empty" relations should hold a reference to the original
-    relation so that insert/update can be performed on them if they are
-    empty not because they are valid, but because the source object is empty
-
 * Remove Order, Reverse, Limit and Offset from the Relation inheritance chain
   * Instead make it so they are proxy classes that wrap Relations, but
     proxy method calls to the Relation methods, and then wrap the return
@@ -34,17 +29,6 @@
   like with #hash that accept no args, and #optimize that accepts
   1 arg.
 
-* Add Relation#antijoin
-  * Allows "NOT EXISTS/IN" type queries to be executes where every tuple
-    from the relation is returned that *does not* join with the tuples in
-    the operand.
-
-* Inclusion/Exclusion improvements:
-  * Allow attribute/function expressions to exist within the enumerable part
-    of the Inclusion and Exclusion operations
-    * The #call method should propagate the Tuple down to each callable entry
-      in the Enumerable.
-
 * Within the restriction context, make sure the attributes have aliases for:
   * Alias #== to #eq (may break alot)
   * Alias #!= to #ne (in 1.9 only)

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
 threshold: 68
-total_score: 738
+total_score: 682

data/config/flog.yml

@@ -1,2 +1,2 @@
 ---
-threshold: 15.7
+threshold: 23.3

data/config/roodi.yml

@@ -1,18 +1,18 @@
 ---
-AbcMetricMethodCheck:            { score: 11.8 }
+AbcMetricMethodCheck:            { score: 10.3 }
 AssignmentInConditionalCheck:    { }
 CaseMissingElseCheck:            { }
-ClassLineCountCheck:             { line_count: 390 }
+ClassLineCountCheck:             { line_count: 289 }
 ClassNameCheck:                  { pattern: !ruby/regexp /\A(?:[A-Z]+|[A-Z][a-z](?:[A-Z]?[a-z])+)\z/ }
 ClassVariableCheck:              { }
 CyclomaticComplexityBlockCheck:  { complexity: 2 }
-CyclomaticComplexityMethodCheck: { complexity: 5 }
+CyclomaticComplexityMethodCheck: { complexity: 4 }
 EmptyRescueBodyCheck:            { }
 ForLoopCheck:                    { }
 # TODO: decrease line_count to 5 to 10
 MethodLineCountCheck:            { line_count: 14 }
 MethodNameCheck:                 { pattern: !ruby/regexp /\A(?:[a-z\d](?:_?[a-z\d])+[?!=]?|\[\]=?|==|<=>|[+*&|-])\z/ }
-ModuleLineCountCheck:            { line_count: 392 }
+ModuleLineCountCheck:            { line_count: 291 }
 ModuleNameCheck:                 { pattern: !ruby/regexp /\A(?:[A-Z]+|[A-Z][a-z](?:[A-Z]?[a-z])+)\z/ }
 # TODO: decrease parameter_count to 2 or less
 ParameterNumberCheck:            { parameter_count: 3 }

data/config/site.reek

@@ -8,10 +8,10 @@ UncommunicativeParameterName:
   - !ruby/regexp /[0-9]$/
   - !ruby/regexp /[A-Z]/
 LargeClass:
-  max_methods: 15  # TODO: decrease max_methods to 10-15 or less
+  max_methods: 14  # TODO: decrease max_methods to 10-15 or less
   exclude: []
   enabled: true
-  max_instance_variables: 5
+  max_instance_variables: 4
 UncommunicativeMethodName:
   accept: []
   exclude: []
@@ -46,7 +46,11 @@ UncommunicativeModuleName:
   - !ruby/regexp /[0-9]$/
 NestedIterators:
   ignore_iterators: []
-  exclude: []
+  exclude: [
+    # none of these use nested iterators, they use nested blocks only
+    Veritas::Comparator#define_comparison_method,
+    Veritas::Comparator#define_hash_method
+  ]
   enabled: true
   max_allowed_nesting: 1
 LongMethod:

data/lib/veritas/aggregate.rb

@@ -4,8 +4,11 @@ module Veritas
 
   # Abstract class for aggregate functions
   class Aggregate
+    extend Comparator
     include AbstractClass, Immutable, Visitable, Operation::Unary
 
+    compare :operand
+
     # Return the default accumulator
     #
     # @example
@@ -96,6 +99,21 @@ module Veritas
       raise NotImplementedError, "#{self.class}#type must be implemented"
     end
 
+    # Compare the aggregate with other aggregate for equivalency
+    #
+    # @example
+    #   aggregate == other  # => true or false
+    #
+    # @param [Aggregate] other
+    #   the other aggregate to compare with
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def ==(other)
+      cmp?(__method__, other)
+    end
+
   private
 
     # Extract the value from the operand or tuple

data/lib/veritas/algebra/extension.rb

@@ -7,6 +7,8 @@ module Veritas
     class Extension < Relation
       include Relation::Operation::Unary
 
+      compare :operand, :extensions
+
       # The extensions for the relation
       #
       # @return [Hash]
@@ -52,33 +54,6 @@ module Veritas
         self
       end
 
-      # Compare the Extension with other relation for equality
-      #
-      # @example
-      #   extension.eql?(other)  # => true or false
-      #
-      # @param [Relation] other
-      #   the other relation to compare with
-      #
-      # @return [Boolean]
-      #
-      # @api public
-      def eql?(other)
-        super && extensions.eql?(other.extensions)
-      end
-
-      # Return the hash of the projection
-      #
-      # @example
-      #   hash = extension.hash
-      #
-      # @return [Fixnum]
-      #
-      # @api public
-      def hash
-        super ^ extensions.hash
-      end
-
       module Methods
 
         # Return an extended relation
@@ -106,8 +81,6 @@ module Veritas
 
       Relation.class_eval { include Methods }
 
-      memoize :hash
-
     end # class Extension
   end # module Algebra
 end # module Veritas

data/lib/veritas/algebra/projection.rb

@@ -7,6 +7,8 @@ module Veritas
     class Projection < Relation
       include Relation::Operation::Unary
 
+      compare :operand, :header
+
       # Initialize a Projection
       #
       # @param [Relation] operand
@@ -46,33 +48,6 @@ module Veritas
         self
       end
 
-      # Compare the Projection with other relation for equality
-      #
-      # @example
-      #   projection.eql?(other)  # => true or false
-      #
-      # @param [Relation] other
-      #   the other relation to compare with
-      #
-      # @return [Boolean]
-      #
-      # @api public
-      def eql?(other)
-        super && header.eql?(other.header)
-      end
-
-      # Return the hash of the projection
-      #
-      # @example
-      #   hash = projection.hash
-      #
-      # @return [Fixnum]
-      #
-      # @api public
-      def hash
-        super ^ header.hash
-      end
-
       module Methods
 
         # Return a relation with only the attributes specified
@@ -137,8 +112,6 @@ module Veritas
 
       Relation.class_eval { include Methods }
 
-      memoize :hash
-
     end # class Projection
   end # module Algebra
 end # module Veritas

data/lib/veritas/algebra/rename/aliases.rb

@@ -6,9 +6,11 @@ module Veritas
 
       # Aliases that map old attributes to new renamed attributes
       class Aliases
-        extend Aliasable
+        extend Aliasable, Comparator
         include Immutable, Enumerable
 
+        compare :to_hash
+
         inheritable_alias(:| => :union)
 
         # Instantiate new set of Aliases
@@ -145,35 +147,7 @@ module Veritas
         #
         # @api public
         def ==(other)
-          to_hash == other.to_hash
-        end
-
-        # Compare the aliases with other aliases for equality
-        #
-        # @example
-        #   aliases.eql?(other)  # => true or false
-        #
-        # @param [Aliases] other
-        #   the other aliases to compare with
-        #
-        # @return [Boolean]
-        #
-        # @api public
-        def eql?(other)
-          instance_of?(other.class) &&
-          to_hash.eql?(other.to_hash)
-        end
-
-        # Return the hash of the aliases
-        #
-        # @example
-        #   hash = aliases.hash
-        #
-        # @return [Fixnum]
-        #
-        # @api public
-        def hash
-          self.class.hash ^ @aliases.hash
+          cmp?(__method__, other)
         end
 
         # Convert the aliases to a Hash
@@ -226,8 +200,6 @@ module Veritas
 
         private_class_method :coerce_alias_pair
 
-        memoize :hash
-
       end # class Aliases
     end # class Rename
   end # module Algebra

data/lib/veritas/algebra/rename.rb

@@ -7,6 +7,8 @@ module Veritas
     class Rename < Relation
       include Relation::Operation::Unary
 
+      compare :operand, :aliases
+
       # The aliases for the relation
       #
       # @return [Aliases]
@@ -58,33 +60,6 @@ module Veritas
         self
       end
 
-      # Compare the Rename with other relation for equality
-      #
-      # @example
-      #   rename.eql?(other)  # => true or false
-      #
-      # @param [Relation] other
-      #   the other relation to compare with
-      #
-      # @return [Boolean]
-      #
-      # @api public
-      def eql?(other)
-        super && aliases.eql?(other.aliases)
-      end
-
-      # Return the hash of the rename
-      #
-      # @example
-      #   hash = rename.hash
-      #
-      # @return [Fixnum]
-      #
-      # @api public
-      def hash
-        super ^ aliases.hash
-      end
-
       module Methods
 
         # Return a relation with the header renamed
@@ -106,8 +81,6 @@ module Veritas
 
       Relation.class_eval { include Methods }
 
-      memoize :hash
-
     end # class Rename
   end # module Algebra
 end # module Veritas

data/lib/veritas/algebra/restriction.rb

@@ -7,6 +7,8 @@ module Veritas
     class Restriction < Relation
       include Relation::Operation::Unary
 
+      compare :operand, :predicate
+
       # The predicate for the relation
       #
       # @return [Function, #call]
@@ -51,33 +53,6 @@ module Veritas
         self
       end
 
-      # Compare the Restriction with other relation for equality
-      #
-      # @example
-      #   restriction.eql?(other)  # => true or false
-      #
-      # @param [Relation] other
-      #   the other relation to compare with
-      #
-      # @return [Boolean]
-      #
-      # @api public
-      def eql?(other)
-        super && predicate.eql?(other.predicate)
-      end
-
-      # Return the hash of the restriction
-      #
-      # @example
-      #   hash = restriction.hash
-      #
-      # @return [Fixnum]
-      #
-      # @api public
-      def hash
-        super ^ predicate.hash
-      end
-
       module Methods
 
         # Return a relation with restricted tuples
@@ -106,8 +81,6 @@ module Veritas
 
       Relation.class_eval { include Methods }
 
-      memoize :hash
-
     end # class Restriction
   end # module Algebra
 end # module Veritas