sequel 5.83.1 → 5.84.0

data/doc/model_dataset_method_design.rdoc

@@ -1,129 +0,0 @@
-= Model Dataset Method Design Guide
-
-How you design your model dataset methods can significantly affect the flexibility of your API for your model classes, as well as the performance.  The goal of this guide is to provide an example of how to design your model dataset methods for maximum flexibility and performance.
-
-== Flexibility: Use Single Method Per Task
-
-In general, it is recommended that you have a single method per task for maximum flexibility.  For example, let's say you need to retrieve all albums released in a given year, ordered by number of units sold descending, and only care about the id, name and number of units sold.  One way to do this is in your application code (outside the model), you can
-call the dataset methods directly:
-
-  Album.
-    select(:id, :name, :copies_sold).
-    where(release_year: params[:year].to_i).
-    order(Sequel.desc(:copies_sold)).
-    all
-
-One issue with this design is that it ties you to your current database schema, and will make it necessary to change your application code if your schema changes.  In general, it is better to encapsulate your code into a dataset method (or a class method, but a dataset method is more flexible):
-
-  class Album < Sequel::Model
-    dataset_module do
-      def all_albums_released_in_year(year)
-        select(:id, :name, :copies_sold).
-        where(release_year: year).
-        order(Sequel.desc(:copies_sold)).
-        all
-      end
-    end
-  end
-
-Then your application code just needs to call your dataset method:
-
-  Album.all_albums_released_in_year(params[:year].to_i)
-
-The advantage of this approach is that you can change your schema at any point in the future, and you should only need to change your model code, you should never need to change other application code.
-
-== Performance
-
-After designing your dataset methods for flexibility, stop.  Don't worry about performance until you need to worry about performance.  However, assuming you have profiled your application and profiling shows you can benefit from optimizing the above method, you can then consider the performance impact of future design choices.
-
-First, considering that the root cause of the performance issue may not be at the Sequel level, it may be at the database itself.  Use +EXPLAIN+ or the equivalent to analyze the query plan for the query in use, and see if there is something you can do to optimize it, such as adding an appropriate index.
-
-Second, assuming the performance issue is at the Sequel level, you need to understand that one of the best ways to improve performance in most ruby code is to reduce the number of objects allocated.  Here is the above code with comments showing datasets allocated:
-
-  def all_albums_released_in_year(year)
-    select(:id, :name, :copies_sold). # new dataset allocated
-    where(release_year: year).        # new dataset allocated
-    order(Sequel.desc(:copies_sold)). # new dataset allocated
-    all
-  end
-
-Third, you need to understand that Sequel has optimizations specifically designed to reduce the number of objects allocated, by caching intermediate datasets.  Unfortunately, those optimizations do not apply in this case.  The reason for this is that +select+, +where+, and +order+ can potentially receive arbitrary arguments, and enabling caching for them could easily lead to unbounded cache size (denial of service due to memory exhaustion).
-
-To allow intermediate dataset caching to work, you need to signal to Sequel that particular arguments to these methods should be cached, and you can do that by calling methods inside +dataset_module+ blocks such as +select+ and +order+.  These methods will add dataset methods to the model that can cache the returned dataset to optimize performance.  Here is an example using these methods:
-
-  class Album < Sequel::Model
-    dataset_module do
-      select :with_name_and_units, :id, :name, :copies_sold
-      order :by_units_sold, Sequel.desc(:copies_sold)
-
-      def all_albums_released_in_year(year)
-        with_name_and_units.
-        by_units_sold.
-        where(release_year: year).
-        all
-      end
-    end
-  end
-
-Performance aside, this does provide a slightly nicer and more readable internal API, though naming such methods can be problematic.
-
-By calling +select+ and +order+ here, Sequel expects that the created dataset methods may be called more than once on the same dataset, and it knows that the arguments to the underlying +select+ and +order+ methods are fixed, so it can cache the resulting datasets.  Let's comment the above example with dataset allocations:
-
-  def all_albums_released_in_year(year)
-    with_name_and_units.        # cached dataset returned 
-    by_units_sold.              # cached dataset returned
-    where(release_year: year).  # new dataset allocated
-    all
-  end
-
-Note that the order of methods here is important.  If you instead change the method chain to filter the dataset first, then no caching happens:
-
-  def all_albums_released_in_year(year)
-    where(release_year: year).  # new dataset allocated
-    with_name_and_units.        # new dataset allocated
-    by_units_sold.              # new dataset allocated
-    all
-  end
-
-This is because any time a new, uncached dataset is returned by a dataset method, all subsequent methods in the method chain cannot benefit from caching.
-
-Usually, when you are designing methods to process data based on user input, the user input affects the rows selected, and not the columns selected or the order in which the rows are returned.  Sequel is aware of this and has dataset methods that specifically take user input (arguments), interpret them as a filter condition and either:
-
-* Return all matching rows in an array (+where_all+)
-* Iterate over all matching rows (+where_each+)
-* Return first matching row (+first+)
-* Return first column in first matching row, assumes only a single column is selected (+where_single_value+)
-
-After calling these methods on a cached dataset a number of times (currently 3), Sequel will automatically build an optimized loader, cache it, and use it for future loads.  So the above example changes to:
-
-  def all_albums_released_in_year(year)
-    with_name_and_units.           # cached dataset returned
-    by_units_sold.                 # cached dataset returned
-    where_all(release_year: year)  # cached loader used
-  end
-
-This can significantly improve performance, up to 3x for complex method chains that only return a few rows.
-
-So the general advice on designing dataset methods for performance is:
-
-* Use +dataset_module+ methods to create named dataset methods that return cached datasets
-* If any filtering is to be done, have it done last using +where_all+, +where_each+, +first+, or +where_single_value+.
-
-By following this advice, you can significantly increase the performance of your model dataset code.
-
-=== Further Increasing Performance
-
-The best way to further increase performance at the Sequel level is to switch to using prepared statements.  This does require more significant changes to the API.  Here's an example using prepared statements:
-
-  class Album < Sequel::Model
-    ALBUMS_RELEASED_IN_YEAR = select(:id, :name, :copies_sold).
-      where(release_year: :$year).
-      order(Sequel.desc(:copies_sold)).
-      prepare(:all, :all_albums_released_in_year)
-
-    def self.all_albums_released_in_year(year)
-      ALBUMS_RELEASED_IN_YEAR.call(year: year)
-    end
-  end
-
-Note that when using prepared statements, you need to use a class method instead of a dataset method, as the SQL for the prepared statement must be fixed for the class.  This limits the flexibility of the method, since you can no longer call it on arbitrary datasets on the class.

data/doc/model_hooks.rdoc

@@ -1,254 +0,0 @@
-= Model Hooks
-
-This guide is based on http://guides.rubyonrails.org/activerecord_validations_callbacks.html
-
-== Overview
-
-Model hooks are used to specify actions that occur at a given point in a model instance's lifecycle, such as before or after the model object is saved, created, updated, destroyed, or validated.  There are also around hooks for all types, which wrap the before hooks, the behavior, and the after hooks.
-
-== Basic Usage
-
-<tt>Sequel::Model</tt> uses instance methods for hooks.  To define a hook on a model, you just add an instance method to the model class:
-
-  class Album < Sequel::Model
-    def before_create
-      self.created_at ||= Time.now
-      super
-    end
-  end
-
-The one important thing to note here is the call to +super+ inside the hook.  Whenever you override one of Sequel::Model's methods, you should be calling +super+ to get the default behavior.  Many of the plugins that ship with Sequel work by overriding the hook methods and calling +super+.  If you use these plugins and override the hook methods but do not call +super+, it's likely the plugins will not work correctly.
-
-== Available Hooks
-
-Sequel calls hooks in the following order when saving/creating a new object (one that does not already exist in the database):
-
-* +around_validation+
-  * +before_validation+
-  * +validate+ method called
-  * +after_validation+
-* +around_save+
-  * +before_save+
-  * +around_create+
-    * +before_create+
-    * INSERT QUERY
-    * +after_create+
-  * +after_save+
-
-Sequel calls hooks in the following order when saving an existing object:
-
-* +around_validation+
-  * +before_validation+
-  * +validate+ method called
-  * +after_validation+
-* +around_save+
-  * +before_save+
-  * +around_update+
-    * +before_update+
-    * UPDATE QUERY
-    * +after_update+
-  * +after_save+
-
-Note that all of the hook calls are the same, except that +around_create+, +before_create+ and +after_create+ are used for a new object, and +around_update+, +before_update+ and +after_update+ are used for an existing object.  Note that +around_save+, +before_save+, and +after_save+ are called in both cases.
-
-Note that the validation hooks are still called if <tt>validate: false</tt> option is passed to save.  If you call <tt>Model#valid?</tt> manually, then only the validation hooks are called:
-
-* +around_validation+
-  * +before_validation+
-  * +validate+ method called
-  * +after_validation+
-
-Sequel calls hooks in the following order when destroying an existing object:
-
-* +around_destroy+
-  * +before_destroy+
-  * DELETE QUERY
-  * +after_destroy+
-
-Note that these hooks are only called when using <tt>Model#destroy</tt>, they are not called if you use <tt>Model#delete</tt>.
-
-== Transaction-related Hooks
-
-Sequel::Model no longer offers transaction hooks for model instances.  However, you can use the database transaction hooks inside model +before_save+ and +after_save+ hooks:
-
-  class Album < Sequel::Model
-    def before_save
-      db.after_rollback{rollback_action}
-      super
-    end
-
-    def after_save
-      super
-      db.after_commit{commit_action}
-    end
-  end
-
-== Running Hooks
-
-Sequel does not provide a simple way to turn off the running of save/create/update hooks.  If you attempt to save a model object, the save hooks are always called.  All model instance methods that modify the database call save in some manner, so you can be sure that if you define the hooks, they will be called when you save the object.
-
-However, you should note that there are plenty of ways to modify the database without saving a model object.  One example is by using plain datasets, or one of the model's dataset methods:
-
-  Album.where(name: 'RF').update(copies_sold: Sequel.+(:copies_sold, 1))
-  # UPDATE albums SET copies_sold = copies_sold + 1 WHERE name = 'RF'
-
-In this case, the +update+ method is called on the dataset returned by <tt>Album.where</tt>.  Even if there is only a single object with the name RF, this will not call any hooks.  If you want model hooks to be called, you need to make sure to operate on a model object:
-
-  album = Album.first(name: 'RF')
-  album.update(copies_sold: album.copies_sold + 1)
-  # UPDATE albums SET copies_sold = 2 WHERE id = 1
-
-For the destroy hooks, you need to make sure you call +destroy+ on the object:
-
-  album.destroy # runs destroy hooks
-
-== Skipping Hooks
-
-Sequel makes it easy to skip destroy hooks by calling +delete+ instead of +destroy+:
-
-  album.delete # does not run destroy hooks
-
-However, skipping hooks is a bad idea in general and should be avoided.  As mentioned above, Sequel doesn't allow you to turn off the running of save hooks. If you know what you are doing and really want to skip them, you need to drop down to the dataset level to do so.  This can be done for a specific model object by using the +this+ method for a dataset that represents a single object:
-
-  album.this # dataset
-
-The +this+ dataset works just like any other dataset, so you can call +update+ on it to modify it:
-
-  album.this.update(copies_sold: album.copies_sold + 1)
-
-If you want to insert a row into the model's table without running the creation hooks, you can use <tt>Model.insert</tt> instead of <tt>Model.create</tt>:
-
-  Album.insert(name: 'RF') # does not run hooks
-
-== Canceling Actions in Hooks
-
-Sometimes want to cancel an action in a before hook, so the action is not performed.  For example, you may want to not allow destroying or saving a record in certain cases.  In those cases, you can call +cancel_action+ inside the <tt>before_*</tt> hook, which will stop processing the hook and will either raise a <tt>Sequel::HookFailed</tt> exception (the default), or return +nil+ if +raise_on_save_failure+ is +false+).  You can use this to implement validation-like behavior, that will run even if validations are skipped:
-
-  class Album < Sequel::Model
-    def before_save
-      cancel_action if name == ''
-      super
-    end
-  end
-
-For around hooks, neglecting to call +super+ halts hook processing in the same way as calling +cancel_action+ in a before hook.  It's probably a bad idea to use +cancel_action+ hook processing in after hooks, or after yielding in around hooks, since by then the main processing has already taken place.
-
-By default, Sequel runs hooks other than validation hooks inside a transaction, so if you cancel the action by calling +cancel_action+ in any hook, Sequel will rollback the transaction.  However, note that the implicit use of transactions when saving and destroying model objects is conditional (it depends on the model instance's +use_transactions+ setting and the <tt>:transaction</tt> option passed to save).
-
-== Conditional Hooks
-
-Sometimes you only take to take a certain action in a hook if the object meets a certain condition.  For example, let's say you only want to make sure a timestamp is set when updating if the object is at a certain status level:
-
-  class Album < Sequel::Model
-    def before_update
-      self.timestamp ||= Time.now if status_id > 3
-      super
-    end
-  end
-
-Note how this hook action is made conditional just be using the standard ruby +if+ conditional.  Sequel makes it easy to handle conditional hook actions by using standard ruby conditionals inside the instance methods.
-
-== Using Hooks in Multiple Classes
-
-If you want all your model classes to use the same hook, you can just define that hook in Sequel::Model:
-
-  class Sequel::Model
-    def before_create
-      self.created_at ||= Time.now
-      super
-    end
-  end
-
-Just remember to call +super+ whenever you override the method in a subclass.  Note that +super+ is also used when overriding the hook in <tt>Sequel::Model</tt> itself.  This is important as if you add any plugins to Sequel::Model itself, if you override a hook in <tt>Sequel::Model</tt> and do not call +super+, the plugin may not work correctly.
-
-If you don't want all classes to use the same hook, but want to reuse hooks in multiple classes, you should use a plugin or a simple module:
-
-=== Plugin
-
-  module SetCreatedAt
-    module InstanceMethods
-      def before_create
-        self.created_at ||= Time.now
-        super
-      end
-    end
-  end
-  Album.plugin(SetCreatedAt)
-  Artist.plugin(SetCreatedAt)
-
-=== Simple Module
-
-  module SetCreatedAt
-    def before_create
-      self.created_at ||= Time.now
-      super
-    end
-  end
-  Album.send(:include, SetCreatedAt)
-  Artist.send(:include, SetCreatedAt)
-
-== +super+ Ordering
-
-While it's not enforced anywhere, it's a good idea to make +super+ the last expression when you override a before hook, and the first expression when you override an after hook:
-
-  class Album < Sequel::Model
-    def before_save
-      self.updated_at ||= Time.now
-      super
-    end
-
-    def after_save
-      super
-      AuditLog.create(log: "Album #{name} created")
-    end
-  end
-
-This allows the following general principles to be true:
-
-* before hooks are run in reverse order of inclusion
-* after hooks are run in order of inclusion
-
-So if you define the same before hook in both a model and a plugin that the model uses, the hooks will be called in this order:
-
-* model before hook
-* plugin before hook
-* plugin after hook
-* model after hook
-
-Again, Sequel does not enforce that, and you are free to call +super+ in an order other than the recommended one (just make sure that you call it).
-
-== Around Hooks
-
-Around hooks should only be used if you cannot accomplish the same results with before and after hooks.  For example, if you want to catch database errors caused by the +INSERT+ or +UPDATE+ query when saving a model object and raise them as validation errors, you cannot use a before or after hook.  You have use an +around_save+ hook:
-
-  class Album < Sequel::Model
-    def around_save
-      super
-    rescue Sequel::DatabaseError => e
-      # parse database error, set error on self, and reraise a Sequel::ValidationFailed
-    end
-  end
- 
-Likewise, let's say that upon retrieval, you associate an object with a file descriptor, and you want to ensure that the file descriptor is closed after the object is saved to the database.  Let's assume you are always saving the object and you are not using validations.  You could not use an +after_save+ hook safely, since if the database raises an error, the +after_save+ method will not be called.  In this case, an +around_save+ hook is also the correct choice:
-
-  class Album < Sequel::Model
-    def around_save
-      super
-    ensure
-      @file_descriptor.close
-    end
-  end
-
-== Hook related plugins
-
-=== +instance_hooks+
-
-Sequel also ships with an +instance_hooks+ plugin that allows you to define before and after hooks on a per instance basis.  It's very useful as it allows you to delay action on an instance until before or after saving.  This can be important if you want to modify a group of related objects together (which is how the +nested_attributes+ plugin uses +instance_hooks+).
-
-=== +hook_class_methods+
-
-While it's recommended to write your hooks as instance methods, Sequel ships with a +hook_class_methods+ plugin that allows you to define hooks via class methods. It exists mostly for legacy compatibility, but is still supported.  However, it does not implement around hooks.
-
-=== +after_initialize+
-
-The after_initialize plugin adds an after_initialize hook, that is called for all model instances on creation (both new instances and instances retrieved from the database).  It exists mostly for legacy compatibility, but it is still supported.

data/doc/model_plugins.rdoc

@@ -1,270 +0,0 @@
-= Model Plugins
-
-Sequel::Model (and Sequel in general) is designed around the idea of a small core, to which application-specific behavior can easily be added.  Sequel::Model implements this design using a plugin system.  Plugins are modules that include submodules for model class methods, model instance methods, and model dataset methods.  All plugins can override the class, instance, and dataset methods added by earlier plugins, and call super to get the behavior before the plugin was added.
-
-== Default Plugins
-
-The Sequel::Model class is completely empty by default, in that it has no class methods or instance methods.  Sequel::Model is itself a plugin, and it is the first plugin loaded, and it is loaded into itself (meta!).  So methods in Sequel::Model::ClassMethods become Sequel::Model class methods, methods in Sequel::Model::InstanceMethods become Sequel::Model instance methods, and methods in Sequel::Model::DatasetMethods become Sequel::Model dataset methods. The Sequel::Model plugin is often referred to as the base plugin. 
-
-By default, the Sequel::Model class also has the Sequel::Model::Associations plugin loaded by default, though it is possible to disable this. 
-
-== Loading Plugins
-
-Loading a plugin into a model class is generally as simple as calling the Sequel::Model.plugin method with the name of the plugin, for example:
-
-  Sequel::Model.plugin :subclasses
-
-What is does is require the <tt>sequel/plugins/subclasses</tt> file, and then assumes that that file defines the <tt>Sequel::Plugins::Subclasses</tt> plugin module.
-
-It's possible to pass module instances to the plugin method to load plugins that are stored in arbitrary files or namespaces:
-
-  Sequel::Model.plugin MyApp::Plugins::Foo
-
-In the examples shown above, the plugin is loaded into Sequel::Model, which means it is loaded into all subclasses that are created afterward.  With many plugins, you are not going to want to add them to Sequel::Model, but to a specific subclass:
-
-  class Node < Sequel::Model
-    plugin :tree
-  end
-
-Doing this, only Node and future subclasses of Node will have the tree plugin loaded.
-
-== Plugin Arguments/Options
-
-Some plugins require arguments and/or support options.  For example, the single_table_inheritance plugin requires an argument containing the column that specifies the class to use, and options:
-
-  class Employee < Sequel::Model
-    plugin :single_table_inheritance, :type_id, model_map: {1=>:Staff, 2=>:Manager}
-  end
-
-You should read the documentation for the plugin to determine if it requires arguments and what if any options are supported.
-
-== Creating Plugins
-
-The simplest possible plugin is an empty module in a file stored in <tt>sequel/plugins/plugin_name</tt> somewhere in ruby's load path:
-
-  module Sequel
-    module Plugins
-      module PluginName
-      end
-    end
-  end
-
-Well, technically, that's not the simplest possible plugin, but it is the simplest one you can load by name.  The absolute simplest plugin would be an empty module:
-
-  Sequel::Model.plugin Module.new
-
-== Example Formatting
-
-In general, loading plugins by module instead of by name is not recommended, so this guide will assume that plugins are loaded by name.  For simplicity, we'll also use the following format for example plugin code (and assume a plugin named Foo stored in <tt>sequel/plugins/foo</tt>):
-
-  module Sequel::Plugins::Foo
-  end
-
-This saves 4 lines per example.  However, it's recommended that you use the nested example displayed earlier for production code.
-
-The examples also assume that the following model class exists:
-
-  class Bar < Sequel::Model
-  end
-
-== Adding Class Methods
-
-If you want your plugin to add class methods to the model class it is loaded into, define a ClassMethods module under the plugin module:
-
-  module Sequel::Plugins::Foo
-    module ClassMethods
-      def a
-        1
-      end
-    end
-  end
-
-This allows a plugin user to do:
-
-  Bar.plugin :foo
-  Bar.a # => 1
-
-== Adding Instance Methods
-
-If you want your plugin to add instance methods to the model class it is loaded into, define an InstanceMethods module under the plugin module:
-
-  module Sequel::Plugins::Foo
-    module InstanceMethods
-      def a
-        1
-      end
-    end
-  end
-
-This allows a plugin user to do:
-
-  Bar.plugin :foo
-  Bar.new.a # => 1
-
-== Adding Dataset Methods
-
-If you want your plugin to add methods to the dataset of the model class it is loaded into, define a DatasetMethods module under the plugin module:
-
-  module Sequel::Plugins::Foo
-    module DatasetMethods
-      def a
-        1
-      end
-    end
-  end
-
-This allows a plugin user to do:
-
-  Bar.plugin :foo
-  Bar.dataset.a # => 1
-
-== Calling super to get Previous Behavior
-
-No matter if you are dealing with class, instance, or dataset methods, you can call super inside the method to get the previous behavior.  This makes it easy to hook into the method, add your own behavior, but still get the previous behavior:
-
-  module Sequel::Plugins::Foo
-    module InstanceMethods
-      def save
-        if allow_saving?
-          super
-        else
-          raise Sequel::Error, 'saving not allowed for this object'
-        end
-      end
-
-      private
-
-      def allow_saving?
-        moon =~ /Waxing/
-      end
-    end
-  end
-
-== Running Code When the Plugin is Loaded
-
-Some plugins require more than just adding methods.  Any plugin that requires state is going to have to initialize that state and store it somewhere (generally in the model class itself).  If you want to run code when a plugin is loaded (usually to initialize state, but possibly for other reasons), there are two methods you can define to do so.  The first method is apply, and it is called only the first time the plugin is loaded into the class, before it is loaded into the class.  This is generally only used if a plugin depends on another plugin or for initializing state.  You define this method as a singleton method of the plugin module:
-
-  module Sequel::Plugins::Foo
-    def self.apply(model)
-      model.instance_eval do
-        plugin :plugin_that_foo_depends_on
-        @foo_states = {}
-      end
-    end
-  end
-
-The other method is called configure, and it is called everytime the plugin is loaded into the class, after it is loaded into the class:
-
-  module Sequel::Plugins::Foo
-    def self.configure(model)
-      model.instance_eval do
-        @foo_states[:initial] ||= :baz
-      end
-    end
-  end
-
-Note that in the configure method, you know apply has already been called at least once (so @foo_state will definitely exist).
-
-If you want your plugin to take arguments and/or support options, you handle that by making your apply and configure methods take arguments and/or an options hash.  For example, if you want the user to be able to set the initial state via an option, you can do:
-
-  module Sequel::Plugins::Foo
-    def self.apply(model, opts={})
-      model.instance_eval do
-        plugin :plugin_foo_depends_on
-        @foo_states = {}
-      end
-    end
-
-    def self.configure(model, opts={})
-      model.instance_eval do
-        @foo_states[:initial] = opts[:initial_state] || @foo_states[:initial] || :baz
-      end
-    end
-  end
-
-This allows a user of the plugin to do either of the following
-
-  Bar.plugin :foo
-  Bar.plugin :foo, initial_state: :quux
-
-If you want to require the initial state to be provided as an argument:
-
-  module Sequel::Plugins::Foo
-    def self.apply(model, initial_state)
-      model.instance_eval do
-        plugin :plugin_foo_depends_on
-        @foo_states = {}
-      end
-    end
-
-    def self.configure(model, initial_state)
-      model.instance_eval do
-        @foo_states[:initial] = initial_state
-      end
-    end
-  end
-
-This requires that the user of the plugin specify the argument:
-
-  Bar.plugin :foo, :quux
-
-In general you should only require plugin arguments if you absolutely must have a value and there is no good default.
-
-== Handling Subclasses
-
-Sequel::Model uses a copy-on-subclassing approach to model state.  So instead of having a model subclass ask its superclass for a value if the subclass don't have the value defined, the value should be copied from the parent class to the subclass when the subclass is created.  While this can be implemented by overriding the +inherited+ class method, there is an available shortcut that handles most cases:
-
-  module Sequel::Plugins::Foo
-    module ClassMethods
-      Sequel::Plugins.inherited_instance_variables(self, :@foo_states => :dup)
-    end
-  end
-
-Inside the ClassMethods submodule, you call the Sequel::Plugins.inherited_instance_variables method with the first argument being self.  The second argument should be a hash describing how to copy the value from the parent class into the subclass.  The keys of this hash are instance variable names, including the @ symbol (e.g. :@foo_state).  The values of this hash describe how to copy it:
-
-nil :: Use the value directly.
-:dup :: Call dup on the value.
-:hash_dup :: Create a new hash with the same keys, but a dup of all the values.
-Proc :: An arbitrary proc that is called with the parent class value and should return the value to set into the subclass.
-
-== Handling Changes to the Model's Dataset
-
-In many plugins, if the model class changes the dataset, you need to change the state for the plugin.  While you can do this by overriding the set_dataset class method, there is an available shortcut:
-
-  module Sequel::Plugins::Foo
-    module ClassMethods
-      Sequel::Plugins.after_set_dataset(self, :set_foo_table)
-      
-      private
-
-      def set_foo_table
-        @foo_states[:table] = table_name
-      end
-    end
-  end
-
-With this code, any time the model's dataset changes, the state of the plugin will be updated to set the correct table name.  This is also called when creating a new model class with a dataset.
-
-== Making Dataset Methods Callable as Class Methods
-
-In some cases, when dataset methods are added, you want to also create a model class method that will call the dataset method, so you can write:
-
-  Model.method
-
-instead of:
-
-  Model.dataset.method
-
-There is an available shortcut that automatically creates the class methods:
-
-  module Sequel::Plugins::Foo
-    module ClassMethods
-      Sequel::Plugins.def_dataset_methods(self, :quux)
-    end
-
-    module DatasetMethods
-      def quux
-        2
-      end
-    end
-  end