momomoto 0.1.13 → 0.1.14

data/lib/momomoto/datatype/inet.rb

@@ -1,7 +1,11 @@
 module Momomoto
   module Datatype
+
+    # This class represents data type Inet which is an IPv4 or IPv6 host or address.
     class Inet < Text
 
+      # Values are filtered by this method when being set.
+      # Returns nil if +value+ is empty or nil.
       def filter_set( value )
         case value
           when nil, '' then nil

data/lib/momomoto/datatype/integer.rb

@@ -1,7 +1,12 @@
 module Momomoto
   module Datatype
+
+    # This class represents data type Integer.
     class Integer < Base
 
+      # Values are filtered by this method when being set.
+      # Converts +value+ to Integer or return +nil+ if +value+ is nil or empty.
+      # Raises ConversionError if converting fails.
       def filter_set( value )
         case value
           when nil, '' then nil

data/lib/momomoto/datatype/interval.rb

@@ -1,7 +1,14 @@
 module Momomoto
   module Datatype
+
+    # This class represents the data type Interval.
     class Interval < Time_without_time_zone
 
+      # Escapes +value+ before storing to database.
+      # +value+ can be either 
+      #   nil, resulting in 'NULL',
+      #   String, which is escaped using Database#escape_string,
+      #   or some Date-like format
       def escape( value )
         case value
           when nil then 'NULL'
@@ -9,7 +16,11 @@ module Momomoto
           else "'#{Database.escape_string(value.strftime('%H:%M:%S'))}'"
         end
       end
-
+  
+      # Values are filtered by this method when getting them from database.
+      # Returns an instance of TimeInterval or nil if +value+ is nil or
+      # empty.
+      # Raises ConversionError if the given +value+ cannot be parsed.
       def filter_get( value )
         case value
           when nil, '' then nil
@@ -21,6 +32,8 @@ module Momomoto
         raise ConversionError, "Error while parsing interval (#{e.message})"
       end
 
+      # Values are filtered by this function when being set.
+      # See Interval#filter_get
       def filter_set( value )
         filter_get( value )
       end

data/lib/momomoto/datatype/numeric.rb

@@ -1,8 +1,13 @@
 
 module Momomoto
   module Datatype
+
+    # This class represents data type Numeric.
     class Numeric < Base
 
+      # Values are filtered by this method when being set.
+      # Converts +value+ to Float or returns nil if +value+ is nil or
+      # empty.
       def filter_set( value )
         case value
           when nil, '' then nil

data/lib/momomoto/datatype/real.rb

@@ -1,5 +1,7 @@
 module Momomoto
   module Datatype
+    
+    # Represents the data type Real
     class Real < Numeric
     
     end

data/lib/momomoto/datatype/smallint.rb

@@ -1,5 +1,7 @@
 module Momomoto
   module Datatype
+
+    # Represents the data type Smallint
     class Smallint < Integer
     
     end

data/lib/momomoto/datatype/text.rb

@@ -1,11 +1,19 @@
 module Momomoto
   module Datatype
+
+    # Represents the data type Text.
     class Text < Base
 
+      # Compares two values and returns true if equal or false otherwise.
+      # It is used to check if a row field has been changed so that only
+      # changed fields are written to database. 
       def equal( a, b )
         a.to_s == b.to_s
       end
 
+      # Escapes +input+ to be saved in database.
+      # Returns 'NULL' if +input+ is nil or empty. Otherwise escapes
+      # using Database#escape_string
       def escape( input )
         if input.nil? || input.to_s.empty?
           "NULL"
@@ -14,6 +22,12 @@ module Momomoto
         end
       end
 
+      # Additional operators for instances of Text.
+      # See Base#operator_sign
+      #
+      #   # Selects all posts having "surveillance" in their content field 
+      #   # while ignoring case.
+      #   Posts.select( :content => {:ilike => 'surveillance'} )
       def self.operator_sign( op )
         case op
           when :like then 'LIKE'

data/lib/momomoto/datatype/time_with_time_zone.rb

@@ -3,8 +3,10 @@ require 'date'
 
 module Momomoto
   module Datatype
+
+    # Represents the data type Time with time zone.
     class Time_with_time_zone < Time_without_time_zone
-    
+
     end
   end
 end

data/lib/momomoto/datatype/time_without_time_zone.rb

@@ -3,12 +3,20 @@ require 'time'
 
 module Momomoto
   module Datatype
+
+    # Represents the data type Time without time zone.
     class Time_without_time_zone < Base
 
+      # Compares two values and returns true if equal or false otherwise.
+      # It is used to check if a row field has been changed so that only
+      # changed fields are written to database. 
+      # Escapes before comparing.
       def equal( a, b )
         escape(a) == escape(b)
       end
 
+      # Escapes +value+ to be saved in database.
+      # Returns 'NULL' if +value+ is nil.
       def escape( value )
         case value
           when nil then 'NULL'
@@ -17,6 +25,8 @@ module Momomoto
         end
       end
 
+      # Values are filtered by this function when being set.
+      # Returns an instance of Time or nil if +value+ is nil or empty.
       def filter_set( value )
         case value
           when nil, '' then nil

data/lib/momomoto/datatype/timestamp_with_time_zone.rb

@@ -1,5 +1,7 @@
 module Momomoto
   module Datatype
+
+    # Represents the data type Timestamp with time zone.
     class Timestamp_with_time_zone < Timestamp_without_time_zone
 
     end

data/lib/momomoto/datatype/timestamp_without_time_zone.rb

@@ -3,8 +3,11 @@ require 'date'
 
 module Momomoto
   module Datatype
+
+    # Represents the data type Timestamp without time zone.
     class Timestamp_without_time_zone < Base
 
+      # Escapes +value+ to be saved in database.
       def escape( value )
         case value
           when nil then 'NULL'
@@ -13,6 +16,8 @@ module Momomoto
         end
       end
 
+      # Values are filtered by this function when being set.
+      # Returns an instance of Time or nil if +value+ is nil or empty.
       def filter_set( value )
         case value
           when nil, '' then nil

data/lib/momomoto/information_schema/columns.rb

@@ -1,6 +1,14 @@
 
 module Momomoto
+
+  # This module is used by Momomoto to access the database's meta
+  # information on the current active database.
   module Information_schema
+
+    # internal use only
+    #
+    # Represents the corresponding view from Information Schema and is
+    # used when getting the data type of a column.
     class Columns < Momomoto::Table
       primary_keys( [] )
       schema_name( "information_schema" )

data/lib/momomoto/information_schema/fetch_procedure_columns.rb

@@ -1,6 +1,8 @@
 
 module Momomoto
   module Information_schema
+
+    # internal use only
     class Fetch_procedure_columns < Momomoto::Procedure
       schema_name( "momomoto" )
       parameters( :procedure_name => Momomoto::Datatype::Text.new )

data/lib/momomoto/information_schema/fetch_procedure_parameters.rb

@@ -1,6 +1,8 @@
 
 module Momomoto
   module Information_schema
+
+    # internal use only
     class Fetch_procedure_parameters < Momomoto::Procedure
       schema_name( "momomoto" )
       parameters( :procedure_name => Momomoto::Datatype::Text.new )

data/lib/momomoto/information_schema/key_column_usage.rb

@@ -1,6 +1,11 @@
 
 module Momomoto
   module Information_schema
+
+    # internal use only
+    #
+    # Represents the corresponding view from Information Schema and is
+    # used for getting the column names of primary keys of a table.
     class Key_column_usage < Momomoto::Table
       schema_name( "information_schema" )
     end

data/lib/momomoto/information_schema/routines.rb

@@ -3,6 +3,10 @@ module Momomoto
 
   module Information_schema
 
+    # internal use only
+    #
+    # Represents the corresponding view from Information Schema and is
+    # used for getting all defined functions within a database.
     class Routines < Momomoto::Table
       schema_name( "information_schema" )
     end

data/lib/momomoto/information_schema/table_constraints.rb

@@ -1,6 +1,11 @@
 
 module Momomoto
   module Information_schema
+
+    # internal use only
+    #
+    # Represents the corresponding view from Information Schema and is
+    # used when fetching primary keys.
     class Table_constraints < Momomoto::Table
       primary_keys( [] )
       schema_name( "information_schema" )

data/lib/momomoto/order.rb

@@ -1,14 +1,55 @@
 
 module Momomoto
 
+  # This class is used to specify the order of returned +Row+s.
+  # Whenever selecting rows you can use plain +Symbol+s for column names
+  # or the builtin classes for having the result automatically sorted +asc+
+  # ending, +desc+ending or case-insensitive with +lower+.
+  #
+  # When executing SELECT on tables the method Base#compile_order is
+  # invoked, which compiles the order statement according to Table#default_order
+  # if defined. This can be overwritten with options[:order] set as parameter
+  # for the select method.
+  #
+  #   class Feeds < Momomoto::Table
+  #     default_order Momomoto.desc( :last_changed )
+  #     #equals default_order Momomoto::Order::Desc.new( :last_changed )
+  #   end
+  #
+  #   newest_five_feeds = Feeds.select( {}, { :limit => 5} )
+  #     => Returns the five rows from Feeds with the newest column last_changed
+  # 
+  # Now, if you want to get all feeds sorted by column title instead of
+  # last_changed and also want to ignore case, do the following:
+  #
+  #   feeds_by_title = Feeds.select( {}, {:order => Momomoto::lower(:title)} )
+  #
+  # This overwrites the default value for order.
+  #
+  # You can also define multiple order statements at once, which are then
+  # joined together.
+  #
+  #   class Feeds < Momomoto::Table
+  #     default_order [Momomoto::desc(:last_changed), Momomoto::lower(:title)]
+  #   end
   class Order
 
+    # Getter and setter methods for +fields+. +fields+ are +Symbol+s
+    # representing the columns the Order class operates on.
     attr_accessor :fields
 
+    # Creates a new instance of Order and flattens the given parameter
+    # +fields+.
+    #
+    # Usage:
+    #   Momomoto::Order.new(:url_class, [:url, :title])
     def initialize( *fields )
       @fields = fields.flatten
     end
 
+    # This method is used to build the SQL statement from the given
+    # +columns+ and their class. This method is only invoked from
+    # Base#compile_order.
     def to_sql( columns )
       sql = []
       fields.each do | field |
@@ -22,7 +63,17 @@ module Momomoto
       sql.join(',')
     end
 
+    # This class is used for case-insensitive orders. It is derived from
+    # the Order class where you can find more information on usage.
     class Lower < Order
+
+      # Creates a new instance of Lower and flattens the given parameter
+      # +fields+. 
+      # Raises Error if presented with fields that are either instances of 
+      # Order::Asc or Order::Desc.
+      #
+      # Usage:
+      #   Momomoto::Order::Lower.new(:author, [:title, :publisher])
       def initialize( *fields )
         fields = fields.flatten
         fields.each do | field |
@@ -31,6 +82,8 @@ module Momomoto
         @fields = fields
       end
 
+      # Translates all +argument+s to the SQL statement.
+      # Returns the joined arguments.
       def function( argument )
         argument = [ argument ] if not argument.kind_of?( Array )
         argument = argument.map{|a| "lower(#{a})"}
@@ -38,13 +91,21 @@ module Momomoto
       end
     end
 
+    # This class is used for ascending orders. It is derived from the
+    # Order class where you can find more information on usage.
     class Asc < Order
+
+      # translates +argument+ to SQL statement for ascending.
       def function( argument )
         "#{argument} asc"
       end
     end
 
+    # This class is used for descending orders. It is derived from the
+    # Order class where you can find more information on usage.
     class Desc < Order
+
+      # translates +argument+ to SQL statement for descending.
       def function( argument )
         "#{argument} desc"
       end

data/lib/momomoto/procedure.rb

@@ -1,8 +1,8 @@
 
 module Momomoto
 
-  # this class implements access to stored procedures
-  # it must not be used directly but you should inherit from this class
+  # This class implements access to stored procedures.
+  # It must not be used directly but you should inherit from this class.
   class Procedure < Base
 
     class << self
@@ -28,12 +28,12 @@ module Momomoto
         classname.split('::').last.downcase.gsub(/[^a-z_0-9]/, '')
       end
 
-      # set the procedure name
+      # sets the procedure name
       def procedure_name=( procedure_name )
         @procedure_name = procedure_name
       end
 
-      # get the procedure name
+      # gets the procedure name
       def procedure_name( procedure_name = nil )
         return self.procedure_name=( procedure_name ) if procedure_name
         if not instance_variable_defined?( :@procedure_name )
@@ -42,34 +42,34 @@ module Momomoto
         @procedure_name
       end
 
-      # get the full name of the procedure including schema if set
+      # gets the full name of the procedure including schema if set
       def full_name # :nodoc:
         "#{ schema_name ? schema_name + '.' : ''}#{procedure_name}"
       end
 
-      # set the parameters this procedures accepts
+      # sets the parameters this procedures accepts
       # example: parameters = {:param1=>Momomoto::Datatype::Text.new}
       def parameters=( *p )
         p = p.flatten
         @parameters = p
       end
 
-      # get the parameters this procedure accepts
-      # returns an array of hashes with the fieldnames as key and the datatype as value
+      # gets the parameters this procedure accepts
+      # returns an array of hashes with the field names as keys and the datatype as values
       def parameters( *p )
         return self.send( :parameters=, *p ) if not p.empty?
         initialize_procedure if not instance_variable_defined?( :@parameters )
         @parameters
       end
 
-      # set the columns of the resultset this procedure returns
-      # expects a hash with the fieldnames as key and the datatype as value
+      # sets the columns of the result set this procedure returns
+      # expects a hash with the field names as keys and the datatype as values
       def columns=( columns )
         @columns = columns
       end
 
-      # get the columns of the resultset this procedure returns
-      # returns a hash with the fieldnames as key and the datatype as value
+      # gets the columns of the result set this procedure returns
+      # returns a hash with the field names as keys and the datatype as values
       def columns( c = nil )
         return self.columns=( c ) if c
         initialize_procedure if not instance_variable_defined?( :@columns )
@@ -81,13 +81,13 @@ module Momomoto
         parameters.each do | parameter |
           field_name, datatype = parameter.to_a.first
           raise Error, "parameter #{field_name} not specified" if not params.member?( field_name )
-          raise Error, "Not null fields(#{field_name}) need to be set in #{procedure_name}" if !params[field_name] && datatype.not_null?
+          raise Error, "Not null fields(#{field_name}) need to be set in #{full_name}" if !params[field_name] && datatype.not_null?
           args << datatype.escape( params[field_name] )
         end
         args.join(',')
       end
 
-      # execute the stored procedure
+      # executes the stored procedure
       def call( params = {}, conditions = {}, options = {} )
         initialize_procedure unless initialized
         sql = "SELECT #{columns.keys.join(',')} FROM "