kyanite 0.6.1 → 0.7.0

data/lib/kyanite/enumerable/enumerable_strings.rb

@@ -1,24 +1,20 @@
-# ruby encoding: utf-8 
+# ruby encoding: utf-8
 # ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 
-# [ | Kyanite | Object | Array | Set | *Enumerable* | Hash | ]     | Enumerable | EnumerableNumerics | *EnumerableStrings* | EnumerableEnumerables | 
-# ---
-#
-#
-# == *Enumeration* *Of* *Strings*
-# See TestKyaniteEnumerableStrings for tests and examples.
-# See ArrayOfStrings for an Array with modul EnumerableStrings included. 
-#
-# 
-module EnumerableStrings
 
 
-  # Bsp.: 
+# @!macro enum_of_strings
+module EnumerableStrings
+
+  # Delete every element from the front with is identical with the back -- leave the significant middle part.
+  # Example: 
   #  ['lut', 'lutm', 'lutmi', 'lutmil', 'lutmila', 'lutrika', 'lutrik', 'lutri', 'lutr', 'lut'].palindrom_rumpf  =>
   #  ['lutm', 'lutmi', 'lutmil', 'lutmila', 'lutrika', 'lutrik', 'lutri', 'lutr']
-  # d.h. vorne und hinten wird alles Gleiche weggestrichen.
-  #
-  # Tests and examples see TestKyaniteEnumerableStrings.
   #
   def palindrom_rumpf
     result = self.dup
@@ -38,26 +34,23 @@ end
 
 
 
-# [ | Kyanite | Object | *Array* | Set | Enumerable | Hash | ]     | Array |  ArrayOfNumerics  | *ArrayOfStrings* |  ArrayOfEnumerables | Range |  
-# ---
-#
-#
-# == *Array* *Of* *Strings*
-# An ArrayOfstrings is an Array with modul EnumerableStrings included. 
-# See TestKyaniteEnumerableStrings for tests and examples.
-#
+
+# @!macro enum_of_strings
 class ArrayOfStrings < Array
   include EnumerableStrings
 end
 
-
+  
 
 class Array
 
-  # Liefert ein ArrayOfStrings (das ist ein Array mit inkludiertem Modul EnumerableStrings)
+  # @!group Cast
+  # Returns {ArrayOfStrings} (this is an {Array} with modul {EnumerableStrings} included)
+  # @return [ArrayOfStrings]
   def to_array_of_strings
     ArrayOfStrings.new(self)
   end
+  #@!endgroup
   
 end
 

data/lib/kyanite/enumerable/structure.rb

@@ -1,10 +1,11 @@
 # ruby encoding: utf-8
-# ü
+
 if $0 == __FILE__ 
-  require File.join(File.dirname(__FILE__), '..', '..', '..', 'smart_load_path.rb' )
-  smart_load_path   
+  require 'drumherum'
+  smart_init
 end
 
+
 require 'kyanite/general/object'
 require 'kyanite/array/array'
 require 'kyanite/dictionary' 
@@ -14,73 +15,63 @@ require 'kyanite/dictionary'
 
 class Object
 
-  # Enthält ein Objekt mehrere Objekte?
-  # String und Range gelten nicht als Collection.
-  # See TestKyaniteEnumerableStructure for tests and examples.
+  # @!macro [new] is_collection
+  #  -- Defined for all objects: Do I contain multiple objects? {String} and {Range} are not considered as collection.
+  # 
+  #  Tests and examples {TestKyaniteEnumerableStructure#test_is_collection here}.
+  
+  # +false+  
+  # @!macro is_collection  
+  # @return [false]
   def is_collection?;                 false;          end
   
 end
 
 
-module Enumerable
+class Range 
 
-  # Enthält ein Objekt mehrere Objekte?
-  # Rückgabe: true  
-  # String und Range gelten nicht als Collection.
-  # See TestKyaniteEnumerableStructure for tests and examples.
-  def is_collection?;                 true;          end
+  # +false+  
+  # @!macro is_collection  
+  # @return [false]
+  def is_collection?;                 false;          end
   
 end
 
 
-class String 
 
-  # ---------------------------------------------------------------------------------------------------------------------------------
-  # :section: Structure
-  #  
+class String 
 
-  # Enthält ein Objekt mehrere Objekte?
-  # Rückgabe: false  
-  # String und Range gelten nicht als Collection.
-  # See TestKyaniteEnumerableStructure for tests and examples.
+  # @!group Miscellaneous
+  # +false+  
+  # @!macro is_collection  
+  # @return [false]
   def is_collection?;                 false;          end
-  
-  
+  # @!endgroup   
 end
 
 
-class Range 
-
-  # Enthält ein Objekt mehrere Objekte?
-  # Rückgabe: false  
-  # String und Range gelten nicht als Collection.
-  # See TestKyaniteEnumerableStructure for tests and examples.
-  def is_collection?;                 false;          end
+  # @!group Structure Reflection
   
-end
-
+module Enumerable
 
+  # @!macro is_collection
+  # +true+  
+  # @!macro is_collection  
+  # @return [true]
+  def is_collection?;                 true;          end
+  
+end  
 
 
 
 
 
-# [ | Kyanite | Object | Array | Set | *Enumerable* | Hash | ]     | *Enumerable* | EnumerableNumerics | EnumerableStrings | EnumerableEnumerables | 
-# ---
-#
-#
-# == *General* *Enumerations*
-# See TestKyaniteEnumerableStructure for tests and examples.
-#
-# 
+# @!macro enumerable
 module Enumerable
 
-  # Liefert die Verteilung der size 
-  # oder die Verteilung der class 
-  # oder die Verteilung eines anderen Merkmals der aufgezählten Elemente.
-  # die Methode gibt es auch als Hash#distribution.  
-  # See TestKyaniteEnumerableStructure  for tests and examples.
-  #
+  # Returns the distribution of +size+, +class+ or any other characteristics of the enumerated elements.
+  # See also {Hash#distribution}. Tests and examples {TestKyaniteEnumerableStructure#test_distribution_class here}.
+  # @return [Array]
   def distribution( mode = :size)
     verteilung = Hash.new
     each do | element |
@@ -96,20 +87,17 @@ module Enumerable
   
   
   
-  
-
-  
-  # Was für Objekte beinhaltet die Collection?
-  # Liefert die Klasse der Contentelemente, oder <tt>Object</tt> wenn es verschiedene sind. 
-  #  
-  # Parameter ist die Genauigkeit, mit der der Inhalt geprüft wird.
-  #  :precision  => 1      nur das erste Element wird geprüft
-  #  :precision  => 2      das erste und das letzte Element werden geprüft   (STANDARD)
-  #  :precision  => :all   alle Elemente werden geprüft
-  #  :ignore_nil => true   NilClass wird nicht aufgeführt                    (STANDARD)
-  #  :ignore_nil => false  NilClass wird mit aufgeführt  
+  # What kind of objects contains the collection?
+  # Returns the class of content elements, or +Object+ if there are several.
+  #
+  # Parameters is the accuracy with which the content is checked.  
+  # [:precision  => 1]      only the first element is checked
+  # [:precision  => 2]      the first and the last elements are checked      (STANDARD)
+  # [:precision  => :all]   every element is checked
+  # [:ignore_nil => true]   NilClass will not be listed                      (STANDARD)
+  # [:ignore_nil => false]  NilClass will be listed  
   #
-  # See TestKyaniteEnumerableStructure  for tests and examples.
+  # Tests and examples {TestKyaniteEnumerableStructure#test_contentclass_mono here}.
   #
   def contentclass( options={} )
     precision  = options[:precision]    || 2

data/lib/kyanite/general/callerutils.rb

@@ -1,30 +1,31 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 require 'kyanite/string/include'
 
 
 
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric |  
-# [ ] | Object | KKernel | *CallerUtils* | Undoable | Class |
-#
-# ---
-#
-#
-# == *Tools* *for* Kernel#caller
-#
+
+# @!macro caller_utils
 class CallerUtils
 
-  # Untersucht den Call-Stack. Liefert die Größe des Stacks oder den letzten Eintrag.
+  # Examines the call stack, returns the size of the stack, or the last caller.
+  # @param options [Hash] Options
+  # @option options [String, Array] :skip Ignore caller that contain the specified fragment 
+  # @option options [Symbol] :mode What kind of result is to be returned? +:caller+ (default) returns the caller, +:size+ returns the size of the call stack.
   #
-  # Options: 
-  #   :skip    Ignoriere caller, die das angegebene Fragment enthalten   (String oder Array)
-  #   :mode    Welche Art von Ergebnis soll geliefert werden? 
-  #            :caller (Standard) liefert den Caller, 
-  #            :size liefert die Größe das Call-Stacks
+  # Example:
+  #  CallerUtils.mycaller(:skip => ['ruby\gems', 'ruby/gems', 'test/unit']) 
+  #  => "C:/Ruby-Projekte/kyanite/lib/kyanite/general/callerutils.rb:110:in `<main>'"
   #
-  # Beispiel:        
-  #  CallerUtils.mycaller(:skip => ['perception', 'ruby\gems', 'ruby/gems', 'test/unit'])
-  #  => "R:/_Eigene_Projekte_unter_SVN/kyanite/lib/kyanite/general/callerutils.rb:100"
-  #       
+  #  CallerUtils.mycaller(:skip => ['ruby\gems', 'ruby/gems', 'test/unit'], :mode=> :size) 
+  #  => 1
+  #     
+  # @return [String, Integer]
   def self.mycaller(options={})
     skip = options[:skip] || []
     skip = [skip]   if skip.kind_of?(String)
@@ -53,14 +54,14 @@ class CallerUtils
 
 
   
-  # Ermittelt das Hauptverzeichnis eines Callers auf heuristischem Wege.
-  # Der Name des Hauptverzeichnisses entspricht meist dem Namen der Applikation oder Library.
-  #
-  # Beispiel:
-  #   my_caller  = CallerUtils.mycaller(:skip => ['perception', 'ruby\gems', 'ruby/gems', 'test/unit']) 
+
+  # Determines the root directory of a caller on heuristic way. The name of the main directory is usually the name of the application or library.
+  # Example:
+  #   my_caller  = CallerUtils.mycaller(:skip => ['ruby\gems', 'ruby/gems', 'test/unit']) 
   #   CallerUtils.mycaller_maindir(my_caller)           
-  #   => "R:/_Eigene_Projekte_unter_SVN/kyanite"
+  #   => "C:/Ruby-Projekte/kyanite"
   #
+  # @return [String]  
   def self.mycaller_maindir(mycaller)
     dir_caller =File.dirname(mycaller)
     array_caller = dir_caller.split('/')
@@ -109,10 +110,11 @@ if $0 == __FILE__
            
            
            
-        require 'pp'
-        my_caller  = CallerUtils.mycaller(:skip => ['perception', 'ruby\gems', 'ruby/gems', 'test/unit']) 
-        my_maindir = CallerUtils.mycaller_maindir(my_caller)            if my_caller
-        pp my_maindir
+
+my_caller  = CallerUtils.mycaller(:skip => ['ruby\gems', 'ruby/gems', 'test/unit']) 
+#puts my_caller  
+puts CallerUtils.mycaller_maindir(my_caller)            if my_caller
+
 
 
 

data/lib/kyanite/general/classutils.rb

@@ -1,26 +1,34 @@
 # ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+end
+
 
-require 'facets/kernel/singleton_class'     # Easy access to an object‘s "special" class, otherwise known as it‘s eigen or meta class.
-require 'facets/class/descendants'          # Methode   descendants 
+# @!group Class Utils
 
+require 'facets/class/descendants'          # Methode descendants 
+# require 'facets/kernel/singleton_class'     # Easy access to an object‘s "special" class, otherwise known as it‘s eigen or meta class.
 
-# [ | Kyanite | *Object* | Array | Set | Enumerable | Hash | ]     | *Object* | String | Symbol | Numeric | 
-# [ ] | Object | KKernel | CallerUtils | Undoable | *Class* | 
+# =================================================================================================================
 #
-# ---
+# @!macro class_utils
 #
-# == *Class* *Utils*  
-# See TestKyaniteClassutils for tests and examples.
+# === Added from  {http://rubyworks.github.com/rubyfaux/?doc=http://rubyworks.github.com/facets/docs/facets-2.9.3/core.json#api-class-Class Facets Class}:  
+# [+descendants(generations=-1))+] List all descedents of this class.
 #
 class Class
   
-  # Vergleichsoperator: Alphabetisch. 
+  # Comparison operator (alphabetical)
+  # @return [Integer] 1, 0, -1
   def <=>(other) 
       ( ( self.to_s ) <=> ( other.to_s ) )
   end   
   
   
-  # Unscharfer Vergleich zweier Klassen, z.B. für Tests
+  # Fuzzy comparison of two classes (useful for tests)
+  # @return [Boolean] 
   def =~(other)
     return true   if self == other
     return true   if self.descendants.include?(other)
@@ -28,21 +36,13 @@ class Class
     return false
   end  
 
-  # Die Methode to_class wandelt einen Klassennamen in eine Klasse.
-  # Die Methode gibt es insbesondere für String und Symbol, siehe String#to_class, Symbol#to_class  
-  # Für Class ist sie einfach transparent, d.h. sie liefert self.   
-  # Tests and examples see TestKyaniteClassutils
-  # 
+  # (see String#to_class)
   def to_class 
     self
   end     
 
   
-  # Gegenstück zu to_class: 
-  # Wandelt eine Klasse in einen Klassennamen um, der nur Kleinbuchstaben enthält.
-  # Siehe String#to_classname, Symbol#to_classname
-  # Tests and examples see TestKyaniteClassutils
-  #
+  # (see String#to_classname)
   def to_classname
     self.to_s.demodulize.underscore
   end         
@@ -52,58 +52,32 @@ end # class
 
 
 
-
-  
-class Symbol
-
-  # Wandelt ein Symbol in einen Klassennamen, der nur Kleinbuchstaben enthält. 
-  # Siehe String#to_classname     
-  # Tests and examples see TestKyaniteClassutils
-  #
-  def to_classname 
-      self.to_s.to_classname
-  end
-
-  # Wandelt einen Klassennamen in eine Klasse.
-  # Akzeptiert sowohl CamelCase als auch down_case.
-  # Die Methode gibt es auch für String und Class.
-  # Tests and examples see TestKyaniteClassutils
-  #
-  def to_class 
-      self.to_s.to_class
-  end   
-
-end # class 
+ 
 
 
+class String
 
 
-  
- 
-  
-class String  
 
-  # ---------------------------------------------------------------------------------------------------------------------------------
-  # :section: Class Utils
-  # See TestKyaniteClassutils for tests and examples.
-  #  
-
-
-  # Wandelt einen String in einen Klassennamen, der nur Kleinbuchstaben enthält. 
-  #   'MeinModul::EineKlasse'  =>  'eine_klasse'
+  # Converts to a class name , the reverse of {String#to_class to_class}.
   #
-  # Tests and examples see TestKyaniteClassutils
+  # classes {Class}, {Symbol}, {String}. The class name will contain only lowercase letters.
+  #   'MyModul::MyClass'  =>  'my_class'
+  #
+  # Tests and examples {TestKyaniteClassutils here}.
+  # @return [String]
   #
   def to_classname
       self.demodulize.underscore
   end
   
   
-
-  # Wandelt einen Klassennamen in eine Klasse.
-  # Akzeptiert sowohl CamelCase als auch down_case.
-  # Die Methode gibt es auch für Symbol und Class.
-  # Tests and examples see TestKyaniteClassutils
+  # Converts to a class, the reverse of {String#to_classname to_classname}
+  #
+  # Defined for classes {Class}, {Symbol}, {String}. Accepts both CamelCase and down_case.
+  #
+  # Tests and examples {TestKyaniteClassutils here}.
+  # @return [Class]
   #
   def to_class
       self.camelize.constantize
@@ -122,6 +96,7 @@ class String
   #   "ActiveRecord::Errors".underscore # => active_record/errors
   # From ActiveSupport, Copyright (c) 2005 David Heinemeier Hansson. See License.txt.  
   #  
+  # @return [String]  
   def underscore
     self.gsub(/::/, '/').
       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -144,6 +119,7 @@ class String
   #   "active_record/errors".camelize(:lower) # => "activeRecord::Errors"
   # From ActiveSupport, Copyright (c) 2005 David Heinemeier Hansson. See License.txt.   
   #  
+  # @return [String]  
   def camelize(first_letter_in_uppercase = true)
     if first_letter_in_uppercase
       self.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
@@ -160,6 +136,7 @@ class String
   #   "Inflections".demodulize                                       # => "Inflections"
   # From ActiveSupport, Copyright (c) 2005 David Heinemeier Hansson. See License.txt.   
   #  
+  # @return [String]  
   def demodulize
     self.gsub(/^.*::/, '')
   end  
@@ -185,6 +162,7 @@ class String
   # unknown.
   # From ActiveSupport, Copyright (c) 2005 David Heinemeier Hansson. See License.txt.   
   #
+  # @return [Class]  
   def constantize
     unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ self
       raise NameError, "#{self.inspect} is not a valid constant name!"
@@ -193,14 +171,46 @@ class String
     Object.module_eval("::#{$1}", __FILE__, __LINE__)
   end
   
-end # class  
+end # String
+
+
+
+
+
+
 
-if defined? TransparentNil
+# =================================================================================================================
+#
+# @!macro class_utils  
+#
+class Symbol
+
+  # (see String#to_classname)
+  def to_classname 
+      self.to_s.to_classname
+  end
+
+  # (see String#to_class)
+  def to_class 
+      self.to_s.to_class
+  end   
+
+end # Symbol 
+
+
+
+
+
+  # =================================================================================================================
+  # @!macro class_utils
+  #
   class NilClass
 
-    # Rückgabe: Leerer String  
+    # @return [String] empty String 
     def to_classname;             '';                   end  
 
+    # @!group return nil   
+    
     def camelize;                 nil;                  end 
     def constantize;              nil;                  end 
     def demodulize;               nil;                  end 
@@ -208,7 +218,7 @@ if defined? TransparentNil
     def underscore;               nil;                  end 
 
   end
-end
+