attic 0.5.3 → 0.9.0.pre.rc2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b8515c2812b3e4523d79d1fae98c348f041b4d6862d632e7a41ff4fb6555d7a
+  data.tar.gz: 29f3b9a07abb04e0d4611724a015ff8a0fcb704d7d8f3038d4ecd99ed6ae6768
+SHA512:
+  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

@@ -1,4 +1,6 @@
-Copyright (c) 2009 Solutious Inc, Delano Mandelbaum
+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
@@ -7,13 +9,13 @@ 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 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.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# Attic - v1.0-RC1 (2023-03-15)
+
+A place to hide private instance variables in your Ruby objects: in the attic.
+
+## 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
+
+    # 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                      # => []
+
+    # 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]
+
+    # Looking at the attic again shows that the timestamp
+    # is still there too.
+    a.attic_variables                         # => [:timestamp, :tags]
+```
+
+
+### **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.
+
+These objects do not have metaclasses so the attic is hidden in the object itself.
+
+### Explore in irb
+
+```shell
+    $ irb -r attic
+```
+
+---
+
+## Installation
+
+```shell
+    $ gem install attic
+```
+
+```shell
+    $ bundle install attic
+```
+
+or via download:
+* [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
+
+* (@delano) Delano Mandelbaum
+
+
+## License
+
+MIT

data/Rakefile

@@ -1,25 +1,16 @@
 require 'rubygems'
 require 'rake/clean'
-require 'rake/gempackagetask'
+require 'rubygems/package_task'
 require 'fileutils'
+require 'rdoc/task'
 include FileUtils
- 
-
-begin
-  require 'hanna/rdoctask'
-rescue LoadError
-  require 'rake/rdoctask'
-end
-
 
 task :default => :package
- 
+
 # CONFIG =============================================================
 
 # Change the following according to your needs
-README = "README.rdoc"
-CHANGES = "CHANGES.txt"
-LICENSE = "LICENSE.txt"
+README = "README.md"
 
 # Files and directories to be deleted when you run "rake clean"
 CLEAN.include [ 'pkg', '*.gem', '.config']
@@ -30,7 +21,7 @@ load "#{name}.gemspec"
 version = @spec.version
 
 # That's it! The following defaults should allow you to get started
-# on other things. 
+# on other things.
 
 
 # TESTS/SPECS =========================================================
@@ -39,7 +30,7 @@ version = @spec.version
 
 # INSTALL =============================================================
 
-Rake::GemPackageTask.new(@spec) do |p|
+Gem::PackageTask.new(@spec) do |p|
   p.need_tar = true if RUBY_PLATFORM !~ /mswin/
 end
 
@@ -52,25 +43,6 @@ task :uninstall => [ :clean ] do
 end
 
 
-# RUBYFORGE RELEASE / PUBLISH TASKS ==================================
-
-if @spec.rubyforge_project
-  desc 'Publish website to rubyforge'
-  task 'publish:rdoc' => 'doc/index.html' do
-    sh "scp -rp doc/* rubyforge.org:/var/www/gforge-projects/#{name}/"
-  end
-
-  desc 'Public release to rubyforge'
-  task 'publish:gem' => [:package] do |t|
-    sh <<-end
-      rubyforge add_release -o Any -a #{CHANGES} -f -n #{README} #{name} #{name} #{@spec.version} pkg/#{name}-#{@spec.version}.gem &&
-      rubyforge add_file -o Any -a #{CHANGES} -f -n #{README} #{name} #{name} #{@spec.version} pkg/#{name}-#{@spec.version}.tgz 
-    end
-  end
-end
-
-
-
 # RUBY DOCS TASK ==================================
 
 Rake::RDocTask.new do |t|
@@ -78,10 +50,7 @@ Rake::RDocTask.new do |t|
 	t.title    = @spec.summary
 	t.options << '--line-numbers' << '-A cattr_accessor=object'
 	t.options << '--charset' << 'utf-8'
-	t.rdoc_files.include(LICENSE)
 	t.rdoc_files.include(README)
-	t.rdoc_files.include(CHANGES)
-	#t.rdoc_files.include('bin/*')
 	t.rdoc_files.include('lib/**/*.rb')
 end
 

data/attic.gemspec

@@ -1,52 +1,23 @@
-@spec = Gem::Specification.new do |s|
-	s.name = "attic"
-  s.rubyforge_project = "attic"
-	s.version = "0.5.3"
-	s.summary = "A place to hide private instance variables in your Ruby objects."
-	s.description = s.summary
-	s.author = "Delano Mandelbaum"
-	s.email = "delano@solutious.com"
-	s.homepage = "http://github.com/delano/attic"
-  
-  # = EXECUTABLES =
-  # The list of executables in your project (if any). Don't include the path, 
-  # just the base filename.
-  s.executables = %w[]
-  
-  # Directories to extract rdocs from
-  s.require_paths = %w[lib]  
-  
-  # Specific files to include rdocs from
-  s.extra_rdoc_files = %w[README.rdoc LICENSE.txt CHANGES.txt]
-  
-  # Update --main to reflect the default page to display
-  s.rdoc_options = ["--line-numbers", "--title", s.summary, "--main", "README.rdoc"]
-  
-  # = MANIFEST =
-  # The complete list of files to be included in the release. When GitHub packages your gem, 
-  # it doesn't allow you to run any command that accesses the filesystem. You will get an
-  # error. You can ask your VCS for the list of versioned files:
-  # git ls-files
-  # svn list -R
-  s.files = %w(
-  CHANGES.txt
-  LICENSE.txt
-  README.rdoc
-  Rakefile
-  attic.gemspec
-  lib/attic.rb
-  try/01_mixins_tryouts.rb
-  try/10_attic_tryouts.rb
-  try/20_accessing_tryouts.rb
-  try/25_string_tryouts.rb
-  try/30_nometaclass_tryouts.rb
-  try/40_explicit_accessor_tryouts.rb
-  try/X1_metaclasses.rb
-  try/X2_extending.rb
-  )
-  
-  s.has_rdoc = true
-  s.rubygems_version = '1.3.0'
+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"
 
-  
-end
+  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