carats 0.3.0

data/lib/carat/nack.rb

@@ -0,0 +1,115 @@
+=begin rdoc
+
+= NackClass
+
+The NackClass is is like the NilClass except one step down.
+Nack is never used to to mean nothingness or emptiness.
+The Nack class is only used to report something is "a miss" w/o
+the system raising an Exception. It's a mechanism for
+lazy error evaluation.
+
+== Usage
+
+  def scalar( x )
+    if x.kind_of?(Enumerable)
+      return nack(ArgumentError, "Value must not be enumerable")
+    end
+    x
+  end
+
+  a = scaler( 1 )            #=> 1
+  b = scaler( [1,2] )        #=> nack
+  b.first                    #=> ArgumentError (previous)
+  
+  a = nail scaler( 1 )       #=> 1
+  b = nail scaler( [1,2] )   #=> ArgumentError
+
+== TODO
+
+* I beleive this class has even more potential yet.
+  It would be interesting to see if a catch/try correction
+  facility could be built into it too.
+
+== Author(s)
+
+* Thomas Sawyer
+
+== Legal
+
+Ruby License
+Copyright (c)2004 Thomas Sawyer
+
+
+== History
+
+* 2005.04.11 Passed basic test.
+
+=end
+
+class InvalidNackError < ArgumentError
+end
+
+class NackClass
+
+  attr_reader :error, :data
+
+  def initialize(error=nil, *data, &ctrl)
+    if Class === error and error <= Exception
+      @error = error.new(*data)
+    elsif error.kind_of?( Exception )
+      @error = error
+    elsif error.kind_of?( String )
+      @error = StandardError.new(error)
+    elsif error == nil
+      @error = StandardError.new
+    else
+      raise InvalidNackError
+    end
+    @data = data
+    @ctrl = ctrl
+  end
+
+  def call(*args)
+    @ctrl.call(*args)
+  end
+
+  def call_with_data
+    @ctrl.call(*@data)
+  end
+
+  def raise_error
+    raise @error
+  end
+
+  def to_s; "n/a"; end
+  
+  def ==(x)
+    x.is_a?(NackClass)
+  end
+
+  def method_missing(meth, *args)
+    raise_error
+  end
+
+end
+
+module Kernel
+  def nack(err=nil, *data, &ctrl)
+    NackClass.new(err, *data, &ctrl)
+  end
+end
+
+# private Object method
+def nail( arg )
+  if NackClass === arg
+    arg.raise_error
+  else
+    return arg
+  end
+end
+
+#class NilClass
+#  def method_missing(meth, *args)
+#    nack()
+#  end
+#end

data/lib/carat/nil-comparable.rb

@@ -0,0 +1,67 @@
+=begin rdoc
+
+= NilComparable
+
+NilComparable does two things. First it make nil comparable, such that 
+all things (except itself) are greater than it.
+
+Secondly it provides a module called NilComparable to include into any
+other class to allow it to compare itself to NilClass as the greater
+of the two.
+
+= Author(s)
+
+* Paul Brannan
+* Thomas Sawyer
+
+=end
+
+class NilClass
+  include Comparable
+  def <=>(x)
+    x.nil? ? 0 : -1
+  end
+  alias_method( :cmp, :<=> )
+end
+
+# # Calling this method for a given class allows instances
+# # of a class to be compared to nil using <=>.
+# # Adapted from code by Paul Brannan (Ruby License)
+# # NOTE: THIS SHOULD BE A CLASS INCLUDING MODULE, I THINK.
+# def nil_comparable(klass=self)
+#   klass.class_eval %{
+#     if method_defined?( :<=> )
+#       alias_method :compare_without_nil, :<=>
+#     else
+#       def compare_without_nil( other )
+#         raise TypeError, "Cannot compare \#{self.inspect} to \#{other.inspect}"
+#       end
+#     end
+#     def <=>( other )
+#       return 1 if other.nil?
+#       compare_without_nil( other )
+#     end
+#   }
+# end
+
+module NilComparable
+
+  def self.included( mod )
+    mod.class_eval %{
+      if method_defined?( :<=> )
+        alias_method :compare_without_nil, :<=>
+      else
+        def compare_without_nil( other )
+          raise TypeError, "Cannot compare \#{self.inspect} to \#{other.inspect}"
+        end
+      end
+      def <=>( other )
+        return 1 if other.nil?
+        compare_without_nil( other )
+      end
+    }
+  end
+
+end
+
+

data/lib/carat/nil-missing.rb

@@ -0,0 +1,12 @@
+class NilClass
+  # Have nil respond to all non-existent methods,
+  # always returning <tt>nil</tt>.
+  #
+  #  require 'facet/nil/nil_missing'
+  #
+  #  nil.foo   #=> nil
+  #
+  def method_missing(meth, *args)
+    nil
+  end
+end

data/lib/carat/notcopyable.rb

@@ -0,0 +1,68 @@
+=begin rdoc
+
+= NotCopyable
+
+Disable copying via dup and clone (and copy).
+
+== Usage
+
+  require 'carat/notcopyable.rb'
+
+  Class FixedString < String
+    include NotCopyable
+  end
+  
+  s = FixedString.new("Don't tred on me!")
+  puts s
+  s2 = s.dup
+   
+produces
+ 
+  Don't tred on me!
+  TypeError, "Object not copyable"
+
+== Todo
+
+* If one is reopening a class and including this, it will
+  not work if the class defined #dub, #clone or #copy (and #deep_copy)
+  itself. It only work if it's ancestors are responsible for those
+  methods. How to fix?
+
+== Notes
+
+* I don't think this will prove very useful, but just in case
+  here it is.
+
+== Author(s)
+
+* Paul Brannan <paul at atdesk.com>
+* Thomas Sawyer
+
+== Legal
+
+Adapted from Ruby Treasures 0.4
+Copyright (C) 2002 Paul Brannan <paul@atdesk.com>
+
+You may distribute this software under the same terms as Ruby 
+(see the file COPYING that was distributed with this library).
+
+== History
+
+* 2005.04.11 Passed basic test.
+
+=end
+
+module NotCopyable
+  def clone
+    raise TypeError, "Object not copyable"
+  end
+  def dup
+    raise TypeError, "Object not copyable"
+  end
+  # if object/copy has been required?
+  def copy
+    raise TypeError, "Object not copyable"
+  end
+  alias_method( :deep_copy, :copy )
+end
+

data/lib/carat/orderedhash.rb

@@ -0,0 +1,249 @@
+#$Id: orderedhash.rb, v2.0 2004-12-05 transami Exp $
+
+=begin rdoc
+
+= OrderedHash
+
+Hash with preserved order and some array-like extensions
+
+== AUTHOR
+
+* jan molic </mig/at/1984/dot/cz/>
+
+== THANKS
+ 
+Andrew Johnson for his suggestions and fixes of Hash[], merge,
+to_a, inspect and shift.
+
+== USAGE
+
+Just require this file and use OrderedHash instead of Hash.
+
+  require 'trix/orderedhash'
+  
+  # You can do simply
+  hsh = OrderedHash.new
+  hsh['z'] = 1
+  hsh['a'] = 2
+  hsh['c'] = 3
+  p hsh.keys     #=> ['z','a','c']
+
+  # or using OrderedHash[] method
+  hsh = OrderedHash['z', 1, 'a', 2, 'c', 3] 
+  p hsh.keys     #=> ['z','a','c']
+
+  # but this don't preserve order
+  hsh = OrderedHash['z'=>1, 'a'=>2, 'c'=>3]
+  p hsh.keys     #=> ['a','c','z']
+
+  # OrderedHash has useful extensions: push, pop and unshift
+  p hsh.push('to_end', 15)       #=> true, key added
+  p hsh.push('to_end', 30)       #=> false, already - nothing happen
+  p hsh.unshift('to_begin', 50)  #=> true, key added
+  p hsh.unshift('to_begin', 60)  #=> false, already - nothing happen
+  p hsh.keys                     #=> ["to_begin", "a", "c", "z", "to_end"]
+  p hsh.pop                      #=> ["to_end", 15], if nothing remains, return nil
+  p hsh.keys                     #=> ["to_begin", "a", "c", "z"]
+  p hsh.shift                    #=> ["to_begin", 30], if nothing remains, return nil
+
+=end  
+
+
+class OrderedHash < Hash
+
+    attr_accessor :order
+
+    class << self
+        def [] *args
+            hsh = OrderedHash.new
+            if Hash === args[0]
+                hsh.replace args[0]
+            elsif (args.size % 2) != 0
+                raise ArgumentError, "odd number of elements for Hash"
+            else
+                hsh[args.shift] = args.shift while args.size > 0
+            end
+            hsh
+        end
+    end
+
+    def initialize 
+        @order = []
+    end
+    
+    def store_only a,b
+        store a,b
+    end
+    
+    alias orig_store store    
+    def store a,b
+        @order.push a unless has_key? a
+        super a,b
+    end
+    alias []= store
+    
+    def == hsh2
+        return false if @order != hsh2.order
+        super hsh2
+    end
+    
+    def clear
+        @order = []
+        super
+    end
+    
+    def delete key
+        @order.delete key
+        super
+    end
+    
+    def each_key
+        @order.each { |k| yield k }
+        self
+    end
+    
+    def each_value
+        @order.each { |k| yield self[k] }
+        self
+    end
+    
+    def each
+        @order.each { |k| yield k,self[k] }
+        self
+    end
+    alias each_pair each    
+
+    def delete_if
+        @order.clone.each { |k| 
+            delete k if yield
+        }
+        self
+    end
+    
+    def values
+        ary = []
+        @order.each { |k| ary.push self[k] }
+        ary
+    end
+    
+    def keys
+        @order
+    end
+    
+    def invert
+        hsh2 = Hash.new    
+        @order.each { |k| hsh2[self[k]] = k }
+        hsh2
+    end
+    
+    def reject &block
+        self.dup.delete_if &block
+    end
+    
+    def reject! &block
+        hsh2 = reject &block
+        self == hsh2 ? nil : hsh2
+    end
+
+    def replace hsh2
+        @order = hsh2.keys 
+        super hsh2
+    end
+    
+    def shift
+        key = @order.first
+        key ? [key,delete(key)] : super
+    end
+
+    def unshift k,v
+        unless self.include? k
+            @order.unshift k
+            orig_store(k,v)
+            true
+        else
+            false
+        end
+    end
+    
+    def push k,v
+        unless self.include? k
+            @order.push k
+            orig_store(k,v)
+            true
+        else
+            false
+        end
+    end
+    
+    def pop
+        key = @order.last
+        key ? [key,delete(key)] : nil
+    end
+    
+    def to_a
+        ary = []
+        each { |k,v| ary << [k,v] }
+        ary
+    end
+    
+    def to_s
+        self.to_a.to_s
+    end
+    
+    def inspect
+        ary = []
+        each {|k,v| ary << k.inspect + "=>" + v.inspect}
+        '{' + ary.join(", ") + '}'
+    end
+    
+    def update hsh2
+        hsh2.each { |k,v| self[k] = v }
+        self
+    end
+    alias :merge! update
+    
+    def merge hsh2
+        self.dup update(hsh2)
+    end
+    
+    def select
+        ary = []
+        each { |k,v| ary << [k,v] if yield k,v }
+        ary
+    end
+    
+end
+
+
+=begin
+# --- development testing ---
+
+if __FILE__ == $0
+
+    # You can do simply
+    hsh = OrderedHash.new
+    hsh['z'] = 1
+    hsh['a'] = 2
+    hsh['c'] = 3
+    p hsh.keys     # ['z','a','c']
+
+    # or using OrderedHash[] method
+    hsh = OrderedHash['z', 1, 'a', 2, 'c', 3] 
+    p hsh.keys     # ['z','a','c']
+
+    # but this don't preserve order
+    hsh = OrderedHash['z'=>1, 'a'=>2, 'c'=>3]
+    p hsh.keys     # ['a','c','z']
+
+    # OrderedHash has useful extensions: push, pop and unshift
+    p hsh.push('to_end', 15)  # true, key added
+    p hsh.push('to_end', 30)  # false, already - nothing happen
+    p hsh.unshift('to_begin', 50)  # true, key added
+    p hsh.unshift('to_begin', 60)  # false, already - nothing happen
+    p hsh.keys     # ["to_begin", "a", "c", "z", "to_end"]
+    p hsh.pop      # ["to_end", 15], if nothing remains, return nil
+    p hsh.keys     # ["to_begin", "a", "c", "z"]
+    p hsh.shift    # ["to_begin", 30], if nothing remains, return nil
+
+end
+=end