attic 0.5.3 → 0.9.0.pre.rc2

data/lib/attic/instance_methods.rb

@@ -0,0 +1,36 @@
+#
+
+# = Attic::InstanceMethods
+#
+module Attic
+  # Adds a few methods for object instances to access the
+  # attic variables of their class.
+  module InstanceMethods
+
+    def attic
+      raise NoSingleton, self, caller unless attic?
+
+      singleton_class
+
+    rescue TypeError
+      NoSingleton.add_member self
+    end
+
+    def attic_variables
+      self.class.attic_variables
+    end
+
+    def attic_variable?(name)
+      self.class.attic_variable? name
+    end
+
+    def attic_variable_set(name, val)
+      attic_variables << name unless attic_variable? name
+      attic.instance_variable_set("@___attic_#{name}", val)
+    end
+
+    def attic_variable_get(name)
+      attic.instance_variable_get("@___attic_#{name}")
+    end
+  end
+end

data/lib/attic.rb

@@ -1,159 +1,175 @@
 
-class NoMetaClass < RuntimeError
-end
+# Attic: A special place to store instance variables.
+
+require_relative "attic/class_methods"
+require_relative "attic/errors"
+require_relative "attic/instance_methods"
 
-# = Object
+# = Attic
 #
-# These methods are copied directly from _why's metaid.rb. 
-# See: http://whytheluckystiff.net/articles/seeingMetaclassesClearly.html
-class Object
-  
-  unless defined?(::Object::NOMETACLASS)
-    # An Array of classes which do not have metaclasses.
-    NOMETACLASS = [Symbol, Fixnum].freeze
-  end
-  
-  def nometaclass?
-    NOMETACLASS.member?(self)
-  end
-  
-  def metaclass?
-    !NOMETACLASS.member?(self.class)
-  end
-  
-  # A convenient method for getting the metaclass of the current object.
-  # i.e.
+# == Usage:
+#
+#  require 'attic'
+#  class MyClass
+#    include Attic
+#    attic :name, :age
+#  end
+#
+#  obj = MyClass.new
+#  obj.attic.nickname = 'My Classic Automobile'
+#  obj.attic.secret_age  = 27
+#
+#  obj.nickname      #=> 'My Classic Automobile'
+#  obj.secret_age    #=> 27
+#  obj.to_h          #=> {}
+#
+#    OR
+#
+#  require 'attic'
+#  Attic.construct MyClass, :nickname, :secret_age
+#
+#
+# == Description:
+#
+# Attic is a module that allows you to store instance variables
+# in a dedicated singleton class. This is useful for storing
+# instance variables that you don't want to be available to
+# the public interface of your class. e.g. you want to store
+# a value for the running instance but want to prevent it
+# from being serialized.
+#
+# == Why?
+#
+# == Important Notes:
+#
+# Some objects just straight up are not capable of contructing
+# an attic. `Symbols`, `Integers`, and `Floats` specifically do not
+# have a dedicated singleton classes. These are what ruby
+# internals refer to as "immediate values". They're special
+# in that they are not objects in the traditional sense.
+# They're just values (they're not even instances of a
+# class 😮‍💨).
+#
+# When you call attic on an immediate value you get an error.
+#
+# :sym.attic       #=> raises NoSingleton error
+# 1.attic          #=> Ditto
+# 1.0.1.attic      #=> Ditto again
+#
+#
+# The other objects that do not have singleton classes are
+# `true`, `false`, and `nil`. Calling attic on these don't
+# raise an error but they simply return their class. This
+# is because they are all instances of their same singleton
+# class.
+#
+# true.attic       #=> TrueClass
+# false.attic      #=> FalseClass
+# nil.attic        #=> NilClass
+#
+# Note: this means that every instance of nil
+# returns the exact same singleton class. This is different
+# from the behaviour of all other objects.
+#
+# nil.attic.object_id   #=> 800
+# nil.attic.object_id   #=> 800
+#
+#
+# NilClass, TrueClass, and FalseClass on the otherhand each
+# have their own singleton class. Calling attic on these
+# returns the singleton class for each of them. But again
+# a singleton class for each of them but again they all
+#
+# TrueClass.attic  #=> #<Class:TrueClass>
+# FalseClass.attic #=> #<Class:FalseClass>
+# NilClass.attic   #=> #<Class:NilClass>
+#
+#
+# For comparison, here's what happens with a String (each
+# time attic is called on a new string you get a new
+# singleton)
+#
+# "".attic         #=> #<Class:#<String:0x0001234>>
+# "".attic         #=> #<Class:#<String:0x0005678>>
+# "".attic.object_id #=> 1234
+# "".attic.object_id #=> 5678
+#
+# nil.attic        #=> NilClass
+# nil.attic        #=> NilClass
+# nil.attic.object_id #=> 800
+# nil.attic.object_id #=> 800
+#
+module Attic
+  VERSION = '0.9.0-RC1'.freeze unless defined?(VERSION)
+  attr_reader :all_attic_variables
+
+  # A convenince method at the class level for including
+  # ConstructMethods in the given object specifically.
   #
-  #     class << self; self; end;
+  #   e.g.
   #
-  # NOTE: Some Ruby class do not have meta classes (see: NOMETACLASS). 
-  # For these classes, this method returns the class itself. That means
-  # the instance variables will stored in the class itself. 
-  def metaclass
-    if !self.metaclass?
-      raise NoMetaClass, self
-    else
-      class << self; self; end; 
-    end
-  end
-  
-  # Execute a block +&blk+ within the metaclass of the current object.
-  def meta_eval &blk; metaclass.instance_eval &blk; end
-  
-  # Add an instance method called +name+ to metaclass for the current object.
-  # This is useful because it will be available as a singleton method
-  # to all subclasses too. 
-  def meta_def name, &blk
-    meta_eval { define_method name, &blk }
-  end
-  
-  # Add a class method called +name+ for the current object's class. This
-  # isn't so special but it maintains consistency with meta_def. 
-  def class_def name, &blk
-    class_eval { define_method name, &blk }
-  end
-
-  
-  # A convenient method for getting the metaclass of the metaclass
-  # i.e.
+  #     Add Attic support to all objects available now and
+  #     in the future:
   #
-  #     self.metaclass.metaclass
+  #       Attic.construct(Object)
   #
-  def metametaclass; self.metaclass.metaclass; end
-
-  def metameta_eval &blk; metametaclass.instance_eval &blk; end
+  #     which is equivalent to:
+  #
+  #       class Object; include Attic::ClassMethods; end
+  #
+  def self.construct(obj)
+    obj.include Attic::ClassMethods
+  end
 
-  def metameta_def name, &blk
-    metameta_eval { define_method name, &blk }
+  def self.included(obj)
+    raise Runtime, "Did you to `extend Attic`` in #{obj}"
   end
-  
-end
 
+  def self.extended(obj)
+    # If the class has already been extended, we don't need
+    # to add the class methods again.
+    return if obj.ancestors.member? self
 
+    # Add the instance methods for accessing attic variables
+    obj.send :include, Attic::InstanceMethods
 
-# = Attic
-#
-# A place to store instance variables. 
-#
-module Attic
-  VERSION = '0.5.3' unless defined?(VERSION)
-  
-  module InstanceMethods
-    def attic_variables
-      self.class.attic_variables
-    end
-    alias_method :attic_vars, :attic_variables
-    def attic_variable? n
-      self.class.attic_variable? n
-    end
-    def attic_variable_set(n,v)
-      attic_variables << n unless attic_variable? n
-      if metaclass?
-        metaclass.instance_variable_set("@#{n}", v)
-      else
-        instance_variable_set("@___attic_#{n}", v)
-      end
-    end
-    def attic_variable_get(n)
-      if metaclass?
-        metaclass.instance_variable_get("@#{n}")
-      else
-        instance_variable_get("@___attic_#{n}")
-      end
+    # If the object doesn't have a dedicated singleton class
+    # an exception will be raised so it can be caught and
+    # handled appropriately.
+    obj.attic.instance_variable_defined?("@attic_variables")
+
+    obj.attic.instance_variable_set("@attic_variables", [])
+
+    def obj.inherited(klass)
+      super
+      attic_vars = self.attic_variables.clone
+      klass.attic.instance_variable_set("@attic_variables", attic_vars)
     end
-  end
-  
-  def self.included(o)
-    raise "You probably meant to 'extend Attic' in #{o}"
-  end
-  
-  def self.extended(o)
-    # This class has already been extended. 
-    return if o.ancestors.member? Attic::InstanceMethods
-    
-    
-    ## NOTE: This is just a reminder for a more descerning way to 
-    ## include the meta methods, instead of using a global mixin. 
-    ##o.class_eval do
-    ##  include ObjectHelpers
-    ##end
-    # Create an instance method that returns the attic variables. 
-    o.send :include, Attic::InstanceMethods
-    #p [:extend, self, o]
-    
-    o.metaclass.instance_variable_set("@attic_variables", [])
-    o.class_eval do
-      def self.inherited(o2)
-        #p [:inherit, self, o2]
-        attic_vars = self.attic_variables.clone
-        o2.metaclass.instance_variable_set("@attic_variables", attic_vars)
+    if method_defined? :instance_variables
+      instance_variables_orig = instance_method(:instance_variables)
+      define_method :instance_variables do
+        ret = _instance_variables_orig.bind(self).call.clone
+        ret.reject! { |v| v.to_s =~ /^@___?attic/ }  # match 2 or 3 underscores
+        ret
       end
-      if method_defined? :instance_variables
-        old_instance_variables = instance_method(:instance_variables)
-        define_method :instance_variables do
-          ret = old_instance_variables.bind(self).call.clone
-          ret.reject! { |v| v.to_s =~ /^@___?attic/ }  # match 2 or 3 underscores
-          ret
-        end
-        define_method :all_instance_variables do
-          old_instance_variables.bind(self).call
-        end
+      define_method :all_instance_variables do
+        _instance_variables_orig.bind(self).call
       end
     end
-  
-    
+
+  rescue TypeError => e
+    raise NoSingleton, obj, caller
   end
-  
-  
-  # A class method for defining variables to store in the attic. 
-  # * +junk+ is a list of variables names. Accessor methods are 
-  #   created for each variable name in the list. 
-  # 
-  # Returns the list of attic variable names or if not junk was
-  # given, returns the metaclass. 
+
+  # A class method for defining variables to store in the attic.
+  # * +names+ is a list of variables names. Accessor methods are
+  #   created for each variable name in the list.
+  #
+  # Returns the list of attic variable names or if no names were
+  # given, returns the attic.
   #
   # e.g.
-  #  
+  #
   #     String.extend Attic
   #     String.attic :timestamp
   #
@@ -161,45 +177,60 @@ module Attic
   # * <tt>String#timestamp</tt> for getting the value
   # * <tt>String#timestamp</tt> for setting the value
   #
-  def attic *junk
-    return metaclass if junk.empty?
-    junk.each do |name|
+  def attic(*names)
+    return all_attic_variables if names.empty?
+
+    names.each do |name|
       next if attic_variable? name
-      self.attic_variables << name
-      
-      unless method_defined? name
+
+      self.all_attic_variables << name
+
+      unless method_defined?(name)
         define_method(name) do
           attic_variable_get name
         end
       end
-      unless method_defined? "#{name}="
+
+      unless method_defined?("#{name}=")
         define_method("#{name}=") do |val|
           attic_variable_set name, val
         end
       end
     end
-    attic_vars
+
+    all_attic_variables
   end
-  
-  # Returns an Array of attic variables for the current class. 
+
+  # Returns an Array of attic variables for the current class.
   # e.g.
   #
   #     String.extend Attic
   #     String.attic :timestamp
   #     String.attic_variables     # => [:timestamp]
   #
-  def attic_variables
-    a = self.metaclass.instance_variable_get("@attic_variables")
-    a ||= self.metaclass.instance_variable_set("@attic_variables", [])
-    a
-  end
-  alias_method :attic_vars, :attic_variables
+  # def attic_variables
+  #   a = attic.instance_variable_get('@attic_variables')
+  #   a ||= attic.instance_variable_set('@attic_variables', [])
+  #   a
+  # end
+  # alias attic_vars attic_variables
 
-  def attic_variable?(n)
-    attic_variables.member? n
+  def attic_variable?(name)
+    attic_variables.member? name
   end
-  
 end
 
 # - Module#instance_method returns an UnboundMethod
 #   - http://ruby-doc.org/core/classes/Module.html#M001659
+
+# Add some candy when we're in irb
+if defined?(IRB)
+  require 'irb/completion'
+  IRB.conf[:PROMPT][:ATTIC] = {
+    PROMPT_I: "attic> ",
+    PROMPT_S: "attic%l> ",
+    PROMPT_C: "attic* ",
+    RETURN:   "=> %s\n\n"
+  }
+  IRB.conf[:PROMPT_MODE] = :ATTIC
+end

data/try/30_nometaclass_tryouts.rb

@@ -1,17 +1,27 @@
-require 'attic'
-  
+require_relative "../lib/attic"
+
+Attic.construct Symbol #, :name
+
 ## has list of no metaclass classes
-Object::NOMETACLASS
-#=> [Symbol, Fixnum]
-  
-## Symbol metaclass raises exception
+NoSingletonError::MEMBERS
+#=> [Symbol, Integer]
+
+# ## Symbol metaclass does not raise an exception
+# begin
+#   :any.attic.class
+# rescue NoSingletonError
+#   :failed
+# end
+# #=> :failed
+
+## Accessing Symbol metaclass raises an exception
 begin
-  :any.metaclass
-rescue NoMetaClass
-  :success
+  :any.attic.class
+rescue NoSingletonError
+  :failed
 end
-#=> :success
-  
+#=> :failed
+
 ## Symbol instances don't cross streams
 Symbol.extend Attic
 Symbol.attic :name
@@ -19,33 +29,40 @@ a, b = :symbol1, :symbol2
 a.name = :roger
 [a.name, b.name]
 #=> [:roger, nil]
-  
-## metaclass? method exists
+
+## attic? method exists
 Symbol.extend Attic
-:any.respond_to? :metaclass?
+:any.respond_to? :attic?
 #=> true
-  
-## metaclass? method is false for a Symbol", false do
-:any.metaclass?
+
+## attic? method is false for a Symbol", false do
+:any.attic?
 #=> false
 
-## A Symbol's attic vars appear in all_instance_variables" do
+## A Symbol's attic vars appear in `all_instance_variables` do
 Symbol.extend Attic
-Symbol.attic :name
+Symbol.attic :_name
 a, b = :symbol1, :symbol2
-a.name = :roger
+a._name = :roger
+a.all_instance_variables
+#=> [:@___attic_name]
+
+## An Integer's attic vars appear in `all_instance_variables` do
+Integer.extend Attic
+Integer.attic :_name
+a, b = 1, 2
+a._name = :roger
 a.all_instance_variables
 #=> [:@___attic_name]
-  
 
-## A Symbol's attic vars do not appear in instance_variables" do
+## A Symbol's attic vars do not appear in `instance_variables` do
 Symbol.extend Attic
 Symbol.attic :name
 a, b = :symbol1, :symbol2
 a.name = :roger
 a.instance_variables
-#=> []  
-  
-## knows attic variables", [:name] do
+#=> []
+
+## knows attic variables, [:name] do
 Symbol.attic_variables
-#=> [:name]
+#=> [:name]

data/try/X3_nosingleton.rb

@@ -0,0 +1,44 @@
+
+
+# "".has_singleton_class? # => true
+# :"".has_singleton_class? # => false
+# 1.has_singleton_class? # =>
+# nil.has_singleton_class? # => false
+# NilClass.has_singleton_class? # => true
+
+# members = ["", :food, 1, 1.00000001, nil, NilClass, true, TrueClass]
+# members2 = members.clone
+
+# members.each_with_index do |member, idx|
+#   puts "member: #{member.inspect}"
+#   member2 = members2[idx]
+
+#   member.has_a_dedicated_singleton_class?  # => false
+#   member2.has_a_dedicated_singleton_class?  # => false
+#   member.bestow_a_singleton_class!
+#   member.has_a_dedicated_singleton_class?  # => true
+#   member2.has_a_dedicated_singleton_class?  # => false
+#   member2.bestow_a_singleton_class!
+#   member2.has_a_dedicated_singleton_class?  # => true
+
+#   member.singleton_class.object_id # => 600
+#   member2.singleton_class.object_id # => 700
+
+#   member.has_method?(:foo) # => false
+#   member.foo # => NoMethodError
+#   member.add_to_singleton_class(:foo)
+#   member.has_method?(:foo) # => true
+#   member.foo = :bar
+#   member.foo # => :bar
+#   member.foo.object_id # => 601
+
+#   member2.has_method?(:foo) # => false
+#   member2.foo # => NoMethodError
+#   member2.add_to_singleton_class(:foo)
+#   member2.has_method?(:foo) # => true
+#   member2.foo = :bar
+#   member2.foo # => :bar
+#   member2.foo.object_id # => 701
+
+#   member2.foo.object_id == member.foo.object_id # => false
+# end