kyanite 0.3.7 → 0.4.0

data/lib/kyanite/general/kernel.rb

@@ -11,7 +11,18 @@ unless defined? RUBYDIR
 end
 
 
-module KyaniteKernel 
+
+
+# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric |  
+# [ ] | Object | *KKernel* | CallerUtils | Undoable | Class | 
+#
+# ---
+#
+#
+# == *General* *Tools*
+#
+#
+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.
@@ -37,7 +48,10 @@ module KyaniteKernel
   
   
   
-  # Quelle: Rails http://api.rubyonrails.org/classes/Kernel.html#M001639
+  
+  # [ ] 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
   def silence_warnings
        old_verbose, $VERBOSE = $VERBOSE, nil
        yield
@@ -46,6 +60,10 @@ module KyaniteKernel
   end    
   
   
+  
+  # [ ] Vereinfacht die require-Statements in den Tests.  
+  # [ ] Wird in allen Kyanite-Tests angewendet, Verwendung siehe dort.  
+  #
   def smart_load_path(__file__ = nil)
     __file__ = caller[0] unless __file__
     dir_caller =File.dirname(__file__)
@@ -76,7 +94,7 @@ module KyaniteKernel
 end # class
 
 class Object
-  include KyaniteKernel
+  include KKernel
 end
 
 

data/lib/kyanite/general/nil.rb

@@ -1,23 +1,46 @@
 
-
-# -----------------------------------------------------------------------------------------
-# Nil  -- hier nur Ruby Core-Methoden!
+# [ | *Kyanite* | Object | Array | Set | Enumerable | Hash | ]    | Kyanite | TrueClass | FalseClass | *NilClass* | Div | 
+#
+# ---
+#
+#
+# == *Transparent* *Nil* 
+# Nil nervt oft. Zwar ist es ein schöner Fehlerindikator 
+# (meist läuft irgendwas schief wenn man es unerwartet mit nil zu tun hat)
+# aber man verunstaltet seinen Quellcode schnell mit Fallunterscheidungen, die den nil-Fall behandeln.
+# 
+# [ ] In Kyanite werden daher zahlreiche Methoden für nil definiert. 
+# [ ] Nil verhält sich damit wie alle anderen Objekte auch.
+# [ ] Man kann immer noch nach Nil fragen, wenn man es möchte, aber man muss es nicht mehr tun!
 #
-
 class NilClass
-  
-    # Spezielle Rückgaben
 
+    # Rückgabe: Array mit dem einen Element
     def <<(element);                    [element];      end     
-    def empty?;                         true;           end      
+    
+    # Rückgabe: true
+    def empty?;                         true;           end 
+
+    # Rückgabe: 0    
     def length;                         0;              end
+    
+    # Rückgabe: 0        
     def size;                           0;              end
+    
+    # Rückgabe: 0        
     def count(*a);                      0;              end
+    
+    # Rückgabe: leeres Array        
     def split(*a);                      [];             end
+    
+    # Rückgabe: false        
     def =~(other);                      false;          end
-    def include?(*a);                   false;          end    # redundante Definition
     
-    # Rückgabe nil
+    # Rückgabe: false     
+    # redundante Definition!    
+    def include?(*a);                   false;          end    
+
+
     def -(other);                       nil;            end    
     def +(other);                       nil;            end    
     def <(*a);                          nil;            end   
@@ -32,12 +55,10 @@ class NilClass
     def downcase;                       nil;            end  
     def dup;                            nil;            end
     def each(*a);                       nil;            end    
-  # def first;                          nil;            end
     def grep(*a);                       nil;            end   
     def gsub!(*a);                      nil;            end   
     def gsub(*a);                       nil;            end   
-    def join;                           nil;            end  
-  # def last;                           nil;            end    
+    def join;                           nil;            end    
     def pop(*a);                        nil;            end 
     def push(*a);                       nil;            end    
     def split(*a);                      nil;            end   
@@ -51,6 +72,7 @@ class NilClass
     def uniq;                           nil;            end   
     def [](*a);                         nil;            end
     def []=(*a);                        nil;            end   
+     
 
 end
 

data/lib/kyanite/general/object.rb

@@ -3,22 +3,39 @@
 $KCODE = 'UTF8' 
 require 'active_support'
 
+
+# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric |
+# [ ] | *Object* | KKernel | CallerUtils | Undoable | Class | 
+#
+# ---
+#
+#
+# == *For* *All* *Objects*
+# [ ] Tests and examples see TestKyaniteObject
+#
+#
 class Object
  
     # <tt> false </tt>    
     #
-    # Test siehe TestTrueFalse#test_blank. 
+    # Tests and examples see TestKyaniteObject    
+    #
     def blank? 
         false
     end     
 
+    
     # Quelle: Facets http://facets.rubyforge.org/quick/rdoc/core/classes/Kernel.html#M000379
+    #
     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.
+    # 
     def deep_copy
       Marshal.load( Marshal.dump( self ) )
     end
@@ -26,7 +43,8 @@ class Object
     
     # Ist ein Objekt numerisch?
     #
-    # Tests & Beispiele siehe TestObject#test_is_numeric
+    # Tests and examples see TestKyaniteObject    
+    #
     def is_numeric?
       Float self 
     rescue Exception => e
@@ -73,8 +91,12 @@ end
 
 class NilClass
  
-  def blank?;                         false;          end     
+  # Rückgabe: false
+  def blank?;                         false;          end    
+
+  # Rückgabe: 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   

data/lib/kyanite/general/true_false.rb

@@ -1,21 +1,34 @@
 
-
+# [ | *Kyanite* | Object | Array | Set | Enumerable | Hash | ]    | Kyanite | *TrueClass* | FalseClass | NilClass | Div | 
+#
+# ---
+#
+# == *True*
+#
+#
 class TrueClass  
      
-  # <tt> 1 </tt>    
+     
+  # Rückgabe: 1     
   def to_i; 1; end
   
-  # <tt> self </tt>   
+  
+  # Rückgabe: self   
   def strip; self; end
   
-  # <tt> self </tt>   
+  
+  # Rückgabe: self  
   def dup; self; end      
   
+  
+  # see TestKyaniteTrueFalse#test_raumschiff_operator for tests  
   def <=>(other)
     return 1 if ! other
     return 0
   end  
   
+  
+  # Rückgabe: false    
   def blank?; false; end
   
   
@@ -24,19 +37,24 @@ end # class
 
 
 
-
+# [ | *Kyanite* | Object | Array | Set | Enumerable | Hash | ]    | Kyanite | TrueClass | *FalseClass* | NilClass | Div | 
+#
+# ---
+#
+# == *False*
+#
 class FalseClass
       
-  # <tt> 0 </tt>    
+  # Rückgabe: 0
   def to_i; 0; end
   
-  # <tt> self </tt>   
+  # Rückgabe: self  
   def strip; self; end  
   
-  # <tt> self </tt>   
+  # Rückgabe: self  
   def dup; self; end    
   
-  # TestTrueFalse#test_raumschiff_operator
+  # see TestKyaniteTrueFalse#test_raumschiff_operator for tests
   def <=>(other)
     return -1 if other
     return 0
@@ -45,7 +63,7 @@ class FalseClass
   
   # umdefiniert!
   #
-  # TestTrueFalse#test_blank  
+  # TestKyaniteObject#test_blank  
   def blank?; self; end
   
 

data/lib/kyanite/general/undoable.rb

@@ -1,21 +1,45 @@
 
+
+# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric | Class | 
+# [ ] | Object | KKernel | CallerUtils | *Undoable* | Class |
+#
+# ---
+#
+#
+# == *Undo* 
+#
+#
 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.
+  #
   def save(method=:dup)
     return if self == @@undoable_history[self.object_id] # nichts zu tun
     @@undoable_history[self.object_id] = self.send(method)
   end
 
+  
+  # [ ] Rückgriff auf den gespeicherten Zustand eines Objektes.
+  # [ ] Der gespeicherte Zustand verbleibt im Speicher.
+  # 
   def load_and_keep
     @@undoable_history[self.object_id]
   end
   
+  
+  # [ ] Rückgriff auf den gespeicherten Zustand eines Objektes.
+  # [ ] Der gespeicherte Zustand wird verworfen. 
+  #   
   def load_and_delete
     @@undoable_history.delete(self.object_id)
   end  
   
+  
+  # Verwirft alle gepeicherten Objektzustände.
+  #
   def self.clear
     @@undoable_history.clear
   end

data/lib/kyanite/hash.rb

@@ -7,67 +7,76 @@ class Hash
   include ActiveSupport::CoreExtensions::Hash::Slice
 end
 
-#
-# Aus {Facets/Hash}[http://facets.rubyforge.org/api/core/classes/Hash.html] eingefügt:
-# * *reverse_merge*      <tt>(other_hash) </tt>        Beispiel: <tt>options.reverse_merge!(:key => default_value)</tt>
+
+
+
+# [ | Kyanite | Object | Array | Set | Enumerable | *Hash* | ]     | *Hash* |  Dictionary |
+# ---
 #  
 #
-# ==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
+# == *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
+#
+#
+# Aus {Facets/Hash}[http://facets.rubyforge.org/doc/api/core/classes/Hash.html] eingefügt:
+# [ ] *reverse_merge*(other_hash)
+# [ ] Beispiel: <tt>options.reverse_merge!(:key => default_value)</tt>
+#  
 #
 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.
+  
+    # [ ] 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.
+    # [ ] 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
 
 
  
-  # Entfernt alle Key-Value-Paare mit <b>nil-Keys</b> in-place.
-  #
-  # Tests: TestHash#test_delete
+  # [ ] Entfernt alle Key-Value-Paare mit <b>nil-Keys</b> in-place.
+  # [ ] Tests: TestHash#test_delete
   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
+  # [ ] Entfernt alle alle Key-Value-Paare mit <b>nil-Values</b> in-place.
+  # [ ] Tests: TestHash#test_compact
   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! ).
+  # [ ] 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! ).
   def delete_key(key)
     delete_if { |k,v| k == key }
   end        
   
-  # Entfernt alle Key-Value-Paare mit einem bestimmten Value in-place.
+  # [ ] Entfernt alle Key-Value-Paare mit einem bestimmten Value in-place.
   #     
   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:<tt>    inputoptions = options.arrayize(:skip, :debug)  </tt>
+  # [ ] erzwingt ein Array der Länge 1, wenn sowohl Einzelwerte als auch Arrays erlaubt sind. 
+  # [ ] Beispiel:
+  #   inputoptions = options.arrayize(:skip, :debug)  
   # 
   def arrayize(*keys)
     keys.each do |k|
@@ -80,7 +89,8 @@ class Hash
   end
   
   
-  # Greift auf den Hash mit nicht-ganz-passenden Schlüsseln zu
+  # [ ] Greift auf den Hash mit nicht-ganz-passenden Schlüsseln zu
+  #
   def fuzzyget(key, level = 3)
     try = self[key]
     return try    if try  ||  level <= 0
@@ -91,8 +101,11 @@ class Hash
   end    
 
   
-  # Liefert die Verteilung der Size / Class / etc. aller Values. 
-  # Die Keys werden ignoriert.
+  # [ ] 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.
   #
   def distribution( mode = :size)
     verteilung = Hash.new
@@ -108,7 +121,8 @@ class Hash
   end  
   
   
-  # liefert irgendein Value  
+  # [ ] liefert irgendein Value  
+  #
   def first
     self.each do |key, value|
       return value
@@ -116,7 +130,8 @@ class Hash
   end #def
   
   
-  # liefert irgendein anderes Value  
+  # [ ] liefert irgendein anderes Value  
+  #
   def last
     first = nil
     self.each do |key, value|
@@ -148,7 +163,7 @@ end
     
     
     
-    # ---------------------------------------------------------
+# ---------------------------------------------------------
 # Ausprobieren
 #
 if $0 == __FILE__