lens_of_truth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c683afe773d926b884d995ae7ff5bc05fec12f11
+  data.tar.gz: 289b22fef2d14618f33c9f9e75414d47f8dbca9c
+SHA512:
+  metadata.gz: 0ed81aaf5eedbb77795e96d087d0539f38e030d501d866c65d606454a1b79bf073fe6d196989731c31c8e22f10012b5c2fa2d0ea03a315ab49243f587d2db21a
+  data.tar.gz: 2231dc06fd3cfb5efafdb4d7f94c5f3b97d08193b8bea926c74efbd797d5a82969f603ce7d4225961d3fb1c5e6bffb909ac97f1e5798665dca9a0950b7600803

data/CODE_OF_CONDUCT

@@ -0,0 +1,9 @@
+,---.    ,---.-./`) ,---.   .--.   ____       .-'''-. .--.      .--.   ____   ,---.   .--.
+|    \  /    \ .-.')|    \  |  | .'  __ `.   / _     \|  |_     |  | .'  __ `.|    \  |  |
+|  ,  \/  ,  / `-' \|  ,  \ |  |/   '  \  \ (`' )/`--'| _( )_   |  |/   '  \  \  ,  \ |  |
+|  |\_   /|  |`-'`"`|  |\_ \|  ||___|  /  |(_ o _).   |(_ o _)  |  ||___|  /  |  |\_ \|  |
+|  _( )_/ |  |.---. |  _( )_\  |   _.-`   | (_,_). '. | (_,_) \ |  |   _.-`   |  _( )_\  |
+| (_ o _) |  ||   | | (_ o _)  |.'   _    |.---.  \  :|  |/    \|  |.'   _    | (_ o _)  |
+|  (_,_)  |  ||   | |  (_,_)\  ||  _( )_  |\    `-'  ||  '  /\  `  ||  _( )_  |  (_,_)\  |
+|  |      |  ||   | |  |    |  |\ (_ o _) / \       / |    /  \    |\ (_ o _) /  |    |  |
+'--'      '--''---' '--'    '--' '.(_,_).'   `-...-'  `---'    `---` '.(_,_).''--'    '--'

data/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION, AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

data/README.md

@@ -0,0 +1,60 @@
+# ![Lens of Truth](http://i.imgur.com/iscFxKa.png) Lens of Truth
+
+**lens_of_truth**, like [its namesake](http://zeldawiki.org/Lens_of_Truth), lets you find things the developers hid from you.
+
+Operating on the assumption that related data tend to live reasonably close together in memory, `Object#find_nearby` looks up and down the heap from the receiver's address in search of an object which meets some specification.
+
+### "Use cases"
+
+Under the hood, `Enumerator` is implemented in terms of fibers so as to support suspension and resumption. CRuby does the right thing by not exposing this implementation detail directly, but maybe we want a reference to the underlying `Fiber` anyway. We knows its [approximate location](https://git.io/vzNsN), so let's see if the **Lens of Truth** can help us home in on it:
+
+```ruby
+require 'fiber' # for Fiber#transfer
+require 'lens_of_truth'
+
+using LensOfTruth # refinement
+
+enum = Enumerator.new { |y|
+  y << y.find_nearby(Fiber) << 42
+}
+enum.next.transfer
+enum.next # => cannot resume transferred Fiber (FiberError)
+```
+
+Another extremely practical use for the Lens is to peek into the internals of lazy sequences.
+
+```ruby
+[].lazy.map(&:succ).take(10)
+# => #<Enumerator::Lazy: #<Enumerator::Lazy: #<Enumerator::Lazy: []>:map>:take(10)>
+```
+
+Instances of `Enumerator::Lazy` clearly know their history, but they've hitherto been pretty hush-hush about it. In CRuby at least, they store [their method and arguments](https://git.io/vzN8H) in hidden instance variables (ones with no leading asperand and which are thus inaccessible from Ruby land). No matter: since an object's [instance variable table](https://git.io/vzNlq) is in the vicinity of the object itself, the **Lens of Truth** can help us find our way:
+
+```ruby
+require 'lens_of_truth/core_ext' # patch Object directly
+
+seq = [].lazy
+seq = seq.map(&:succ)
+seq.find_nearby(Proc).call(41) # => 42
+seq = seq.take(10)
+seq.find_nearby(Array) # => [10]
+```
+
+Finding the right `Proc` or `Array` is a little harder (read: non-deterministic) since there are usually a lot of them about, but 60% of the time, it works every time.
+
+### Usage
+
+`Object#find_nearby` uses case equality (`===`) when performing the search, so you can scan around for nearby strings matching some regular expression or a numeric object within a given range. You can instead pass a block to be used as the predicate. There's also an optional keyword argument `limit` which specifies how far to search in other direction before bailing. Examples follow.
+
+```ruby
+p Object.find_nearby /^[A-Z]+$/
+# => "DESTDIR"
+p LensOfTruth.find_nearby 42..1337, limit: 9001
+# => nil :(
+p find_nearby { |o| o.is_a?(Hash) && o.size == 1 }
+# => {:frozen_string_literal=>false} :)
+```
+
+### Contributing
+
+Interesting use cases welcome.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new :spec do |t|
+  t.test_files = ['spec/lens_of_truth_spec.rb']
+end
+
+task :default => :spec

data/lens_of_truth.gemspec

@@ -0,0 +1,17 @@
+$:.unshift File.expand_path '../lib', __FILE__
+require 'lens_of_truth/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'lens_of_truth'
+  s.version     = LensOfTruth::VERSION
+  s.author      = 'D.E. Akers'
+  s.email       = '0x0dea@gmail.com'
+
+  s.summary     = 'Use the Lens of Truth to find objects hidden nearby.'
+  s.description = 'lens_of_truth adds Object#find_nearby to look around in proximal memory for things of interest.'
+
+  s.homepage    = 'https://github.com/0x0dea/lens_of_truth'
+  s.license     = 'WTFPL'
+
+  s.files       = `git ls-files`.split
+end

data/lib/lens_of_truth/core_ext.rb

@@ -0,0 +1,3 @@
+require 'lens_of_truth'
+
+Object.include LensOfTruth

data/lib/lens_of_truth/version.rb

@@ -0,0 +1,3 @@
+module LensOfTruth
+  VERSION = '0.1.0'
+end

data/lib/lens_of_truth.rb

@@ -0,0 +1,25 @@
+require 'fiddle'
+
+module LensOfTruth
+  def find_nearby spec = Object, limit: Float::INFINITY
+    spec = proc if block_given?
+    found = nil
+    swivel = Fiddle::SIZEOF_UINTPTR_T / 2
+
+    [-swivel, swivel].map { |coef|
+      Thread.new do |i = 0|
+        until found || i > limit
+          begin
+            obj = ObjectSpace._id2ref __id__ + coef * i += 1
+            break found = obj if spec === obj
+          rescue RangeError
+          end
+        end
+      end
+    }.each &:join
+
+    found
+  end
+
+  refine(Object) { include LensOfTruth }
+end

data/spec/lens_of_truth_spec.rb

@@ -0,0 +1,49 @@
+require 'minitest/autorun'
+require 'minitest/pride'
+require 'lens_of_truth'
+
+using LensOfTruth
+
+describe 'Object#find_nearby' do
+
+  it "should be able to find an Enumerator's underlying Fiber" do
+    require 'fiber'
+
+    enum = Enumerator.new { |y| y << y.find_nearby(Fiber) << 42 }
+    enum.next.transfer
+
+    e = -> { enum.next }.must_raise FiberError
+    e.message.must_match 'cannot resume transferred Fiber'
+  end
+
+  it "should be able to find a singleton class's attachee" do
+    obj = Object.new
+    cls = obj.singleton_class
+
+    cls.find_nearby { |o|
+      o.singleton_class == cls rescue nil
+    }.must_be_same_as obj
+  end
+
+  # NOTE: These next two are kinda flaky.
+
+  it "should be able to grab a lazy sequence's method" do
+    seq = [].lazy
+
+    foo = proc {} # Sprinkle the stack
+    seq = seq.map &:succ
+    bar = proc {} # for confusion.
+
+    seq.find_nearby(Proc).call(41).must_equal 42
+  end
+
+  it "should be able to grab a lazy sequence's arguments" do
+    seq = [].lazy
+
+    foo = [1,2,3] # More
+    seq = seq.take 10
+    bar = [4,5,6] # sprinkles.
+
+    seq.find_nearby(Array).must_equal [10]
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: lens_of_truth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- D.E. Akers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-29 00:00:00.000000000 Z
+dependencies: []
+description: lens_of_truth adds Object#find_nearby to look around in proximal memory
+  for things of interest.
+email: 0x0dea@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT
+- LICENSE
+- README.md
+- Rakefile
+- lens_of_truth.gemspec
+- lib/lens_of_truth.rb
+- lib/lens_of_truth/core_ext.rb
+- lib/lens_of_truth/version.rb
+- spec/lens_of_truth_spec.rb
+homepage: https://github.com/0x0dea/lens_of_truth
+licenses:
+- WTFPL
+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.5.1
+signing_key: 
+specification_version: 4
+summary: Use the Lens of Truth to find objects hidden nearby.
+test_files: []