superators 0.9.0

data/History.txt

@@ -0,0 +1,5 @@
+== 1.0.0 / 2007-08-14
+
+* 1 major enhancement
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,10 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/superators
+lib/superators.rb
+lib/superators/macro.rb
+lib/superators/monkey_patch.rb
+lib/superators/version.rb
+spec/superator_spec.rb

data/README.txt

@@ -0,0 +1,44 @@
+superators
+    by Jay Phillips
+    http://jicksta.com
+
+== DESCRIPTION:
+  
+Superators are a superset of new Ruby operators you can create and use.
+
+== FEATURES/PROBLEMS:
+  
+* Presently a superator operand must support having a singleton class. Because true, false, nil, Symbols, and Fixnums are all specially optimized for in MRI and cannot have singleton classes, they can't be given to a superator. There are ways this can be potentially accounted for, but nothing is in place at the moment, causing this to be classified as a bug.
+
+* When defining a superator in a class, any operators overloaded after the superator definition will override a superator definition. For example, if you create the superator "<---" and then define the <() operator, the superator will not work. In this case, the superator's definition should be somewhere after the <() definition.
+
+* Superators work by handling a binary Ruby operator specially and then building a chain of unary operators after it. For this reason, a superator must match the regexp /^(\*\*|\*|\/|%|\+|\-|<<|>>|&|\||\^|<=>|>=|<=|<|>|===|==|=~)(\-|~|\+)+$/.
+
+== SYNOPSIS:
+
+Below is a simple example monkey patch which adds the "<---" operator to all Ruby Arrays.
+
+  class Array
+    superator "<---" do |operand|
+      if operand.kind_of? Array
+        self + operand.map { |x| x.inspect }
+      else
+        operand.inspect
+      end
+    end
+  end
+
+== REQUIREMENTS:
+
+* Only requirement is Ruby.
+
+== INSTALL:
+
+* sudo gem install superators
+* require 'superators'
+
+== LICENSE:
+
+This software is licensed in the public domain. You may do whatever you wish with it.
+
+You are allowed to use this library during dodo poaching as well.

data/Rakefile

@@ -0,0 +1,27 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/superators.rb'
+require 'spec/rake/spectask'
+
+Spec::Rake::SpecTask.new do |opts|
+  opts.spec_opts = %w'-c'
+end
+
+desc "Generate a HTML report of the RSpec specs"
+Spec::Rake::SpecTask.new "report" do |opts|
+  opts.spec_opts = %w'--format html:report.html'
+end
+
+Hoe.new('superators', Superators::VERSION) do |p|
+  p.rubyforge_name = 'superators'
+  p.author = 'Jay Phillips'
+  p.email = 'jay -at- codemecca.com'
+  p.summary = 'Superators add new sexy operators to your Ruby objects.'
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+end
+
+# vim: syntax=Ruby

data/lib/superators.rb

@@ -0,0 +1,7 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+require 'superators/version'
+require 'superators/macro'
+require 'superators/monkey_patch'
+
+include SuperatorMixin

data/lib/superators/macro.rb

@@ -0,0 +1,118 @@
+module SuperatorMixin
+  
+  BINARY_RUBY_OPERATORS = %w"** * / % + - << >> & | ^ <=> >= <= < > === == =~"
+  UNARY_RUBY_OPERATORS  = %w"-@ ~@ +@"
+  
+  BINARY_OPERATOR_PATTERN = BINARY_RUBY_OPERATORS.map { |x| Regexp.escape(x) }.join "|"
+  UNARY_OPERATOR_PATTERN  =  UNARY_RUBY_OPERATORS.map { |x| Regexp.escape(x) }.join "|"
+  UNARY_OPERATOR_PATTERN_WITHOUT_AT_SIGN = UNARY_OPERATOR_PATTERN.map { |x| x.gsub('@', '') }
+  
+  VALID_SUPERATOR = /^(#{BINARY_OPERATOR_PATTERN})(#{UNARY_OPERATOR_PATTERN_WITHOUT_AT_SIGN})+$/
+  
+  def superator_send(sup, operand)
+    if respond_to_superator? sup
+      __send__ superator_definition_name_for(sup), operand
+    else
+      raise NameError, "Superator #{sup} has not been defined on #{self.class}" unless superator_definition
+    end
+  end
+  
+  def respond_to_superator?(sup)
+    respond_to? superator_definition_name_for(sup)
+  end
+  
+  def defined_superators
+    methods.grep(/superator_definition_/).map { |m| superator_decode(m) }
+  end
+  
+  protected
+  
+  def superator(operator, &block)
+    raise ArgumentError, "block not supplied" unless block_given?
+    raise NameError, "Not a valid superator!" unless superator_valid?(operator)
+    
+    real_operator = real_operator_from_superator operator
+    
+    class_eval do
+      # Step in front of the old operator's dispatching.
+      alias_for_real_method = superator_alias_for real_operator
+      
+      if instance_methods.include?(real_operator) && !respond_to_superator?(operator)
+        alias_method alias_for_real_method, real_operator
+      end
+      
+      define_method superator_definition_name_for(operator), &block
+      
+      # When we get to the method defining, we have to know whether the superator had to be aliased
+      # or if it's new entirely.
+      define_method(real_operator) do |operand|
+        if operand.kind_of? SuperatorFlag
+          sup = operand.superator_queue.unshift(real_operator).join
+          operand.superator_queue.clear
+          
+          superator_send(sup, operand)
+        else
+          # If the method_alias is defined
+          if respond_to? alias_for_real_method
+            __send__(alias_for_real_method, operand)
+          else
+            raise NameError, "undefined method #{real_operator} for #{operand.inspect}:#{operand.class}"
+          end
+        end
+      end
+      
+    end
+    
+    def undef_superator(sup)
+      if respond_to_superator?(sup)
+        real_operator = real_operator_from_superator sup
+        real_operator_alias = superator_alias_for sup
+        
+        (class << self; self; end).instance_eval do
+          undef_method superator_definition_name_for(sup)
+          if respond_to? real_operator_alias
+            alias_method real_operator, real_operator_alias if defined_superators.empty?
+          else
+            undef_method real_operator
+          end
+        end
+      else
+        raise NameError, "undefined superator #{sup} for #{self.inspect}:#{self.class}"
+      end
+    end
+  end
+  
+  private
+  
+  def superator_encode(str)
+    tokenizer = /#{BINARY_OPERATOR_PATTERN}|#{UNARY_OPERATOR_PATTERN_WITHOUT_AT_SIGN}/
+    str.scan(tokenizer).map { |op| op.split('').map { |s| s[0] }.join "_" }.join "__"
+  end
+  
+  def superator_decode(str)
+    tokens = str.match /^(superator_(definition|alias_for))?((_?\d{2,3})+)((__\d{2,3})+)$/
+    #puts *tokens
+    if tokens
+      (tokens[3].split("_" ) + tokens[5].split('__')).reject { |x| x.empty? }.map { |s| s.to_i.chr }.join
+    end
+  end
+  
+  def real_operator_from_superator(sup)
+    sup[/^#{BINARY_OPERATOR_PATTERN}/]
+  end
+  
+  def superator_alias_for(name)
+    "superator_alias_for_#{superator_encode(name)}"
+  end
+  
+  def superator_definition_name_for(sup)
+    "superator_definition_#{superator_encode(sup)}"
+  end
+  
+  def superator_valid?(operator)
+    operator =~ VALID_SUPERATOR
+  end
+  
+end
+
+module SuperatorFlag;end

data/lib/superators/monkey_patch.rb

@@ -0,0 +1,26 @@
+class Object
+  
+  attr_reader :superator_queue
+  
+  def -@
+    extend SuperatorFlag
+    @superator_queue ||= []
+    @superator_queue.unshift '-'
+    self
+  end
+  
+  def +@
+    extend SuperatorFlag
+    @superator_queue ||= []
+    @superator_queue.unshift '+'
+    self
+  end
+  
+  def ~@
+    extend SuperatorFlag
+    @superator_queue ||= []
+    @superator_queue.unshift '~'
+    self
+  end
+  
+end

data/lib/superators/version.rb

@@ -0,0 +1,4 @@
+class Superators
+  MAJOR,MINOR,TINY = 0,9,0
+  VERSION = [MAJOR,MINOR,TINY].join '.'
+end

data/spec/superator_spec.rb

@@ -0,0 +1,304 @@
+require 'lib/superators'
+
+describe "The 'superator' macro" do
+  
+  it "should allow two superators to begin with the first 'real' operator" do
+    superatored = Class.new do
+      superator("--") { throw :superator_dash_dash  }
+      superator("-~") { throw :superator_dash_tilde }
+    end
+    lambda { superatored.new() -- Object.new }.should throw_symbol(:superator_dash_dash)
+    lambda { superatored.new() -~ Object.new }.should throw_symbol(:superator_dash_tilde)
+  end
+  
+  it "should raise an error when the 'real' operator isn't a valid Ruby operator" do
+    lambda do
+      Class.new do
+        superator('x--') {}
+      end
+    end.should raise_error
+  end
+
+  it "should raise a NameError when a superator is defined for a class that did not have the 'real' operator but the 'real' operator is used" do
+    superatored = Class.new do
+      superator('**--') {}
+    end
+    lambda do
+      superatored.new ** Object.new
+    end.should raise_error(NameError)
+  end
+
+  it "should be callable on a Class instance (e.g. on 'self' in a class definition)" do
+    Class.new.should respond_to('superator')
+    x = Class.new do
+      self.class.superator("-~+~-") { throw :class_superator }
+    end
+    lambda { x -~+~- Object.new }.should throw_symbol(:class_superator)
+    lambda { x.new() -~+~- Object.new }.should raise_error
+  end
+  
+  it "should work when defined in an eigenclass" do    
+    victim = Object.new
+    class << victim
+      superator('<<~~') { throw :eigenclass }
+    end
+    lambda { victim <<~~ "monkey" }.should throw_symbol(:eigenclass)
+  end
+  
+  it "should preserve the old 'real' operator" do
+    victim = Class.new do
+      def <<(_)
+        throw :original_method
+      end
+      superator('<<~~') { throw :superator }
+    end.new
+    lambda { victim <<   Object.new }.should throw_symbol(:original_method)
+    lambda { victim <<~~ Object.new }.should throw_symbol(:superator)
+  end
+
+  # This one is going to be very difficult to implement. method_added() maybe?
+  it "should work even when the superator's 'main' method is redefined after the superator macro" do
+    victim = Class.new do
+      def <(_) throw :first end
+      superator("<~~") { throw :superator }
+      def <(_) throw :last end
+    end
+    lambda { victim.new()  <  Object.new }.should throw_symbol(:last)
+    lambda { victim.new() <~~ Object.new }.should throw_symbol(:superator)
+  end
+  
+end
+
+describe "Defined binary superators" do
+  
+  it "should be available to subclasses" do
+    superclass = Class.new do
+      superator("<<--") { throw :superclass }
+    end
+    lambda { Class.new(superclass).new <<-- "Foobar" }.should throw_symbol(:superclass)
+  end
+  
+  it "should be overridable in subclasses" do
+    parent = Class.new do
+      superator("<~") { throw :parent }
+    end
+    
+    child = Class.new(parent) do
+      superator("<~") { throw :child }
+    end
+    
+    lambda { parent.new() <~ Object.new }.should throw_symbol(:parent)
+    lambda { child.new()  <~ Object.new }.should throw_symbol(:child)
+  end
+  
+  it "should redefine an already-defined superator of the same class" do
+    lambda do
+      Class.new do
+        superator("<---") { throw :first }
+        superator("<---") { throw :last  }
+      end.new <--- Object.new
+    end.should throw_symbol(:last)
+  end
+end
+
+describe "The superator_send method" do
+  
+  it "should execute the block within the object's instance (so self is the instance, not the class)" do
+    Class.new do
+      superator "-+-" do |other|
+        self.should_not be_kind_of(Class)
+      end
+    end
+  end
+
+  it "should receive the proper arguments" do
+    x = Class.new do
+      superator("-+-+~++~") {}
+    end
+    victim, operand = x.new, "a clue"
+    victim.should_receive(:superator_send).once.with("-+-+~++~", operand)
+    victim -+-+~++~ operand
+  end
+  
+  it "should exist on an Object instance" do
+    Object.new.should respond_to(:superator_send)
+  end
+  
+  it "should raise NameError if an invalid superator is given" do
+    lambda do
+      Object.new.superator_send("17BB&DB & !!  @", Object.new.extend(SuperatorFlag))
+    end.should raise_error(NameError)
+  end
+
+end
+
+describe "The respond_to_superator? method" do
+  
+  it "should be available on all objects" do
+    Object.new.should respond_to(:respond_to_superator?)
+  end
+  
+  it "should return true if a superator was defined for the object's class" do
+    Class.new do
+      superator("<--") {}
+    end.new.respond_to_superator?("<--").should be_true
+  end
+  
+  it "should return true if a superator was defined for the object's superclass" do
+    parent = Class.new do
+      superator("<=~~") {}
+    end
+    Class.new(parent) {}.new.respond_to_superator?("<=~~").should be_true
+  end
+  
+  it "should return false or nil if a superator was not defined" do
+    result = Class.new.new.respond_to_superator?("<" + ("-" * 100))
+    (!! result).should be_false
+  end
+  
+  it "should return false for arguments only similar to (not the same as) the defined superator(s)" do
+    labrat = Class.new do
+      superator("<" + ('~' * 10)) {}
+    end.new
+    (!! labrat.respond_to_superator?('<' + ('~' * 11))).should be_false
+    (!! labrat.respond_to_superator?('<' + ('~' *  9))).should be_false
+  end
+  
+end
+
+describe "The undef_superator method" do
+  
+  it "should properly delete a superator" do
+    klass = Class.new do
+      superator("<----") {}
+    end
+    lambda do
+      obj = klass.new
+      obj.undef_superator "<----"
+      obj <---- Object.new
+    end.should raise_error(NameError)
+  end
+  
+  it "should make respond_to_superator?() return false" do
+    sup = "<<---"
+    klass = Class.new do
+      superator(sup) {}
+    end
+    obj = klass.new
+    obj.undef_superator sup
+    obj.respond_to_superator?(sup).should be_false
+  end
+  
+end
+
+describe "The monkey patch" do
+  
+  it "should create a superators attr_reader" do
+    Object.new.should     respond_to(:superator_queue)
+    Object.new.should_not respond_to(:superator_queue=)
+  end
+  
+end
+
+describe "The defined_superators() method" do
+  
+  it "should return an array of superator Strings when called on an object" do
+    sups = %w"-- ++ +- -+"
+    klass = Class.new do
+      sups.each do |sup|
+        superator(sup) {}
+      end
+    end
+    defined = klass.new.defined_superators
+    
+    defined.should be_kind_of(Array)
+    defined.size.should == sups.size
+    sups.each { |sup| defined.should include(sup) }
+  end
+  
+  it "should include superators defined in a superclass" do
+    parent = Class.new do
+      superator("--") {}
+    end
+    Class.new(parent).new.defined_superators.should include("--")
+  end
+  
+end
+
+describe "The 'real' operator finding algorithm" do
+  
+  it "should work with minus and unary negation" do
+    real_operator_from_superator("---").should == "-"
+  end
+  
+  it "should work with plus and unary plus" do
+    real_operator_from_superator("+++").should == "+"
+  end
+  
+  it "should return nil when given only unary tildes" do
+    real_operator_from_superator("~~~").should be_nil
+  end
+  
+  it "should work properly with the operators that are expanded versions of other operators" do
+    real_operator_from_superator("<<--").should == "<<"
+    real_operator_from_superator("<~~-").should == "<"
+    real_operator_from_superator("**+~").should == "**"
+    real_operator_from_superator("*+~~").should == "*"
+    real_operator_from_superator("<=~~").should == "<="
+    real_operator_from_superator(">=+-").should == ">="
+    real_operator_from_superator("=~~~").should == "=~"
+    real_operator_from_superator("<=>+").should == "<=>"
+    real_operator_from_superator("===+").should == "==="
+    real_operator_from_superator("==+-").should == "=="
+  end
+end
+
+describe "Superator method en-/decoding" do
+  
+  before do
+    @uses = { "<<~~"  => "60_60__126__126",
+             "<=>~"   => "60_61_62__126",
+             "----"   => "45__45__45__45",
+             "+-~+-~" => "43__45__126__43__45__126" }
+  end
+  
+  it "should return the same value after encoding and decoding" do
+    @uses.keys.each do |operator|
+      superator_decode(superator_encode(operator)).should == operator
+    end
+  end
+  
+  it "should encode binary superators properly" do
+    @uses.each_pair { |key, value| superator_encode(key).should == value }
+  end
+  
+  it "should decode binary superators properly" do
+    @uses.each_pair { |key, value| superator_decode(value).should == key }
+  end
+  
+  it "should create proper method definition name" do
+    op = "|+-"
+    superator_definition_name_for(op).should =~ /#{superator_encode(op)}$/
+  end
+  
+  it "should be containable in a method definition" do
+    lambda do
+      eval ":jay_#{superator_encode("<<+~--")}"
+    end.should_not raise_error(SyntaxError)
+  end 
+  
+end
+
+describe "A superator's arguments" do
+  # These specs are included for someone to potentially fix. Their failing
+  # constitutes a bug, though there's no clear way to implement this.
+
+  # These are types that can have no eigenclass. One way to store Kernel#caller
+  # stacktraces against the Fixnum value on which the unary methods were executed.
+  it "should allow a Fixnum as an operand" # This *MAY* never work
+  it "should allow a Symbol as an operand"
+  it "should allow true as an operand"
+  it "should allow false as an operand"
+  it "should allow nil as an operand"
+  
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.4
+specification_version: 1
+name: superators
+version: !ruby/object:Gem::Version 
+  version: 0.9.0
+date: 2007-08-22 00:00:00 +01:00
+summary: Superators add new sexy operators to your Ruby objects.
+require_paths: 
+- lib
+email: jay -at- codemecca.com
+homepage: "    by Jay Phillips"
+rubyforge_project: superators
+description: "== FEATURES/PROBLEMS:  * Presently a superator operand must support having a singleton class. Because true, false, nil, Symbols, and Fixnums are all specially optimized for in MRI and cannot have singleton classes, they can't be given to a superator. There are ways this can be potentially accounted for, but nothing is in place at the moment, causing this to be classified as a bug.  * When defining a superator in a class, any operators overloaded after the superator definition will override a superator definition. For example, if you create the superator \"<---\" and then define the <() operator, the superator will not work. In this case, the superator's definition should be somewhere after the <() definition.  * Superators work by handling a binary Ruby operator specially and then building a chain of unary operators after it. For this reason, a superator must match the regexp /^(\\*\\*|\\*|\\/|%|\\+|\\-|<<|>>|&|\\||\\^|<=>|>=|<=|<|>|===|==|=~)(\\-|~|\\+)+$/.  == SYNOPSIS:"
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Jay Phillips
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/superators
+- lib/superators.rb
+- lib/superators/macro.rb
+- lib/superators/monkey_patch.rb
+- lib/superators/version.rb
+- spec/superator_spec.rb
+test_files: []
+
+rdoc_options: 
+- --main
+- README.txt
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+executables: 
+- superators
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.3.0
+    version: