attic 0.6.pre.RC1 → 0.9.0.pre.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cab1b37cf99fda2d7f47b898c998af908e2c8f4dcdde31ae66cd34d7c337a993
-  data.tar.gz: 7d579f1320f3493b6639705d316aaf1197f77aa20894ecff84abd0a34a162124
+  metadata.gz: 5b8515c2812b3e4523d79d1fae98c348f041b4d6862d632e7a41ff4fb6555d7a
+  data.tar.gz: 29f3b9a07abb04e0d4611724a015ff8a0fcb704d7d8f3038d4ecd99ed6ae6768
 SHA512:
-  metadata.gz: 920f145e1b3eb27151653a69be076fe3224c82e2781695209e2017ac4634708855dc0331ad254a9765bd185f25e566b1c6a712bc6118668c201ec0fa240239fc
-  data.tar.gz: e0e4204bd76ae3f76c7c3a51166c278f69b2152db651a2ccd28ce8d559f281bfbf18e253713608fad2d9d488b96f52d3397070de7cc606842c3f47971db1276a
+  metadata.gz: 37911f6e23435f00b28f5d75643d2e250ee760c9ddee7049b6296dc3f5eaf6a00a48a9a6d3c484e9e9fd24e3feb15b57afaf7cc33d1e9456be80a8383840a360
+  data.tar.gz: bf9811b8008f3d292c0be8087202785ada8fda996ba352194d8d77652fc997ef0c2d9fe324f710493459f6aa79939472569d11bd68a25b6e4c7c31021b8c9c05

data/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.bundle
+.byebug*
+.history
+.devcontainer
+.vscode
+*.env
+*.log
+*.md
+*.txt
+!LICENSE.txt
+.ruby-version
+appendonlydir
+Gemfile.lock
+etc/config
+log
+tmp
+vendor

data/.rubocop.yml

@@ -0,0 +1,28 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1, 3.2
+  EnabledByDefault: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Enabled: true
+  Max: 120
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: false
+
+Lint/Void:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+ruby '>= 3.1'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# bundle install --without production
+# bundle install --with development
+# bundle install --without development
+group "development" do
+  gem "byebug"
+  gem "pry"
+  gem "pry-doc"
+  gem "rubocop"
+  gem "tryouts", '2.2.0.pre.RC1'
+end

data/Gemfile.lock

@@ -0,0 +1,63 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    drydock (0.6.9)
+    json (2.7.1)
+    language_server-protocol (3.17.0.3)
+    method_source (1.0.0)
+    parallel (1.24.0)
+    parser (3.3.0.5)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-doc (1.5.0)
+      pry (~> 0.11)
+      yard (~> 0.9.11)
+    racc (1.7.3)
+    rainbow (3.1.1)
+    regexp_parser (2.9.0)
+    rexml (3.2.6)
+    rubocop (1.62.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.31.2)
+      parser (>= 3.3.0.4)
+    ruby-progressbar (1.13.0)
+    storable (0.10.pre.RC1)
+    sysinfo (0.9.0.pre.RC1)
+      drydock (< 1.0)
+      storable (= 0.10.pre.RC1)
+    tryouts (2.2.0.pre.RC1)
+      sysinfo (= 0.9.0.pre.RC1)
+    unicode-display_width (2.5.0)
+    yard (0.9.36)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  byebug
+  pry
+  pry-doc
+  rubocop
+  tryouts (= 2.2.0.pre.RC1)
+
+RUBY VERSION
+   ruby 3.1.4p223
+
+BUNDLED WITH
+   2.5.7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2009-2024 delano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,54 +1,149 @@
-# Attic - v0.6-RC1 (2021-07-01)
+# Attic - v1.0-RC1 (2023-03-15)
 
-A place to hide private instance variables in your Ruby objects.
+A place to hide private instance variables in your Ruby objects: in the attic.
 
-## Example
+## Description
+
+Attic is a Ruby library that provides a place to hide private instance variables in your Ruby objects: in the attic.
+
+Like, _why though_? Well sometimes you want to hide thing from the public interface of your object. You could use the `@@` prefix to place them at the class level but then you can't use them on a per-instance basis without creating a new data structure to store them. Attic does this for you in a transparent way using the Ruby singleton classes that are already there**.
+
+
+### Example
 
 ```ruby
     require 'attic'
 
+    # Extend a class with Attic
     class String
       extend Attic
+
+      # Add an instance variable to the attic. All instances
+      # of this class will have this variable available.
       attic :timestamp
     end
 
-    a = "anything"
-    a.timestamp = "1980-11-18"
+    # Instantiate a new String object
+    a = "A lovely example of a string"
+
+    # Set and get the timestamp
+    a.timestamp = "1990-11-18"
+    a.timestamp                               # => "1990-11-18"
+
+    # The timestamp is not visible in the public interface
     a.instance_variables                      # => []
-    a.timestamp                               # 1980-11-18
 
+    # But it is available in the attic
     a.attic_variables                         # => [:timestamp]
 
+    # If you prefer getting your hands dirty, you can also
+    # interact with the attic at a lower level.
     a.attic_variable_set :tags, [:a, :b, :c]
-    a.attic_variable_get :tags                # [:a, :b, :c]
+    a.attic_variable_get :tags                # => [:a, :b, :c]
 
+    # Looking at the attic again shows that the timestamp
+    # is still there too.
     a.attic_variables                         # => [:timestamp, :tags]
 ```
 
-## Some objects have no metaclasses
 
-Symbol objects do not have metaclasses so instance variables are hidden in the object itself.
+### **Objects without singleton classes
 
+Symbol, Integer, Float, TrueClass, FalseClass, NilClass, and Fixnum are all objects that do not have singleton classes. TrueClass, FalseClass, and NilClass are all singletons themselves. Fixnum is a singleton of Integer.
 
-## Installation
+These objects do not have metaclasses so the attic is hidden in the object itself.
 
-Via Rubygems, one of:
+### Explore in irb
+
+```shell
+    $ irb -r attic
+```
+
+---
+
+## Installation
 
 ```shell
     $ gem install attic
 ```
 
+```shell
+    $ bundle install attic
+```
+
 or via download:
-* attic-latest.tar.gz[http://github.com/delano/attic/tarball/latest]
-* attic-latest.zip[http://github.com/delano/attic/zipball/latest]
+* [attic-latest.tar.gz](https://github.com/delano/attic/tarball/latest)
+* [attic-latest.zip](https://github.com/delano/attic/zipball/latest)
+
+
+## Proofs
+
+Tested the following code in IRB for Ruby 2.6.8 and 3.0.2:
+
+```ruby
+    rquire 'pp'
+
+    test_values = [:sym, 1, 1.01, Symbol, Integer, Float, String, TrueClass, FalseClass, NilClass, '', true, false, nil]
+
+    results = test_values.map do |value|
+      { value: value,
+        class: value.class,
+        attic: [value.attic?, value.attic? && value.attic.object_id] }
+    end
+```
 
+which produced the same results for both.
+
+```ruby
+    attic> RUBY_VERSION
+    => "3.2.0"
+
+    pp results
+    [
+      {:value=>:sym,        :class=>Symbol,       :attic=>[false, false]},
+      {:value=>1,           :class=>Integer,      :attic=>[false, false]},
+      {:value=>1.01,        :class=>Float,        :attic=>[false, false]},
+      {:value=>Symbol,      :class=>Class,        :attic=>[true, 564680]},
+      {:value=>Integer,     :class=>Class,        :attic=>[true, 564700]},
+      {:value=>Float,       :class=>Class,        :attic=>[true, 564720]},
+      {:value=>String,      :class=>Class,        :attic=>[true, 564740]},
+      {:value=>TrueClass,   :class=>Class,        :attic=>[true, 564760]},
+      {:value=>FalseClass,  :class=>Class,        :attic=>[true, 564780]},
+      {:value=>NilClass,    :class=>Class,        :attic=>[true, 564800]},
+      {:value=>"",          :class=>String,       :attic=>[true, 602880]}
+      {:value=>true,        :class=>TrueClass,    :attic=>[true, 13840]},
+      {:value=>false,       :class=>FalseClass,   :attic=>[true, 13860]},
+      {:value=>nil,         :class=>NilClass,     :attic=>[true, 40]}
+    ]
+```
+```ruby
+    attic> RUBY_VERSION
+    => "2.6.8"
+
+    pp results
+    [
+      {:value=>:sym,        :class=>Symbol,       :attic=>[false, false]},
+      {:value=>1,           :class=>Integer,      :attic=>[false, false]},
+      {:value=>1.01,        :class=>Float,        :attic=>[false, false]},
+      {:value=>Symbol,      :class=>Class,        :attic=>[true, 2844115920]},
+      {:value=>Integer,     :class=>Class,        :attic=>[true, 2844089400]},
+      {:value=>Float,       :class=>Class,        :attic=>[true, 2844087700]},
+      {:value=>String,      :class=>Class,        :attic=>[true, 2844122580]},
+      {:value=>TrueClass,   :class=>Class,        :attic=>[true, 2844136260]},
+      {:value=>FalseClass,  :class=>Class,        :attic=>[true, 2844136000]},
+      {:value=>NilClass,    :class=>Class,        :attic=>[true, 2844139060]},
+      {:value=>"",          :class=>String,       :attic=>[true, 2845261220]},
+      {:value=>true,        :class=>TrueClass,    :attic=>[true, 2844136280]},
+      {:value=>false,       :class=>FalseClass,   :attic=>[true, 2844136020]},
+      {:value=>nil,         :class=>NilClass,     :attic=>[true, 2844139080]}
+    ]
+```
 
 ## Credits
 
-* `gems@solutious.com` (@delano)
+* (@delano) Delano Mandelbaum
 
 
 ## License
 
 MIT
-

data/attic.gemspec

@@ -1,20 +1,23 @@
-@spec = Gem::Specification.new do |s|
-	s.name = "attic"
-	s.version = "0.6-RC1"
-	s.summary = "When in doubt, store it in the attic"
-	s.description = "Attic: a place to hide metadata about the class or variable itself (e.g. SHA hash summaries)."
-	s.author = "Delano Mandelbaum"
-	s.email = "gems@solutious.com"
-	s.homepage = "http://github.com/delano/attic"
-  s.executables = %w[]
-  s.require_paths = %w[lib]
-  s.extra_rdoc_files = %w[README.md]
-  s.licenses = ["MIT"]  # https://spdx.org/licenses/MIT-Modern-Variant.html
-  s.rdoc_options = ["--line-numbers", "--title", s.summary, "--main", "README.md"]
-  s.files = %w(
-    README.md
-    Rakefile
-    attic.gemspec
-    lib/attic.rb
-  )
+Gem::Specification.new do |s|
+  s.name        = "attic"
+  s.version     = "0.9.0-rc2"
+  s.summary     = "When in doubt, store it in the attic"
+  s.description = "Attic: a place to hide metadata about the class or variable itself (e.g. SHA hash summaries)."
+  s.authors     = ["Delano Mandelbaum"]
+  s.email       = "gems@solutious.com"
+  s.homepage    = "https://github.com/delano/attic"
+  s.license     = "MIT"
+
+  s.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  s.bindir        = "exe"
+  s.executables   = s.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+
+  s.add_dependency "rake", ">= 13.0.6"
+
+  # Add development dependencies
+  s.add_development_dependency "rspec", "~> 3.0"
+  s.add_development_dependency "rubocop", "~> 1.0"
 end

data/lib/attic/class_methods.rb

@@ -0,0 +1,66 @@
+#
+# = Attic::ClassMethods
+#
+module Attic
+  # Adds a few methods for accessing the metaclass of an
+  # object. We do this with great caution since the Object
+  # class is as global as it gets in Ruby.
+  module ClassMethods
+    # A list of all the attic variables defined for this class.
+    attr_reader :attic_variables
+
+    # A quick way to check if the current object already has a
+    # dedicated singleton class. We want to know this because
+    # this is where our attic variables will be stored.
+    def attic?
+      return false if NoSingletonError.member? self
+
+      # NOTE: Calling this on an object for the first time lazily
+      # creates a singleton class for itself. Another way of doing
+      # the same thing is to attempt defining a singleton method
+      # for the object. In either case, objects that cannot have
+      # cannot have a dedicated singleton class (e.g. nil, true,
+      # false) will raise a TypeError. We rescue this and add the
+      # object to the NoSingletonError list so we don't have to
+      # keep trying to access its singleton class.
+      !singleton_class.nil?
+
+    rescue TypeError
+      # Remember for next time.
+      NoSingletonError.add_member self
+      false
+    end
+
+    def attic(name=nil)
+      return singleton_class if name.nil?
+
+      name = name.normalize
+
+      self.attic_variables << name unless attic_variable? name
+
+      safe_name = "@_attic_#{name}"
+      instance_variable_set(safe_name, name)
+    end
+
+    def attic_variable?(name)
+      attic_variables.include? name.normalize
+    end
+
+    def attic_variable_set(name, val)
+      unless attic_variable? name
+        attic_variables << name.normalize
+      end
+      attic.instance_variable_set("@_attic_#{name}", val)
+    end
+
+    def attic_variable_get(name)
+      instance_variable_get("@_attic_#{name}")
+    end
+
+    protected
+
+    def normalize(name)
+      name.to_s.gsub(/\@[\?\!\=]$/, '_').to_sym
+    end
+  end
+end

data/lib/attic/core_ext.rb

@@ -0,0 +1,70 @@
+
+class NoMetaClass < RuntimeError
+end
+
+# = Object
+#
+# 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.
+  #
+  #     class << self; self; end;
+  #
+  # 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.
+  #
+  #     self.metaclass.metaclass
+  #
+  def metametaclass; self.metaclass.metaclass; end
+
+  def metameta_eval &blk; metametaclass.instance_eval &blk; end
+
+  def metameta_def name, &blk
+    metameta_eval { define_method name, &blk }
+  end
+
+end

data/lib/attic/errors.rb

@@ -0,0 +1,52 @@
+
+# Attic: A special place to store instance variables.
+
+class NoMetaClass < RuntimeError
+end
+
+# = NoSingletonError
+#
+# This error is raised when an attempt is made to access the
+# attic of an object which does not have a singleton class.
+#
+# This is a TypeError because it is not an exceptional
+# condition. It is simply a condition that is not supported
+# by the Attic module.
+#
+# == Usage
+#
+#   require 'attic'
+#   class MyClass
+#     include Attic
+#     attic :name, :age
+#   end
+#
+class NoSingletonError < TypeError
+  unless defined?(MEMBERS)
+    # A Set of classes which do not have singleton classes
+    # (i.e. meta classes). This is used to prevent an exception
+    # the first time an attic is accessed. It's populated
+    # dynamically at start time by simply checking whether
+    # the object has a singleton. This only needs to be
+    # done once per class.
+    #
+    # We use a set here to avoid having to deal with duplicate
+    # values. Realistically there are only a few classes that
+    # do not have singleton classes. We could hard code them
+    # here which is not lost on us.
+    #
+    MEMBERS = Set.new
+  end
+
+  # Check if the given object is a member of the NoSingleton
+  # members list. This checks for the object itself and all
+  # of its ancestors. See the docs for `Enumerable#===` for
+  # more details.
+  def self.member?(obj)
+    MEMBERS === obj
+  end
+
+  def self.add_member(obj)
+    MEMBERS.merge [self]
+  end
+end

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