activerecord 6.1.6 → 7.1.2

data/lib/active_record/result.rb

@@ -2,6 +2,8 @@
 
 module ActiveRecord
   ###
+  # = Active Record \Result
+  #
   # This class encapsulates a result returned from calling
   # {#exec_query}[rdoc-ref:ConnectionAdapters::DatabaseStatements#exec_query]
   # on any database connection adapter. For example:
@@ -36,6 +38,14 @@ module ActiveRecord
 
     attr_reader :columns, :rows, :column_types
 
+    def self.empty(async: false) # :nodoc:
+      if async
+        EMPTY_ASYNC
+      else
+        EMPTY
+      end
+    end
+
     def initialize(columns, rows, column_types = {})
       @columns      = columns
       @rows         = rows
@@ -57,19 +67,14 @@ module ActiveRecord
     # row as parameter.
     #
     # Returns an +Enumerator+ if no block is given.
-    def each
+    def each(&block)
       if block_given?
-        hash_rows.each { |row| yield row }
+        hash_rows.each(&block)
       else
         hash_rows.to_enum { @rows.size }
       end
     end
 
-    alias :map! :map
-    alias :collect! :map
-    deprecate "map!": :map
-    deprecate "collect!": :map
-
     # Returns true if there are no records, otherwise false.
     def empty?
       rows.empty?
@@ -91,6 +96,14 @@ module ActiveRecord
       n ? hash_rows.last(n) : hash_rows.last
     end
 
+    def result # :nodoc:
+      self
+    end
+
+    def cancel # :nodoc:
+      self
+    end
+
     def cast_values(type_overrides = {}) # :nodoc:
       if columns.one?
         # Separated to avoid allocating an array per row
@@ -98,7 +111,7 @@ module ActiveRecord
         type = if type_overrides.is_a?(Array)
           type_overrides.first
         else
-          column_type(columns.first, type_overrides)
+          column_type(columns.first, 0, type_overrides)
         end
 
         rows.map do |(value)|
@@ -108,7 +121,7 @@ module ActiveRecord
         types = if type_overrides.is_a?(Array)
           type_overrides
         else
-          columns.map { |name| column_type(name, type_overrides) }
+          columns.map.with_index { |name, i| column_type(name, i, type_overrides) }
         end
 
         rows.map do |values|
@@ -124,10 +137,17 @@ module ActiveRecord
       @hash_rows    = nil
     end
 
+    def freeze # :nodoc:
+      hash_rows.freeze
+      super
+    end
+
     private
-      def column_type(name, type_overrides = {})
+      def column_type(name, index, type_overrides)
         type_overrides.fetch(name) do
-          column_types.fetch(name, Type.default_value)
+          column_types.fetch(index) do
+            column_types.fetch(name, Type.default_value)
+          end
         end
       end
 
@@ -171,5 +191,11 @@ module ActiveRecord
             }
           end
       end
+
+      EMPTY = new([].freeze, [].freeze, {}.freeze).freeze
+      private_constant :EMPTY
+
+      EMPTY_ASYNC = FutureResult::Complete.new(EMPTY).freeze
+      private_constant :EMPTY_ASYNC
   end
 end

data/lib/active_record/runtime_registry.rb

@@ -1,24 +1,29 @@
 # frozen_string_literal: true
 
-require "active_support/per_thread_registry"
-
 module ActiveRecord
   # This is a thread locals registry for Active Record. For example:
   #
-  #   ActiveRecord::RuntimeRegistry.connection_handler
-  #
-  # returns the connection handler local to the current thread.
+  #   ActiveRecord::RuntimeRegistry.sql_runtime
   #
-  # See the documentation of ActiveSupport::PerThreadRegistry
-  # for further details.
-  class RuntimeRegistry # :nodoc:
-    extend ActiveSupport::PerThreadRegistry
+  # returns the connection handler local to the current unit of execution (either thread of fiber).
+  module RuntimeRegistry # :nodoc:
+    extend self
 
-    attr_accessor :sql_runtime
+    def sql_runtime
+      ActiveSupport::IsolatedExecutionState[:active_record_sql_runtime] ||= 0.0
+    end
 
-    [:sql_runtime].each do |val|
-      class_eval %{ def self.#{val}; instance.#{val}; end }, __FILE__, __LINE__
-      class_eval %{ def self.#{val}=(x); instance.#{val}=x; end }, __FILE__, __LINE__
+    def sql_runtime=(runtime)
+      ActiveSupport::IsolatedExecutionState[:active_record_sql_runtime] = runtime
+    end
+
+    def reset
+      rt, self.sql_runtime = sql_runtime, 0.0
+      rt
     end
   end
 end
+
+ActiveSupport::Notifications.monotonic_subscribe("sql.active_record") do |name, start, finish, id, payload|
+  ActiveRecord::RuntimeRegistry.sql_runtime += (finish - start) * 1_000.0
+end

data/lib/active_record/sanitization.rb

@@ -5,8 +5,8 @@ module ActiveRecord
     extend ActiveSupport::Concern
 
     module ClassMethods
-      # Accepts an array or string of SQL conditions and sanitizes
-      # them into a valid SQL fragment for a WHERE clause.
+      # Accepts an array of SQL conditions and sanitizes them into a valid
+      # SQL fragment for a WHERE clause.
       #
       #   sanitize_sql_for_conditions(["name=? and group_id=?", "foo'bar", 4])
       #   # => "name='foo''bar' and group_id=4"
@@ -17,8 +17,19 @@ module ActiveRecord
       #   sanitize_sql_for_conditions(["name='%s' and group_id='%s'", "foo'bar", 4])
       #   # => "name='foo''bar' and group_id='4'"
       #
+      # This method will NOT sanitize a SQL string since it won't contain
+      # any conditions in it and will return the string as is.
+      #
       #   sanitize_sql_for_conditions("name='foo''bar' and group_id='4'")
       #   # => "name='foo''bar' and group_id='4'"
+      #
+      # Note that this sanitization method is not schema-aware, hence won't do any type casting
+      # and will directly use the database adapter's +quote+ method.
+      # For MySQL specifically this means that numeric parameters will be quoted as strings
+      # to prevent query manipulation attacks.
+      #
+      #   sanitize_sql_for_conditions(["role = ?", 0])
+      #   # => "role = '0'"
       def sanitize_sql_for_conditions(condition)
         return nil if condition.blank?
 
@@ -29,8 +40,8 @@ module ActiveRecord
       end
       alias :sanitize_sql :sanitize_sql_for_conditions
 
-      # Accepts an array, hash, or string of SQL conditions and sanitizes
-      # them into a valid SQL fragment for a SET clause.
+      # Accepts an array or hash of SQL conditions and sanitizes them into
+      # a valid SQL fragment for a SET clause.
       #
       #   sanitize_sql_for_assignment(["name=? and group_id=?", nil, 4])
       #   # => "name=NULL and group_id=4"
@@ -41,8 +52,19 @@ module ActiveRecord
       #   Post.sanitize_sql_for_assignment({ name: nil, group_id: 4 })
       #   # => "`posts`.`name` = NULL, `posts`.`group_id` = 4"
       #
+      # This method will NOT sanitize a SQL string since it won't contain
+      # any conditions in it and will return the string as is.
+      #
       #   sanitize_sql_for_assignment("name=NULL and group_id='4'")
       #   # => "name=NULL and group_id='4'"
+      #
+      # Note that this sanitization method is not schema-aware, hence won't do any type casting
+      # and will directly use the database adapter's +quote+ method.
+      # For MySQL specifically this means that numeric parameters will be quoted as strings
+      # to prevent query manipulation attacks.
+      #
+      #   sanitize_sql_for_assignment(["role = ?", 0])
+      #   # => "role = '0'"
       def sanitize_sql_for_assignment(assignments, default_table_name = table_name)
         case assignments
         when Array; sanitize_sql_array(assignments)
@@ -54,7 +76,7 @@ module ActiveRecord
       # Accepts an array, or string of SQL conditions and sanitizes
       # them into a valid SQL fragment for an ORDER clause.
       #
-      #   sanitize_sql_for_order(["field(id, ?)", [1,3,2]])
+      #   sanitize_sql_for_order([Arel.sql("field(id, ?)"), [1,3,2]])
       #   # => "field(id, 1,3,2)"
       #
       #   sanitize_sql_for_order("id ASC")
@@ -92,26 +114,32 @@ module ActiveRecord
       end
 
       # Sanitizes a +string+ so that it is safe to use within an SQL
-      # LIKE statement. This method uses +escape_character+ to escape all occurrences of "\", "_" and "%".
+      # LIKE statement. This method uses +escape_character+ to escape all
+      # occurrences of itself, "_" and "%".
       #
-      #   sanitize_sql_like("100%")
-      #   # => "100\\%"
+      #   sanitize_sql_like("100% true!")
+      #   # => "100\\% true!"
       #
       #   sanitize_sql_like("snake_cased_string")
       #   # => "snake\\_cased\\_string"
       #
-      #   sanitize_sql_like("100%", "!")
-      #   # => "100!%"
+      #   sanitize_sql_like("100% true!", "!")
+      #   # => "100!% true!!"
       #
       #   sanitize_sql_like("snake_cased_string", "!")
       #   # => "snake!_cased!_string"
       def sanitize_sql_like(string, escape_character = "\\")
-        pattern = Regexp.union(escape_character, "%", "_")
-        string.gsub(pattern) { |x| [escape_character, x].join }
+        if string.include?(escape_character) && escape_character != "%" && escape_character != "_"
+          string = string.gsub(escape_character, '\0\0')
+        end
+
+        string.gsub(/(?=[%_])/, escape_character)
       end
 
       # Accepts an array of conditions. The array has each value
-      # sanitized and interpolated into the SQL statement.
+      # sanitized and interpolated into the SQL statement. If using named bind
+      # variables in SQL statements where a colon is required verbatim use a
+      # backslash to escape.
       #
       #   sanitize_sql_array(["name=? and group_id=?", "foo'bar", 4])
       #   # => "name='foo''bar' and group_id=4"
@@ -119,8 +147,19 @@ module ActiveRecord
       #   sanitize_sql_array(["name=:name and group_id=:group_id", name: "foo'bar", group_id: 4])
       #   # => "name='foo''bar' and group_id=4"
       #
+      #   sanitize_sql_array(["TO_TIMESTAMP(:date, 'YYYY/MM/DD HH12\\:MI\\:SS')", date: "foo"])
+      #   # => "TO_TIMESTAMP('foo', 'YYYY/MM/DD HH12:MI:SS')"
+      #
       #   sanitize_sql_array(["name='%s' and group_id='%s'", "foo'bar", 4])
       #   # => "name='foo''bar' and group_id='4'"
+      #
+      # Note that this sanitization method is not schema-aware, hence won't do any type casting
+      # and will directly use the database adapter's +quote+ method.
+      # For MySQL specifically this means that numeric parameters will be quoted as strings
+      # to prevent query manipulation attacks.
+      #
+      #   sanitize_sql_array(["role = ?", 0])
+      #   # => "role = '0'"
       def sanitize_sql_array(ary)
         statement, *values = ary
         if values.first.is_a?(Hash) && /:\w+/.match?(statement)
@@ -137,14 +176,18 @@ module ActiveRecord
       def disallow_raw_sql!(args, permit: connection.column_name_matcher) # :nodoc:
         unexpected = nil
         args.each do |arg|
-          next if arg.is_a?(Symbol) || Arel.arel_node?(arg) || permit.match?(arg.to_s)
+          next if arg.is_a?(Symbol) || Arel.arel_node?(arg) || permit.match?(arg.to_s.strip)
           (unexpected ||= []) << arg
         end
 
         if unexpected
           raise(ActiveRecord::UnknownAttributeReference,
-            "Query method called with non-attribute argument(s): " +
-            unexpected.map(&:inspect).join(", ")
+            "Dangerous query method (method whose arguments are used as raw " \
+            "SQL) called with non-attribute argument(s): " \
+            "#{unexpected.map(&:inspect).join(", ")}." \
+            "This method should not be called with user-provided values, such as request " \
+            "parameters or model attributes. Known-safe values can be passed " \
+            "by wrapping them in Arel.sql()."
           )
         end
       end
@@ -168,9 +211,11 @@ module ActiveRecord
         end
 
         def replace_named_bind_variables(statement, bind_vars)
-          statement.gsub(/(:?):([a-zA-Z]\w*)/) do |match|
+          statement.gsub(/([:\\]?):([a-zA-Z]\w*)/) do |match|
             if $1 == ":" # skip postgresql casts
               match # return the whole match
+            elsif $1 == "\\" # escaped literal colon
+              match[1..-1] # return match with escaping backlash char removed
             elsif bind_vars.include?(match = $2.to_sym)
               replace_bind_variable(bind_vars[match])
             else
@@ -183,13 +228,13 @@ module ActiveRecord
           if value.respond_to?(:map) && !value.acts_like?(:string)
             values = value.map { |v| v.respond_to?(:id_for_database) ? v.id_for_database : v }
             if values.empty?
-              c.quote(nil)
+              c.quote(c.cast_bound_value(nil))
             else
-              values.map! { |v| c.quote(v) }.join(",")
+              values.map! { |v| c.quote(c.cast_bound_value(v)) }.join(",")
             end
           else
             value = value.id_for_database if value.respond_to?(:id_for_database)
-            c.quote(value)
+            c.quote(c.cast_bound_value(value))
           end
         end
 

data/lib/active_record/schema.rb

@@ -10,7 +10,7 @@ module ActiveRecord
   #
   # Usage:
   #
-  #   ActiveRecord::Schema.define do
+  #   ActiveRecord::Schema[7.0].define do
   #     create_table :authors do |t|
   #       t.string :name, null: false
   #     end
@@ -30,32 +30,46 @@ module ActiveRecord
   # ActiveRecord::Schema is only supported by database adapters that also
   # support migrations, the two features being very similar.
   class Schema < Migration::Current
-    # Eval the given block. All methods available to the current connection
-    # adapter are available within the block, so you can easily use the
-    # database definition DSL to build up your schema (
-    # {create_table}[rdoc-ref:ConnectionAdapters::SchemaStatements#create_table],
-    # {add_index}[rdoc-ref:ConnectionAdapters::SchemaStatements#add_index], etc.).
-    #
-    # The +info+ hash is optional, and if given is used to define metadata
-    # about the current schema (currently, only the schema's version):
-    #
-    #   ActiveRecord::Schema.define(version: 2038_01_19_000001) do
-    #     ...
-    #   end
-    def self.define(info = {}, &block)
-      new.define(info, &block)
-    end
+    module Definition
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Eval the given block. All methods available to the current connection
+        # adapter are available within the block, so you can easily use the
+        # database definition DSL to build up your schema (
+        # {create_table}[rdoc-ref:ConnectionAdapters::SchemaStatements#create_table],
+        # {add_index}[rdoc-ref:ConnectionAdapters::SchemaStatements#add_index], etc.).
+        #
+        # The +info+ hash is optional, and if given is used to define metadata
+        # about the current schema (currently, only the schema's version):
+        #
+        #   ActiveRecord::Schema[7.0].define(version: 2038_01_19_000001) do
+        #     ...
+        #   end
+        def define(info = {}, &block)
+          new.define(info, &block)
+        end
+      end
 
-    def define(info, &block) # :nodoc:
-      instance_eval(&block)
+      def define(info, &block) # :nodoc:
+        instance_eval(&block)
 
-      if info[:version].present?
         connection.schema_migration.create_table
-        connection.assume_migrated_upto_version(info[:version])
+        if info[:version].present?
+          connection.assume_migrated_upto_version(info[:version])
+        end
+
+        connection.internal_metadata.create_table_and_set_flags(connection.migration_context.current_environment)
       end
+    end
+
+    include Definition
 
-      ActiveRecord::InternalMetadata.create_table
-      ActiveRecord::InternalMetadata[:environment] = connection.migration_context.current_environment
+    def self.[](version)
+      @class_for_version ||= {}
+      @class_for_version[version] ||= Class.new(Migration::Compatibility.find(version)) do
+        include Definition
+      end
     end
   end
 end

data/lib/active_record/schema_dumper.rb

@@ -7,14 +7,13 @@ module ActiveRecord
   #
   # This class is used to dump the database schema for some connection to some
   # output format (i.e., ActiveRecord::Schema).
-  class SchemaDumper #:nodoc:
+  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 if ActiveRecord::Base.schema_format == :ruby.
-    # Only strings are accepted if ActiveRecord::Base.schema_format == :sql.
+    # Acceptable values are strings and regexps.
     cattr_accessor :ignore_tables, default: []
 
     ##
@@ -29,6 +28,18 @@ module ActiveRecord
     # should not be dumped to db/schema.rb.
     cattr_accessor :chk_ignore_pattern, default: /^chk_rails_[0-9a-f]{10}$/
 
+    ##
+    # :singleton-method:
+    # Specify a custom regular expression matching exclusion constraints which name
+    # should not be dumped to db/schema.rb.
+    cattr_accessor :excl_ignore_pattern, default: /^excl_rails_[0-9a-f]{10}$/
+
+    ##
+    # :singleton-method:
+    # Specify a custom regular expression matching unique constraints which name
+    # should not be dumped to db/schema.rb.
+    cattr_accessor :unique_ignore_pattern, default: /^uniq_rails_[0-9a-f]{10}$/
+
     class << self
       def dump(connection = ActiveRecord::Base.connection, stream = STDOUT, config = ActiveRecord::Base)
         connection.create_schema_dumper(generate_options(config)).dump(stream)
@@ -46,7 +57,9 @@ module ActiveRecord
 
     def dump(stream)
       header(stream)
+      schemas(stream)
       extensions(stream)
+      types(stream)
       tables(stream)
       trailer(stream)
       stream
@@ -59,6 +72,11 @@ module ActiveRecord
         @connection = connection
         @version = connection.migration_context.current_version rescue nil
         @options = options
+        @ignore_tables = [
+          ActiveRecord::Base.schema_migrations_table_name,
+          ActiveRecord::Base.internal_metadata_table_name,
+          self.class.ignore_tables
+        ].flatten
       end
 
       # turns 20170404131909 into "2017_04_04_131909"
@@ -73,22 +91,21 @@ module ActiveRecord
       end
 
       def header(stream)
-        stream.puts <<HEADER
-# This file is auto-generated from the current state of the database. Instead
-# of editing this file, please use the migrations feature of Active Record to
-# incrementally modify your database, and then regenerate this schema definition.
-#
-# This file is the source Rails uses to define your schema when running `bin/rails
-# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
-# be faster and is potentially less error prone than running all of your
-# migrations from scratch. Old migrations may fail to apply correctly if those
-# migrations use external dependencies or application code.
-#
-# It's strongly recommended that you check this file into your version control system.
-
-ActiveRecord::Schema.define(#{define_params}) do
-
-HEADER
+        stream.puts <<~HEADER
+          # This file is auto-generated from the current state of the database. Instead
+          # of editing this file, please use the migrations feature of Active Record to
+          # incrementally modify your database, and then regenerate this schema definition.
+          #
+          # This file is the source Rails uses to define your schema when running `bin/rails
+          # db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+          # be faster and is potentially less error prone than running all of your
+          # migrations from scratch. Old migrations may fail to apply correctly if those
+          # migrations use external dependencies or application code.
+          #
+          # It's strongly recommended that you check this file into your version control system.
+
+          ActiveRecord::Schema[#{ActiveRecord::Migration.current_version}].define(#{define_params}) do
+        HEADER
       end
 
       def trailer(stream)
@@ -99,6 +116,14 @@ HEADER
       def extensions(stream)
       end
 
+      # (enum) types are only supported by PostgreSQL
+      def types(stream)
+      end
+
+      # schemas are only supported by PostgreSQL
+      def schemas(stream)
+      end
+
       def tables(stream)
         sorted_tables = @connection.tables.sort
 
@@ -107,7 +132,7 @@ HEADER
         end
 
         # dump foreign keys at the end to make sure all dependent tables exist.
-        if @connection.supports_foreign_keys?
+        if @connection.use_foreign_keys?
           sorted_tables.each do |tbl|
             foreign_keys(tbl, stream) unless ignored?(tbl)
           end
@@ -154,6 +179,7 @@ HEADER
           columns.each do |column|
             raise StandardError, "Unknown type '#{column.sql_type}' for column '#{column.name}'" unless @connection.valid_type?(column.type)
             next if column.name == pk
+
             type, colspec = column_spec(column)
             if type.is_a?(Symbol)
               tbl.print "    t.#{type} #{column.name.inspect}"
@@ -166,12 +192,13 @@ HEADER
 
           indexes_in_create(table, tbl)
           check_constraints_in_create(table, tbl) if @connection.supports_check_constraints?
+          exclusion_constraints_in_create(table, tbl) if @connection.supports_exclusion_constraints?
+          unique_constraints_in_create(table, tbl) if @connection.supports_unique_constraints?
 
           tbl.puts "  end"
           tbl.puts
 
-          tbl.rewind
-          stream.print tbl.read
+          stream.print tbl.string
         rescue => e
           stream.puts "# Could not dump table #{table.inspect} because of following #{e.class}"
           stream.puts "#   #{e.message}"
@@ -196,6 +223,18 @@ HEADER
 
       def indexes_in_create(table, stream)
         if (indexes = @connection.indexes(table)).any?
+          if @connection.supports_exclusion_constraints? && (exclusion_constraints = @connection.exclusion_constraints(table)).any?
+            exclusion_constraint_names = exclusion_constraints.collect(&:name)
+
+            indexes = indexes.reject { |index| exclusion_constraint_names.include?(index.name) }
+          end
+
+          if @connection.supports_unique_constraints? && (unique_constraints = @connection.unique_constraints(table)).any?
+            unique_constraint_names = unique_constraints.collect(&:name)
+
+            indexes = indexes.reject { |index| unique_constraint_names.include?(index.name) }
+          end
+
           index_statements = indexes.map do |index|
             "    t.index #{index_parts(index).join(', ')}"
           end
@@ -214,6 +253,8 @@ HEADER
         index_parts << "opclass: #{format_index_parts(index.opclasses)}" if index.opclasses.present?
         index_parts << "where: #{index.where.inspect}" if index.where
         index_parts << "using: #{index.using.inspect}" if !@connection.default_index_type?(index)
+        index_parts << "include: #{index.include.inspect}" if index.include
+        index_parts << "nulls_not_distinct: #{index.nulls_not_distinct.inspect}" if index.nulls_not_distinct
         index_parts << "type: #{index.type.inspect}" if index.type
         index_parts << "comment: #{index.comment.inspect}" if index.comment
         index_parts
@@ -230,6 +271,8 @@ HEADER
               parts << "name: #{check_constraint.name.inspect}"
             end
 
+            parts << "validate: #{check_constraint.validate?.inspect}" unless check_constraint.validate?
+
             "    #{parts.join(', ')}"
           end
 
@@ -245,7 +288,7 @@ HEADER
               remove_prefix_and_suffix(foreign_key.to_table).inspect,
             ]
 
-            if foreign_key.column != @connection.foreign_key_column_for(foreign_key.to_table)
+            if foreign_key.column != @connection.foreign_key_column_for(foreign_key.to_table, "id")
               parts << "column: #{foreign_key.column.inspect}"
             end
 
@@ -259,6 +302,8 @@ HEADER
 
             parts << "on_update: #{foreign_key.on_update.inspect}" if foreign_key.on_update
             parts << "on_delete: #{foreign_key.on_delete.inspect}" if foreign_key.on_delete
+            parts << "deferrable: #{foreign_key.deferrable.inspect}" if foreign_key.deferrable
+            parts << "validate: #{foreign_key.validate?.inspect}" unless foreign_key.validate?
 
             "  #{parts.join(', ')}"
           end
@@ -286,13 +331,17 @@ HEADER
       end
 
       def remove_prefix_and_suffix(table)
+        # This method appears at the top when profiling active_record test cases run.
+        # Avoid costly calculation when there are no prefix and suffix.
+        return table if @options[:table_name_prefix].blank? && @options[:table_name_suffix].blank?
+
         prefix = Regexp.escape(@options[:table_name_prefix].to_s)
         suffix = Regexp.escape(@options[:table_name_suffix].to_s)
         table.sub(/\A#{prefix}(.+)#{suffix}\z/, "\\1")
       end
 
       def ignored?(table_name)
-        [ActiveRecord::Base.schema_migrations_table_name, ActiveRecord::Base.internal_metadata_table_name, ignore_tables].flatten.any? do |ignored|
+        @ignore_tables.any? do |ignored|
           ignored === remove_prefix_and_suffix(table_name)
         end
       end