mongoid 2.0.0.beta.20 → 2.0.0.rc.1

data/lib/mongoid/callbacks.rb

@@ -5,7 +5,6 @@ module Mongoid #:nodoc:
     included do
       extend ActiveModel::Callbacks
 
-      # Define all the callbacks that are accepted by the document.
       define_model_callbacks \
         :create,
         :destroy,
@@ -15,7 +14,13 @@ module Mongoid #:nodoc:
         :validation
     end
 
-    def valid?(*) #nodoc
+    # Determine if the document is valid.
+    #
+    # @example Is the document valid?
+    #   person.valid?
+    #
+    # @return [ true, false ] True if valid, false if not.
+    def valid?(*)
       _run_validation_callbacks { super }
     end
   end

data/lib/mongoid/collection.rb

@@ -5,16 +5,17 @@ require "mongoid/collections/master"
 require "mongoid/collections/slaves"
 
 module Mongoid #:nodoc
-  # The Mongoid wrapper to the Mongo Ruby driver's collection object.
+
+  # This class is the Mongoid wrapper to the Mongo Ruby driver's collection
+  # object.
   class Collection
     attr_reader :counter, :name
 
     # All write operations should delegate to the master connection. These
     # operations mimic the methods on a Mongo:Collection.
     #
-    # Example:
-    #
-    # <tt>collection.save({ :name => "Al" })</tt>
+    # @example Delegate the operation.
+    #   collection.save({ :name => "Al" })
     Collections::Operations::PROXIED.each do |name|
       define_method(name) { |*args| master.send(name, *args) }
     end
@@ -23,13 +24,15 @@ module Mongoid #:nodoc
     # defined then send to master. If the read counter is under the configured
     # maximum then return the master. In any other case return the slaves.
     #
-    # Example:
+    # @example Send the operation to the master or slaves.
+    #   collection.directed
     #
-    # <tt>collection.directed</tt>
+    # @param [ Hash ] options The operation options.
     #
-    # Return:
+    # @option options [ true, false ] :cache Should the query cache in memory?
+    # @option options [ true, false ] :enslave Send the write to the slave?
     #
-    # Either a +Master+ or +Slaves+ collection.
+    # @return [ Master, Slaves ] The connection to use.
     def directed(options = {})
       options.delete(:cache)
       enslave = options.delete(:enslave) || @klass.enslaved?
@@ -38,14 +41,13 @@ module Mongoid #:nodoc
 
     # Find documents from the database given a selector and options.
     #
-    # Options:
-    #
-    # selector: A +Hash+ selector that is the query.
-    # options: The options to pass to the db.
+    # @example Find documents in the collection.
+    #   collection.find({ :test => "value" })
     #
-    # Example:
+    # @param [ Hash ] selector The query selector.
+    # @param [ Hash ] options The options to pass to the db.
     #
-    # <tt>collection.find({ :test => "value" })</tt>
+    # @return [ Cursor ] The results.
     def find(selector = {}, options = {})
       cursor = Mongoid::Cursor.new(@klass, self, directed(options).find(selector, options))
       if block_given?
@@ -57,14 +59,13 @@ module Mongoid #:nodoc
 
     # Find the first document from the database given a selector and options.
     #
-    # Options:
+    # @example Find one document.
+    #   collection.find_one({ :test => "value" })
     #
-    # selector: A +Hash+ selector that is the query.
-    # options: The options to pass to the db.
+    # @param [ Hash ] selector The query selector.
+    # @param [ Hash ] options The options to pass to the db.
     #
-    # Example:
-    #
-    # <tt>collection.find_one({ :test => "value" })</tt>
+    # @return [ Document, nil ] A matching document or nil if none found.
     def find_one(selector = {}, options = {})
       directed(options).find_one(selector, options)
     end
@@ -72,47 +73,63 @@ module Mongoid #:nodoc
     # Initialize a new Mongoid::Collection, setting up the master, slave, and
     # name attributes. Masters will be used for writes, slaves for reads.
     #
-    # Example:
+    # @example Create the new collection.
+    #   Collection.new(masters, slaves, "test")
     #
-    # <tt>Mongoid::Collection.new(masters, slaves, "test")</tt>
+    # @param [ Class ] klass The class the collection is for.
+    # @param [ String ] name The name of the collection.
     def initialize(klass, name)
       @klass, @name = klass, name
     end
 
     # Perform a map/reduce on the documents.
     #
-    # Options:
+    # @example Perform the map/reduce.
+    #   collection.map_reduce(map, reduce)
+    #
+    # @param [ String ] map The map javascript function.
+    # @param [ String ] reduce The reduce javascript function.
+    # @param [ Hash ] options The options to pass to the db.
     #
-    # map: The map javascript function.
-    # reduce: The reduce javascript function.
+    # @return [ Cursor ] The results.
     def map_reduce(map, reduce, options = {})
       directed(options).map_reduce(map, reduce, options)
     end
-
     alias :mapreduce :map_reduce
 
     # Return the object responsible for writes to the database. This will
     # always return a collection associated with the Master DB.
     #
-    # Example:
+    # @example Get the master connection.
+    #   collection.master
     #
-    # <tt>collection.writer</tt>
+    # @return [ Master ] The master connection.
     def master
-      @master ||= Collections::Master.new(Mongoid.master, @name)
+      db = Mongoid.databases[@klass.database] || Mongoid.master
+      @master ||= Collections::Master.new(db, @name)
     end
 
     # Return the object responsible for reading documents from the database.
     # This is usually the slave databases, but in their absence the master will
     # handle the task.
     #
-    # Example:
+    # @example Get the slaves array.
+    #   collection.slaves
     #
-    # <tt>collection.reader</tt>
+    # @return [ Slaves ] The pool of slave connections.
     def slaves
-      @slaves ||= Collections::Slaves.new(Mongoid.slaves, @name)
+      slaves = Mongoid.databases["#{@klass.database}_slaves"] || Mongoid.slaves
+      @slaves ||= Collections::Slaves.new(slaves, @name)
     end
 
     protected
+
+    # Determine if the read is going to the master or the slaves.
+    #
+    # @example Use the master or slaves?
+    #   collection.master_or_slaves
+    #
+    # @return [ Master, Slaves ] Master if not slaves exist, or slaves.
     def master_or_slaves
       slaves.empty? ? master : slaves
     end

data/lib/mongoid/collections.rb

@@ -18,7 +18,6 @@ module Mongoid #:nodoc
       #
       # Returns: <tt>Mongo::Collection</tt>
       def collection
-        raise Errors::InvalidCollection.new(self) if embedded?
         self._collection || set_collection
         add_indexes; self._collection
       end

data/lib/mongoid/components.rb

@@ -2,39 +2,44 @@
 module Mongoid #:nodoc
   module Components #:nodoc
     extend ActiveSupport::Concern
+
+    # All modules that a +Document+ is composed of are defined in this
+    # module, to keep the document class from getting too cluttered.
     included do
-      # All modules that a +Document+ is composed of are defined in this
-      # module, to keep the document class from getting too cluttered.
-      include ActiveModel::Conversion
-      include ActiveModel::Naming
-      include ActiveModel::Serialization
-      include ActiveModel::MassAssignmentSecurity
-      include ActiveModel::Serializers::JSON
-      include ActiveModel::Serializers::Xml
-      include Mongoid::Associations
-      include Mongoid::Atomicity
-      include Mongoid::Attributes
-      include Mongoid::Collections
-      include Mongoid::Dirty
-      include Mongoid::Extras
-      include Mongoid::Fields
-      include Mongoid::Hierarchy
-      include Mongoid::Indexes
-      include Mongoid::JSON
-      include Mongoid::Keys
-      include Mongoid::Matchers
-      include Mongoid::Memoization
-      include Mongoid::Modifiers
-      include Mongoid::MultiParameterAttributes
-      include Mongoid::Paths
-      include Mongoid::Persistence
-      include Mongoid::Safety
-      include Mongoid::State
-      include Mongoid::Validations
-      include Mongoid::Callbacks
       extend ActiveModel::Translation
+      extend Mongoid::DefaultScope
       extend Mongoid::Finders
       extend Mongoid::NamedScope
     end
+
+    include ActiveModel::Conversion
+    include ActiveModel::Naming
+    include ActiveModel::Serialization
+    include ActiveModel::MassAssignmentSecurity
+    include ActiveModel::Serializers::JSON
+    include ActiveModel::Serializers::Xml
+    include Mongoid::Atomicity
+    include Mongoid::Attributes
+    include Mongoid::Collections
+    include Mongoid::Copyable
+    include Mongoid::Dirty
+    include Mongoid::Extras
+    include Mongoid::Fields
+    include Mongoid::Hierarchy
+    include Mongoid::Indexes
+    include Mongoid::Inspection
+    include Mongoid::JSON
+    include Mongoid::Keys
+    include Mongoid::Matchers
+    include Mongoid::MultiParameterAttributes
+    include Mongoid::Modifiers
+    include Mongoid::NestedAttributes
+    include Mongoid::Paths
+    include Mongoid::Persistence
+    include Mongoid::Relations
+    include Mongoid::Safety
+    include Mongoid::State
+    include Mongoid::Validations
+    include Mongoid::Callbacks
   end
 end

data/lib/mongoid/config.rb

@@ -1,52 +1,134 @@
 # encoding: utf-8
 require "uri"
+require "mongoid/config/database"
 
 module Mongoid #:nodoc
-  class Config #:nodoc
-    include Singleton
 
-    attr_accessor \
-      :allow_dynamic_fields,
-      :include_root_in_json,
-      :reconnect_time,
-      :parameterize_keys,
-      :persist_in_safe_mode,
-      :raise_not_found_error,
-      :autocreate_indexes,
-      :skip_version_check
+  # This module defines all the configuration options for Mongoid, including the
+  # database connections.
+  #
+  # @todo Durran: This module needs an overhaul, remove singleton, etc.
+  module Config
+    extend self
 
-    # Initializes the configuration with default settings.
-    def initialize
-      reset
+    attr_accessor :master, :slaves, :settings
+    @settings = {}
+
+    # Define a configuration option with a default.
+    #
+    # @example Define the option.
+    #   Config.option(:persist_in_safe_mode, :default => false)
+    #
+    # @param [ Symbol ] name The name of the configuration option.
+    # @param [ Hash ] options Extras for the option.
+    #
+    # @option options [ Object ] :default The default value.
+    #
+    # @since 2.0.0.rc.1
+    def option(name, options = {})
+      define_method(name) do
+        settings.has_key?(name) ? settings[name] : options[:default]
+      end
+      define_method("#{name}=") { |value| settings[name] = value }
+      define_method("#{name}?") { send(name) }
     end
 
-    # Sets whether the times returned from the database are in UTC or local time.
-    # If you omit this setting, then times will be returned in
-    # the local time zone.
+    option :allow_dynamic_fields, :default => true
+    option :include_root_in_json, :default => false
+    option :parameterize_keys, :default => true
+    option :persist_in_safe_mode, :default => false
+    option :raise_not_found_error, :default => true
+    option :reconnect_time, :default => 3
+    option :autocreate_indexes, :default => false
+    option :skip_version_check, :default => false
+    option :time_zone, :default => nil
+
+    # Adds a new I18n locale file to the load path.
     #
-    # Example:
+    # @example Add a portuguese locale.
+    #   Mongoid::Config.add_language('pt')
     #
-    # <tt>Config.use_utc = true</tt>
+    # @example Add all available languages.
+    #   Mongoid::Config.add_language('*')
     #
-    # Returns:
+    # @param [ String ] language_code The language to add.
+    def add_language(language_code = nil)
+      Dir[
+        File.join(
+          File.dirname(__FILE__), "..", "config", "locales", "#{language_code}.yml"
+        )
+      ].each do |file|
+        I18n.load_path << File.expand_path(file)
+      end
+    end
+
+    # Get any extra databases that have been configured.
     #
-    # A boolean
-    def use_utc=(value)
-      @use_utc = value || false
+    # @example Get the extras.
+    #   config.databases
+    #
+    # @return [ Hash ] A hash of secondary databases.
+    def databases
+      configure_extras(@settings["databases"]) unless @databases || !@settings
+      @databases || {}
     end
 
-    # Returns whether times are return from the database in UTC. If
-    # this setting is false, then times will be returned in the local time zone.
+    # @todo Durran: There were no tests around the databases setter, not sure
+    # what the exact expectation was. Set with a hash?
+    def databases=(databases)
+    end
+
+    # Return field names that could cause destructive things to happen if
+    # defined in a Mongoid::Document.
     #
-    # Example:
+    # @example Get the destructive fields.
+    #   config.destructive_fields
     #
-    # <tt>Config.use_utc</tt>
+    # @return [ Array<String> ] An array of bad field names.
+    def destructive_fields
+      @destructive_fields ||= lambda {
+        klass = Class.new do
+          include Mongoid::Document
+        end
+        klass.instance_methods(true).collect { |method| method.to_s }
+      }.call
+    end
+
+    # Configure mongoid from a hash. This is usually called after parsing a
+    # yaml config file such as mongoid.yml.
     #
-    # Returns:
+    # @example Configure Mongoid.
+    #   config.from_hash({})
     #
-    # A boolean
-    attr_reader :use_utc
-    alias_method :use_utc?, :use_utc
+    # @param [ Hash ] options The settings to use.
+    def from_hash(options = {})
+      options.except("database", "slaves", "databases").each_pair do |name, value|
+        send("#{name}=", value) if respond_to?("#{name}=")
+      end
+      configure_databases(options)
+      configure_extras(options["databases"])
+    end
+
+    # Returns the logger, or defaults to Rails logger or stdout logger.
+    #
+    # @example Get the logger.
+    #   config.logger
+    #
+    # @return [ Logger ] The desired logger.
+    def logger
+      @logger ||= defined?(Rails) ? Rails.logger : ::Logger.new($stdout)
+    end
+
+    # Sets the logger for Mongoid to use.
+    #
+    # @example Set the logger.
+    #   config.logger = Logger.new($stdout, :warn)
+    #
+    # @return [ Logger ] The newly set logger.
+    def logger=(logger)
+      @logger = logger
+      @master.connection.instance_variable_set(:@logger, logger)
+    end
 
     # Sets whether the times returned from the database use the ruby or
     # the ActiveSupport time zone.
@@ -80,31 +162,32 @@ module Mongoid #:nodoc
     # Sets the Mongo::DB master database to be used. If the object trying to be
     # set is not a valid +Mongo::DB+, then an error will be raised.
     #
-    # Example:
+    # @example Set the master database.
+    #   config.master = Mongo::Connection.db("test")
     #
-    # <tt>Config.master = Mongo::Connection.db("test")</tt>
+    # @param [ Mongo::DB ] db The master database.
     #
-    # Returns:
+    # @raise [ Errors::InvalidDatabase ] If the master isnt a valid object.
     #
-    # The master +Mongo::DB+ instance.
+    # @return [ Mongo::DB ] The master instance.
     def master=(db)
       check_database!(db)
       @master = db
     end
+    alias :database= :master=
 
     # Returns the master database, or if none has been set it will raise an
     # error.
     #
-    # Example:
-    #
-    # <tt>Config.master</tt>
+    # @example Get the master database.
+    #   config.master
     #
-    # Returns:
+    # @raise [ Errors::InvalidDatabase ] If the database was not set.
     #
-    # The master +Mongo::DB+
+    # @return [ Mongo::DB ] The master database.
     def master
       unless @master
-        _master(@settings)  if @settings
+        configure_databases(@settings) unless @settings.blank?
         raise Errors::InvalidDatabase.new(nil) unless @master
       end
       if @reconnect
@@ -113,20 +196,44 @@ module Mongoid #:nodoc
       end
       @master
     end
-
     alias :database :master
-    alias :database= :master=
+
+    # Convenience method for connecting to the master database after forking a
+    # new process.
+    #
+    # @example Reconnect to the master.
+    #   Mongoid.reconnect!
+    #
+    # @param [ true, false ] now Perform the reconnection immediately?
+    def reconnect!(now = true)
+      if now
+        master.connection.connect
+      else
+        # We set a @reconnect flag so that #master knows to reconnect the next
+        # time the connection is accessed.
+        @reconnect = true
+      end
+    end
+
+    # Reset the configuration options to the defaults.
+    #
+    # @example Reset the configuration options.
+    #   config.reset
+    def reset
+      settings.clear
+    end
 
     # Sets the Mongo::DB slave databases to be used. If the objects provided
     # are not valid +Mongo::DBs+ an error will be raised.
     #
-    # Example:
+    # @example Set the slaves.
+    #   config.slaves = [ Mongo::Connection.db("test") ]
     #
-    # <tt>Config.slaves = [ Mongo::Connection.db("test") ]</tt>
+    # @param [ Array<Mongo::DB> ] dbs The slave databases.
     #
-    # Returns:
+    # @raise [ Errors::InvalidDatabase ] If the slaves arent valid objects.
     #
-    # The slave DB instances.
+    # @return [ Array<Mongo::DB> ] The slave DB instances.
     def slaves=(dbs)
       return unless dbs
       dbs.each do |db|
@@ -137,186 +244,93 @@ module Mongoid #:nodoc
 
     # Returns the slave databases or nil if none have been set.
     #
-    # Example:
+    # @example Get the slaves.
+    #   config.slaves
     #
-    # <tt>Config.slaves</tt>
-    #
-    # Returns:
-    #
-    # The slave +Mongo::DBs+
+    # @return [ Array<Mongo::DB>, nil ] The slave databases.
     def slaves
-      _slaves(@settings)  unless @slaves || !@settings
-      @slaves
-    end
-
-    # Returns the logger, or defaults to Rails logger or stdout logger.
-    #
-    # Example:
-    #
-    # <tt>Config.logger</tt>
-    def logger
-      return @logger if defined?(@logger)
-
-      @logger = defined?(Rails) ? Rails.logger : ::Logger.new($stdout)
-    end
-
-    # Sets the logger for Mongoid to use.
-    #
-    # Example:
-    #
-    # <tt>Config.logger = Logger.new($stdout, :warn)</tt>
-    def logger=(logger)
-      @logger = logger
-    end
-
-    # Return field names that could cause destructive things to happen if
-    # defined in a Mongoid::Document
-    #
-    # Example:
-    #
-    # <tt>Config.destructive_fields</tt>
-    #
-    # Returns:
-    #
-    # An array of bad field names.
-    def destructive_fields
-      @destructive_fields ||= lambda {
-        klass = Class.new do
-          include Mongoid::Document
-        end
-        klass.instance_methods(true).collect { |method| method.to_s }
-      }.call
-    end
-
-    # Configure mongoid from a hash. This is usually called after parsing a
-    # yaml config file such as mongoid.yml.
-    #
-    # Example:
-    #
-    # <tt>Mongoid::Config.instance.from_hash({})</tt>
-    def from_hash(settings)
-      settings.except("database", "slaves").each_pair do |name, value|
-        send("#{name}=", value) if respond_to?("#{name}=")
+      unless @slaves
+        configure_databases(@settings) if @settings && @settings[:database]
       end
-      @settings = settings.dup
+      @slaves
     end
 
-    # Adds a new I18n locale file to the load path
-    #
-    # Example:
-    #
-    # Add portuguese locale
-    # <tt>Mongoid::config.add_language('pt')</tt>
+    # Sets whether the times returned from the database are in UTC or local time.
+    # If you omit this setting, then times will be returned in
+    # the local time zone.
     #
-    # Adds all available languages
-    # <tt>Mongoid::Config.add_language('*')</tt>
-    def add_language(language_code = nil)
-      Dir[File.join(File.dirname(__FILE__), "..", "config", "locales", "#{language_code}.yml")].each do |file|
-        I18n.load_path << File.expand_path(file)
-      end
-    end
-
-    # Convenience method for connecting to the master database after forking a
-    # new process.
+    # @example Set the use of UTC.
+    #   config.use_utc = true
     #
-    # Example:
+    # @param [ true, false ] value Whether to use UTC or not.
     #
-    # <tt>Mongoid.reconnect!</tt>
-    def reconnect!(now = true)
-      if now
-        master.connection.connect
-      else
-        # We set a @reconnect flag so that #master knows to reconnect the next
-        # time the connection is accessed.
-        @reconnect = true
-      end
+    # @return [ true, false ] Are we using UTC?
+    def use_utc=(value)
+      @use_utc = value || false
     end
 
-    # Reset the configuration options to the defaults.
+    # Returns whether times are return from the database in UTC. If
+    # this setting is false, then times will be returned in the local time zone.
     #
-    # Example:
+    # @example Are we using UTC?
+    #   config.use_utc
     #
-    # <tt>config.reset</tt>
-    def reset
-      @allow_dynamic_fields = true
-      @include_root_in_json = false
-      @parameterize_keys = true
-      @persist_in_safe_mode = false
-      @raise_not_found_error = true
-      @reconnect_time = 3
-      @autocreate_indexes = false
-      @skip_version_check = false
-      @time_zone = nil
-    end
+    # @return [ true, false ] True if UTC, false if not.
+    attr_reader :use_utc
+    alias :use_utc? :use_utc
 
     protected
 
     # Check if the database is valid and the correct version.
     #
-    # Example:
+    # @example Check if the database is valid.
+    #   config.check_database!
     #
-    # <tt>config.check_database!</tt>
+    # @param [ Mongo::DB ] database The db to check.
+    #
+    # @raise [ Errors::InvalidDatabase ] If the object is not valid.
+    # @raise [ Errors::UnsupportedVersion ] If the db version is too old.
     def check_database!(database)
       raise Errors::InvalidDatabase.new(database) unless database.kind_of?(Mongo::DB)
-      unless Mongoid.skip_version_check
+      unless skip_version_check
         version = database.connection.server_version
         raise Errors::UnsupportedVersion.new(version) if version < Mongoid::MONGODB_VERSION
       end
     end
 
-    # Get a master database from settings.
+    # Get a database from settings.
     #
-    # TODO: Durran: This code's a bit hairy, refactor.
+    # @example Configure the master and slave dbs.
+    #   config.configure_databases("database" => "mongoid")
     #
-    # Example:
+    # @param [ Hash ] options The options to use.
     #
-    # <tt>config._master({}, "test")</tt>
-    def _master(settings)
-      mongo_uri = settings["uri"].present? ? URI.parse(settings["uri"]) : OpenStruct.new
-
-      name = settings["database"] || mongo_uri.path.to_s.sub("/", "")
-      host = settings["host"] || mongo_uri.host || "localhost"
-      port = settings["port"] || mongo_uri.port || 27017
-      pool_size = settings["pool_size"] || 1
-      username = settings["username"] || mongo_uri.user
-      password = settings["password"] || mongo_uri.password
-
-      connection = Mongo::Connection.new(host, port, :logger => Mongoid::Logger.new, :pool_size => pool_size)
-      if username || password
-        connection.add_auth(name, username, password)
-        connection.apply_saved_authentication
-      end
-      self.master = connection.db(name)
+    # @option options [ String ] :database The database name.
+    # @option options [ String ] :host The database host.
+    # @option options [ String ] :password The password for authentication.
+    # @option options [ Integer ] :port The port for the database.
+    # @option options [ Array<Hash> ] :slaves The slave db options.
+    # @option options [ String ] :uri The uri for the database.
+    # @option options [ String ] :username The user for authentication.
+    #
+    # @since 2.0.0.rc.1
+    def configure_databases(options)
+      @master, @slaves = Database.new(options).configure
     end
 
-    # Get a bunch-o-slaves from settings and names.
+    # Get the secondary databases from settings.
     #
-    # TODO: Durran: This code's a bit hairy, refactor.
+    # @example Configure the master and slave dbs.
+    #   config.configure_extras("databases" => settings)
     #
-    # Example:
+    # @param [ Hash ] options The options to use.
     #
-    # <tt>config._slaves({}, "test")</tt>
-    def _slaves(settings)
-      mongo_uri = settings["uri"].present? ? URI.parse(settings["uri"]) : OpenStruct.new
-      name = settings["database"] || mongo_uri.path.to_s.sub("/", "")
-      self.slaves = []
-      slaves = settings["slaves"]
-      slaves.to_a.each do |slave|
-        slave_uri = slave["uri"].present? ? URI.parse(slave["uri"]) : OpenStruct.new
-        slave_username = slave["username"] || slave_uri.user
-        slave_password = slave["password"] || slave_uri.password
-
-        slave_connection = Mongo::Connection.new(
-          slave["host"] || slave_uri.host || "localhost",
-          slave["port"] || slave_uri.port,
-          :slave_ok => true
-        )
-
-        if slave_username || slave_password
-          slave_connection.add_auth(name, slave_username, slave_password)
-          slave_connection.apply_saved_authentication
+    # @since 2.0.0.rc.1
+    def configure_extras(extras)
+      @databases = (extras || []).inject({}) do |dbs, (name, options)|
+        dbs.tap do |extra|
+          dbs[name], dbs["#{name}_slaves"] = Database.new(options).configure
         end
-        self.slaves << slave_connection.db(name)
       end
     end
   end