object_shadow 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ebcf54f524f3ab83fac7d05282f3510682a8e75b1c6f4744616aef84f2291f0
+  data.tar.gz: 6db42ef5f1cfff3b3927662cfddc774b779196521c023d3b224bf3b37a41e258
+SHA512:
+  metadata.gz: 7350dd92d83503c51dc1d4a3172d8eda8713f2dcee47d41fdc324c289ab809ff93410cb49a18f5297218536f5bb0dfbb38ca8a1b42d603049ce724a9afdac7dc
+  data.tar.gz: 516a2e61c66368c4cfef098878e1493eccb536e5a26788b861013875be14bccdaedf415674d08c8adef07f5906d5810c378da830556f723c45bfeeada5659a16

data/.gitignore

@@ -0,0 +1,2 @@
+Gemfile.lock
+/pkg

data/.travis.yml

@@ -0,0 +1,18 @@
+sudo: false
+language: ruby
+
+rvm:
+- 2.6
+- 2.5
+- 2.4
+- 2.3
+- ruby-head
+- jruby-9.2.6.0
+- truffleruby
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: truffleruby
+    - rvm: 2.3
+#   fast_finish: true

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## CHANGELOG
+
+### 1.0.0
+
+* Initial release
+

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at opensource@janlelis.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest"
+gem "rake"

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2019 Jan Lelis, mail@janlelis.de
+
+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

@@ -0,0 +1,195 @@
+# Object#shadow [![[version]](https://badge.fury.io/rb/object.svg)](https://badge.fury.io/rb/object)  [![[travis]](https://travis-ci.org/janlelis/object.svg)](https://travis-ci.org/janlelis/object)
+
+Have you ever been [confused by some of Ruby's meta-programming methods](https://idiosyncratic-ruby.com/25-meta-methodology.html). If your answer is *Yes*, you have come to the right place:
+
+![Object and Shadow](/object_shadow.png)
+
+With **shadow**, every Ruby object has a shadow which encapsulates a clean API to access the object's variables and methods.
+
+Never again you will have to do the `x.methods - Object.methods` trick to get a meaningful method list.
+
+## Setup
+
+Add to your `Gemfile`:
+
+```ruby
+gem "object_shadow"
+```
+
+## Usage Example
+
+```ruby
+class P
+  def a_public_parent_method
+  end
+end
+
+class C < P
+  def initialize
+    @ivar = 42
+    @another_variable = 43
+  end
+
+  attr_reader :another_variable
+
+  def a_public_method
+  end
+
+  protected
+
+  def a_protected_method
+  end
+
+  private
+
+  def a_private_method
+  end
+end
+
+object = C.new
+
+def object.a_public_singleton_method
+end
+```
+
+### # Get an Overview
+
+```ruby
+object.shadow
+# ObjectShadow of Object #47023274596520
+
+## Lookup Chain
+
+    #<Class:#<C:0x00005588eb283150>> → C → P → Object → …
+
+## 2 Instance Variables
+
+    [:ivar, :another_variable]
+
+## 4 Public Methods (Non-Class/Object)
+
+    [:a_public_method, :a_public_parent_method, :a_public_singleton_method, :another_variable]
+
+## 1 Protected Method (Non-Class/Object)
+
+    [:a_protected_method]
+
+## 2 Private Methods (Non-Class/Object)
+
+    [:a_private_method, :initialize]
+
+```
+
+### # Read & Manipulate Instance Variables
+
+```ruby
+object.shadow[:ivar] # => 42
+object.shadow[:another_variable] = 23; object.another_variable # => 23
+object.shadow.variables # => [:ivar, :another_variable]
+object.shadow.to_h # => {:ivar=>42, :another_variable=>23}
+object.shadow.remove(:ivar) # => 42 (and removed)
+```
+
+### # List Available Methods
+
+```ruby
+# shadow features a single method called `methods` which takes some keyword arguments for further listing options
+object.shadow.methods # => [:a_public_method, :a_public_parent_method, :a_public_singleton_method, :another_variable]
+
+# Use scope: option to toggle visibility (default is public)
+object.shadow.methods(scope: :public) # => [:a_public_method, :a_public_parent_method, :a_public_singleton_method, :another_variable]
+object.shadow.methods(scope: :protected) # => [:a_protected_method]
+object.shadow.methods(scope: :private) # => [:a_private_method, :initialize]
+object.shadow.methods(scope: :all) # => [:a_private_method, :a_protected_method, :a_public_method, :a_public_parent_method, :a_public_singleton_method, :another_variable, :initialize]
+
+# Use inherit: option to allow or prevent traversal of the inheritance chain
+object.shadow.methods(scope: :public, inherit: :singleton) # => [:a_public_singleton_method]
+object.shadow.methods(scope: :public, inherit: :self) # => [:a_public_method, :a_public_singleton_method, :another_variable]
+object.shadow.methods(scope: :public, inherit: :exclude_object) # => [:a_public_method, :a_public_parent_method, :a_public_singleton_method, :another_variable]
+object.shadow.methods(scope: :public, inherit: :all) # => [:!, :!=, :!~, :<=>, :==, :===, :=~, :__id__, :__send__, :a_public_method, :a_public_parent_method, :a_public_singleton_method, :another_variable, :class, :clone, :define_singleton_method, :display, :dup, :enum_for, :eql?, :equal?, :extend, :freeze, :frozen?, :hash, :inspect, :instance_eval, :instance_exec, :instance_of?, :instance_variable_defined?, :instance_variable_get, :instance_variable_set, :instance_variables, :is_a?, :itself, :kind_of?, :method, :methods, :nil?, :object_id, :private_methods, :protected_methods, :public_method, :public_methods, :public_send, :remove_instance_variable, :respond_to?, :send, :shadow, :singleton_class, :singleton_method, :singleton_methods, :taint, :tainted?, :tap, :then, :to_enum, :to_s, :trust, :untaint, :untrust, :untrusted?, :yield_self]
+
+# Use target: :instances or :class to jump between child and class method listings
+C.shadow.methods == C.new.shadow.methods(target: :class) #=> true
+C.shadow.methods(target: :instances) == C.new.shadow.methods #=> true
+Enumerable.shadow.methods(target: :instances) # (lists Enumerables' methods)
+```
+
+## Documentation
+
+### Instance Variables
+
+Shadow exposes instance variables in a Hash-like manner:
+
+Method     | Description
+-----------|------------
+`[]`       | Retrieve instance variables. Takes a symbol without `@` to identify variable.
+`[]=`      | Sets instance variables. Takes a symbol without `@` to identify variable.
+`remove`   | Removes an instance variables. Takes a symbol without `@` to identify variable.
+`variable?`| Checks if a variable with that name exists. Takes a symbol without `@` to identify variable.
+`variables`| Returns the list of instance variables as symbols without `@`.
+`to_h`     | Returns a hash of instance variable names with `@`-less variables names as the keys.
+`to_a`     | Returns an array of all instance variable values.
+
+### Method Introspection
+
+All method introspection methods get called on the shadow and take a `target:` keyword argument, which defaults to `:self`. It can take one of the following values:
+
+Value of `target:` | Meaning
+-------------------|--------
+`:self`            | Operate on the current object
+`:class`           | Operate on the current object's class (the class for instances, the singleton class for classes)
+`:instances`       | Operate on potential instances created by the object, which is a class (or module)
+
+#### `methods(target: :self, scope: :public, inherit: :exclude_class)`
+
+Returns a list of methods available to the object.
+
+Only shows methods matching the given `scope:`, i.e. when you request all **public** methods, **protected** and **private** methods will not be included. You can also pass in `:all` to get methods of *all* scopes.
+
+The `inherit:` option lets you choose how deep you want to dive into the inheritance chain:
+
+Value of `inherit:` | Meaning
+--------------------|--------
+`:singleton`        | Show only methods directly defined in the object's singleton class
+`:self`             | Show singleton methods and methods directly defined in the object's class, but do not traverse the inheritance chain
+`:exclude_class`    | Stop inheritance chain just before Class or Module. For non-modules it fallbacks to `:exclude_object`
+`:exclude_object`   | Stop inheritance chain just before Object
+`:all`              | Show methods from the whole inheritance chain
+
+#### `method?(method_name, target: :self)`
+
+Returns `true` if such a method can be found, `false` otherwise
+
+#### `method_scope(method_name, target: :self)`
+
+Returns the visibility scope of the method in question, one of `:public`, `:protected`, `:private`. If the method cannot be located, returns `nil`.
+
+#### `method(method_name, target: :self, unbind: false, all: false)`
+
+Returns the `Method` or `UnboundMethod` object of the method requested. Use `unbind: true` to force the return value to be an `UnboundMethod` object. Will always return `UnboundMethod`s if used in conjunction with `target: :instances`.
+
+If you pass in `all: true`, it will return an array of all (unbound) method objects found in the inheritance chain for the given method name.
+
+#### `method_lookup_chain(target: :self, inherit: :exclude_class)`
+
+Shows the lookup chain for the target. See `methods()` for description of the `inherit:` option.
+
+## Q & A
+
+### Can I Access Hidden Instance Variables?
+
+Some of Ruby's core classes use `@`-less instance variables, such as [Structs](https://ruby-doc.org/core/Struct.html). They cannot be accessed using shadow.
+
+### Does It Support Refinements?
+
+[Currently not.](https://ruby-doc.org/core/doc/syntax/refinements_rdoc.html#label-Methods+Introspection)
+
+### Other Meta Programming?
+
+Only some aspects of Ruby meta-programming are covered. However, **shadow** aims to cover all kinds of meta-programming. Maybe you have an idea about how to integrate `eval`, `method_missing`, and friends?
+
+## J-_-L
+
+Copyright (C) 2019 Jan Lelis <https://janlelis.com>. Released under the MIT license.
+
+PS: This gem would not exist if the [instance gem](https://rubyworks.github.io/instance/) did not come up with the idea.

data/Rakefile

@@ -0,0 +1,38 @@
+# # #
+# Get gemspec info
+
+gemspec_file = Dir["*.gemspec"].first
+gemspec = eval File.read(gemspec_file), binding, gemspec_file
+info = "#{gemspec.name} | #{gemspec.version} | " \
+       "#{gemspec.runtime_dependencies.size} dependencies | " \
+       "#{gemspec.files.size} files"
+
+# # #
+# Gem build and install task
+
+desc info
+task :gem do
+  puts info + "\n\n"
+  print "  "; sh "gem build #{gemspec_file}"
+  FileUtils.mkdir_p "pkg"
+  FileUtils.mv "#{gemspec.name}-#{gemspec.version}.gem", "pkg"
+  puts; sh %{gem install --no-document pkg/#{gemspec.name}-#{gemspec.version}.gem}
+end
+
+# # #
+# Start an IRB session with the gem loaded
+
+desc "#{gemspec.name} | IRB"
+task :irb do
+  sh "irb -I ./lib -r #{gemspec.name.gsub '-','/'}"
+end
+
+# # #
+# Run specs
+
+desc "#{gemspec.name} | Spec"
+task :spec do
+  sh "for file in spec/*_spec.rb; do ruby $file; done"
+end
+task default: :spec
+

data/lib/object_shadow.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "object_shadow/basic_object"
+require_relative "object_shadow/version"
+require_relative "object_shadow/object_method"
+
+require_relative "object_shadow/wrap"
+require_relative "object_shadow/instance_variables"
+require_relative "object_shadow/method_introspection"
+require_relative "object_shadow/info_inspect"
+
+class ObjectShadow
+  include Wrap
+  include InstanceVariables
+  include MethodIntrospection
+  include InfoInspect
+end

data/lib/object_shadow/basic_object.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class ObjectShadow < BasicObject
+  def class
+    ::ObjectShadow
+  end
+
+  def respond_to?(what)
+    ::ObjectShadow.instance_methods.include?(what)
+  end
+
+  def instance_of?(other)
+    other == ::ObjectShadow
+  end
+
+  def is_a?(other)
+    other.ancestors.include? ::ObjectShadow
+  end
+
+  def singleton_class
+    class << self; self end
+  end
+end

data/lib/object_shadow/info_inspect.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class ObjectShadow
+  module InfoInspect
+    def inspect
+      public_methods = methods(scope: :public)
+      protected_methods = methods(scope: :protected)
+      private_methods = methods(scope: :private)
+
+      inherit_till = object.instance_of?(Object) ? :all : Object
+      lookup_chain = method_lookup_chain(inherit: inherit_till).join(" →  ") + " →  …"
+
+      res = \
+        "# ObjectShadow of Object #%{object_id}\n\n" \
+        "## Lookup Chain\n\n%{method_lookup_chain}\n\n"
+
+      unless variables.empty?
+        res += "## %{variables_count} Instance Variable%{variables_plural}\n\n%{variables}\n\n" \
+      end
+
+      unless public_methods.empty?
+        res += "## %{public_methods_count} Public Method%{public_methods_plural} (Non-Class/Object)\n\n%{public_methods}\n\n" \
+      end
+
+      unless protected_methods.empty?
+        res += "## %{protected_methods_count} Protected Method%{protected_methods_plural} (Non-Class/Object)\n\n%{protected_methods}\n\n" \
+      end
+
+      unless private_methods.empty?
+        res += "## %{private_methods_count} Private Method%{private_methods_plural} (Non-Class/Object)\n\n%{private_methods}\n\n" \
+      end
+
+      res % {
+        object_id: object.object_id,
+        method_lookup_chain: InfoInspect.column100(lookup_chain),
+        variables_count: variables.size,
+        variables_plural: variables.size == 1 ? "" : "s",
+        variables: InfoInspect.column100(variables.inspect),
+        public_methods_count: public_methods.size,
+        public_methods_plural: public_methods.size == 1 ? "" : "s",
+        public_methods: InfoInspect.column100(public_methods.inspect),
+        protected_methods_count: protected_methods.size,
+        protected_methods_plural: protected_methods.size == 1 ? "" : "s",
+        protected_methods: InfoInspect.column100(protected_methods.inspect),
+        private_methods_count: private_methods.size,
+        private_methods_plural: private_methods.size == 1 ? "" : "s",
+        private_methods: InfoInspect.column100(private_methods.inspect),
+      }
+    end
+
+    class << self
+      def column100(input)
+        words = input.split(" ")
+        lines = [""]
+        words.each{ |word|
+          if lines[-1].size + word.size < 95 # 95 + 1 word space + 4 indent spaces = 95
+            lines[-1] = lines[-1] + word + " "
+          else
+            lines << word + " "
+          end
+        }
+
+        lines.map{ |line|
+          "    #{line}"
+        }.join("\n")
+      end
+    end
+  end
+end