# <!-- rdoc-file=lib/singleton.rb -->
# The Singleton module implements the Singleton pattern.
#
# ## Usage
#
# To use Singleton, include the module in your class.
#
#     class Klass
#        include Singleton
#        # ...
#     end
#
# This ensures that only one instance of Klass can be created.
#
#     a,b = Klass.instance, Klass.instance
#
#     a == b
#     # => true
#
#     Klass.new
#     # => NoMethodError - new is private ...
#
# The instance is created at upon the first call of Klass.instance().
#
#     class OtherKlass
#       include Singleton
#       # ...
#     end
#
#     ObjectSpace.each_object(OtherKlass){}
#     # => 0
#
#     OtherKlass.instance
#     ObjectSpace.each_object(OtherKlass){}
#     # => 1
#
# This behavior is preserved under inheritance and cloning.
#
# ## Implementation
#
# This above is achieved by:
#
# *   Making Klass.new and Klass.allocate private.
#
# *   Overriding Klass.inherited(sub_klass) and Klass.clone() to ensure that the
#     Singleton properties are kept when inherited and cloned.
#
# *   Providing the Klass.instance() method that returns the same object each
#     time it is called.
#
# *   Overriding Klass._load(str) to call Klass.instance().
#
# *   Overriding Klass#clone and Klass#dup to raise TypeErrors to prevent
#     cloning or duping.
#
#
# ## Singleton and Marshal
#
# By default Singleton's #_dump(depth) returns the empty string. Marshalling by
# default will strip state information, e.g. instance variables from the
# instance. Classes using Singleton can provide custom _load(str) and
# _dump(depth) methods to retain some of the previous state of the instance.
#
#     require 'singleton'
#
#     class Example
#       include Singleton
#       attr_accessor :keep, :strip
#       def _dump(depth)
#         # this strips the @strip information from the instance
#         Marshal.dump(@keep, depth)
#       end
#
#       def self._load(str)
#         instance.keep = Marshal.load(str)
#         instance
#       end
#     end
#
#     a = Example.instance
#     a.keep = "keep this"
#     a.strip = "get rid of this"
#
#     stored_state = Marshal.dump(a)
#
#     a.keep = nil
#     a.strip = nil
#     b = Marshal.load(stored_state)
#     p a == b  #  => true
#     p a.keep  #  => "keep this"
#     p a.strip #  => nil
#
module Singleton
  def self.__init__: (Class klass) -> Class

  # <!--
  #   rdoc-file=lib/singleton.rb
  #   - instance()
  # -->
  # Returns the singleton instance.
  #
  def self.instance: () -> instance

  public

  # <!--
  #   rdoc-file=lib/singleton.rb
  #   - _dump(depth = -1)
  # -->
  # By default, do not retain any state when marshalling.
  #
  def _dump: (?Integer depth) -> String

  # <!--
  #   rdoc-file=lib/singleton.rb
  #   - clone()
  # -->
  # Raises a TypeError to prevent cloning.
  #
  def clone: () -> bot

  # <!--
  #   rdoc-file=lib/singleton.rb
  #   - dup()
  # -->
  # Raises a TypeError to prevent duping.
  #
  def dup: () -> bot

  module SingletonClassMethods
  end
end

Singleton::VERSION: String