sequel 0.3.1 → 0.3.2

data/CHANGELOG

@@ -1,3 +1,31 @@
+=== 0.3.2 (2007-11-01)
+
+* Added #to_column_name as alias to #to_field_name, #column_title as alias to #field_title.
+
+* Added Dataset#interval method for getting interval between minimum/maximum values for a column.
+
+* Fixed Oracle::Database#execute (#84).
+
+* Added group_and_count as general implementation for count_by_xxx.
+
+* Added count_by magic method.
+
+* Added Dataset#range method for getting the minimum/maximum values for a column.
+
+* Fixed timestamp translation in SQLite adapter (#83).
+
+* Experimental DB2 adapter.
+
+* Added Dataset#set as alias to Dataset#update.
+
+* Removed long deprecated expressions.rb code.
+
+* Better documentation.
+
+* Implemented Dataset magic methods: order_by_xxx, group_by_xxx, filter_by_xxx, all_by_xxx, first_by_xxx, last_by_xxx.
+
+* Changed Model.create and Model.new to accept a block.
+
 === 0.3.1 (2007-10-30)
 
 * Typo fixes (#79).

data/Rakefile

@@ -6,7 +6,7 @@ require 'fileutils'
 include FileUtils
 
 NAME = "sequel"
-VERS = "0.3.1"
+VERS = "0.3.2"
 CLEAN.include ['**/.*.sw?', 'pkg/*', '.config', 'doc/*', 'coverage/*']
 RDOC_OPTS = ['--quiet', '--title', "Sequel: Concise ORM for Ruby",
   "--opname", "index.html",

data/lib/sequel/ado.rb

@@ -5,6 +5,15 @@ end
 require 'win32ole'
 
 module Sequel
+  # The ADO adapter provides connectivity to ADO databases in Windows. ADO
+  # databases can be opened using a URL with the ado schema:
+  #
+  #   DB = Sequel.open('ado://mydb')
+  # 
+  # or using the Sequel.ado method:
+  #
+  #   DB = Sequel.ado('mydb')
+  #
   module ADO
     class Database < Sequel::Database
       set_adapter_scheme :ado
@@ -51,8 +60,7 @@ module Sequel
         @db.synchronize do
           s = @db.execute sql
           
-          fields = s.Fields.extend(Enumerable)
-          @columns = fields.map {|x| x.Name.to_sym}
+          @columns = s.Fields.extend(Enumerable).map {|x| x.Name.to_sym}
           
           s.moveFirst
           s.getRows.transpose.each {|r| yield hash_row(r)}
@@ -71,11 +79,10 @@ module Sequel
         @db.synchronize do
           s = @db.execute sql
           
-          fields = s.Fields.extend(Enumerable)
-          @columns = fields.map {|x| x.Name.to_sym}
+          @columns = s.Fields.extend(Enumerable).map {|x| x.Name.to_sym}
           
           s.moveFirst
-          s.getRows.transpose.each {|r| r.fields = @columns; yield r}
+          s.getRows.transpose.each {|r| r.keys = @columns; yield r}
         end
         self
       end

data/lib/sequel/array_keys.rb

@@ -1,24 +1,38 @@
-# Based on the arrayfields gem by Ara Howard
-
+# ArrayKeys provide support for accessing array elements by keys. ArrayKeys are
+# based on the arrayfields gem by Ara Howard, and can be used as substitutes
+# for fetching records tuples as Ruby hashes.
+#
+# The main advantage offered by ArrayKeys over hashes is that the values are 
+# always ordered according to the column order in the query. Another purported
+# advantage is that they reduce the memory footprint, but this has turned out
+# to be a false claim.
 module ArrayKeys
+  # The KeySet module contains methods that extend an array of keys to return
+  # a key's position in the key set.
   module KeySet
+    # Returns the key's position in the key set. Provides indifferent access
+    # for symbols and strings.
     def key_pos(key)
       @key_indexes ||= inject({}) {|h, k| h[k.to_sym] = h.size; h}
       @key_indexes[key] || @key_indexes[key.to_sym] || @key_indexes[key.to_s]
     end
  
+    # Adds a key to the key set.
     def add_key(key)
       self << key
       @key_indexes[key] = @key_indexes.size
     end
     
+    # Removes a key from the key set by its index.
     def del_key(idx)
       delete_at(idx)
       @key_indexes = nil # reset key indexes
     end
   end
   
+  # The KeyAccess provides a large part of the Hash API for arrays with keys.
   module KeyAccess
+    # Returns a value referenced by an array index or a key.
     def [](idx, *args)
       if String === idx or Symbol === idx
         (idx = @keys.key_pos(idx)) ? super(idx, *args) : nil
@@ -27,6 +41,7 @@ module ArrayKeys
       end
     end
  
+    # Sets the value referenced by an array index or a key.
     def []=(idx,*args)
       if String === idx or Symbol === idx
         idx = @keys.key_pos(idx) || @keys.add_key(idx.to_sym)
@@ -34,14 +49,17 @@ module ArrayKeys
       super(idx, *args)
     end
     
+    # Stores a value by index or key.
     def store(k, v); self[k] = v; end
     
+    # Slices the array, and returns an array with its keys sliced accordingly.
     def slice(*args)
       s = super(*args)
       s.keys = @keys.slice(*args)
       s
     end
     
+    # Converts the array into a hash.
     def to_hash
       h = {}
       each_with_index {|v, i| h[@keys[i].to_sym] = v}
@@ -49,43 +67,60 @@ module ArrayKeys
     end
     alias_method :to_h, :to_hash
     
+    # Iterates over each key-value pair in the array.
     def each_pair
       each_with_index {|v, i| yield @keys[i], v}
     end
     
+    # Iterates over the array's associated keys.
     def each_key(&block)
       @keys.each(&block)
     end
     
+    # Iterates over the array's values.
     def each_value(&block)
       each(&block)
     end
     
+    # Deletes a value by its key.
     def delete(key, *args)
       if (idx = @keys.key_pos(key))
         delete_at(idx)
       end
     end
     
+    # Deletes a value by its index.
     def delete_at(idx)
       super(idx)
       @keys = @keys.clone
       @keys.del_key(idx)
     end
     
+    # Returns true if the array's key set contains the given key.
     def include?(k)
       @keys.include?(k) || @keys.include?(k.to_sym) || @keys.include?(k.to_s)
     end
     
+    # Returns true if the array's key set contains the given key.
     def has_key?(k)
       @keys.include?(k) || @keys.include?(k.to_sym) || @keys.include?(k.to_s)
     end
     alias_method :member?, :has_key?
     alias_method :key?, :has_key?
     
+    # Returns true if the array contains the given value.
     def has_value?(k); orig_include?(k); end
     alias_method :value?, :has_value?
     
+    # Fetches a value by its key and optionally passes it through the given
+    # block:
+    #
+    #   row.fetch(:name) {|v| v.to_sym}
+    #
+    # You can also give a default value
+    #
+    #   row.fetch(:name, 'untitled')
+    #
     def fetch(k, *args, &block)
       if idx = @keys.key_pos(k)
         v = at idx
@@ -95,26 +130,35 @@ module ArrayKeys
       block ? block[v] : v
     end
     
+    # Returns self.
     def values
       self
     end
     
+    # Creates a copy of self with the same key set.
     def dup
       copy = super
       copy.keys = @keys
       copy
     end
     
+    # Creates a copy of self with a copy of the key set.
     def clone
       copy = super
       copy.keys = @keys.clone
       copy
     end
     
+    # Returns an array merged from self and the given array.
     def merge(values, &block)
       clone.merge!(values, &block)
     end
     
+    # Merges the given array with self, optionally passing the values from self
+    # through the given block:
+    #
+    #   row.merge!(new_values) {|k, old, new| (k == :name) ? old : new}
+    #
     def merge!(values, &block)
       values.each_pair do |k, v|
         self[k] = (has_key?(k) && block) ? block[k, self[k], v] : v
@@ -125,8 +169,12 @@ module ArrayKeys
     alias_method :update!, :merge!
   end
   
+  # The ArrayExtensions module provides extensions for the Array class.
   module ArrayExtensions
     attr_reader :keys
+    
+    # Sets the key set for the array. Once a key set has been set for an array,
+    # it is extended with the KeyAccess API
     def keys=(keys)
       extend ArrayKeys::KeyAccess if keys
       @keys = keys.frozen? ? keys.dup : keys
@@ -139,11 +187,17 @@ module ArrayKeys
     alias_method :fields=, :keys=
   end
   
+  # The DatasetExtensions module provides extensions that modify
+  # a dataset to return Array tuples instead of Hash tuples.
   module DatasetExtensions
+    # Fetches a dataset's records, converting each tuple into an array with 
+    # keys.
     def array_tuples_each(opts = nil, &block)
       fetch_rows(select_sql(opts)) {|h| block[Array.from_hash(h)]}
     end
 
+    # Provides the corresponding behavior to Sequel::Dataset#update_each_method,
+    # using array tuples.
     def array_tuples_update_each_method
       # warning: ugly code generation ahead
       if @row_proc && @transform
@@ -183,11 +237,13 @@ module ArrayKeys
   end
 end
 
+# Array extensions.
 class Array
   alias_method :orig_include?, :include?
 
   include ArrayKeys::ArrayExtensions
 
+  # Converts a hash into an array with keys.
   def self.from_hash(h)
     a = []; a.keys = []
     a.merge!(h)
@@ -195,6 +251,8 @@ class Array
 end
 
 module Sequel
+  # Modifies all dataset classes to fetch records as arrays with keys. By 
+  # default records are fetched as hashes.
   def self.use_array_tuples
     Dataset.dataset_classes.each do |c|
       c.class_eval do
@@ -212,6 +270,7 @@ module Sequel
     end
   end
   
+  # Modifies all dataset classes to fetch records as hashes.
   def self.use_hash_tuples
     Dataset.dataset_classes.each do |c|
       c.class_eval do

data/lib/sequel/connection_pool.rb

@@ -68,6 +68,10 @@ module Sequel
       raise e.is_a?(StandardError) ? e : e.message
     end
     
+    # Removes all connection currently available, optionally yielding each 
+    # connection to the given block. This method has the effect of 
+    # disconnecting from the database. Once a connection is requested using
+    # #hold, the connection pool creates new connections to the database.
     def disconnect(&block)
       @mutex.synchronize do
         @available_connections.each {|c| block[c]} if block
@@ -138,6 +142,8 @@ module Sequel
       raise e.is_a?(StandardError) ? e : e.message
     end
     
+    # Disconnects from the database. Once a connection is requested using
+    # #hold, the connection is reestablished.
     def disconnect(&block)
       block[@conn] if block && @conn
       @conn = nil

data/lib/sequel/core_ext.rb

@@ -59,23 +59,24 @@ class String
     Time.parse(self)
   end
   
-  # Converts a string into a field name.
+  # Converts a string into a column name.
   def to_field_name
     self
   end
+  alias_method :to_column_name, :to_field_name
 end
 
-# Methods to format field names and associated constructs. This module is
+# Methods to format column names and associated constructs. This module is
 # included in String and Symbol.
 module FieldCompositionMethods
   # Constructs a DESC clause for use in an ORDER BY clause.
   def DESC
-    "#{to_field_name} DESC".lit
+    "#{to_column_name} DESC".lit
   end
   
-  # Constructs an AS clause for field aliasing.
+  # Constructs an AS clause for column aliasing.
   def AS(target)
-    "#{to_field_name} AS #{target}".lit
+    "#{to_column_name} AS #{target}".lit
   end
 
   # Constructs a qualified wildcard (*) clause.
@@ -86,17 +87,19 @@ module FieldCompositionMethods
   FIELD_TITLE_RE1 = /^(.*)\sAS\s(.+)$/i.freeze
   FIELD_TITLE_RE2 = /^([^\.]+)\.([^\.]+)$/.freeze
   
-  # Returns the field name. If the field name is aliased, the alias is 
+  # Returns the column name. If the column name is aliased, the alias is 
   # returned.
   def field_title
-    case s = to_field_name
+    case s = to_column_name
     when FIELD_TITLE_RE1, FIELD_TITLE_RE2: $2
     else
       s
     end
   end
+  alias_method :column_title, :field_title
 end
 
+# String extensions
 class String
   include FieldCompositionMethods
 end
@@ -110,14 +113,14 @@ class Symbol
   FIELD_REF_RE2 = /^(\w+)___(\w+)$/.freeze
   FIELD_REF_RE3 = /^(\w+)__(\w+)$/.freeze
   
-  # Converts a symbol into a field name. This method supports underscore
+  # Converts a symbol into a column name. This method supports underscore
   # notation in order to express qualified (two underscores) and aliased 
-  # (three underscores) fields:
+  # (three underscores) columns:
   #
-  #   :abc.to_field_name #=> "abc"
-  #   :abc___a.to_field_name #=> "abc AS a"
-  #   :items__abc.to_field_name #=> "items.abc"
-  #   :items__abc___a.to_field_name #=> "items.abc AS a"
+  #   :abc.to_column_name #=> "abc"
+  #   :abc___a.to_column_name #=> "abc AS a"
+  #   :items__abc.to_column_name #=> "items.abc"
+  #   :items__abc___a.to_column_name #=> "items.abc AS a"
   #
   def to_field_name
     s = to_s
@@ -129,12 +132,13 @@ class Symbol
       s
     end
   end
+  alias_method :to_column_name, :to_field_name
   
   # Converts missing method calls into functions on columns, if the
   # method name is made of all upper case letters.
   def method_missing(sym)
     ((s = sym.to_s) =~ /^([A-Z]+)$/) ? \
-      "#{s.downcase}(#{to_field_name})".lit : super
+      "#{s.downcase}(#{to_column_name})".lit : super
   end
   
   # Formats an SQL function with optional parameters

data/lib/sequel/database.rb

@@ -29,22 +29,28 @@ module Sequel
       @logger = opts[:logger]
     end
     
+    # Connects to the database. This method should be overriden by descendants.
     def connect
       raise NotImplementedError, "#connect should be overriden by adapters"
     end
     
+    # Disconnects from the database. This method should be overriden by 
+    # descendants.
     def disconnect
       raise NotImplementedError, "#disconnect should be overriden by adapters"
     end
     
+    # Returns true if the database is using a multi-threaded connection pool.
     def multi_threaded?
       !@single_threaded
     end
     
+    # Returns true if the database is using a single-threaded connection pool.
     def single_threaded?
       @single_threaded
     end
     
+    # Returns the URI identifying the database.
     def uri
       uri = URI::Generic.new(
         self.class.adapter_scheme.to_s,
@@ -68,6 +74,24 @@ module Sequel
       ds = Sequel::Dataset.new(self)
     end
     
+    # Fetches records for an arbitrary SQL statement. If a block is given,
+    # it is used to iterate over the records:
+    #
+    #   DB.fetch('SELECT * FROM items') {|r| p r}
+    #
+    # If a block is not given, the method returns a dataset instance:
+    #
+    #   DB.fetch('SELECT * FROM items').print
+    #
+    # Fetch can also perform parameterized queries for protection against SQL
+    # injection:
+    #
+    #   DB.fetch('SELECT * FROM items WHERE name = ?', my_name).print
+    #
+    # A short-hand form for Database#fetch is Database#[]:
+    #
+    #   DB['SELECT * FROM items'].each {|r| p r}
+    #
     def fetch(sql, *args, &block)
       ds = dataset
       sql = sql.gsub('?') {|m|  ds.literal(args.shift)}
@@ -97,10 +121,22 @@ module Sequel
     # Returns a new dataset with the select method invoked.
     def select(*args); dataset.select(*args); end
     
+    # Returns a dataset from the database. If the first argument is a string,
+    # the method acts as an alias for Database#fetch, returning a dataset for
+    # arbitrary SQL:
+    #
+    #   DB['SELECT * FROM items WHERE name = ?', my_name].print
+    #
+    # Otherwise, the dataset returned has its from option set to the given
+    # arguments:
+    #
+    #   DB[:items].sql #=> "SELECT * FROM items"
+    #
     def [](*args)
       (String === args.first) ? fetch(*args) : from(*args)
     end
-    
+
+    # Raises a NotImplementedError. This method is overriden in descendants.
     def execute(sql)
       raise NotImplementedError
     end
@@ -142,13 +178,12 @@ module Sequel
       create_table_sql_list(*g.create_info).each {|sta| execute(sta)}
     end
     
-    # Drops a table.
+    # Drops one or more tables corresponding to the given table names.
     def drop_table(*names)
       execute(names.map {|n| drop_table_sql(n)}.join)
     end
     
-    # Performs a brute-force check for the existance of a table. This method is
-    # usually overriden in descendants.
+    # Returns true if the given table exists.
     def table_exists?(name)
       if respond_to?(:tables)
         tables.include?(name.to_sym)
@@ -257,6 +292,7 @@ module Sequel
     
     @@single_threaded = false
     
+    # Sets the default single_threaded mode for new databases.
     def self.single_threaded=(value)
       @@single_threaded = value
     end