fluent-query 0.9.0

data/.document

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

data/Gemfile

@@ -0,0 +1,22 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+   gem "hash-utils", ">= 0.18.0"
+   gem "abstract", ">= 1.0.0"
+   gem "hashie", ">= 1.0.0"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0.13"
+  gem "jeweler", "~> 1.6.0"
+end
+
+
+
+# fluent-query-sql
+# fluent-query-dbh
+# fluent-query-mysql
+# fluent-query-sqlite
+# fluent-query-postgresql
+# native-query

data/Gemfile.lock

@@ -0,0 +1,22 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    git (1.2.5)
+    hash-utils (0.18.0)
+    hashie (1.0.0)
+    jeweler (1.6.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.9.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  abstract (>= 1.0.0)
+  bundler (~> 1.0.13)
+  hash-utils (>= 0.18.0)
+  hashie (>= 1.0.0)
+  jeweler (~> 1.6.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2009 - 2011 Martin Kozák (martinkozak@martinkozak.net)
+
+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,230 @@
+Fluent Query
+============
+
+**Fluent Query** is cool way how to write SQL queries and general way 
+how to convert series of method calls to string query in an universal 
+and system independent manner. It may sounds like a piece of magic, but 
+it works. It's inspired by [Dibi][1].
+
+
+### General Principle
+
+Some example:
+
+    connection.select("[id], [name]").from("[maintainers]").orderBy("[code] ASC")
+    
+Will be rendered to:
+
+    SELECT `id`, `name` FROM `maintainers` ORDER BY `code` ASC
+    
+It looks trivial, but for example call `connection.heyReturnMeSomething("[yeah]")` 
+will be transformed to:
+
+    HEY RETURN ME SOMETHING `yeah`
+    
+Which gives big potential. Of sure, escaping, aggregation and chaining 
+of chunks for example for `WHERE` directive or another is necessary. 
+It's ensured by appropriate *language* (e.g. database) *driver*.
+
+And what a more: order of tokens isn't mandatory, so with exception
+of initial world (`SELECT`, `INSERT` etc.) you can add them according to
+your needs.
+
+### Connecting
+
+    # Include it!
+    require "fluent-query/mysql"
+    require "fluent-query"
+    
+    # Setup it!
+    driver = FluentQuery::Drivers::MySQL
+    settings = {
+        :username => "wikistatistics.net",
+        :password => "alfabeta",
+        :server => "localhost",
+        :port => 5432,
+        :database => "wikistatistics.net",
+        :schema => "public"
+    }
+    
+    # Create it!
+    connection = FluentQuery::Connection::new(driver, settings)
+
+Now we have connection prepared for use.
+
+### Placeholders
+
+Simple translation calls to queries isn't the only functionality. Very
+helpful are also *placeholders*. They works principially by the same way
+as `#printf` method, but are more suitable for use in queries and 
+supports automatic quoting. Available are:
+
+* `%%s` which quotes string,
+* `%%i` which quotes integer,
+* `%%b` which quotes boolean,
+* `%%f` which quotes float,
+* `%%d` which quotes date,
+* `%%t` which quotes date-time,
+
+And also three special:
+
+* `%%sql` which quotes subquery (expects query object),
+* `%%and` which joins input by `AND` operator (expects hash),
+* `%%or` which joins input by `OR` operator (expects hash).
+
+An example:
+
+    connection.select("[id], [name]") \
+      .from("[maintainers]") \
+      .where("[id] = %%i AND company = %%s", 5, "Wikia") \
+      .where("[language] IN %%l", ["cz", "en"]) \
+      .or \
+      .where("[active] IS %%b", true)
+      
+Will be transformed to:
+    
+    SELECT `id`, `name` FROM `maintainers` 
+        WHERE `id` = 5 
+            AND `company` = "Wikia"
+            AND `language` IN ("cz", "en")
+            OR `active` IS TRUE
+            
+It's way how to write complex or special queries. But **direct values 
+assigning is supported**, so for example:
+
+    connection.select(:id, :name) \
+      .from(:maintainers) \
+      .where(:id => 5, :company => "Wikia") \
+      .where("[language] IN %%l", ["cz", "en"])   # %l will join items by commas
+      .or \
+      .where(:active => true)
+      
+Will give you expected result too and as you can see, it's much more 
+readable, flexible, thus it's preferred. 
+
+### Checking Out the Results
+
+Query results can be executed by `#execute` which returns result object
+or by `#do` which returns count of affected rows. Following methods for
+checking out the results are available:
+
+* `#each` which iterates through all returned rows,
+* `#one` which returns first row only,
+* `#single` which returns first value fo first row,
+* `#assoc` which allows building complex Hashes (see below).
+    
+#### Associative Fetching
+
+Special associative method is the `assoc` one which is directly inspired
+by appropriate feature of the [Dibi][1] layer. It's aim is automatic
+aggregation of returned rows to multidimensional Hashes.
+
+Simply give it key names from your dataset. Be warn, only one or two 
+levels (e.g. dimesions in resultant Hash) are supported:
+
+    records = connection.select(:maintainer_id, :language) \
+        .from(:sites) \
+        .execute.assoc(:maintainer_id, :language)
+    
+Will transform the dataset:
+
+    # maintainer_id, language, name
+    [1, "en", "English Wikipedia"],
+    [1, "es", "Spain Wikipedia"],
+    [2, "cs", "Czech Wikihow"],
+    [2, "ja", "Japan Wikihow"],
+
+To the following structure:
+
+        1 => {
+            "en" => "English Wikipedia",
+            "es" => "Spain Wikipedia"
+        },
+        
+        2 => {
+            "cs" => "Czech Wikihow",
+            "ja" => "Japan Wikihow"
+        }
+
+### Inserts, Updates and Deletes
+
+Inserting, updating and deleteing the records works by the same way as
+selecting. Some examples:
+
+    connection.insert(:maintainers, :name => "Wikimedia", :country => "United States")
+    
+    # Will be:
+    #   INSERT INTO `maintainers` (`name`, `country`) VALUES ("Wikimedia", "United States")
+    
+    connection.update(:maintainers).set(:country => "Czech Republic").where(:id => 10).limit(1)
+    
+    # Will be:
+    #   UPDATE `maintainers` SET `country` = "Czech Republic" WHERE `id` = 10 LIMIT 1
+    
+    connection.delete(:maintainers).where(:id => 10).limit(1)
+    
+    # Will be:
+    #   DELETE FROM `maintainers` WHERE `id` = 10 LIMIT 1
+    
+
+#### Transactions
+
+Transactions support is available manual:
+    
+* `connection.begin`,
+* `connection.commit`,
+* `connection.rollback`.
+
+Or by automatic way:
+
+    connection.transaction do
+        #...
+    end
+
+### Compiled and Prepared Queries
+
+Queries can be pre-prepared and pre-optimized by two different methods:
+
+* `#compile` which compiles query to form of array of direct callbacks, 
+so builds it and quotes all identifiers, keeps intact placeholders only,
+* `#prepare` which transforms compiled query to prepared form as it's
+known from DBD or PDO if it's supported by driver.
+
+Simply call one of these methods upon the query and use resultant query
+as usuall (of sure, without methods which would change it because it's
+compiled so cannot be further changed).
+
+Also note, SQL token calls cannot be called by mandatory way (e.g. you 
+can call `#order` before `#where` etc.), but they will be reordered
+in resultant both compiled and prepared query, so arguments given to 
+execute must be taken to call in correct order according to resultant
+SQL query. So in case of using compiled or prepared statements, it's 
+good idea to write calls in the same order as SQL requires.
+
+### Examples
+
+More examples or tutorials than these above aren't available. It's in 
+development, although stable and production ready state. For well 
+documented and fully usable application see [Native Query][4].
+    
+
+Contributing
+------------
+
+1. Fork it.
+2. Create a branch (`git checkout -b 20101220-my-change`).
+3. Commit your changes (`git commit -am "Added something"`).
+4. Push to the branch (`git push origin 20101220-my-change`).
+5. Create an [Issue][2] with a link to your branch.
+6. Enjoy a refreshing Diet Coke and wait.
+
+Copyright
+---------
+
+Copyright © 2009-2011 [Martin Kozák][3]. See `LICENSE.txt` for
+further details.
+
+[1]: http://dibiphp.com/
+[2]: http://github.com/martinkozak/fluent-query/issues
+[3]: http://www.martinkozak.net/
+[4]: http://github.com/martinkozak/native-query

data/Rakefile

@@ -0,0 +1,29 @@
+# encoding: utf-8
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'jeweler'
+
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "fluent-query"
+  gem.homepage = "http://github.com/martinkozak/fluent-query"
+  gem.license = "MIT"
+  gem.summary = 'Cool way how to write SQL queries and general way how to convert series of method calls to string query in an universal and system independent manner. This gem contains base libraries only. SQL implementation is available standalone.'
+  gem.email = "martinkozak@martinkozak.net"
+  gem.authors = ["Martin Kozák"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new

data/VERSION

@@ -0,0 +1 @@
+0.9.0

data/fluent-query.gemspec

@@ -0,0 +1,75 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{fluent-query}
+  s.version = "0.9.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = [%q{Martin Kozák}]
+  s.date = %q{2011-07-14}
+  s.email = %q{martinkozak@martinkozak.net}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "fluent-query.gemspec",
+    "lib/fluent-query.rb",
+    "lib/fluent-query/compiler.rb",
+    "lib/fluent-query/compilers/result.rb",
+    "lib/fluent-query/connection.rb",
+    "lib/fluent-query/data.rb",
+    "lib/fluent-query/driver.rb",
+    "lib/fluent-query/drivers/exception.rb",
+    "lib/fluent-query/drivers/result.rb",
+    "lib/fluent-query/exception.rb",
+    "lib/fluent-query/queries/abstract.rb",
+    "lib/fluent-query/queries/compiled.rb",
+    "lib/fluent-query/queries/prepared.rb",
+    "lib/fluent-query/queries/processor.rb",
+    "lib/fluent-query/query.rb",
+    "lib/fluent-query/result.rb",
+    "lib/fluent-query/token.rb",
+    "lib/fluent-query/tokens/raw.rb"
+  ]
+  s.homepage = %q{http://github.com/martinkozak/fluent-query}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.5}
+  s.summary = %q{Cool way how to write SQL queries and general way how to convert series of method calls to string query in an universal and system independent manner. This gem contains base libraries only. SQL implementation is available standalone.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<hash-utils>, [">= 0.18.0"])
+      s.add_runtime_dependency(%q<abstract>, [">= 1.0.0"])
+      s.add_runtime_dependency(%q<hashie>, [">= 1.0.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.13"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.0"])
+    else
+      s.add_dependency(%q<hash-utils>, [">= 0.18.0"])
+      s.add_dependency(%q<abstract>, [">= 1.0.0"])
+      s.add_dependency(%q<hashie>, [">= 1.0.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.13"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
+    end
+  else
+    s.add_dependency(%q<hash-utils>, [">= 0.18.0"])
+    s.add_dependency(%q<abstract>, [">= 1.0.0"])
+    s.add_dependency(%q<hashie>, [">= 1.0.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.13"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
+  end
+end
+

data/lib/fluent-query.rb

@@ -0,0 +1,2 @@
+# encoding: utf-8
+require "fluent-query/connection"

data/lib/fluent-query/compiler.rb

@@ -0,0 +1,182 @@
+# encoding: utf-8
+require "date"
+require "fluent-query/query"
+require "fluent-query/compilers/result"
+require "hash-utils/array"  # >= 0.17.0
+
+module FluentQuery
+
+    ##
+    # Query compiler.
+    #
+
+    class Compiler
+
+        ##
+        # Contains all possible formatting directives.
+        #
+
+        FORMATTING_DIRECTIVES = [:i, :s, :l, :b, :f, :d, :t, :sql, :and, :or]
+
+        ##
+        # Indicates directive prefix.
+        #
+
+        DIRECTIVE_PREFIX = "%%"
+
+        ##
+        # Compiling cache.
+        #
+
+        private
+        @__compile_cache
+
+        ##
+        # Calls hash cache.
+        #
+
+        private 
+        @__calls_cache
+
+        ##
+        # Processor upon which compiler should work upon.
+        #
+
+        protected
+        @_processor
+
+        ##
+        # Constructor.
+        #
+
+        public
+        def initialize(processor)
+            @_processor = processor
+        end
+
+        ##
+        # Compiles formatting.
+        #
+
+        public
+        def compile_formatting(directive)
+            self.calls[directive.to_sym]
+        end
+
+        ##
+        # Returns calls array.
+        #
+        
+        public
+        def calls
+            if @__calls_cache.nil?
+                @__calls_cache = {
+                    :i => Proc::new { |v| @_processor.quote_value(v.to_i) },
+                    :s => Proc::new { |v| @_processor.quote_value(v.to_s) },
+                    :b => Proc::new { |v| @_processor.quote_value(v ? true : false) },
+                    :f => Proc::new { |v| @_processor.quote_value(v.to_f) },
+                    
+                    :l => Proc::new do |v|
+                        if v.array?
+                            output = v
+                        elsif v.hash?
+                            output = v.values
+                        end
+
+                        "(" << @_processor.process_array(output) << ")"
+                    end,
+            
+                    :d => Proc::new do |v|
+                        if v.string?
+                            output = Date.parse(v)
+                        elsif argument.kind_of? DateTime
+                            output = Date.parse(v.to_s)
+                        elsif argument.kind_of? Date
+                            output = v
+                        end
+
+                        @_processor.quote_value(output)
+                    end,
+                        
+                    :t => Proc::new do |v|
+                        if v.string?
+                            output = DateTime.parse(v)
+                        elsif argument.kind_of? Date
+                            output = DateTime.parse(v.to_s)
+                        elsif argument.kind_of? DateTime
+                            output = v
+                        end
+
+                        @_processor.quote_value(output)
+                    end,
+
+                    :sql => Proc::new do |v|
+                        if v.kind_of? MP::Fluent::Query
+                            output = v.build!
+                        end
+                        
+                        @_processor.quote_subquery(output)
+                    end,
+                    
+                    :and => Proc::new do |v|
+                        operator = @_processor.driver.quote_operator(:and)
+                        @_processor.process_hash(v, operator)
+                    end,
+
+                    :or => Proc::new do |v|
+                        operator = @_processor.driver.quote_operator(:or)
+                        @_processor.process_hash(v, operator)
+                    end,
+                }
+            end
+            
+            @__calls_cache
+        end
+
+        ##
+        # Compiles string.
+        #
+
+        public
+        def compile(string) 
+            output = FluentQuery::Compilers::Result::new
+            prefix = self.class::DIRECTIVE_PREFIX
+            buffer = ""
+
+            # Builds compile informations
+            if not @__compile_cache
+                directives = self.class::FORMATTING_DIRECTIVES.map { |s| s.to_s }
+                regexp = Regexp::new("^(" << directives.join("|") << ")(?:[^\w]|$)")
+                
+                @__compile_cache = regexp
+            else
+                regexp = @__compile_cache
+            end
+            
+       
+            # Splits to by directive separated parts
+            string.split(prefix).each do |part|
+                match = part.match(regexp)
+                
+                if match
+                    if not buffer.empty?
+                        output << buffer
+                    end
+                    
+                    output << self.compile_formatting(match[1])
+                    buffer = part[match[1].length..-1]
+                else
+                    buffer << prefix << part
+                end
+            end
+            
+            output << buffer
+            
+            # Corrects and returns result
+            output.first.replace(output.first[prefix.length..-1])   # strips out initial "%%"
+            return output
+            
+        end                
+     end
+ end
+