Permalink
Browse files

Moving Superators from RubyForge SVN to Github

  • Loading branch information...
0 parents commit 735d579010c34ac495e97729efc7c7b296e44a48 Jay Phillips committed Mar 18, 2008
Showing with 561 additions and 0 deletions.
  1. +5 −0 History.txt
  2. +10 −0 Manifest.txt
  3. +44 −0 README.txt
  4. +27 −0 Rakefile
  5. 0 bin/superators
  6. +7 −0 lib/superators.rb
  7. +118 −0 lib/superators/macro.rb
  8. +26 −0 lib/superators/monkey_patch.rb
  9. +4 −0 lib/superators/version.rb
  10. +320 −0 spec/superator_spec.rb
5 History.txt
@@ -0,0 +1,5 @@
+== 1.0.0 / 2007-08-14
+
+* 1 major enhancement
+ * Birthday!
+
10 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
44 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.
27 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
0 bin/superators
No changes.
7 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
118 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.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 NoMethodError, "Superator #{sup} has not been defined on #{self.class}"
+ 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 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.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) && 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}/
+ 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
26 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
4 lib/superators/version.rb
@@ -0,0 +1,4 @@
+class Superators
+ MAJOR,MINOR,TINY = 0,9,1
+ VERSION = [MAJOR,MINOR,TINY].join '.'
+end
320 spec/superator_spec.rb
@@ -0,0 +1,320 @@
+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
+
+ 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

0 comments on commit 735d579

Please sign in to comment.