instance 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cee2d02baf52220acdc856e29882e4f010ba2738
+  data.tar.gz: 431b52894e0f05ed07f01a659a32dfee9afd46d5
+SHA512:
+  metadata.gz: 6db8dc0db1016e250ef002411b651027c934e627baf1feb292e1846c412897b35b975cad3de8a993a7f7c8b746dfa132d45d5e409c1e267e525851f02c86c35e
+  data.tar.gz: 36957724377899c20c5e5e604444b8e3da459522fea4c9154ec1781c89174354912e653a9a8848d3e464431c899e841b6b8ba188c284796cbae199ca3f379a49

data/.index

@@ -0,0 +1,62 @@
+---
+revision: 2013
+type: ruby
+sources:
+- index/
+authors:
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+organizations: []
+requirements:
+- groups:
+  - test
+  development: true
+  name: qed
+- groups:
+  - test
+  development: true
+  name: ae
+- groups:
+  - test
+  development: true
+  name: simplecov
+conflicts: []
+alternatives: []
+resources:
+- type: home
+  uri: http://rubyworks.github.com/instance
+  label: Homepage
+- type: code
+  uri: http://github.com/rubyworks/instance
+  label: Source Code
+- type: bugs
+  uri: http://github.com/rubyworks/instance/issues
+  label: Issue Tracker
+- type: docs
+  uri: http://rubydoc.info/gems/instance
+  label: Documentation
+- type: mail
+  uri: http://groups.google.com/group/facets-universal
+  label: Mailing List
+repositories:
+- name: upstream
+  scm: git
+  uri: git@github.com:rubyworks/instance.git
+categories: []
+copyrights:
+- holder: Rubyworks
+  year: '2014'
+  license: BSD-2-Clause
+customs: []
+paths:
+  load:
+  - lib
+name: instance
+title: Instance
+summary: Object Instance API
+created: '2014-01-31'
+description: |-
+  Instance is a spin-off of Ruby Facets. It provides a simple convenient API
+  for accessing an object's state.
+version: 0.1.0
+date: '2014-02-01'

data/HISTORY.md

@@ -0,0 +1,10 @@
+# RELEASE HISTORY
+
+## 0.1.0 | 2014-02-01
+
+This is the initial release of Instance, a class spun-off from
+Ruby Facets.
+
+Changes:
+
+* Happy Release Day!

data/LICENSE.txt

@@ -0,0 +1,23 @@
+BSD-2-Clause License (http://spdx.org/licenses/BSD-2-Clause)
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+

data/README.md

@@ -0,0 +1,58 @@
+# Instance
+
+## What Is It?
+
+Instance is a *convenient* and *safe* API for accessing and manipulating
+an object's state.
+
+## How Does It Work
+
+Instance adds a method to all objects called `#instance`. It returns
+an `Instance` delegator that provides the full interface to the
+object's instance state.
+
+Of course, without implementing this in C, directly in the Ruby source,
+we  are left to depend on the current provisions Ruby has for accessing
+the state of an object. So there are some limitations here. However,
+we implement the Ruby code in such a way as to minimize the downsides
+by caching all the method definitions the Instance class will utilize.
+
+## Usage
+
+Let's use a very simple example class with which to demonstrate usage.
+
+```ruby
+    class Song
+      attr_accessor :title
+      attr_accessor :author
+      attr_accessor :length
+
+      def initialize(title, author, length)
+        @title  = title
+        @author = author
+        @length = length
+      end
+    end
+```
+
+```ruby
+    song = Song.new("Paranoid", "Black Sabbath", 1970)
+
+    song.instance.variables   #=> [:@author, :@title, :@length]
+
+    song.instance.get(:name)  #=> "Black Sabbath"
+
+    song.instance[:name]      #=> "Black Sabbath"
+```
+
+For more a more complete set of usage examples see the QED documentation.
+
+
+## Copyrights
+
+Copyright 2014 Rubyworks
+
+BSD-2-Clause License
+
+See LICENSE.txt file for license details.
+

data/demo/applique/env.rb

@@ -0,0 +1 @@
+require 'ae'

data/demo/instance.md

@@ -0,0 +1,149 @@
+# Instance
+
+First thing we need to do, of course, is load the library.
+
+    require 'instance'
+
+Now we can create an example class with which to work.
+
+    class ::Friend
+      attr_accessor :name, :age, :phone
+
+      def initialize(name, age, phone)
+        @name, @age, @phone = name, age, phone
+      end
+    end
+
+And now demonstrate the available API.
+
+## Instance#variables
+
+    f1 = Friend.new("John", 30, "555-1212")
+    f1.instance.variables.assert == [:@name, :@age, :@phone]
+
+## Instance#names
+
+    f1 = Friend.new("John", 30, "555-1212")
+    f1.instance.names.assert == ["name", "age", "phone"]
+
+## Instance#keys
+
+    f1 = Friend.new("John", 30, "555-1212")
+    f1.instance.keys.assert == [:name, :age, :phone]
+
+## Instance#values
+
+    f1 = Friend.new("John", 30, "555-1212")
+    f1.instance.values.assert == ["John", 30, "555-1212"]
+
+## Instance#size
+
+The `#size` method reports how many instance variables are defined.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.size.assert == 3
+
+This method is primarily of use to the Enumerable mixin.
+
+## Instance#variable_defined?
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.assert.variable_defined?(:@name)
+    f.instance.assert.variable_defined?(:name)
+
+## Instance#update and #assign
+
+    f1 = Friend.new("John", 30, "555-1212")
+    f1.name.assert == 'John'
+
+    f1.instance.update(:name=>'Jerry')
+    f1.name.assert == 'Jerry'
+
+    f1.instance.assign(:name=>'John')
+    f1.name.assert == 'John'
+
+## Instance#to_h
+
+We can convert the object's state, i.e. it's instance variable names and values
+into a Hash very easily with the `#to_h` method.
+
+    f1 = Friend.new("John", 30, "555-1212")
+    f1.instance.to_h.assert == {:name=>"John", :age=>30, :phone=>"555-1212"}
+
+Notice that the `@` has beenn removed from the instance variable names. If we
+want the `@` to stay simply pass `true` to the `#to_h` method.
+
+    f1 = Friend.new("John", 30, "555-1212")
+    f1.instance.to_h(true).assert == {:@name=>"John", :@age=>30, :@phone=>"555-1212"}
+
+## Instance#class
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.class.assert == ::Friend
+
+## Instance#id
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.id == f.object_id
+
+## Instance#of?
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.assert.of?(::Friend)
+
+## Instance#get and #set
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.get(:name).assert == "John"
+    f.instance.set(:name, "Bill")
+    f.name.assert == "Bill"
+
+## Instance#remove
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.remove(:name)
+    f.instance.refute.variable_defined?(:@name)
+
+## Instance#method
+
+The Instance class provides a `method` method for getting a Method object for
+any of the target object's methods by name.
+
+    f1 = Friend.new("John", 30, "555-1212")
+    m  = f1.instance.method(:name)
+    m.assert.is_a?(::Method)
+
+This can seem a little confusing because Ruby's `instance_method` method actually
+returns an `UnboundMethod` object. Unfortunately Ruby's use of the term `instance_method`
+is a complete misnomer. It should be something like `method_definition` instead.
+The actual *instance method* is the object's method.
+
+## Instance#methods
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.methods
+    f.instance.methods(:private)
+    f.instance.methods(:protected)
+    f.instance.methods(:public)
+    f.instance.methods(:public, :private)
+
+## Instance#eval and #exec
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.eval("@name").assert == "John"
+    f.instance.exec{ @name }.assert == "John"
+
+## Instance#send
+
+Sending a message to an object as if within the object itself and thus by-passing
+method visibility is somehting that should only be done as an act of *metaprogramming*.
+Hence it makes sense for it to be done via the `instance` interface.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.send(:name).assert == "John"
+
+## Instance#delegate
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.delegate.assert == f
+

data/etc/qed.rb

@@ -0,0 +1,8 @@
+QED.configure 'coverage' do
+  require 'simplecov'
+  SimpleCov.command_name 'QED'
+  SimpleCov.start do
+    coverage_dir 'log/coverage'
+  end
+end
+

data/lib/instance.rb

@@ -0,0 +1,303 @@
+# Instance class is a delgator for any object which provides
+# an elegant and protected interface to an object's state, i.e.
+# its *instance*.
+#
+# Examples
+#
+#   class Friend
+#     attr_accessor :name, :age, :phone
+#     def initialize(name, age, phone)
+#       @name, @age, @phone = name, age, phone
+#     end
+#   end
+#
+#   f1 = Friend.new("John", 30, "555-1212")
+#   f1.instance
+#
+#   f1.instance.update({:name=>'Jerry'})
+#   f1.instance
+#
+# TODO: Should we add `is_a?` and `kind_of?` too?
+
+class Instance
+  include Enumerable
+
+  # Store Object methods so they cannot be overriden by the delegate class.
+  METHODS = {}
+
+  def self.freeze_method(name)
+    METHODS[name.to_sym] = Object.instance_method(name)
+  end
+
+  freeze_method :object_id
+  freeze_method :class
+  freeze_method :instance_of?
+  freeze_method :method
+  freeze_method :methods
+  freeze_method :public_methods
+  freeze_method :protected_methods
+  freeze_method :private_methods
+  freeze_method :instance_eval
+  freeze_method :instance_exec
+  freeze_method :instance_variables
+  freeze_method :instance_variable_get
+  freeze_method :instance_variable_set
+  freeze_method :instance_variable_defined?
+  freeze_method :remove_instance_variable
+  freeze_method :send
+
+  #module Kernel
+  #  # Returns an instance of Instance for +self+,
+  #  # which allows convenient access to an object's
+  #  # internals.
+  #  def instance
+  #    Instance.instance(self)
+  #  end
+  #end
+
+  # Instance cache acts as a global cache for instances of Instance.
+  @cache = {}
+
+  # Instance is multiton. Use this method instead of #new to get a
+  # cached instance.
+  def self.instance(delegate)
+    @cache[delegate] ||= Instance.new(delegate)
+  end
+
+  # Initialize new Instance instance.
+  def initialize(delegate)
+    @delegate = delegate
+  end
+
+  # The delegated object.
+  def delegate
+    @delegate
+  end
+
+  # Iterate over instance variables.
+  def each
+    variables.each do |name|
+      yield(name[1..-1].to_sym, get(name))
+    end
+  end
+
+  # Number of instance variables.
+  def size
+    variables.size
+  end
+
+  # Get instance variables with values as a hash.
+  #
+  # Examples
+  #
+  #   class X
+  #     def initialize(a,b)
+  #       @a, @b = a, b
+  #     end
+  #   end
+  #
+  #   x = X.new(1,2)
+  #
+  #   x.instance.to_h  #=> { :a=>1, :b=>2 }
+  #
+  # Returns [Hash].
+  def to_h(at=false)
+    h = {}
+    if at
+      variables.each do |name|
+        h[name] = get(name)
+      end
+    else
+      each do |key, value|
+        h[key] = value
+      end
+    end
+    h
+  end
+
+  # TODO: Not sure if this should be used.
+  alias_method :to_hash, :to_h
+
+  #
+  def get(name)
+    name = atize(name)
+    #@delegate.instance_variable_get(name)
+    METHODS[:instance_variable_get].bind(@delegate).call(name)
+  end
+  alias :[] :get
+
+  #
+  def set(name, value)
+    name = atize(name)
+    #@delegate.instance_variable_set(name,value)
+    METHODS[:instance_variable_set].bind(@delegate).call(name,value)
+  end
+  alias :[]= :set
+
+  #
+  def <<(pair)
+    name, value = *pair
+    name = atize(name)
+    set(name, value)
+  end
+
+  # Remove instance variable.
+  def remove(name)
+    name = atize(name)
+    METHODS[:remove_instance_variable].bind(@delegate).call(name)
+  end
+
+  # Set instance variables given a +hash+.
+  #
+  #   instance.update('@a'=>1, '@b'=>2)
+  #   @a   #=> 1
+  #   @b   #=> 2
+  #
+  # Also, +@+ sign is not neccessary.
+  #
+  #   instance.update(:a=>1, :b=>2)
+  #   @a   #=> 1
+  #   @b   #=> 2
+  #
+  def update(hash)
+    hash.each do |pair|
+      self << pair
+    end
+  end
+
+  # A hold-over from the the old #instance_assign method.
+  alias_method :assign, :update
+
+  # Same as #instance_variables.
+  def variables
+    #@delegate.instance_variables
+    METHODS[:instance_variables].bind(@delegate).call
+  end
+
+  # Instance vairable names as symbols.
+  #
+  # Returns [Array<Symbols>].
+  def keys
+    variables.collect do |name|
+      name[1..-1].to_sym
+    end
+  end
+
+  # Instance variable names as strings.
+  #
+  # Returns [Array<String>].
+  def names
+    variables.collect do |name|
+      name[1..-1]
+    end
+  end
+
+  # Instance variable values.
+  #
+  # Returns [Array<Object>].
+  def values
+    variables.collect do |name|
+      get(name)
+    end
+  end
+
+  # Instance evaluation.
+  def eval(*a,&b)
+    #@delegate.instance_eval(*a,&b)
+    METHODS[:instance_eval].bind(@delegate).call(*a,&b)
+  end
+
+  # Instance execution.
+  def exec(*a,&b)
+    #@delegate.instance_exec(*a,&b)
+    METHODS[:instance_exec].bind(@delegate).call(*a,&b)
+  end
+
+  # Get method. Usage of this might seem strange because Ruby's own
+  # `instance_method` method is a misnomer. It should be something
+  # like `definition` or `method_definition`. In Ruby the acutal
+  # "instance" method is accessed via the unadorned `method` method.
+  #
+  # Returns [Method].
+  def method(name)
+    #@delegate.instance_exec(*a,&b)
+    METHODS[:method].bind(@delegate).call(name)
+  end
+
+  # Returns list of method names.
+  #
+  # Returns [Array<Symbol>].
+  def methods(*selection)
+    list = []
+
+    if selection.empty?
+      list.concat METHODS[:methods].bind(@delegate).call
+    end
+
+    selection.each do |s|
+      case s
+      when :public
+        list.concat METHODS[:public_methods].bind(@delegate).call
+      when :protected
+        list.concat METHODS[:protected_methods].bind(@delegate).call
+      when :private
+        list.concat METHODS[:private_methods].bind(@delegate).call
+      end
+    end
+
+    return list
+  end
+
+  # Is the object an instance of a given class?
+  #
+  # Returns [Boolean]
+  def of?(a_class)
+    #@delegate.instance_of?(aclass)
+    METHODS[:instance_of?].bind(@delegate).call(a_class)
+  end
+
+  #
+  def variable_defined?(name)
+    name = atize(name)
+    #@delegate.variable_defined?(name)
+    METHODS[:instance_variable_defined?].bind(@delegate).call(name)
+  end
+
+  # Get object's instance id.
+  #
+  # Returns [Integer]
+  def id
+    #@delegate.variable_defined?(name)
+    METHODS[:object_id].bind(@delegate).call
+  end
+
+  # Get object's instance id.
+  #
+  # Returns [Class]
+  def class
+    #@delegate.variable_defined?(name)
+    METHODS[:class].bind(@delegate).call
+  end
+
+  # Send message to instance.
+  def send(*a, &b)
+    METHODS[:send].bind(@delegate).call(*a, &b)
+  end
+
+private
+
+  def atize(name)
+    name.to_s !~ /^@/ ? "@#{name}" : name
+  end
+
+end
+
+
+class BasicObject
+  # Returns an instance of Instance for `self`, which allows convenient
+  # access to an object's internals.
+  def instance
+    ::Instance.instance(self)
+  end
+end
+

data/lib/instance.yml

@@ -0,0 +1,62 @@
+---
+revision: 2013
+type: ruby
+sources:
+- index/
+authors:
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+organizations: []
+requirements:
+- groups:
+  - test
+  development: true
+  name: qed
+- groups:
+  - test
+  development: true
+  name: ae
+- groups:
+  - test
+  development: true
+  name: simplecov
+conflicts: []
+alternatives: []
+resources:
+- type: home
+  uri: http://rubyworks.github.com/instance
+  label: Homepage
+- type: code
+  uri: http://github.com/rubyworks/instance
+  label: Source Code
+- type: bugs
+  uri: http://github.com/rubyworks/instance/issues
+  label: Issue Tracker
+- type: docs
+  uri: http://rubydoc.info/gems/instance
+  label: Documentation
+- type: mail
+  uri: http://groups.google.com/group/facets-universal
+  label: Mailing List
+repositories:
+- name: upstream
+  scm: git
+  uri: git@github.com:rubyworks/instance.git
+categories: []
+copyrights:
+- holder: Rubyworks
+  year: '2014'
+  license: BSD-2-Clause
+customs: []
+paths:
+  load:
+  - lib
+name: instance
+title: Instance
+summary: Object Instance API
+created: '2014-01-31'
+description: |-
+  Instance is a spin-off of Ruby Facets. It provides a simple convenient API
+  for accessing an object's state.
+version: 0.1.0
+date: '2014-02-01'

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: instance
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Sawyer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: qed
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ae
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |-
+  Instance is a spin-off of Ruby Facets. It provides a simple convenient API
+  for accessing an object's state.
+email:
+- transfire@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+- HISTORY.md
+files:
+- .index
+- etc/qed.rb
+- lib/instance.rb
+- lib/instance.yml
+- demo/applique/env.rb
+- demo/instance.md
+- README.md
+- HISTORY.md
+- LICENSE.txt
+homepage: http://rubyworks.github.com/instance
+licenses:
+- BSD-2-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Object Instance API
+test_files: []
+has_rdoc: