diff options
Diffstat (limited to 'activerecord')
6 files changed, 67 insertions, 28 deletions
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 8f8ed241d5..5d614442c3 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -389,6 +389,8 @@ module ActiveRecord #:nodoc: # So it's possible to assign a logger to the class through <tt>Base.logger=</tt> which will then be used by all # instances in the current object space. class Base + ## + # :singleton-method: # Accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed # on to any new database connections made and which can be retrieved on both a class and instance level by calling +logger+. cattr_accessor :logger, :instance_writer => false @@ -414,7 +416,9 @@ module ActiveRecord #:nodoc: end @@subclasses = {} - + + ## + # :singleton-method: # Contains the database configuration - as is typically stored in config/database.yml - # as a Hash. # @@ -443,6 +447,8 @@ module ActiveRecord #:nodoc: cattr_accessor :configurations, :instance_writer => false @@configurations = {} + ## + # :singleton-method: # Accessor for the prefix type that will be prepended to every primary key column name. The options are :table_name and # :table_name_with_underscore. If the first is specified, the Product class will look for "productid" instead of "id" as # the primary column. If the latter is specified, the Product class will look for "product_id" instead of "id". Remember @@ -450,34 +456,46 @@ module ActiveRecord #:nodoc: cattr_accessor :primary_key_prefix_type, :instance_writer => false @@primary_key_prefix_type = nil + ## + # :singleton-method: # Accessor for the name of the prefix string to prepend to every table name. So if set to "basecamp_", all # table names will be named like "basecamp_projects", "basecamp_people", etc. This is a convenient way of creating a namespace # for tables in a shared database. By default, the prefix is the empty string. cattr_accessor :table_name_prefix, :instance_writer => false @@table_name_prefix = "" + ## + # :singleton-method: # Works like +table_name_prefix+, but appends instead of prepends (set to "_basecamp" gives "projects_basecamp", # "people_basecamp"). By default, the suffix is the empty string. cattr_accessor :table_name_suffix, :instance_writer => false @@table_name_suffix = "" + ## + # :singleton-method: # Indicates whether table names should be the pluralized versions of the corresponding class names. # If true, the default table name for a Product class will be +products+. If false, it would just be +product+. # See table_name for the full rules on table/class naming. This is true, by default. cattr_accessor :pluralize_table_names, :instance_writer => false @@pluralize_table_names = true + ## + # :singleton-method: # Determines whether to use ANSI codes to colorize the logging statements committed by the connection adapter. These colors # make it much easier to overview things during debugging (when used through a reader like +tail+ and on a black background), but # may complicate matters if you use software like syslog. This is true, by default. cattr_accessor :colorize_logging, :instance_writer => false @@colorize_logging = true + ## + # :singleton-method: # Determines whether to use Time.local (using :local) or Time.utc (using :utc) when pulling dates and times from the database. # This is set to :local by default. cattr_accessor :default_timezone, :instance_writer => false @@default_timezone = :local + ## + # :singleton-method: # Specifies the format to use when dumping the database schema with Rails' # Rakefile. If :sql, the schema is dumped as (potentially database- # specific) SQL statements. If :ruby, the schema is dumped as an @@ -487,6 +505,8 @@ module ActiveRecord #:nodoc: cattr_accessor :schema_format , :instance_writer => false @@schema_format = :ruby + ## + # :singleton-method: # Specify whether or not to use timestamps for migration numbers cattr_accessor :timestamped_migrations , :instance_writer => false @@timestamped_migrations = true @@ -640,16 +660,24 @@ module ActiveRecord #:nodoc: connection.select_all(sanitize_sql(sql), "#{name} Load").collect! { |record| instantiate(record) } end - # Checks whether a record exists in the database that matches conditions given. These conditions - # can either be a single integer representing a primary key id to be found, or a condition to be - # matched like using ActiveRecord#find. + + # Returns true if a record exists in the table that matches the +id+ or + # conditions given, or false otherwise. The argument can take four forms: + # + # * Integer - Finds the record with this primary key. + # * String - Finds the record with a primary key corresponding to this + # string (such as <tt>'5'</tt>). + # * Array - Finds the record that matches these +find+-style conditions + # (such as <tt>['color = ?', 'red']</tt>). + # * Hash - Finds the record that matches these +find+-style conditions + # (such as <tt>{:color => 'red'}</tt>). # - # The +id_or_conditions+ parameter can be an Integer or a String if you want to search the primary key - # column of the table for a matching id, or if you're looking to match against a condition you can use - # an Array or a Hash. + # For more information about specifying conditions as a Hash or Array, + # see the Conditions section in the introduction to ActiveRecord::Base. # - # Possible gotcha: You can't pass in a condition as a string e.g. "name = 'Jamie'", this would be - # sanitized and then queried against the primary key column as "id = 'name = \'Jamie" + # Note: You can't pass in a condition as a string (like <tt>name = + # 'Jamie'</tt>), since it would be sanitized and then queried against + # the primary key column, like <tt>id = 'name = \'Jamie\''</tt>. # # ==== Examples # Person.exists?(5) @@ -2320,15 +2348,15 @@ module ActiveRecord #:nodoc: # object. The default implementation returns this record's id as a String, # or nil if this record's unsaved. # - # For example, suppose that you have a Users model, and that you have a - # <tt>map.resources :users</tt> route. Normally, +users_path+ will - # construct an URI with the user object's 'id' in it: + # For example, suppose that you have a User model, and that you have a + # <tt>map.resources :users</tt> route. Normally, +user_path+ will + # construct a path with the user object's 'id' in it: # # user = User.find_by_name('Phusion') # user_path(user) # => "/users/1" # - # You can override +to_param+ in your model to make +users_path+ construct - # an URI using the user's name instead of the user's id: + # You can override +to_param+ in your model to make +user_path+ construct + # a path using the user's name instead of the user's id: # # class User < ActiveRecord::Base # def to_param # overridden diff --git a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb index a968fc0fd3..ccb79f547a 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb @@ -7,6 +7,8 @@ module ActiveRecord end end + ## + # :singleton-method: # The connection handler cattr_accessor :connection_handler, :instance_writer => false @@connection_handler = ConnectionAdapters::ConnectionHandler.new diff --git a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb index 1e452ae88a..c3cbdc8c2f 100644 --- a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb @@ -156,13 +156,16 @@ module ActiveRecord # * <tt>:sslcapath</tt> - Necessary to use MySQL with an SSL connection. # * <tt>:sslcipher</tt> - Necessary to use MySQL with an SSL connection. # - # By default, the MysqlAdapter will consider all columns of type <tt>tinyint(1)</tt> - # as boolean. If you wish to disable this emulation (which was the default - # behavior in versions 0.13.1 and earlier) you can add the following line - # to your environment.rb file: - # - # ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans = false class MysqlAdapter < AbstractAdapter + + ## + # :singleton-method: + # By default, the MysqlAdapter will consider all columns of type <tt>tinyint(1)</tt> + # as boolean. If you wish to disable this emulation (which was the default + # behavior in versions 0.13.1 and earlier) you can add the following line + # to your environment.rb file: + # + # ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans = false cattr_accessor :emulate_booleans self.emulate_booleans = true diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb index 1d843fff28..15350cf1e1 100644 --- a/activerecord/lib/active_record/migration.rb +++ b/activerecord/lib/active_record/migration.rb @@ -130,7 +130,9 @@ module ActiveRecord # To run migrations against the currently configured database, use # <tt>rake db:migrate</tt>. This will update the database by running all of the # pending migrations, creating the <tt>schema_migrations</tt> table - # (see "About the schema_migrations table" section below) if missing. + # (see "About the schema_migrations table" section below) if missing. It will also + # invoke the db:schema:dump task, which will update your db/schema.rb file + # to match the structure of your database. # # To roll the database back to a previous migration version, use # <tt>rake db:migrate VERSION=X</tt> where <tt>X</tt> is the version to which diff --git a/activerecord/lib/active_record/schema_dumper.rb b/activerecord/lib/active_record/schema_dumper.rb index 2181bdf2dd..557a554966 100644 --- a/activerecord/lib/active_record/schema_dumper.rb +++ b/activerecord/lib/active_record/schema_dumper.rb @@ -7,6 +7,8 @@ module ActiveRecord class SchemaDumper #:nodoc: private_class_method :new + ## + # :singleton-method: # A list of tables which should not be dumped to the schema. # Acceptable values are strings as well as regexp. # This setting is only used if ActiveRecord::Base.schema_format == :ruby diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index 9220eae4d1..dae00aa7db 100644 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -494,18 +494,20 @@ module ActiveRecord # The first_name attribute must be in the object and it cannot be blank. # # If you want to validate the presence of a boolean field (where the real values are true and false), - # you will want to use validates_inclusion_of :field_name, :in => [true, false] - # This is due to the way Object#blank? handles boolean values. false.blank? # => true + # you will want to use <tt>validates_inclusion_of :field_name, :in => [true, false]</tt>. + # + # This is due to the way Object#blank? handles boolean values: <tt>false.blank? # => true</tt>. # # Configuration options: # * <tt>message</tt> - A custom error message (default is: "can't be blank"). - # * <tt>on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>). + # * <tt>on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, + # <tt>:update</tt>). # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should - # occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }). The - # method, proc or string should return or evaluate to a true or false value. + # occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). + # The method, proc or string should return or evaluate to a true or false value. # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should - # not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }). The - # method, proc or string should return or evaluate to a true or false value. + # not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). + # The method, proc or string should return or evaluate to a true or false value. # def validates_presence_of(*attr_names) configuration = { :on => :save } |