axiom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 918161948535c59c8eaec2a5d5da0e287f7453f6
+  data.tar.gz: 54109ae07a49a23ca7c370b85a9fe95022000f31
+SHA512:
+  metadata.gz: 51106a149efe43e41c86f252efc8afc7c96f302bc8d99bd870b83d756a0f18d3b7df12e725f63947f6ab9700ba3a39d41f23dba049730c20c5dfc25d37f12bd6
+  data.tar.gz: e816775476690b89236613881eead6a07c11dcddc6cdb7f646a00ed676d1f3e284ff49c18c442e97f7541be53c0f859d8190c5de01db379f7cc66810c301b918

data/.gitignore

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

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format progress
+--profile
+--order random

data/.rvmrc

@@ -0,0 +1 @@
+rvm use @$(basename `pwd`) --create

data/.travis.yml

@@ -0,0 +1,35 @@
+language: ruby
+before_install: gem install bundler
+bundler_args: --without yard guard benchmarks
+script: "bundle exec rake ci"
+rvm:
+  - ree
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - ruby-head
+  - rbx-18mode
+  - rbx-19mode
+  - jruby-18mode
+notifications:
+  irc:
+    channels:
+      - irc.freenode.org#datamapper
+    on_success: never
+    on_failure: change
+  email:
+    recipients:
+      - dan.kubb@gmail.com
+    on_success: never
+    on_failure: change
+matrix:
+  include:
+    - rvm: jruby-19mode
+      env: JRUBY_OPTS="$JRUBY_OPTS --debug"
+    - rvm: jruby-head
+      env: JRUBY_OPTS="$JRUBY_OPTS --debug"
+  allow_failures:
+    # mutant fails
+    - rvm: 1.9.3
+    - rvm: rbx-19mode

data/.yardopts

@@ -0,0 +1,4 @@
+--quiet
+README.md
+lib/**/*.rb
+LICENSE

data/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+Contributing
+------------
+
+* 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 the direction it is going may not always be clear. 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.

data/Gemfile

@@ -0,0 +1,8 @@
+# encoding: utf-8
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'devtools', :git => 'https://github.com/datamapper/devtools.git'
+eval File.read('Gemfile.devtools')

data/Gemfile.devtools

@@ -0,0 +1,57 @@
+# encoding: utf-8
+
+group :development do
+  gem 'rake',  '~> 10.0.4'
+  gem 'rspec', '~> 2.13.0'
+  gem 'yard',  '~> 0.8.5.2'
+end
+
+group :yard do
+  gem 'kramdown', '~> 1.0.1'
+end
+
+group :guard do
+  gem 'guard',         '~> 1.7.0'
+  gem 'guard-bundler', '~> 1.0.0'
+  gem 'guard-rspec',   '~> 2.5.2'
+
+  # file system change event handling
+  gem 'listen',     '~> 0.7.3'
+  gem 'rb-fchange', '~> 0.0.6', :require => false
+  gem 'rb-fsevent', '~> 0.9.3', :require => false
+  gem 'rb-inotify', '~> 0.9.0', :require => false
+
+  # notification handling
+  gem 'libnotify',               '~> 0.8.0', :require => false
+  gem 'rb-notifu',               '~> 0.0.4', :require => false
+  gem 'terminal-notifier-guard', '~> 1.5.3', :require => false
+end
+
+group :metrics do
+  gem 'backports',       '~> 3.3', '>= 3.3.0'
+  gem 'coveralls',       '~> 0.6.4'
+  gem 'flay',            '~> 2.1.0'
+  gem 'flog',            '~> 3.2.3'
+  gem 'reek',            '~> 1.3.1', :git => 'https://github.com/troessner/reek.git'
+  gem 'simplecov',       '~> 0.7.1'
+  gem 'yardstick',       '~> 0.9.5'
+  gem 'yard-spellcheck', '~> 0.1.5'
+
+  platforms :mri_19, :rbx do
+    gem 'mutant', '~> 0.2.20'
+  end
+
+  platforms :rbx do
+    gem 'pelusa', '~> 0.2.2'
+  end
+end
+
+group :benchmarks do
+  gem 'rbench', '~> 0.2.3'
+end
+
+platform :jruby do
+  group :jruby do
+    gem 'jruby-openssl', '~> 0.8.5'
+  end
+end

data/Guardfile

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+guard :bundler do
+  watch('Gemfile')
+end
+
+guard :rspec, :cli => File.read('.rspec').split.join(' '), :keep_failed => false do
+  # run all specs if configuration is modified
+  watch('Guardfile')           { 'spec' }
+  watch('Gemfile.lock')        { 'spec' }
+  watch('spec/spec_helper.rb') { 'spec' }
+
+  # run all specs if supporting files files are modified
+  watch(%r{\Aspec/(?:lib|support|shared)/.+\.rb\z}) { 'spec' }
+
+  # run unit specs if associated lib code is modified
+  watch(%r{\Alib/(.+)\.rb\z})                                         { |m| Dir["spec/unit/#{m[1]}"]         }
+  watch(%r{\Alib/(.+)/support/(.+)\.rb\z})                            { |m| Dir["spec/unit/#{m[1]}/#{m[2]}"] }
+  watch("lib/#{File.basename(File.expand_path('../', __FILE__))}.rb") { 'spec'                               }
+
+  # run a spec if it is modified
+  watch(%r{\Aspec/(?:unit|integration)/.+_spec\.rb\z})
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2013 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.md

@@ -0,0 +1,187 @@
+axiom
+=====
+
+Simplifies querying of structured data using relational algebra.
+
+[![Gem Version](https://badge.fury.io/rb/axiom.png)][gem]
+[![Build Status](https://secure.travis-ci.org/dkubb/axiom.png?branch=master)][travis]
+[![Dependency Status](https://gemnasium.com/dkubb/axiom.png)][gemnasium]
+[![Code Climate](https://codeclimate.com/github/dkubb/axiom.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/dkubb/axiom/badge.png?branch=master)][coveralls]
+
+[gem]: https://rubygems.org/gems/axiom
+[travis]: https://travis-ci.org/dkubb/axiom
+[gemnasium]: https://gemnasium.com/dkubb/axiom
+[codeclimate]: https://codeclimate.com/github/dkubb/axiom
+[coveralls]: https://coveralls.io/r/dkubb/axiom
+
+Installation
+------------
+
+With Rubygems:
+
+```bash
+$ gem install axiom
+$ irb -rubygems
+>> require 'axiom'
+=> true
+```
+
+With git and local working copy:
+
+```bash
+$ git clone git://github.com/dkubb/axiom.git
+$ cd axiom
+$ rake install
+$ irb -rubygems
+>> require 'axiom'
+=> true
+```
+
+Usage
+-----
+
+```ruby
+relation = Axiom::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')) }
+new_relation = relation.restrict(relation.name.eq('Screw'))
+new_relation = relation.restrict(name: 'Screw')
+new_relation = relation.restrict([ [ :name, 'Screw' ] ])
+
+# 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)
+
+# get a tuple from a relation containing exactly one tuple
+tuple = relation.one
+
+# Updatable Views
+# ---------------
+
+# add a set to a relation variable
+new_relation = relation.insert(other)
+
+# remove a set from a relation variable
+new_relation = relation.delete(other)
+
+# replace a relation variable with another set
+new_relation = relation.replace(other)
+
+# each subset of unique keys as header objects
+keys = header.keys
+```
+
+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 updatable 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 Axiom 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.
+
+Related Projects
+----------------
+
+* [axiom-optimizer](https://github.com/dkubb/axiom-optimizer)
+
+This is an optimizer that takes a Axiom relation, scalar or aggregate function and will transform it into something equivalent but simpler in structure to the original.
+
+* [axiom-sql-generator](https://github.com/dkubb/axiom-sql-generator)
+
+This is a visitor class that takes a Axiom relation and generates valid SQL from it.
+
+* [axiom-do-adapter](https://github.com/dkubb/axiom-do-adapter)
+
+This is a system that manages the database connections and executes the SQL generated from the relations.
+
+Contributing
+------------
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+Copyright
+---------
+
+Copyright © 2009-2013 Dan Kubb. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+require 'devtools'
+
+Devtools.init_rake_tasks

data/TODO

@@ -0,0 +1,107 @@
+* TODO:
+
+* Change Algebra::Extension#extensions to be a non-primtive
+  * May also change EvaluationContext#functions to return a set of functions.
+
+* Add key minimization to Header
+  * When unioning two keys together it is really simple to end up
+    with indexes that overlap and cause an exception.
+
+* Add Header#size
+  * Replace code that coerces the Header to an Array in order to get the size
+    with Header#size.
+
+* Make Equalizer handle subclasses without having to specify the attribtues
+  again in each descendant.
+
+* Allow Evaluator::Context to be used like:
+
+    relation.extend { new_extensions }
+
+  This will require the return value from the block to become useful.
+
+* Add domain object for Extensions and Summarizers
+  * Add Evaluator::Context subclasses for Extensions and Summarizers, and return
+    those as instances rather than Hashes of attributes and functions.
+
+* Convert Tuple to a Struct
+  * Make Header a "Struct Class", and copy all the Header instance methods to
+    the class level. Move all the Tuple instance methods into the Header
+    instance.
+    * Rename Header as Tuple
+    * Make sure the Tuple has a class level method called #header that returns
+      the set of attributes.
+    * Use a class variable to store each "Tuple class" so that anything with a
+      similar header will be reused.
+
+* Remove mean/variance/stddev modules from Virtus::Attribute::Comparable
+  * It makes no sense for comparable objects to be "averaged", what would it
+    mean to get the average string?
+
+* 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.
+  * 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 Relation#group and Relation#ungroup
+
+* 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.
+
+* 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.
+
+* Within the restriction context, make sure the attributes have aliases for:
+  * 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
+
+* Within the sort_by context, make sure the attributes have aliases for:
+  * Alias #@+ to #asc
+  * Alias #@- to #desc
+
+* Handle case where one attribute is required, and the other is not, when joined
+  (or other ops), the resulting attribute should always be required.
+  * In other operations, the resulting attribute may be something else, but will
+    need to research to know how to handle this.
+  * Current behaviour is to require both attributes are equivalent all the way
+    around to allow them to be joined. This constraint will need to be relaxed
+    to implement this new behaviour.
+
+* Add operations for efficiently determining the following Enumerable properties
+  of a relation, when no block is provided:
+  * all?
+  * any?
+  * empty?
+  * one?
+  * none?
+  * many?
+  * include? / member?
+  * min / max / minmax (when the tuples are sorted)
+
+* Rename Order to Sorted
+  * In other languages, "ordered" implies that the order tuples are added to the
+    relation is tracked, while "sorted" means that they are sorted according to
+    some criteria. The latter is closer to what is meant.