veritas 0.0.1

data/.autotest

@@ -0,0 +1,42 @@
+begin
+  require 'autotest/fsevent'
+rescue LoadError
+  # do nothing
+end
+
+MATCH_ALL_SPECS = %r{\Aspec/.+_spec\.rb\z}.freeze
+
+Autotest.add_hook :initialize do |at|
+  at.clear_mappings
+
+  # run the spec if it is modified
+  at.add_mapping(MATCH_ALL_SPECS) { |filename, _| filename }
+
+  # run specs if core_ext patches are modified
+  at.add_mapping(%r{\Alib/veritas/core_ext/(.+)\.rb\z}) do |_, match|
+    at.files_matching %r{\Aspec/unit/#{Regexp.quote(match[1])}/.*_spec\.rb\z}
+  end
+
+  # run specs if support libs are modified
+  at.add_mapping(%r{\Alib/veritas/support/(.+)\.rb\z}) do |_, match|
+    at.files_matching %r{\Aspec/unit/veritas/#{Regexp.quote(match[1])}/.*_spec\.rb\z}
+  end
+
+  # run specs if the main libs are modified
+  at.add_mapping(%r{\Alib/(.+)\.rb\z}) do |_, match|
+    at.files_matching %r{\Aspec/unit/#{Regexp.quote(match[1])}/.*_spec\.rb\z}
+  end
+
+  # run all specs if the spec_helper or spec support lib are modified
+  at.add_mapping(%r{\Aspec/(?:spec_helper\.rb|(?:support|shared)/.+)\z}) do
+    at.files_matching MATCH_ALL_SPECS
+  end
+
+  at.add_exception('.git')
+
+  File.foreach('.gitignore') do |line|
+    line.strip!
+    next if line.empty? || line[0, 1] == '#'
+    at.add_exception(File.expand_path(line))
+  end
+end

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,34 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## Rubinius
+*.rbc
+
+## PROJECT::GENERAL
+*.gem
+coverage
+profiling
+rdoc
+pkg
+tmp
+doc
+log
+.yardoc
+measurements
+
+## BUNDLER
+.bundle
+
+## PROJECT::SPECIFIC

data/Gemfile

@@ -0,0 +1,25 @@
+source :rubygems
+
+gemspec
+
+platforms :mri_18 do
+  group :quality do
+    gem 'activesupport', '~> 2.3.10'
+    gem 'flay',          '~> 1.4.1'
+    gem 'flog',          '~> 2.4.0', :git => 'git://github.com/dkubb/flog.git'
+    gem 'heckle',        '~> 1.4.3'
+    gem 'json',          '~> 1.4.6'
+    gem 'metric_fu',     '~> 2.0.1'
+    gem 'mspec',         '~> 1.5.17'
+    gem 'rcov',          '~> 0.9.9'
+    gem 'reek',          '~> 1.2.8'
+    gem 'roodi',         '~> 2.1.0'
+    gem 'ruby2ruby',     '=  1.2.2'
+    gem 'yard',          '~> 0.6.1'
+    gem 'yardstick',     '~> 0.2.0'
+  end
+end
+
+group :benchmarks do
+  gem 'rbench', '~> 0.2.3'
+end

data/Gemfile.lock

@@ -0,0 +1,122 @@
+GIT
+  remote: git://github.com/dkubb/flog.git
+  revision: 4522d547d0f2977dd581be24a8a9985d78699e4c
+  specs:
+    flog (2.4.0)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+
+PATH
+  remote: .
+  specs:
+    veritas (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ParseTree (3.0.6)
+      RubyInline (>= 3.7.0)
+      sexp_processor (>= 3.0.0)
+    RubyInline (3.8.6)
+      ZenTest (~> 4.3)
+    Saikuro (1.1.0)
+    ZenTest (4.4.0)
+    activesupport (2.3.10)
+    arrayfields (4.7.4)
+    backports (1.18.2)
+    chronic (0.2.3)
+      hoe (>= 1.2.1)
+    churn (0.0.12)
+      chronic (~> 0.2.3)
+      hirb
+      json_pure
+      main
+      ruby_parser (~> 2.0.4)
+      sexp_processor (~> 3.0.3)
+    colored (1.2)
+    fattr (2.2.0)
+    flay (1.4.1)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    gemcutter (0.6.1)
+    git (1.2.5)
+    heckle (1.4.3)
+      ParseTree (>= 2.0.0)
+      ZenTest (>= 3.5.2)
+      ruby2ruby (>= 1.1.6)
+    hirb (0.3.5)
+    hoe (2.7.0)
+      rake (>= 0.8.7)
+      rubyforge (>= 2.0.4)
+    jeweler (1.4.0)
+      gemcutter (>= 0.1.0)
+      git (>= 1.2.5)
+      rubyforge (>= 2.0.0)
+    json (1.4.6)
+    json_pure (1.4.6)
+    main (4.3.0)
+      arrayfields (>= 4.7.4)
+      fattr (>= 2.1.0)
+    metric_fu (2.0.1)
+      Saikuro (>= 1.1.0)
+      activesupport (>= 2.0.0)
+      chronic (~> 0.2.3)
+      churn (>= 0.0.7)
+      flay (>= 1.2.1)
+      flog (>= 2.2.0)
+      rails_best_practices (>= 0.3.16)
+      rcov (>= 0.8.3.3)
+      reek (>= 1.2.6)
+      roodi (>= 2.1.0)
+    mspec (1.5.17)
+    progressbar (0.9.0)
+    rails_best_practices (0.5.0)
+      activesupport
+      colored (~> 1.2)
+      progressbar (~> 0.9.0)
+      ruby_parser (~> 2.0.4)
+    rake (0.8.7)
+    rbench (0.2.3)
+    rcov (0.9.9)
+    reek (1.2.8)
+      ruby2ruby (~> 1.2)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    roodi (2.1.0)
+      ruby_parser
+    rspec (1.3.1)
+    ruby2ruby (1.2.2)
+      ParseTree (~> 3.0)
+    ruby_parser (2.0.5)
+      sexp_processor (~> 3.0)
+    rubyforge (2.0.4)
+      json_pure (>= 1.1.7)
+    sexp_processor (3.0.5)
+    yard (0.6.2)
+    yardstick (0.2.0)
+      yard (~> 0.6.1)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 2.3.10)
+  backports (~> 1.18.2)
+  flay (~> 1.4.1)
+  flog (~> 2.4.0)!
+  heckle (~> 1.4.3)
+  jeweler (~> 1.4.0)
+  json (~> 1.4.6)
+  metric_fu (~> 2.0.1)
+  mspec (~> 1.5.17)
+  rake (~> 0.8.7)
+  rbench (~> 0.2.3)
+  rcov (~> 0.9.9)
+  reek (~> 1.2.8)
+  roodi (~> 2.1.0)
+  rspec (~> 1.3.1)
+  ruby2ruby (= 1.2.2)
+  veritas!
+  yard (~> 0.6.1)
+  yardstick (~> 0.2.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Dan Kubb
+
+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.rdoc

@@ -0,0 +1,143 @@
+= Veritas
+
+Simplifies querying of structured data using relational algebra
+
+== 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[http://github.com/carllerche/koios] and arel[http://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 has been marked as 90% complete for some time. In actuality most of the features below are completed besides the first examples for #extend and #summarize. Those will require a system to define functions as objects that can be introspected and walked to "visit" and generate SQL or other query languages from them. The Proc based functions are opaque and will probably never be possible to generate native queries from them. For this reason they will only be recommended when they depends on functionality not available in the datastore.
+
+=== Phase 2: RDBMS Engines
+
+The second phase of this project will be to add an 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.
+
+=== 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.
+
+== Usage
+
+  relation = Veritas::Relation.new([ [ :id, Integer ] ], [ [ 1 ] ])
+
+  # Relational Operators
+  # --------------------
+
+  # projection
+  new_relation = relation.project([ :a, :b, :c ])
+
+  # removal
+  new_relation = relation.remove([ :a, :b, :c ])
+
+  # rename
+  new_relation = relation.rename(:a => :b, :c => :d)
+
+  # 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
+
+  # restriction
+  new_relation = relation.restrict(relation.name.eq('other'))
+  new_relation = relation.restrict { |r| r[:a].eq('other').and(r[:b].gte(42)) }
+
+  # theta-join
+  new_relation = relation.join(other, relation[:a].gte(other[:b]))
+  new_relation = relation.join(other) { |r| r[:a].gte(r[:b]) }
+
+  # NOTE: theta-join is effectively restricting a product of the relations
+
+  # extend
+  new_relation = relation.extend { |r| r.add(:total, r[:unit_price] * r[:quantity]) }
+  new_relation = relation.extend { |r| r.add(:total) { |t| t[:unit_price] * t[:quantity] } }
+
+  # summarize
+  new_relation = relation.summarize(relation.project([ :name ])) { |r| r.add(:count, r[:name].count)
+  new_relation = relation.summarize(relation.project([ :name ])) { |r| r.add(:count) { |acc, t| acc.to_i + 1 } }
+
+  # Non-Relational Operators
+  # ------------------------
+
+  # returns a set that represents the relation header
+  header = relation.header
+
+  # simplifies and normalizes the relation operations
+  optimized_relation = relation.optimize
+
+  # a relation is Enumerable
+  relation = relation.each { |tuple| ... }
+
+  # order by attribute and direction
+  new_relation = relation.order([ relation[:a].desc, relation[:b] ])
+  new_relation = relation.order { |r| [ r[:a].desc, r[:b] ] }
+
+  # limiting (only allowed if ordered)
+  new_relation = relation.take(10)
+
+  # offset (only allowed if ordered)
+  new_relation = relation.drop(5)
+
+  # get the first n tuples (only allowed if ordered)
+  new_relation = relation.first     # default is 1
+  new_relation = relation.first(5)
+
+  # get the last n tuples (only allowed if ordered)
+  new_relation = relation.last      # default is 1
+  new_relation = relation.last(5)
+
+  # reverse the relation (only allowed if ordered)
+  new_relation = relation.reverse
+
+  # CRUD Operators
+  # --------------
+
+  # can only modify relations that project all candidate keys for the base relations
+  new_relation = relation.create(:a => 'test', :b => 'other', :c => 'yet another')
+  new_relation = relation.update(:a => 'test', :b => 'other', :c => 'yet another')
+  new_relation = relation.delete
+
+== 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 styleguide: http://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 (c) 2010 Dan Kubb. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rake'
+
+require File.expand_path('../lib/veritas/version', __FILE__)
+
+begin
+  gem('jeweler', '~> 1.4.0') if respond_to?(:gem, true)
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gem|
+    gem.name        = 'veritas'
+    gem.summary     = 'Ruby Relational Algebra'
+    gem.description = 'Simplifies querying of structured data using relational algebra'
+    gem.email       = 'dan.kubb@gmail.com'
+    gem.homepage    = 'http://github.com/dkubb/veritas'
+    gem.authors     = [ 'Dan Kubb' ]
+    gem.has_rdoc    = 'yard'
+
+    gem.version = Veritas::VERSION
+
+    gem.add_development_dependency 'rake',      '~> 0.8.7'
+    gem.add_development_dependency 'rspec',     '~> 1.3.1'
+    gem.add_development_dependency 'jeweler',   '~> 1.4.0'
+    gem.add_development_dependency 'backports', '~> 1.18.2'
+  end
+
+  Jeweler::GemcutterTasks.new
+
+  FileList['tasks/**/*.rake'].each { |task| import task }
+rescue LoadError
+  puts 'Jeweler ~> 1.4.0 (or a dependency) not available. Install it with: gem install jeweler'
+end

data/TODO

@@ -0,0 +1,126 @@
+* Add Extension and Summarization Functions
+  * Overview: http://gist.github.com/584588
+
+* 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
+    value (assuming it's a Relation) in a copy of itself.
+  * Also this will allow knowledge of #directions to be removed from
+    all the Relation classes. Only the Ranking classes will need to know
+    about directions.
+  * We can also do things like optimize away an Order that is not
+    wrapped by a Limit/Offset if it is wrapped in Join or Set relation.
+    We can do this because joining sorted relations results in
+    an undefined sort order depending on the algorithm used to join
+    the tuples. The correct approach to get unambiguous results is to
+    wrap the Join in an Order.
+  * The Reverse class will probably not be needed either. All we need is
+    for the #reverse method to create a new Order with the directions
+    reversed.
+  * Remove the knowledge of directions from materialized relations
+    and instead wrap materialized relations in the Order object
+    if any.
+
+* Add further optimizations:
+  * Operation Order:
+    * Projection should follow Rename
+      * When a Projection contains a Restriction, wrap the Projection
+        in the Restriction, projecting away any attributes not used in
+        the restriction. If there are any remaining attributes, then
+        wrap the operation in a Projection removing those attributes.
+        * If all attributes are being used in the Restriction do nothing
+      * When a Projection contains a Join, wrap the Join with a Projection
+        of all the headers, minus those used in the Join. If there were
+        any used, then wrap the whole operation in a Projection with
+        the remaining attributes.
+        * If all the attributes are used in the Join, do nothing
+        * Try to use the same approach for Product
+        * Test if it's possible to fully distribute projections over
+          joins rather than splitting it up like this.
+    * Restriction should follow Projection
+      * Restriction optimizations:
+        * "attr > ? OR attr > ?" -> "attr > ?", with the least restrictive value
+          * Do the same for >=, <, <=
+        * "attr > ? AND attr > ?" -> "attr > ?", with the most restrictive value
+          * Do the same for >=, <, <=
+        * "attr > 5 OR attr == 5" -> "attr >= 5"
+        * "attr < 5 OR attr == 5" -> "attr <= 5"
+        * "attr" = "string" AND "attr" =~ /string/ -> "attr" = "string"
+          * If the regexp matches the constant, then it should be
+            optimized down to a constant match. If it does not match
+            then it should be optimized to False.
+        * Constant folding, eg:
+          "attr1 > attr2 AND attr1 = 5" -> "5 > attr2 AND attr1 = 5"
+          * This will probably only work across Conjunctions.
+        * "attr > 5 AND attr = 6" -> "attr = 6", because attr must be
+          equal to 6. this will probably be related to constant folding;
+          the first expression will become 6 > 5, which evaluates to
+          True, then the expression is True AND attr = 6, which simplifies
+          down to attr = 6.
+        * "attr < 5 AND attr = 6" -> "False", because attr must be equal to
+          6, and 6 < 5 evaluates to False.  False AND attr = 6 simplifies
+          down to False.
+      * Figure out how to reorganize the Restriction predicates so that all
+        similar operations are closer together to allow more efficient
+        optimizations. This would allow optimizations of stuff like this:
+
+          "attr1 = ? OR attr2 = ? OR attr1 = ?"
+
+        Into:
+
+          "attr1 IN(..) OR attr2 = ?"
+    * Rename should distribute over Join, Product and Set operations
+      * The goal should be to push Rename as close to the base tables
+        as possible so that the names of attribute will be consistent
+        throughout the whole tree.
+  * A Union of relations with the same base, header, and restrictions should
+    try to combine into a single relation with the restrictions using OR.
+  * An Intersection of relations with the same base, header, and restrictions
+    should try to combine into a single relation with the restrictions using
+    AND.
+  * A Difference of relations with the same base and restrictions should
+    try to combine into a single relation with the restrictions using NOT.
+  * Join Optimizations
+    * When a Join contains a Join, and the size of the base relations is
+      known, join the smallest with the largest, and then join that result
+      with the remaining relation.
+    * Make sure the smallest relation (with a known size) is always the
+      right-most operation.
+
+* Allow Inclusion match to accept a Relation
+  * Ensure that Inclusion can have the left/right be an Array of
+    Attributes.
+  * Consider transforming the value provided to an Inclusion into
+    a Relation.
+
+* Update Attributes so that constraints are modelled using predicates,
+  so that when "join-ability" is tested, the predicates can just be
+  compared for equality.
+  * Create an object that can wrap a predicate, and if it fails it will
+    set the object's error state, and then propagate the status to the
+    caller. This will allow a "complex" predicate to set the errors
+    on tuples, while still allowing all the same objects to be used.
+
+* Add Relation#antijoin
+
+* Add Relation#nest and Relation#unnest
+
+* Add aliases for some common operations in Method classes, eg:
+  * Predicates:
+    * Alias #== to #eq (may break alot)
+    * Alias #!= to #ne (in 1.9 only)
+    * Alias #>= to #gte
+    * Alias #> to #gt
+    * Alias #<= to #lte
+    * Alias #< to #lt
+    * Alias #=~ to #match
+  * Direction:
+    * Alias #@+ to #asc
+    * Alias #@- to #desc
+
+* Update memoization to take into account the arguments passed into
+  the method. It should memoize differently for different
+  methods. Perhaps it could have a special case for methods
+  with a 0-arity vs n-arity methods, but it needs to handle cases
+  like with #hash that accept no args, and #optimize that accepts
+  1 arg.