meta_instance 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be835e42320b77c3472c9daa12b24e40ae031df6
-  data.tar.gz: 92e0ba8cbdf56b9d1348c5e7fbd5e437afc94830
+  metadata.gz: b5ac0a81bfddb2ae4fbf907fa143708453c7d0e9
+  data.tar.gz: 5a1caa2e9320ac41222b9ba149a1e7c5aec0c61d
 SHA512:
-  metadata.gz: e7474fb5b29bf649f53e8dfeb759e39afe853aa1ff532d6437d47da825038be142a5fe577996374231c656ad4f13f69e5e46f149341e33b512691d9da5af9be3
-  data.tar.gz: 9e088dd0372b3b1e2d1c01d4203ac842100a2e4ebd748f56e3e5400575035925fd6cfe5c090b60f79231865f86bcb5086682aa5c69f61dfa2890bf8eef132229
+  metadata.gz: fa17b965044435b3f57dd1b2c2b8a04fa5d60d827a973907b229e214725389228ef688f2c2b7a31c7ab449b416773b72746219d1646de685680fec40964befd0
+  data.tar.gz: 8a5f58deae6e2e3dae92c2a3812e25af21d2730b380de4753cc29c8c7ce9a8073b3fbfaaeb6498f0b794d9cfbfda06bfcb8470d54432be6c7afe8b2f50be6f84

data/.codeclimate.yml

@@ -0,0 +1,7 @@
+languages:
+  Ruby: true
+  JavaScript: false
+  PHP: false
+  Python: false
+exclude_paths:
+- "spec"

data/.gitignore

@@ -1,18 +1,35 @@
 *.gem
 *.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-README.html
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.travis.yml

@@ -1,13 +1,17 @@
 language: ruby
 bundler_args: --without guard
 rvm:
-  - "2.0"
-  - "2.1"
+  - 2.0.0
+  - 2.2
   - ruby-head
-script: "bundle exec rspec"
+matrix:
+  allow_failures:
+    - rvm:
+      - ruby-head
+script: bundle exec rspec
 addons:
   code_climate:
-    repo_token: 1d1b1a31bb3137d986297ad8a1ad5a3a1adbd70f0e8583d7eaf1dd4c0ab0bbe1
+    repo_token: "97758529c5c06792d2f683e15e6ffe819ac16d140fe244640dcf103f1d172fc4 "
 branches:
   only: master
 notifications:

data/Gemfile

@@ -1,4 +1,3 @@
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in MetaInstance.gemspec
+source "https://rubygems.org"
 gemspec
+

data/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: .
+  specs:
+    meta_instance (1.1.0)
+      activesupport
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.2.1)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    byebug (4.0.5)
+      columnize (= 0.9.0)
+    codeclimate-test-reporter (0.4.7)
+      simplecov (>= 0.7.1, < 1.0.0)
+    coderay (1.1.0)
+    columnize (0.9.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    i18n (0.7.0)
+    json (1.8.2)
+    method_source (0.8.2)
+    minitest (5.6.1)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pry-byebug (3.1.0)
+      byebug (~> 4.0)
+      pry (~> 0.10)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    simplecov (0.10.0)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    slop (3.6.0)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  codeclimate-test-reporter
+  meta_instance!
+  pry-byebug
+  rspec

data/HISTORY.md

@@ -0,0 +1,33 @@
+# RELEASE HISTORY
+
+## 1.1.0 | 2015-05-27
+
+This release prepares for gemification.
+
+Changes:
+
+* Add RSpec Tests
+* Prep for gem publishing
+* Merge code with NullVoxPopuli/meta_instance
+* New Architecture
+* Rename to MetaInstance, replacing existing meta_instance gem
+
+
+## 0.2.0 | 2014-02-02
+
+This release adds an extra set of methods for modules and classes.
+
+Changes:
+
+* Add `method_definition` if object is a module or class.
+* Add `method_definitions` if object is a module or class.
+
+
+## 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

@@ -1,42 +1,73 @@
 MetaInstance
-============
+========
+[![Gem Version](http://img.shields.io/gem/v/meta_instance.svg?style=flat-square)](http://badge.fury.io/rb/meta_instance)
+[![Build Status](http://img.shields.io/travis/NullVoxPopuli/MetaInstance.svg?style=flat-square)](https://travis-ci.org/NullVoxPopuli/MetaInstance)
+[![Code Climate](http://img.shields.io/codeclimate/github/NullVoxPopuli/MetaInstance.svg?style=flat-square)](https://codeclimate.com/github/NullVoxPopuli/MetaInstance)
+[![Test Coverage](http://img.shields.io/codeclimate/coverage/github/NullVoxPopuli/MetaInstance.svg?style=flat-square)](https://codeclimate.com/github/NullVoxPopuli/MetaInstance)
+[![Dependency Status](http://img.shields.io/gemnasium/NullVoxPopuli/MetaInstance.svg?style=flat-square)](https://gemnasium.com/NullVoxPopuli/MetaInstance)
 
-[![Gem Version](https://badge.fury.io/rb/meta-instance.svg)](http://badge.fury.io/rb/meta_instance)
-[![Build Status](https://travis-ci.org/NullVoxPopuli/MetaInstance.svg)](https://travis-ci.org/NullVoxPopuli/MetaInstance)
-[![Code Climate](https://codeclimate.com/github/NullVoxPopuli/MetaInstance/badges/gpa.svg)](https://codeclimate.com/github/NullVoxPopuli/MetaInstance)
-[![Test Coverage](https://codeclimate.com/github/NullVoxPopuli/MetaInstance/badges/coverage.svg)](https://codeclimate.com/github/NullVoxPopuli/MetaInstance)
-[![Dependency Status](https://gemnasium.com/NullVoxPopuli/MetaInstance.svg)](https://gemnasium.com/NullVoxPopuli/MetaInstance)
-[![Security](https://hakiri.io/github/NullVoxPopuli/MetaInstance/master.svg)](https://hakiri.io/github/NullVoxPopuli/MetaInstance/master)
 
-A few helpers for manipulating methods on an instance of an object.
 
+## What Is It?
 
-#### In your Gemfile
+MetaInstance is a *convenient* and *safe* API for accessing and manipulating
+an object's state.
 
-    gem 'meta_instance'
+## How Does It Work
 
-#### Usage
+MetaInstance adds a method to all objects called `#instance`. It returns
+an `Instance` delegator that provides the full interface to the
+object's state.
 
-With a class:
+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.
 
-    class Foo
-      include MetaInstance
+## Usage
 
-      def bar; "bar"; end
+Let's use a very simple example class with which to demonstrate usage.
+
+```ruby
+    class Song
+      attr_accessor :title
+      attr_accessor :artist
+      attr_accessor :year
+
+      def initialize(title, artist, year)
+        @title  = title
+        @artist = artist
+        @year   = year
+      end
     end
+```
+
+Now we can create an instance of Song and work with it's state.
+
+```ruby
+    song = Song.new("Paranoid", "Black Sabbath", 1970)
+
+    song.instance.variables
+    # => [:@title, :@artist, :@year]
+
+    song.instance.get(:title)
+    # => "Paranoid"
+
+    song.instance[:artist]
+    # => "Black Sabbath"
+
+    song.instance.to_h
+    # => {:title => "Paranoid", :artist => "Black Sabbath", :year => 1970}
+```
 
-You can do this:
+For a more complete set of usage examples see the [QED](http://rubyworks.github.com/instance/qed.html) documentation.
 
-    f = Foo.new
-    f.bar
-    # => "bar"
 
-    f.instance_define(:bar){ "foo" }
-    f.bar
-    # => "foo"
+## Copyrights
 
-    Foo.new.bar
-    # => "bar"
+Copyright © 2014 [Rubyworks](http://rubyworks.github.io)
 
+BSD-2-Clause License
 
-See Specs for examples :-)
+See [LICENSE.txt](LICENSE.txt) file for license details.

data/docs/instance.md

@@ -0,0 +1,201 @@
+# 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
+
+A list of instance variables can be had via the `#variables` method.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.variables.assert == [:@name, :@age, :@phone]
+
+## Instance#names
+
+To get a list of variables names as strings and without the `@` prefix,
+use the `#names` method.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.names.assert == ["name", "age", "phone"]
+
+## Instance#keys
+
+Likewise, to get symbols instead of strings, use the `#keys` method.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.keys.assert == [:name, :age, :phone]
+
+## Instance#values
+
+The values of the instance variables alone can be had via the `#values` method.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.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
+
+The `#update` method can be used to change instance variables in mass via
+method options.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.name.assert == 'John'
+    f.instance.update(:name=>'Jerry')
+    f.name.assert == 'Jerry'
+
+## Instance#assign
+
+The `#assign` method is simply an alias for `#update`.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.assign(:name=>'Joe')
+    f.name.assert == 'Joe'
+
+## 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
+
+To know the class of an object use the `#class` method.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.class.assert == ::Friend
+
+Note that to get the class of Instance itself, you must use `#object_class`. 
+
+## Instance#id
+
+To know the id of an object use the `#id` method.
+
+    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
+
+To get the value of a specific instance variable use the `#get` or `#[]`
+methods.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.get(:name).assert == "John"
+    f.instance[:name].assert == "John"
+
+## Instance#set
+
+To set the value of a specific instance variable use the `#set` or `#[]=`
+methods.
+
+    f = Friend.new("John", 30, "555-1212")
+
+    f.instance.set(:name, "Bill")
+    f.name.assert == "Bill"
+
+    f.instance[:name] = "Billy"
+    f.name.assert == "Billy"
+
+## Instance#remove
+
+To remove an instance variable from an object use the `#remove` method.
+
+    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
+
+We can also get a whole list of an object's methods via the `#methods` method.
+
+    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
+
+To evaluate code in the context to the object's instance use the `#eval` method.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.eval("@name").assert == "John"
+
+## Instance#exec
+
+Likewise the `#exec` method can also be used.
+
+    f = Friend.new("John", 30, "555-1212")
+    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.instance.send(:name).assert == "John"
+
+## Instance#delegate
+
+To get at the delegated object of an Instance, use the `#delegate` method.
+
+    f = Friend.new("John", 30, "555-1212")
+    f.instance.delegate.assert == f
+
+