sql-maker 0.0.2 → 0.0.3

data/doc/sql/maker/error.md

@@ -0,0 +1,11 @@
+# NAME
+
+SQL::Maker::Error
+
+# SYNOPSIS
+
+    SQL::Maker::Error.new('message')
+
+# DESCRIPTION
+
+An error class of the SQL::Maker.

data/doc/sql/maker/helper.md

@@ -0,0 +1,48 @@
+# NAME
+
+SQL::Maker::Helper - helper functions for SQL::Maker
+
+# SYNOPSIS
+
+    include SQL::Maker::Helper
+    sql_raw('WHERE `id` = ?' => [1])
+
+# DESCRIPTION
+
+This module is to to provide sql_xxx helper functions. 
+
+# FUNCTIONS
+
+Following functions will be available by `include SQL::Maker::Helper`: 
+
+* sql_raw
+* sql_op
+* sql_is_null
+* sql_is_not_null
+* sql_eq
+* sql_ne
+* sql_lt
+* sql_gt
+* sql_le
+* sql_ge
+* sql_like
+* sql_between
+* sql_not_between
+* sql_not
+* sql_and
+* sql_or
+* sql_in
+* sql_not_in
+* sql_not_in
+
+and
+
+* sql_union
+* sql_union_all
+* sql_intersect
+* sql_intersect_all
+* sql_except
+* sql_except_all
+
+Please see [SQL::QueryMaker](../query_maker.md)
+and [SQL::Maker::SelectSet](./select_set.md) for details.

data/doc/sql/maker/quoting.md

@@ -0,0 +1,11 @@
+# NAME
+
+SQL::Maker::Quoting - Quoting and Escaping
+
+# DESCRIPTION
+
+This module is to privide quoting and escaping function of SQL values. 
+
+# REFERENCE
+
+ActiveRecord::ConnectionAdapter::Quoting

data/doc/sql/maker/select.md

@@ -0,0 +1,204 @@
+# NAME
+
+SQL::Maker::Select - dynamic SQL generator
+
+# SYNOPSIS
+
+    sql = SQL::Maker::Select.new
+      .add_select('foo')
+      .add_select('bar')
+      .add_select('baz')
+      .add_from('table_name' => 't')
+      .as_sql
+    # => "SELECT foo, bar, baz FROM table_name t"
+
+# DESCRIPTION
+
+# METHODS
+
+
+
+### sql = stmt.as_sql
+
+Render the SQL string.
+
+### bind = stmt.bind
+
+Get the bind variables.
+
+### stmt.add_select('*')
+
+### stmt.add_select(:col => alias)
+
+### stmt.add_select(sql_raw('COUNT(*)') => 'cnt')
+
+Add a new select term. It's automatically quoted.
+
+### stmt.add_from(table :Str | select :SQL::Maker::Select) : SQL::Maker::Select
+
+Add a new FROM clause. You can specify the table name or an instance of SQL::Maker::Select for a sub-query.
+
+I<Return:> stmt itself.
+
+### stmt.add_join(:user => {:type => 'inner', :table => 'config', :condition => 'user.user_id = config.user_id'})
+
+### stmt.add_join(:user => {:type => 'inner', :table => 'config', :condition => {'user.user_id' => 'config.user_id'})
+
+### stmt.add_join(:user => {:type => 'inner', :table => 'config', :condition => ['user_id']})
+
+Add a new JOIN clause. If you pass an array for 'condition' then it uses 'USING'. If 'type' is omitted
+it falls back to plain JOIN.
+
+    stmt = SQL::Maker::Select.new
+    stmt.add_join(
+        :user => {
+            :type      => 'inner',
+            :table     => 'config',
+            :condition => 'user.user_id = config.user_id',
+        }
+    )
+    stmt.as_sql
+    # => 'FROM user INNER JOIN config ON user.user_id = config.user_id'
+
+    stmt = SQL::Maker::Select.new(:quote_char => '`', :name_sep => '.')
+    stmt.add_join(
+        :user => {
+            :type      => 'inner',
+            :table     => 'config',
+            :condition => {'user.user_id' => 'config.user_id'},
+        }
+    )
+    stmt.as_sql
+    # => 'FROM `user` INNER JOIN `config` ON `user`.`user_id` = `config`.`user_id`'
+
+    stmt = SQL::Maker::Select.new
+    stmt.add_select('name')
+    stmt.add_join(
+        :user => {
+            :type      => 'inner',
+            :table     => 'config',
+            :condition => ['user_id'],
+        }
+    )
+    stmt.as_sql
+    # => 'SELECT name FROM user INNER JOIN config USING (user_id)'
+
+    subquery = SQL::Maker::Select.new
+    subquery.add_select('*')
+    subquery.add_from( 'foo' )
+    subquery.add_where( 'hoge' => 'fuga' )
+    stmt = SQL::Maker::Select.new
+    stmt.add_join(
+        [ subquery, 'bar' ] => {
+            :type      => 'inner',
+            :table     => 'baz',
+            :alias     => 'b1',
+            :condition => 'bar.baz_id = b1.baz_id'
+        },
+    )
+    stmt.as_sql
+    # => "FROM (SELECT * FROM foo WHERE (hoge = ?)) bar INNER JOIN baz b1 ON bar.baz_id = b1.baz_id"
+
+### stmt.add_index_hint(:foo => {:type => 'USE', :list => ['index_hint']})
+
+### stmt.add_index_hint(:foo => 'index_hint')
+
+### stmt.add_index_hint(:foo => ['index_hint'])
+
+    stmt = SQL::Maker::Select.new
+    stmt.add_select('name')
+    stmt.add_from('user')
+    stmt.add_index_hint(:user => {:type => 'USE', :list => ['index_hint']})
+    stmt.as_sql
+    # => "SELECT name FROM user USE INDEX (index_hint)"
+
+### stmt.add_where('foo_id' => 'bar');
+
+Add a new WHERE clause.
+
+    stmt = SQL::Maker::Select.new.add_select('c')
+                                 .add_from('foo')
+                                 .add_where('name' => 'john')
+                                 .add_where('type' => {:IN => %w/1 2 3/})
+                                 .as_sql
+    # => "SELECT c FROM foo WHERE (name = ?) AND (type IN (?, ?, ?))"
+
+Please see SQL::Maker::Condition#add for more details.
+
+### stmt.add_where_raw('id = ?', [1])
+
+Add a new WHERE clause from raw placeholder string and bind variables.
+
+    stmt = SQL::Maker::Select.new.add_select('c')
+                                 .add_from('foo')
+                                 .add_where_raw('EXISTS(SELECT * FROM bar WHERE name = ?)' => ['john'])
+                                 .add_where_raw('type IS NOT NULL')
+                                 .as_sql
+    # => "SELECT c FROM foo WHERE (EXISTS(SELECT * FROM bar WHERE name = ?)) AND (type IS NOT NULL)"
+
+
+### stmt.set_where(condition)
+
+Set the WHERE clause.
+
+condition should be instance of SQL::Maker::Condition.
+
+    cond1 = SQL::Maker::Condition.new.add("name" => "john")
+    cond2 = SQL::Maker::Condition.new.add("type" => {:IN => %w/1 2 3/})
+    stmt = SQL::Maker::Select.new.add_select('c')
+                                 .add_from('foo')
+                                 .set_where(cond1 & cond2)
+                                 .as_sql
+    # => "SELECT c FROM foo WHERE ((name = ?)) AND ((type IN (?, ?, ?)))"
+
+### stmt.add_order_by('foo');
+
+### stmt.add_order_by({'foo' => 'DESC'});
+
+Add a new ORDER BY clause.
+
+    stmt = SQL::Maker::Select.new.add_select('c')
+                                 .add_from('foo')
+                                 .add_order_by('name' => 'DESC')
+                                 .add_order_by('id')
+                                 .as_sql
+    # => "SELECT c FROM foo ORDER BY name DESC, id"
+
+### stmt.add_group_by('foo');
+
+Add a new GROUP BY clause.
+
+    stmt = SQL::Maker::Select.new.add_select('c')
+                                 .add_from('foo')
+                                 .add_group_by('id')
+                                 .as_sql
+    # => "SELECT c FROM foo GROUP BY id"
+
+    stmt = SQL::Maker::Select.new.add_select('c')
+                                 .add_from('foo')
+                                 .add_group_by('id' => 'DESC')
+                                 .as_sql
+    # => "SELECT c FROM foo GROUP BY id DESC"
+
+### stmt.limit(30)
+
+### stmt.offset(5)
+
+Add LIMIT and OFFSET.
+
+    stmt = SQL::Maker::Select.new.add_select('c')
+                                 .add_from('foo')
+                                 .limit(30)
+                                 .offset(5)
+                                 .as_sql
+    # => "SELECT c FROM foo LIMIT 30 OFFSET 5"
+
+### stmt.add_having(:cnt => 2)
+
+Add a HAVING clause.
+
+    stmt = SQL::Maker::Select.new.add_from('foo')
+                                 .add_select(sql_raw('COUNT(*)') => 'cnt')
+                                 .add_having(:cnt => 2)
+                                 .as_sql
+    # => "SELECT COUNT(*) AS cnt FROM foo HAVING (COUNT(*) = ?)"

data/doc/sql/maker/select_set.md

@@ -0,0 +1,100 @@
+# NAME
+
+SQL::Maker::SelectSet - provides set functions
+
+# SYNOPSIS
+
+    include SQL::Maker::Helper
+
+    s1 = SQL::Maker::Select.new()
+      .add_select('foo')
+      .add_from('t1')
+    s2 = SQL::Maker::Select.new()
+      .add_select('bar')
+      .add_from('t2')
+    sql_union_all( s1, s2 ).as_sql
+    # =>
+    #  SQL::Maker::SelectSet.new_set(
+    #      :operator => 'UNION ALL',
+    #      :new_line => s1.new_line
+    #  ).add_statement(s1)
+    #   .add_statement(s2)
+    #   .as_sql
+    # => "SELECT foo FROM t1 UNION ALL SELECT bar FROM t2"
+    except( s1, s2 ).as_sql
+    # => SQL::Maker::SelectSet.new_set( :operator => 'EXCEPT', :new_line => s1.new_line )
+    #     .add_statement( s1 )
+    #     .add_statement( s2 )
+    #     .as_sql
+    # => "SELECT foo FROM t1 EXCEPT SELECT bar FROM t2"
+
+# DESCRIPTION
+
+This module provides some set functions which return a SQL::Maker::SelectSet object
+inherited from SQL::Maker::Select.
+
+# FUNCTION
+
+Following functions will be avaiable with `include SQL::Maker::Helper`.
+
+### sql_union(select :SQL::Maker::Select | set :SQL::Maker::SelectSet) : SQL::Maker::SelectSet
+
+Tow statements are combined by UNION.
+
+### sql_union_all(select :SQL::Maker::Select | set :SQL::Maker::SelectSet) : SQL::Maker::SelectSet
+
+Tow statements are combined by UNION ALL.
+
+### sql_intersect(select :SQL::Maker::Select | set :SQL::Maker::SelectSet) : SQL::Maker::SelectSet
+
+Tow statements are combined by INTERSECT.
+
+### sql_intersect_all(select :SQL::Maker::Select | set :SQL::Maker::SelectSet) : SQL::Maker::SelectSet
+
+Tow statements are combined by INTERSECT ALL.
+
+### sql_except(select :SQL::Maker::Select | set :SQL::Maker::SelectSet) : SQL::Maker::SelectSet
+
+Tow statements are combined by EXCEPT.
+
+### sql_except(select :SQL::Maker::Select | set :SQL::Maker::SelectSet) : SQL::Maker::SelectSet
+
+Tow statements are combined by EXCEPT ALL.
+
+# Class Method
+
+## stmt = SQL::Maker::SelectSet.new( args )
+
+opretaor is a set operator (ex. UNION).
+one and another are SQL::Maker::Select object or SQL::Maker::SelectSet object.
+It returns a SQL::Maker::SelectSet object.
+
+The parameters are:
+
+### new_line
+
+Default values is "\n".
+
+### operator : Str
+
+The operator. This parameter is required.
+
+# Instance Methods
+
+## sql = set.as_sql : Str
+
+Returns a new select statement.
+
+## bind = set.bind : Array[Str]
+
+Returns bind variables.
+
+## set.add_statement(stmt) : SQL::Maker::SelectSet
+
+This method adds new statement object. stmt must provides 'as_sql' method.
+
+I<Return Value> is the set itself.
+
+# SEE ALSO
+
+[SQL::Maker::Select](./select.md)

data/doc/sql/maker/util.md

@@ -0,0 +1,7 @@
+# NAME
+
+SQL::Maker::Util - utility functions
+
+# DESCRITPION
+
+Just a set of utility functions used inside of SQL::Maker

data/doc/sql/query_maker.md

@@ -0,0 +1,242 @@
+# NAME
+
+SQL::QueryMaker - helper functions for SQL query generation
+
+# SYNOPSIS
+
+    include SQL::Maker::Helper # adds `sql_eq`, etc
+    
+    query = sql_eq(:foo => v)
+    query.as_sql                 # `foo`=?
+    query.bind                   # (v)
+
+    query = sql_lt(:foo => v)
+    query.as_sql                 # `foo`<?
+    query.bind                   # (v)
+
+    query = sql_in(:foo => [
+        v1, v2, v3,
+    ])
+    query.as_sql                 # `foo` IN (?,?,?)
+    query.bind                   # (v1,v2,v3)
+
+    query = sql_and(:foo => [
+        sql_ge(min),
+        sql_lt(max)
+    ])
+    query.as_sql                 # `foo`>=? AND `foo`<?
+    query.bind                   # (min,max)
+
+    query = sql_and([
+        sql_eq(:foo => v1),
+        sql_eq(:bar => v2)
+    ]
+    query.as_sql                 # `foo`=? AND `bar`=?
+    query.bind                   # (v1,v2)
+
+    query = sql_and([
+        :foo => v1,
+        :bar => sql_lt(v2),
+    ])
+    query.as_sql                 # `foo`=? AND `bar`<?
+    query.bind                   # (v1,v2)
+
+    query = sql_raw('COUNT(*)')
+    query.as_asl                 # COUNT(*)
+    query.bind                   # []
+
+    query = sql_raw('SELECT * FROM t WHERE id=?',123)
+    query.as_sql                 # SELECT * FROM t WHERE id=?
+    query.bind                   # [123]
+
+# DESCRIPTION
+
+This module concentrates on providing an expressive, concise way to declare SQL
+expressions by exporting carefully-designed functions.
+It is possible to use the module to generate SQL query conditions and pass them
+as arguments to other more versatile query builders such as SQL::Maker.
+
+The functions exported by the module instantiate comparator objects that build
+SQL expressions when their as_sql method are being invoked.
+There are two ways to specify the names of the columns to the comparator; to
+pass in the names as argument or to specify then as an argument to the
+as_sql method.
+
+# FUNCTIONS
+
+### sql_eq([column,] value)
+### sql_eq(column => value)
+
+### sql_lt([column,] value)
+### sql_lt(column => value)
+
+### sql_gt([column,] value)
+### sql_gt(column => value)
+
+### sql_le([column,] value)
+### sql_le(column => value)
+
+### sql_ge([column,] value)
+### sql_ge(column => value)
+
+### sql_like([column,] value)
+### sql_like(column => value)
+
+### sql_is_null([column])
+
+### sql_is_not_null([column])
+
+### sql_not([column])
+
+### sql_between([column,] min_value, max_value)
+### sql_between([column,] min_value, max_value)
+
+### sql_not_between([column,] min_value, max_value)
+
+### sql_in([column,] values)
+### sql_in(column => values)
+
+### sql_not_in([column,] \@values)
+### sql_not_in(column => \@values)
+
+Instantiates a comparator object that tests a column against given value(s).
+
+### sql_and([column,] conditions)
+### sql_and(column => conditions)
+
+### sql_or([column,] conditions)
+### sql_or(column => conditions)
+
+Aggregates given comparator objects into a logical expression.
+
+If specified, the column name is pushed down to the arguments when the
+as_sql method is being called, as show in the second example below.
+
+    sql_and([                   # => `foo`=? AND `bar`<?
+        sql_eq("foo" => v1),
+        sql_lt("bar" => v2)
+    ])
+
+    sql_and("foo" => [          # => `foo`>=min OR `foo`<max
+        sql_ge(min),
+        sql_lt(max),
+    ])
+
+### sql_and(conditions)
+
+### sql_or(conditions)
+
+Aggregates given pairs of column names and comparators into a logical
+expression.
+
+The value part is composed of as the argument to the = operator if it is
+not a blessed reference.
+
+    query = sql_and({
+        :foo => 'abc',
+        :bar => sql_lt(123),
+    })
+    query.as_sql             # => `foo`=? AND bar<?
+    query.bind               # => ('abc', 123)
+
+
+### sql_op([column,] op_sql, bind_values)
+
+Generates a comparator object that tests a column using the given SQL and
+values.  <@> in the given SQL are replaced by the column name (specified
+either by the argument to the function or later by the call to the <as_sql>
+method), and <?> are substituted by the given bind values.
+
+### sql_raw(sql[, bind_values])
+### sql_raw(sql => bind_values)
+
+Generates a comparator object from raw SQL and bind values.  <?> in the
+given SQL are replaced by the bind values.
+
+### obj.as_sql
+
+### obj.as_sql(column_name)
+
+### obj.as_sql(column_name, quote_identifier_cb)
+
+Compiles given comparator object and returns an SQL expression.
+Corresponding bind values should be obtained by calling the bind method.
+
+The function optionally accepts a column name to which the comparator object
+should be bound; an error is thrown if the comparator object is already bound
+to another column.
+
+The function also accepts a callback for quoting the identifiers.  If omitted,
+the identifiers are quoted using ` after being splitted using .; i.e. a
+column designated as foo.bar is quoted as `foo`.`bar`.
+
+### obj.bind
+
+Returns a list of bind values corresponding to the SQL expression returned by
+the as_sql method.
+
+# CHEAT SHEET
+
+    IN:        sql_eq('foo' => 'bar')
+    OUT QUERY: '`foo` = ?'
+    OUT BIND:  ['bar']
+
+    IN:        sql_in('foo' => ['bar', 'baz'])
+    OUT QUERY: '`foo` IN (?,?)'
+    OUT BIND:  ['bar','baz']
+
+    IN:        sql_and([sql_eq('foo' => 'bar'), sql_eq('baz' => 123)])
+    OUT QUERY: '(`foo` = ?) AND (`baz` = ?)'
+    OUT BIND:  ['bar',123]
+
+    IN:        sql_and('foo' => [sql_ge(3), sql_lt(5)])
+    OUT QUERY: '(`foo` >= ?) AND (`foo` < ?)'
+    OUT BIND:  [3,5]
+
+    IN:        sql_or([sql_eq('foo' => 'bar'), sql_eq('baz' => 123)])
+    OUT QUERY: '(`foo` = ?) OR (`baz` = ?)'
+    OUT BIND:  ['bar',123]
+
+    IN:        sql_or('foo' => ['bar', 'baz'])
+    OUT QUERY: '(`foo` = ?) OR (`foo` = ?)'
+    OUT BIND:  ['bar','baz']
+
+    IN:        sql_is_null('foo')
+    OUT QUERY: '`foo` IS NULL'
+    OUT BIND:  []
+
+    IN:        sql_is_not_null('foo')
+    OUT QUERY: '`foo` IS NOT NULL'
+    OUT BIND:  []
+
+    IN:        sql_between('foo', 1, 2)
+    OUT QUERY: '`foo` BETWEEN ? AND ?'
+    OUT BIND:  [1,2]
+
+    IN:        sql_not('foo')
+    OUT QUERY: 'NOT `foo`'
+    OUT BIND:  []
+
+    IN:        sql_op('apples', 'MATCH (@) AGAINST (?)', ['oranges'])
+    OUT QUERY: 'MATCH (`apples`) AGAINST (?)'
+    OUT BIND:  ['oranges']
+
+    IN:        sql_raw('COUNT(*)')
+    OUT QUERY: 'COUNT(*)'
+    OUT BIND:  []
+
+    IN:        sql_raw('SELECT * FROM t WHERE id=?',123)
+    OUT QUERY: 'SELECT * FROM t WHERE id=?'
+    OUT BIND:  [123]
+
+    IN:        sql_in('foo' => [123,sql_raw('SELECT id FROM t WHERE cat=?',5)])
+    OUT QUERY: '`foo` IN (?,(SELECT id FROM t WHERE cat=?))'
+    OUT BIND:  [123,5]
+
+# AUTHOR
+
+Natoshi Seo (Originally designed by Kazuho Oku as a Perl module)
+
+# LICENSE
+
+This library is free software; you can redistribute it and/or modify it under the MIT License.