superators19 0.9.2

data/History.txt

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

data/README.md

@@ -0,0 +1,47 @@
+# 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,17 @@
+# -*- ruby -*-
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern    = "spec/**/*_spec.rb"
+  spec.verbose    = true
+  spec.rspec_opts = ['--color']
+end

data/lib/superators19.rb

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

data/lib/superators19/macro.rb

@@ -0,0 +1,131 @@
+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.gsub '@', ''
+
+  VALID_SUPERATOR = /^(#{BINARY_OPERATOR_PATTERN})(#{UNARY_OPERATOR_PATTERN_WITHOUT_AT_SIGN})+$/
+
+  def superator_send(sup, operand)
+    meth = method(superator_definition_name_for(sup))
+    begin
+      # If the user supplied a block that doesn't take any arguments, Ruby 1.9
+      # objects if we try to pass it an argument
+      if meth.arity.zero?
+        meth.call
+      else
+        meth.call(operand)
+      end
+    rescue NoMethodError
+      # Checking for respond_to_superator? is relatively slow, so only do this
+      # if calling the superator didn't work out as expected
+      if not respond_to_superator? sup
+        raise NoMethodError, "Superator #{sup} has not been defined on #{self.class}"
+      else
+        raise
+      end
+    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.to_s) }
+  end
+
+  protected
+
+  def superator(operator, &block)
+    raise ArgumentError, "block not supplied" unless block_given?
+    raise ArgumentError, "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.any? {|m| m.to_s == 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) && operand.superator_queue.any?
+          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 NoMethodError, "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 NoMethodError, "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}/
+    r = str.scan(tokenizer).map do |op|
+      op.enum_for(:each_byte).to_a.join "_"
+    end
+    r.join "__"
+  end
+
+  def superator_decode(str)
+    tokens = str.match /^(superator_(definition|alias_for))?((_?\d{2,3})+)((__\d{2,3})+)$/
+    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/superators19/monkey_patch.rb

@@ -0,0 +1,24 @@
+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/superators19/version.rb

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

data/spec/superator_spec.rb

@@ -0,0 +1,320 @@
+require 'superators19'
+
+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
+
+  it "should allow the 'real' operator to be called within the superator definition" do
+    victim = "Super"
+    class << victim
+      superator "++" do |operand|
+        upcase + operand.upcase
+      end
+      superator "-~+~-" do |operand|
+        self + operand
+      end
+    end
+    (victim ++ "ators").should == "SUPERATORS"
+    lambda { victim -~+~- "man" }.should_not raise_error
+  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

data/superators19.gemspec

@@ -0,0 +1,18 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "superators19/version"
+
+Gem::Specification.new do |s|
+  s.name        = "superators19"
+  s.version     = Superators::VERSION
+  s.authors     = ["Jay Phillips", "Neil Conway", "Scott Gonyea"]
+  s.email       = ["jay@codemecca.com"]
+  s.homepage    = "https://github.com/neilconway/superators"
+  s.summary     = %q{Superators add new sexy operators to your Ruby objects.}
+  s.description = %q{Superators are a superset of new Ruby operators you can create and use.}
+
+  s.add_development_dependency "rspec"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: superators19
+version: !ruby/object:Gem::Version 
+  hash: 63
+  prerelease: 
+  segments: 
+  - 0
+  - 9
+  - 2
+  version: 0.9.2
+platform: ruby
+authors: 
+- Jay Phillips
+- Neil Conway
+- Scott Gonyea
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Superators are a superset of new Ruby operators you can create and use.
+email: 
+- jay@codemecca.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- History.txt
+- README.md
+- Rakefile
+- lib/superators19.rb
+- lib/superators19/macro.rb
+- lib/superators19/monkey_patch.rb
+- lib/superators19/version.rb
+- spec/superator_spec.rb
+- superators19.gemspec
+homepage: https://github.com/neilconway/superators
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Superators add new sexy operators to your Ruby objects.
+test_files: 
+- spec/superator_spec.rb