kyanite 0.6.1 → 0.7.0

data/lib/kyanite/general/kernel.rb

@@ -1,33 +1,29 @@
 # ruby encoding: utf-8
-require 'facets/timer'
-require 'rbconfig'
-
-unless defined? WINDOWS  
-  WINDOWS = /djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM ? RUBY_PLATFORM : false       
-end
-
-unless defined? RUBYDIR
-  RUBYDIR = RbConfig::CONFIG['prefix']
-  # puts "rubydir=" + RUBYDIR
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
 end
 
+require 'facets/timer'
 
 
 
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric |  
-# [ ] | Object | *KKernel* | CallerUtils | Undoable | Class | 
-#
-# ---
-#
-#
-# == *General* *Tools*
-#
-#
+# @!macro object
 module KKernel 
 
-  # Wiederholt einen Block so lange, bis die Zeit abgelaufen ist.
-  # Liefert die Anzahl der Durchläufe, die in dieser Zeit möglich waren.
-  # Alle Exceptions werden abgefangen (=> fehlerhafte Blöcke scheinen schneller zu laufen)
+  # @!macro [new] seconds
+  #  Repeats a block until the time is up. 
+  #  Returns the number of passes. All Exceptions are caught (=> bad blocks seem to run faster).
+  #  Example (using {Numeric}):
+  #   3.seconds do
+  #    puts Time.now.inspect
+  #   end  
+  #  Example (using {KKernel}):
+  #   repeat_n_seconds 3 do
+  #    puts Time.now.inspect
+  #   end
+  #
   def repeat_n_seconds( n=1, &block )
     timer = Timer.new(n) 
     begin
@@ -35,7 +31,7 @@ module KKernel
         count = 0
         until false
           count += 1
-          yield block
+          yield block if block
         end
       timer.stop
     rescue TimeoutError 
@@ -50,9 +46,15 @@ module KKernel
   
   
   
-  # Stellt für den nachfolgenden Block die Ruby-Warnungen ab.
-  # Nützlich, um z.B. Konstanten zu überschreiben.
-  # Quelle: Rails http://api.rubyonrails.org/classes/Kernel.html#M001639
+
+  
+  # Silence all Ruby warnings for the following block. Useful to override constants.
+  # Example:
+  #  TEST = 1
+  #  silence_warnings do
+  #   TEST = 2
+  #  end  
+  #
   def silence_warnings
        old_verbose, $VERBOSE = $VERBOSE, nil
        yield
@@ -61,58 +63,37 @@ module KKernel
   end    
   
   
-  # Vereinfacht die require-Statements in den Tests bei der Entwicklung von Libraries.  
-  # Beim lokalen Aufruf eines einzelnen Tests wird die lokale Version der Library verwendet, nicht die installierte gem.
-  # Verwendung:
-  #   if $0 == __FILE__ 
-  #     require 'kyanite/smart_load_path'
-  #     smart_load_path   
-  #   end
-  #   require 'mygemproject'  
-  #
-  def smart_load_path(__file__ = nil)
-    __file__ = caller[0] unless __file__
-    dir_caller =File.dirname(__file__)
-    
-    #puts "smart_load_path " + dir_caller    
-    
-    patharray = dir_caller.split('/')
-    patharray = dir_caller.split("\\")       if patharray.size == 1  
-    # libpath = File.join(patharray)   
-    patharray.size.times do |i|
-      break   if File.directory?( File.join(patharray, 'lib') ) 
-      patharray << '..'
-    end
-    newpath = File.join(patharray,'lib')  
-    if $:.include?(newpath)
-      return false
-    else
-      $:.unshift(newpath)  
-      return true
-    end
-    
-  end  #def  
+
   
   
-end # module
+end 
 
 class Object
   include KKernel
 end
 
+class Numeric
+
+  # @!macro seconds
+  def seconds( &block )
+    repeat_n_seconds( self ) do 
+          yield block if block    
+    end
+  end
+  
+end
+
 
 # ---------------------------------------------------------
 # Ausprobieren
 #
 if $0 == __FILE__ 
 
-# pp RUBYDIR
-
-smart_load_path(__FILE__)
-$LOAD_PATH.each do |path|
-puts path
+TEST = 1
+silence_warnings do
+TEST = 2
 end
-
+puts TEST
 end
 
 

data/lib/kyanite/general/object.rb

@@ -1,46 +1,39 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 
 
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric |
-# [ ] | *Object* | KKernel | CallerUtils | Undoable | Class | 
-#
-# ---
-#
-#
-# == *For* *All* *Objects*
-# Tests and examples see TestKyaniteObject
-#
-#
+# @!macro object
 class Object
  
-    # <tt> false </tt>    
-    #
-    # Tests and examples see TestKyaniteObject    
-    #
+    # Returns +false+
+    # @return [false]
     def blank? 
         false
     end     
 
     
-    # Quelle: Facets http://facets.rubyforge.org/quick/rdoc/core/classes/Kernel.html#M000379
-    #
+
+    # Like +respond_to?+ but returns the result of the call if it does indeed respond.
+    # See {http://rubyworks.github.com/rubyfaux/?doc=http://rubyworks.github.com/facets/docs/facets-2.9.3/core.json#api-module-Kernel/api-method-Kernel-h-respond Facets +Kernel#respond+}.
     def respond(sym, *args)
       return nil if not respond_to?(sym)
       send(sym, *args)
     end    
     
     
-    # Alternative zu Object#dup. Dupliziert auch Unterobjekte. Langsam.
-    # Wird z.B. für Undo-Operationen verwendet, siehe Modul Undoable.
-    # 
+    # Slow but in-depth alternative to +dup+. Also duplicates sub-objects. Is e.g. for undo operations used, see module {Undoable}.
     def deep_copy
       Marshal.load( Marshal.dump( self ) )
     end
 
     
-    # Ist ein Objekt numerisch?
-    #
-    # Tests and examples see TestKyaniteObject    
+    # Is the object numeric?
+    # Tests see {TestKyaniteObject here}.   
     #
     def is_numeric?
       Float self 
@@ -48,30 +41,13 @@ class Object
       false 
     end        
     
-    
-    # <tt> false </tt>    
+    # Returns +false+    
+    # @return [false]  
     def empty? 
         false
     end  
 
-    
-
-    
-    
-    # Liefert nil, wenn die Condition erfüllt ist. Sonst self.
-    #
-    def to_nil(condition = :empty) 
-        return nil         if self.respond(condition.to_s + '?')
-        return self
-    end    
-    
-    
-    # Liefert nil, wenn die Condition nicht erfüllt ist. Sonst self.
-    #
-    def to_nil_unless(condition = :empty) 
-        return nil         unless self.respond(condition.to_s + '?')
-        return self
-    end    
+   
 
 
     # Findet den Namen einer Ruby-Konstanten anhand seines Wertes.
@@ -88,14 +64,14 @@ end
 if defined? TransparentNil
   class NilClass
    
-    # Rückgabe: false
+    # +false+
+    # @return [false]
     def blank?;                         false;          end    
 
-    # Rückgabe: false
+    # +false+    
+    # @return [false]
     def is_numeric?;                    false;          end
     
-    def to_nil;                         nil;            end   
-    def to_nil_unless(*a);              nil;            end   
     def name_of_constant(*a);           nil;            end   
   end
 end

data/lib/kyanite/general/true_false.rb

@@ -1,34 +1,40 @@
 # ruby encoding: utf-8
-# [ | *Kyanite* | Object | Array | Set | Enumerable | Hash | ]    | Kyanite | *TrueClass* | FalseClass | NilClass | Div | 
-#
-# ---
-#
-# == *True*
-#
-#
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
+
+# @!macro true_false
 class TrueClass  
      
      
-  # Rückgabe: 1     
+  # Returns +1+
+  # @return [1]  
   def to_i; 1; end
   
   
-  # Rückgabe: self   
+  # Returns +self+
+  # @return [self]   
   def strip; self; end
   
   
-  # Rückgabe: self  
+  # Returns +self+
+  # @return [self]  
   def dup; self; end      
+ 
   
-  
-  # see TestKyaniteTrueFalse#test_raumschiff_operator for tests  
+  # Defines true <=> true, true <=> false, false <=> true, false <=> false.
+  # See Tests {TestKyaniteTrueFalse#test_raumschiff_operator here}.  
   def <=>(other)
     return 1 if ! other
     return 0
   end  
   
   
-  # Rückgabe: false    
+  # Returns +false+
+  # @return [false]    
   def blank?; false; end
   
   
@@ -37,33 +43,33 @@ end # class
 
 
 
-# [ | *Kyanite* | Object | Array | Set | Enumerable | Hash | ]    | Kyanite | TrueClass | *FalseClass* | NilClass | Div | 
-#
-# ---
-#
-# == *False*
-#
+# @!macro true_false
 class FalseClass
       
-  # Rückgabe: 0
+  # Returns +0+
+  # @return [0]  
   def to_i; 0; end
-  
-  # Rückgabe: self  
+ 
+ 
+  # Returns +self+
+  # @return [self]  
   def strip; self; end  
+
   
-  # Rückgabe: self  
+  # Returns +self+
+  # @return [self]  
   def dup; self; end    
+
   
-  # see TestKyaniteTrueFalse#test_raumschiff_operator for tests
+  # (see TrueClass#<=>)
   def <=>(other)
     return -1 if other
     return 0
   end    
  
   
-  # umdefiniert!
-  #
-  # TestKyaniteObject#test_blank  
+  # Returns +false+
+  # @return [self]  
   def blank?; self; end
   
 

data/lib/kyanite/general/undoable.rb

@@ -1,20 +1,18 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
 
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric | Class | 
-# [ ] | Object | KKernel | CallerUtils | *Undoable* | Class |
-#
-# ---
-#
-#
-# == *Undo* 
-#
-#
+
+# @!macro undoable
 module Undoable
 
   @@undoable_history = Hash.new
 
-  # Speichert ein Objekt.
-  # Verwendet standardmäßig Object#dup. Für komplexere Objekte muss allerdings Object#deep_copy genutzt werden.
+  # Saves an object. 
+  # @param method [Symbol] method to use. Default is +:dup+. For more complex objects use {Object#deep_copy +:deep_copy+} instead.
   #
   def save(method=:dup)
     return if self == @@undoable_history[self.object_id] # nichts zu tun
@@ -22,23 +20,21 @@ module Undoable
   end
 
   
-  # Rückgriff auf den gespeicherten Zustand eines Objektes.
-  # Der gespeicherte Zustand verbleibt im Speicher.
+  # Loads a saved state of an object, the saved state remains in memory.
   # 
   def load_and_keep
     @@undoable_history[self.object_id]
   end
   
   
-  # Rückgriff auf den gespeicherten Zustand eines Objektes.
-  # Der gespeicherte Zustand wird verworfen. 
+  # Loads a saved state of an object, the saved state will be discarded.
   #   
   def load_and_delete
     @@undoable_history.delete(self.object_id)
   end  
   
   
-  # Verwirft alle gepeicherten Objektzustände.
+  # Discards all saved states of all objects.
   #
   def self.clear
     @@undoable_history.clear

data/lib/kyanite/hash.rb

@@ -1,4 +1,10 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 require 'active_support/core_ext/hash/slice'          # Slice a hash to include only the given keys. 
 require 'active_support/core_ext/hash/reverse_merge'  # Merges the caller into +other_hash+. 
 require 'kyanite/enumerable'                          # is_collection?
@@ -11,72 +17,56 @@ require 'kyanite/enumerable'                          # is_collection?
 
 
 
-# [ | Kyanite | Object | Array | Set | Enumerable | *Hash* | ]     | *Hash* |  Dictionary |
-# ---
-#  
-#
-# == *Tools* *For* *Hash*
-# See TestKyaniteHash for tests and examples.
-#
-# === Generelle Anmerkungen zu Hashes
-# Definiert man in irgendeinem Objekt die Methode <tt>==(other)</tt>, so muss man auch die Methode +hash+ neu definieren! 
-#
-# Rubys +delete+ und +delete_if+ verändern den Hash! Siehe TestHash#test_delete
-#
-#
-class Hash
 
 
-  if RUBY_VERSION < "1.9"
-  
-    # Credit: Paul Murur http://mucur.name/posts/when-is-a-set-not-a-set
-    # Create a hash based on the keys and values.
-    def hash
-      keys.hash + values.hash + (default ? default.hash : 0)
-    end
-
-    # Credit: Paul Murur http://mucur.name/posts/when-is-a-set-not-a-set
-    # To determine whether two hashes are the same, compare their hashes.
-    def eql?(other)
-      hash == other.hash
-    end
-    
-  end # Ruby Version
+# @!macro hash
+class Hash
 
 
- 
-  # Entfernt alle Key-Value-Paare mit <b>nil-Keys</b> in-place.
-  # Tests: TestHash#test_delete
+  # Deletes all key-value pairs with <b>nil-keys</b> in-place.
+  # @return [Hash] in-place modificated
   def compact_keys!
       delete_if {|key, value| key.nil? }
   end
   
   
-  # Entfernt alle alle Key-Value-Paare mit <b>nil-Values</b> in-place.
-  # Tests: TestHash#test_compact
+  # Deletes all key-value pairs with <b>nil-values</b> in-place.
+  # @return [Hash] in-place modificated 
   def compact_values!
       delete_if {|key, value| value.nil? }
   end    
 
   
-  # Entfernt das Key-Value-Paar mit einem bestimmten Key in-place. 
-  # Rückgabe ist der modifizierte Hash (im Gegensatz zur +delete+-Methode, die das entfernte Key-Value-Paar zurückgibt! ).
+  # Deletes the key-value pair with a <b>given key</b> in-place. 
+  # Returns the modificated hash (in contrast to Rubys +delete+ method that returns the deleted key-value pair! ).
+  # @return [Hash] in-place modificated 
   def delete_key(key)
     delete_if { |k,v| k == key }
   end        
   
-  # Entfernt alle Key-Value-Paare mit einem bestimmten Value in-place.
-  #     
+  # Deletes all key-value pairs with a <b>given value</b> in-place. 
+  # Returns the modificated hash (in contrast to Rubys +delete+ method that returns the deleted key-value pair! ).
+  # @return [Hash] in-place modificated 
   def delete_value(value)
     delete_if { |k,v| v == value }
   end
     
-    
-  # erzwingt ein Array der Länge 1, wenn sowohl Einzelwerte als auch Arrays erlaubt sind. 
-  # Beispiel:
-  #   inputoptions = options.arrayize(:skip, :debug)  
+  
+  # Forces some options in a methods options hash to be an array. 
+  # Useful if both individual values ​​and arrays are allowed as an input option.
+  #
+  # Example:
+  #  options = { :skip => 1, :debug => true, :test => false }
+  #  puts options 
+  #  => {:skip=>1, :debug=>true, :test=>false}
+  #
+  #  options.arrayize!(:skip, :debug)
+  #  puts options 
+  #  => {:skip=>[1], :debug=>[true], :test=>false}
   # 
-  def arrayize(*keys)
+  # @return [Hash]
+  # @param keys [Key, Array of keys] Keys to process 
+  def arrayize!(*keys)
     keys.each do |k|
       if self[k]  &&  !self[k].respond_to?(:first) 
         self[k] =  [self[k]]
@@ -87,7 +77,7 @@ class Hash
   end
   
   
-  # Greift auf den Hash mit nicht-ganz-passenden Schlüsseln zu
+  # Accesses the hash with keys that do not match exactly
   #
   def fuzzyget(key, level = 3)
     try = self[key]
@@ -99,12 +89,9 @@ class Hash
   end    
 
   
-  # Liefert die Verteilung der size 
-  # oder die Verteilung der class 
-  # oder die Verteilung eines anderen Merkmals der aufgezählten Elemente.
-  # Siehe auch Enumerable#distribution.  
-  # Die Keys des Hash werden ignoriert.
-  #
+  # Returns the distribution of +size+, +class+ or any other characteristic of the enumerated elements.
+  # The keys of the hash will be ignored. See also {Enumerable#distribution}, examples there.
+  # @return [Array]
   def distribution( mode = :size)
     verteilung = Hash.new
     each do | key, element |
@@ -119,8 +106,8 @@ class Hash
   end  
   
   
-  # liefert irgendein Value  
-  #
+
+  # @return any value
   def first
     self.each do |key, value|
       return value
@@ -128,8 +115,7 @@ class Hash
   end #def
   
   
-  # liefert irgendein anderes Value  
-  #
+  # @return any other value
   def last
     first = nil
     self.each do |key, value|
@@ -143,7 +129,21 @@ class Hash
   end #def 
  
 
-   
+  # if RUBY_VERSION < "1.9"
+  
+    # Credit: Paul Murur http://mucur.name/posts/when-is-a-set-not-a-set
+    # Create a hash based on the keys and values.
+    # def hash
+      # keys.hash + values.hash + (default ? default.hash : 0)
+    # end
+
+    # Credit: Paul Murur http://mucur.name/posts/when-is-a-set-not-a-set
+    # To determine whether two hashes are the same, compare their hashes.
+    # def eql?(other)
+      # hash == other.hash
+    # end
+    
+  # end # Ruby Version   
     
 
 end #class   
@@ -167,9 +167,14 @@ end
 #
 if $0 == __FILE__ 
 
-  test = {:b => 2, :a => 1,  :c => 3}
-  see test.first
-  see test.last
+  require 'perception'
+  
+  options = { :skip => 1, :debug => true, :test => false }
+  puts options
+  options.arrayize!(:skip) 
+  puts options
+
+