elliottcable-refinery 0

data/README.markdown

@@ -0,0 +1,126 @@
+Refinery
+========
+Refinery stemmed from a very specific need that arose while writing
+[attr_*][] — to be able to utilize the Ruby hooks (for example, the
+`method_added` and `method_missing` methods) without “gobbling them up” so to
+speak. Normally, had I used those methods (especially if my particular
+implementation was very dependent on these methods operating in a specific
+way), the person using my library would be precluded from using the same
+methods in whatever class they included/extended my library into; if they used
+one of those methods for some purpose, their definition would ‘overwrite’ mine,
+thus quite possibly making my library (or their code using my library) cease
+to function correctly.
+
+The simple, singular purpose of Refinery is to ‘refine’ methods in such a way
+that your important functionality can be assigned safely to these methods.
+Any attempts to re-define a ‘refined’ method after the refining process will
+simply ‘stack’ with your own implementation — your method code will execute
+first, with further re-definitions each being executed in turn when the method
+is called.
+
+[attr_*]: <http://by.elliottcable.name/attr_splat.xhtml> "elliottcable's attr_splat project"
+
+Usage
+-----
+Using Refinery is very simple - extend it into your class (or include it into
+the Class class if you use it often), and then pass a method's name (as a
+symbol) to the refine_method singleton method. A short example:
+    
+    class Something
+      extend Refinery
+      
+      def method_missing meth, *args
+        # Do some magic!
+        puts 'abc'
+      end
+      
+      refine_method :method_missing
+    end
+    
+    # Later, somewhere else…
+    
+    class Nothing < Something
+      def method_missing meth, *args
+        # Do other magic, not knowing about the former magic!
+        puts 'def'
+      end
+    end
+    
+    nothing = Nothing.new
+    nothing.nonexistant_method
+    
+Once refined, any further re-openings of your class (or a descendant) and
+re-definitions of the refined method will simply result in the implementations
+'stacking' with eachother.
+
+Care must obviously still be taken to ensure your code will 'stack' in a
+friendly way with the other implementations — be sure to programmatically
+check whatever may be necessary before executing your method's code!
+
+Installation
+------------
+You can install Refinery as a pre-built gem, or as a gem generated directly
+from the source.
+
+The easiest way to install Refinery is to use [RubyGems][] to acquire the
+latest 'release' version from [RubyForge][], using the `gem` command line tool:
+
+    sudo gem install refinery # You'll be asked for your account password.
+
+Alternatively, you can acquire it (possibly slightly more up-to-date,
+depending on how often I update the gemspec) from GitHub as follows:
+
+    # If you've ever done this before, you don't need to do it now - see http://gems.github.com
+    gem sources -a http://gems.github.com
+    sudo gem install elliottcable-refinery # You'll be asked for your account password.
+    
+Finally, you can build a gem from the latest source yourself. You need [git][],
+as well as [rake][]:
+
+    git clone git://github.com/elliottcable/refinery.git
+    cd refinery
+    # If you've ever done this before, you don't need to do it now - see http://gems.github.com
+    gem sources -a http://gems.github.com
+    sudo gem install elliottcable-echoe # You'll be asked for your account password.
+    rake install # You'll be asked for your account password.
+
+[RubyGems]: <http://rubyforge.org/projects/rubygems/> "RubyGems - Ruby package manager"
+[RubyForge]: <http://rubyforge.org/projects/refinery/> "Refinery on RubyForge"
+[git]: <http://git-scm.com/> "git - Fast Version Control System"
+
+Contributing
+------------
+You can contribute bug fixes or new features to Refinery by forking the project
+on GitHub (you'll need to register for an account first), and sending me a
+pull request once you've committed your changes.
+
+Links
+-----
+- [GitHub](http://github.com/elliottcable/refinery "Refinery on GitHub") is the
+    project's primary repository host, and currently also the project's home
+    page
+- [RubyForge](http://rubyforge.org/projects/refinery "Refinery on RubyForge") is
+    out primary RubyGem host, as well as an alternative repository host
+- [integrity](http://integrit.yreality.net/refinery "Refinery on yreality's integrity server")
+    is out continuous integration server - if the top build on that page is
+    green, you can assume the latest git HEAD is safe to run/install/utilize.
+- [Gitorious](http://gitorious.org/projects/refinery "Refinery on Gitorious") is
+    an alternative repository host
+- [repo.or.cz](http://repo.or.cz/w/refinery.git "Refinery on repo.or.cz") is
+    an alternative repository host
+
+Attribution
+-----------
+The Sing extension was contributed by [John Mair][banisterfiend].
+
+[banisterfiend]: <http://banisterfiend.wordpress.com/> "Banisterfiend (John Mair)'s Weblog"
+
+License
+-------
+Refinery is copyright 2008 by elliott cable.
+
+Refinery is released under the [GNU General Public License v3.0][gpl], which
+allows you to freely utilize, modify, and distribute all Refinery's source code
+(subject to the terms of the aforementioned license).
+
+[gpl]: <http://www.gnu.org/licenses/gpl.txt> "The GNU General Public License v3.0"

data/Rakefile.rb

@@ -0,0 +1,134 @@
+($:.unshift File.expand_path(File.join( File.dirname(__FILE__), 'lib' ))).uniq!
+begin 
+  require 'refinery'
+rescue LoadError
+  module Refinery; Version = -1; end
+end
+
+# =======================
+# = Gem packaging tasks =
+# =======================
+begin
+  require 'echoe'
+  
+  task :package => :'package:install'
+  task :manifest => :'package:manifest'
+  namespace :package do
+    Echoe.new('refinery', Refinery::Version) do |g|; g.name = 'Refinery'
+      g.project = 'refinery'
+      g.author = ['elliottcable']
+      g.email = ['Refinery@elliottcable.com']
+      g.summary = 'Mmmmagic'
+      g.url = 'http://github.com/elliottcable/refinery'
+      g.development_dependencies = ['elliottcable-echoe >= 3.0.2', 'rspec', 'rcov', 'yard', 'stringray']
+      g.manifest_name = '.manifest'
+      g.retain_gemspec = true
+      g.rakefile_name = 'Rakefile.rb'
+      g.ignore_pattern = /^\.git\/|^meta\/|\.gemspec/
+    end
+  
+    desc 'tests packaged files to ensure they are all present'
+    task :verify => :package do
+      # An error message will be displayed if files are missing
+      if system %(ruby -e "require 'rubygems'; require 'pkg/refinery-#{Refinery::Version}/lib/refinery'")
+        puts "\nThe library files are present"
+      end
+    end
+  end
+  
+rescue LoadError
+  desc 'You need the `elliottcable-echoe` gem to package Refinery'
+  task :package
+end
+
+# =======================
+# = Spec/Coverage tasks =
+# =======================
+begin
+  require 'spec'
+  require 'rcov'
+  require 'spec/rake/spectask'
+  
+  task :default => :'coverage:run'
+  task :coverage => :'coverage:run'
+  namespace :coverage do
+    Spec::Rake::SpecTask.new(:run) do |t|
+      t.spec_opts = ["--format", "specdoc"]
+      t.spec_opts << "--colour" unless ENV['CI']
+      t.spec_files = Dir['spec/**/*_spec.rb'].sort
+      t.libs = ['lib']
+      t.rcov = true
+      t.rcov_opts = [ '--include-file', '"^lib"', '--exclude-only', '".*"']
+      t.rcov_dir = File.join('meta', 'coverage')
+    end
+    
+    begin
+      require 'spec/rake/verify_rcov'
+      # For the moment, this is the only way I know of to fix RCov. I may
+      # release the fix as it's own gem at some point in the near future.
+      require 'stringray/core_ext/spec/rake/verify_rcov'
+      RCov::VerifyTask.new(:verify) do |t|
+        t.threshold = 95.0
+        t.index_html = File.join('meta', 'coverage', 'index.html')
+        t.require_exact_threshold = false
+      end
+    rescue LoadError
+      desc 'You need the `stringray` gem to verify coverage'
+      task :verify
+    end
+    
+    task :open do
+      system 'open ' + File.join('meta', 'coverage', 'index.html') if PLATFORM['darwin']
+    end
+  end
+  
+rescue LoadError
+  desc 'You need the `rcov` and `rspec` gems to run specs/coverage'
+  task :coverage
+end
+
+# =======================
+# = Documentation tasks =
+# =======================
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+  
+  task :documentation => :'documentation:generate'
+  namespace :documentation do
+    YARD::Rake::YardocTask.new :generate do |t|
+      t.files   = ['lib/**/*.rb']
+      t.options = ['--output-dir', File.join('meta', 'documentation'),
+                   '--readme', 'README.markdown']
+    end
+    
+    YARD::Rake::YardocTask.new :dotyardoc do |t|
+      t.files   = ['lib/**/*.rb']
+      t.options = ['--no-output',
+                   '--readme', 'README.markdown']
+    end
+    
+    task :open do
+      system 'open ' + File.join('meta', 'documentation', 'index.html') if PLATFORM['darwin']
+    end
+  end
+  
+rescue LoadError
+  desc 'You need the `yard` gem to generate documentation'
+  task :documentation
+end
+
+# =========
+# = Other =
+# =========
+desc 'Removes all meta producs'
+task :clobber do
+  `rm -rf #{File.expand_path(File.join( File.dirname(__FILE__), 'meta' ))}`
+end
+
+desc 'Check everything over before commiting'
+task :aok => [:'documentation:generate', :'documentation:open',
+              :'package:manifest', :'package:package', :'package:compile',
+              :'coverage:run', :'coverage:open', :'coverage:verify']
+
+task :ci => [:'documentation:generate', :'coverage:run', :'coverage:verify']

data/ext/sing/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+
+create_makefile("sing")

data/ext/sing/sing.c

@@ -0,0 +1,13 @@
+#include <ruby.h>
+#include <stdio.h>
+
+VALUE jm_Module;
+VALUE singleton(VALUE self) {
+  if(FL_TEST(self, FL_SINGLETON)) return Qtrue;
+  else return Qfalse;
+}
+
+void Init_sing() {
+  jm_Module = rb_define_module("Sing");
+  rb_define_method(jm_Module,"singleton?",singleton,0);
+}

data/lib/refinery.rb

@@ -0,0 +1,10 @@
+require 'refinery/core_ext/class'
+
+module Refinery
+  Version = 0
+  
+  # This refines an instance method named 'meth'.
+  def refine_method meth
+    
+  end
+end

data/lib/refinery/core_ext/class.rb

@@ -0,0 +1,12 @@
+require 'sing'
+
+class Class
+  # Pulls in #singleton?
+  include Sing
+  
+  ##
+  # Returns a list of all instances of this class
+  def instances
+    ObjectSpace.each_object(self).to_a
+  end
+end

data/lib/refinery/core_ext/object.rb

@@ -0,0 +1,7 @@
+class Object
+  ##
+  # Returns the singleton class for this object.
+  def singleton
+    class<<self;self;end
+  end
+end

data/refinery.gemspec

@@ -0,0 +1,128 @@
+
+# Gem::Specification for Refinery-0
+# Originally generated by Echoe
+
+--- !ruby/object:Gem::Specification 
+name: refinery
+version: !ruby/object:Gem::Version 
+  version: "0"
+platform: ruby
+authors: 
+- elliottcable
+autorequire: 
+bindir: bin
+
+date: 2008-10-12 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: echoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 3.0.1
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: stringray
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Mmmmagic
+email: 
+- Refinery@elliottcable.com
+executables: []
+
+extensions: 
+- ext/sing/extconf.rb
+extra_rdoc_files: 
+- ext/sing/extconf.rb
+- ext/sing/sing.c
+- lib/refinery/core_ext/class.rb
+- lib/refinery/core_ext/object.rb
+- lib/refinery.rb
+- LICENSE.text
+- README.markdown
+files: 
+- ext/sing/extconf.rb
+- ext/sing/sing.c
+- lib/refinery/core_ext/class.rb
+- lib/refinery/core_ext/object.rb
+- lib/refinery.rb
+- LICENSE.text
+- Rakefile.rb
+- README.markdown
+- spec/refinery/core_ext/class_spec.rb
+- spec/refinery_spec.rb
+- spec/spec_helper.rb
+- .manifest
+- refinery.gemspec
+has_rdoc: true
+homepage: http://github.com/elliottcable/refinery
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Refinery
+- --main
+- README.markdown
+require_paths: 
+- lib
+- ext
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: refinery
+rubygems_version: 1.3.0
+specification_version: 2
+summary: Mmmmagic
+test_files: []

data/spec/refinery/core_ext/class_spec.rb

@@ -0,0 +1,18 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe Class do
+  describe '#is_singleton?' do
+    
+    it 'should return false for a normal class' do
+      klass = Class.new
+      klass.should_not be_singleton
+    end
+    
+    it 'should return true for a singleton class' do
+      klass = Class.new
+      sing = klass.class_eval { class << self; self; end }
+      sing.should be_singleton
+    end
+    
+  end
+end