perception 0.3.4 → 0.3.5

data/lib/perception/logging.rb

@@ -28,6 +28,7 @@ module Perception
     #    @logdev =            #<Logger::LogDevice:0x2a57c60  @dev=#<File:C:/Ruby-Projekte/perception/log/see.log>,  @filename='C:/Ruby-Projekte/perception/log/see.log',  @mutex=#<<>>,  @shift_age=0,  @shift_size=1048576>,
     #    @progname =          nil>
     #
+    # More: {Object#log log}, {Object#rawlog rawlog}    
     # @return [Logger]
     #
     def logger( logdir=nil, filename='see.log' )
@@ -107,7 +108,12 @@ end # module
 
 class Object
 
-  # Same as method see, but outputs in logfile only
+  # Same as method see, but outputs in logfile only.
+  #
+  # If you want to use both logfile and console , use
+  #   seee.out << :log
+  #
+  # More: {Object#rawlog rawlog}, {Perception::SeeSession#logger seee.logger}  
   def log(input=:kein_input, *rest)
     out_bak = seee.out.dup
     seee.out=[:log]
@@ -121,7 +127,9 @@ class Object
   end    
   
   
-  # raw output into logfile
+  # raw output into logfile without formating.
+  #
+  # More: {Object#log log}, {Perception::SeeSession#logger seee.logger}  
   def rawlog(input='')
     seee.logger << (input)       
     nil

data/lib/perception/numeric.rb

@@ -10,13 +10,15 @@ end
 
 module Perception 
 
+
  module NumericI 
  
     # ------------------------------------------------------------------------------
-    # @group Slash needless digits
+    # @group Intelligent round: slash needless digits
     #   
     
-    # Slash needless digits.
+    # Intelligent round: slash needless digits. 
+    # Specify only the significant digits so that the magnitude can be easily realised.
     # Needless are digits that are
     # * beyond the measurement precision or
     # * not perceived by humans (instead they disturb the reception)    
@@ -43,6 +45,7 @@ module Perception
     #
     # @return [Numeric]
     # @param [Integer] precision How many digits are significant?
+    #
     def significant( precision = 3)
     
         # sprintf mit gemischter Schreibweise
@@ -81,24 +84,56 @@ module Perception
     # @group Easily human readable numbers
     #    
     
-    # Formatiert eine Zahl so, dass sie leicht menschenlesbar wird: 
-    # - Quasi-rechtsbündig (mit dem Komma als Bezugspunkt, abhängig von der Klassenzugehörigkeit der Zahl)
-    # - vorangestellte Währungszeichen oder angefügte Einheiten, ohne die Bündigkeit zu zerstören    
-    # - intelligente Ausweichstrategie, wenn der vorgegebene Platz nicht ausreicht
-    # - nur die signifikanten Stellen werden angegeben, damit die Größenordnung leicht erfasst werden kann
-    # - Tausendertrennzeichen wenn nötig
+    # Formats a number for easily human readability.
+    # Example: (using +.inspect_see+ without options)
+    #      input    (barrier)    output   (barrier)    note
+    #  -------------------------------------------------------------------------------------------------------    
+    #       -7213541 ########-7 210 000    ########   Intelligent fallback strategy if space is not sufficient
+    #        7213541 ########7 210 000     ########
+    #        -553337 ######## -553 000     ########
+    #         553337 ########  553 000     ########   Intelligent round: slash needless digits
+    #      -12567.89 ########  -12 600     ########
+    #       12567.89 ########   12 600     ########   Thousands separator only if necessary
+    #      -1256.789 ########    -1260     ########
+    #       1256.789 ########     1260     ########
+    #     -123.56789 ########     -124     ########
+    #      123.56789 ########      124     ########
+    #         100.01 ########      100     ########
+    #           12.0 ########       12     ########
+    #             12 ########       12     ########
+    #      -12.56789 ########      -12.6   ########
+    #       12.56789 ########       12.6   ########
+    #      -1.256789 ########       -1.26  ########
+    #       1.256789 ########        1.26  ########
+    #     -0.1256789 ########       -0.126 ########
+    #      0.1256789 ########        0.126 ########
+    #    -0.01256789 ########       -0.0126########
+    #     0.01256789 ########        0.0126########
+    #   -0.001256789 ########      -0.00126########
+    #    0.001256789 ########       0.00126########
+    #  -0.0001256789 ########     -0.000126########
+    #   0.0001256789 ########      0.000126######## 
+    #
+    # Features:
+    # * aligned right with the separator as reference point
+    # * you can preced a currency symbol or append units, without destroying the alignment
+    # * intelligent fallback strategy if the predetermined space is not sufficient
+    # * thousands separator if necessary, and only if necessary
+    # * only the significant digits are specified so that the magnitude can be easily realised (see {#significant})   
     #
-    # Optionen sind:
-    # * :precision   Wieviel signifikante Stellen sollen ausgegeben werden? Default: 3
-    # * :space_l     Wieviel Platz wird vor dem Komma eingeplant? 
-    # * :space_r     wie :space, bezieht sich aber nur auf den Nachkommateil. Wird abhängig davon vorbelegt, ob self Integer oder Float ist.
-    # * :separator   Kommazeichen 
-    # * :delimiter   Tausendertrennzeichen
-    # * :pre         wird direkt vor der Zahl ausgegeben  (z.B. €)
-    # * :past        wird direkt nach der Zahl ausgegeben (z.B. %)      
+    # If you don't need alignment and thousands separator, use {Perception::NumericI#significant significant} instead.        
+    # See {http://de.wikipedia.org/wiki/Wikipedia:Schreibweise_von_Zahlen Schreibweise von Zahlen}.
+    #
+    # @return [String]
+    # @param [Hash] options
+    # @option options [Integer] :precision how many digits are significant? Default: 3
+    # @option options [Integer] :space_l space before the separator as reference point 
+    # @option options [Integer] :space_r space behind the separator. Default depends on class (Integer or Float).
+    # @option options [Char] :separator separator
+    # @option options [Char] :delimiter  thousands separator 
+    # @option options [String] :pre preceding string (e.g. a currency symbol) 
+    # @option options [String] :past appended string (e.g. a unit) 
     #
-    # Für eine schlichte linksbündige Ausgabe reicht die Methode #significant!               
-    # vgl. http://de.wikipedia.org/wiki/Wikipedia:Schreibweise_von_Zahlen
     #
     def inspect_see(options={})
       precision =         options[:precision]   ||  3
@@ -106,7 +141,7 @@ module Perception
       past  =             options[:past]        ||  ''      
       space_l =           options[:space_l]     ||  9 + pre.size  
       space_r =           options[:space_r]     ||  (self.kind_of?(Integer) ?  (0+past.size) : (5+past.size))    # Integer oder Float?
-      separator =         options[:separator]   ||  ','
+      separator =         options[:separator]   ||  '.'
       delimiter  =        options[:delimiter]   ||  ' '
 
       
@@ -173,7 +208,7 @@ if $0 == __FILE__  &&  Drumherum::loaded? then
 
   # Hier einstellen, was laufen soll
   $run = :try1
-  #$run = :try2
+  $run = :try2
   #$run = :tests
   #$run = :demo
   
@@ -197,11 +232,14 @@ if $0 == __FILE__  &&  Drumherum::loaded? then
     
   when :try2 #-------------------------------------------------------------------------------      
     
+    seee.out << :log    
     test = [7213541, 553337, 12567.89, 1256.789, 123.56789, 100.01, 100.0, 99.9, 12.0, 12, 12.56789, 1.256789, 1.5, 0, 0.1256789,0.01256789,0.001256789,0.0001256789, ]
     test.each do |t|
       t = t*-1    
+      see_print "#"
       see_print t.to_s.rjust(15) +      ' ########'     + t.to_f.inspect_see + "########\n"  
       t = t*-1
+      see_print "#"      
       see_print t.to_s.rjust(15) +      ' ########'     + t.to_f.inspect_see + "########\n"  
     end    
     

data/lib/perception/perception_main.rb

@@ -17,22 +17,27 @@ require 'kyanite/enumerable/structure'   # Methode contentclass
 
   
 
-# Perception: Human perceptible printouts
-# ========================================
+# = Perception: Human perceptible printouts
 #
 # Welcome to Perception. It's a intuitive toolkit for simple everyday debugging. 
-# Perception offers a powerfull replacement for print, puts and pp.
+# Perception offers a powerfull replacement for print, puts and pp 
+# and is an alternative to {https://github.com/michaeldv/awesome_print Awesome Print}.
+#
 # You get auto-intended and structured output on your console without any configuration.
+#
 # Perception also offers temporary printouts (overwritten by the next print),
 # printing two informations in one line without destroying the structure and
 # optionally slows down printing to readable speed, depending on the complexity of the output.
 #
 module Perception 
   
-  # Eine SeeSession-Instanz entspricht einer Session mit der Konsole.
+  # An instance of SeeSession corresponds to a session with the console.
   class SeeSession  
+  
+    # @group Automatic Indenting
     
     # Turns automatic indention ON. 
+    # @return void
     def indent!
       @indent           = true
       @level            = SEE_LEVEL_START
@@ -42,7 +47,8 @@ module Perception
     end
     
     
-    # Turns automatic indention OFF.    
+    # Turns automatic indention OFF.  
+    # @return void
     def left!
       @indent           = false
       @level            = SEE_LEVEL_START
@@ -50,10 +56,46 @@ module Perception
       @call_stack_now   = 0 
       nil
     end    
+    
+    # @group Slowing down
+
+    # Slows down output to readable speed. 
+    # The speed depends on the length and the complexity of the printing.
+    # You can adjust the speed with the parameter:
+    # * slow! 1    -->  same as slow!
+    # * slow! 2    -->  slow, but double speed
+    # * slow! 0.5  -->  even slower 
+    # * slow! nil  -->  full speed (same as fast!)
+    # @return void
+    # @param [Float] speed 
+    def slow!(speed=1)
+      @speed = speed  
+      nil
+    end  
 
     
+    # Adjusts printing speed to full speed.
+    # This is used after slow!
+    # @return void    
+    def fast!
+      @speed = nil 
+      nil
+    end      
+
+    # @group Simple Benchmarking    
+    
+    # @return [Float] the time in seconds since the last printout with see.
+    def bench
+      return 0 unless @time_last
+      return (Time.now - @time_last)   
+    end    
+    
+    
+    # @group Progress Indicator   
+    
     # Undos the last print. 
     # Note: Indention will get lost.
+    # @return void      
     def clear!     
       return if @cursor_now <= SEE_TAB_WIDTH * @level    
       return if @string_last.empty?
@@ -71,41 +113,16 @@ module Perception
     
     # Marks the last print as temporary.
     # The following print will overwrite it. 
-    # Note: Indention will get lost.    
+    # Note: Indention will get lost.  
+    # @return void  
     def temp! 
       @delayed_clear = true   
       nil
     end        
   
     
-    # Slows down output to readable speed. 
-    # The speed depends on the length and the complexity of the printing.
-    # You can adjust the speed with the parameter:
-    # * slow! 1    -->  same as slow!
-    # * slow! 2    -->  slow, but double speed
-    # * slow! 0.5  -->  even slower 
-    # * slow! nil  -->  full speed (same as fast!)
-    def slow!(speed=1)
-      @speed = speed  
-      nil
-    end  
-
-    
-    # Adjusts printing speed to full speed.
-    # This is used after slow!
-    def fast!
-      @speed = nil 
-      nil
-    end      
-
-    
-    # Returns the time in seconds since the last #see-printout. 
-    def bench
-      return 0 unless @time_last
-      return (Time.now - @time_last)   
-    end    
+    # @group Two layers of information in one line       
 
-    
     # Shows two informations in one line. See the demo.
     #
     # Via seee.flash! können zwei Informationen abwechselnd in der gleichen Zeile angezeigt werden.
@@ -114,6 +131,7 @@ module Perception
     # Ohne Angabe eines Zweittextes wird der Ersttext einfach zum Blinken gebracht. Nachträglich, also wenn er schon ausgegeben ist.
     # Das ist sehr nützlich, wenn man bestimme Werte verfolgen will.  
     #
+    # @return void      
     def flash!(alternativtext=' ', how_many=6)
       string_bak = @string_last.dup
       method_bak = @method_last    
@@ -149,6 +167,8 @@ class Object
 #  Wrapper for SeeSession
 #  
   
+  # @group Main methods  
+  
   # Returns the SeeSession-Object. Offers the following methods: 
   # * seee.indent!
   # * seee.left!
@@ -159,12 +179,34 @@ class Object
   # * seee.flash!
   # * seee.bench
   #
+  # @return [Perception::SeeSession]
   def seee
     return Perception::SeeSession.instance
   end  
   
+
+
   
-  # This is the main method. It prints out objects. See the demo.
+  # You get auto-intended and structured output on your console without any configuration. 
+  # Usage:
+  #   require 'perception'
+  # and use +see+ instead of +pp+, +puts+, +print+ and +.inspect+.
+  #
+  # This is the printout for a nested hash as example:
+  #  {:hash        =>  true,
+  #   :init        =>  true,
+  #   :nil         =>  nil,
+  #   :symbol      =>  :symbol,
+  #   :text        =>  'text',
+  #   :array       =>  [1,  2,  3],
+  #   :integer     =>  1,
+  #   :string      =>  'hallo',
+  #   :nochn_hash  =>  {:key=>:value,  :bla=>:blubb,  :array=>[:a, :b, :c],  :another_key=>'another value'}}  
+  #
+  # See more examples at {file:demo/Example_Output_1.rb} and {file:demo/Example_Output_2.rb} 
+  # or watch the interactive demo at {file:demo/demo3.rb}.
+  #
+  # @return [String]
   def see(input=:kein_input, *rest)
 
     if input == :kein_input  
@@ -181,6 +223,7 @@ class Object
   end # def
   
   
+  # @private
   def see_each(input)
     if self.contentclass == Array
       see_puts '['
@@ -190,11 +233,12 @@ class Object
     input.each {|elt| see elt}     
   end
   
-
+    # @group Several variants of see
 
   # Like see, but temporary print. 
   # The following print will overwrite it. 
-  # Note: Indention will get lost.      
+  # Note: Indention will get lost. 
+  # @return [String]
   def see_temp(input=:kein_input)
     if input == :kein_input  
       seee.delayed_newlines += 1   
@@ -206,6 +250,7 @@ class Object
   
   
   # Shows two informations in one line. See the demo.
+  # @return [String]  
   def see_flash(input=:kein_input, alternativtext=' ', times=6)
     if input == :kein_input  
       seee.delayed_newlines += 1   
@@ -218,7 +263,8 @@ class Object
   
   # Like see, but forces behavior like the originally puts method. 
   # So you get a newline after every print.
-  # Note: All newlines are delayed. This offers you to undo the print.    
+  # Note: All newlines are delayed. This offers you to undo the print.   
+  # @return [String]
   def see_puts(input=:kein_input)
     if input == :kein_input  
       seee.delayed_newlines += 1   
@@ -231,12 +277,14 @@ class Object
   # Like see, but forces behavior like the originally print method.  
   # So you have fully control over your newlines. 
   # Note: If you use "\n", #see will indent it. See SEE_LEVEL_START.
+  # @return [String]  
   def see_print(input=$_)
     return seee.process_print( input, :method => :print )
   end
   
   
-  # Like see, but forces behavior like the originally pp method.   
+  # Like see, but behavior similar to the originally pp method.   
+  # @return [String]  
   def see_pp(input=:kein_input)
     if input == :kein_input  
       seee.delayed_newlines += 1   
@@ -247,6 +295,7 @@ class Object
   
   
 
+  # @endgroup 
   
   
 

data/lib/perception/perception_private.rb

@@ -12,9 +12,12 @@ end
 module Perception 
 
   
-  # Eine SeeSession-Instanz entspricht einer Session mit der Konsole.
+
+  
   class SeeSession
     @@instance = nil
+    
+    # @private
     attr_accessor :time_last, :delayed_newlines, :level, :indent, :out
     
     # ------------------------------------------------------------------------------
@@ -22,6 +25,7 @@ module Perception
     #    
     
     # Liefert die eine notwendige Instanz 
+    # @private
     def self.instance
         return @@instance   if @@instance
         @@instance = SeeSession.new
@@ -29,11 +33,12 @@ module Perception
     end
     
     
+    # @private    
     def initialize
       init
     end
     
-    
+    # @private    
     def init
       # früher
       @string_last        = ''                # enthält den letzten ausgegebenen String (damit man ihn löschen und wiederherstellen kann)
@@ -67,6 +72,7 @@ module Perception
     #  Ausgeben
     #      
     
+    # @private    
     def wait!(string_akt)
       return unless @time_last 
       verstrichene_zeit = Time.now - @time_last   
@@ -81,6 +87,7 @@ module Perception
     end # wait
     
     
+    # @private    
     def adjust_level
       @call_stack_now   = caller.size 
       call_stack_diff = @call_stack_now - @call_stack_last
@@ -97,6 +104,7 @@ module Perception
     end
     
     
+    # @private    
     def clear_indent!
       @call_stack_last  = 0      # wie direkt nach der Initialisierung 
       @call_stack_now   = 0       
@@ -109,6 +117,7 @@ module Perception
     
     
     # Gibt das see aus
+    # @private    
     def process_print( input, options={} )
     
       # vorbereiten
@@ -157,6 +166,7 @@ module Perception
     
     
     # Führt die aufgeschobenen Newlines aus. Ohne Berücksichtigung der Zeit.
+    # @private    
     def process_newline    
       result = "\n" * @delayed_newlines     
       self.clear!                    if @delayed_clear 
@@ -166,6 +176,7 @@ module Perception
     end    
     
     
+    # @private    
     def printout(string, backward=nil)
       if @out.include?(:console)
         spacer = (' '*SEE_TAB_WIDTH * @level)
@@ -205,8 +216,8 @@ end # module
 
 class Object
   
-  # Liefert entweder inspect oder to_s, je nach Klassenzugehörigkeit
-  # Explizite Typabfrage ohne duck typing!
+  # Returns the result of +inspect+ or the result of +to_s+, depending on the class. 
+  # No duck typing.
   def inspect_or_to_s
     return 'empty'            if self == ''
     return self.to_s          if self.class == String

data/lib/perception/ppp.rb

@@ -8,6 +8,7 @@ end
 
 
 # patches pretty print
+# @private
 class PPP < PP
 
 
@@ -347,7 +348,7 @@ class PPP < PP
 
 end # class
 
-
+# @private
 class String 
 
   # @return [String]
@@ -357,7 +358,7 @@ class String
   
 end
 
-
+# @private
 class Set 
 
   # @return [String]
@@ -376,7 +377,7 @@ class Set
   
 end
 
-
+# @private
 class Dictionary 
 
  # @return [String]

data/lib/perception/string_spread.rb

@@ -9,9 +9,11 @@ require 'kyanite/array_of_enumerables'
 
 
 module Perception 
+
+  # @private
   module StringSpreadI 
   
-
+  # @private
   def analyze_columns(options={})
   
     # vorbereiten
@@ -64,6 +66,7 @@ module Perception
   # Mit position_add= 0 werden die Spaces vor dem gefundenen Zeichen eingefügt.
   # Standard ist position_add= search.size, damit werden die Spaces hinter den gefundenen Zeichen eingefügt.    
   # Mit PPP_ANTI_NEWLINE werden Zeilen markiert, bei denen anschließend noch das \n entfernt werden kann.
+  # @private  
   def spread_line(tabstops=[], search=/,/, position_add=nil, start=0)
     #puts "spread_line, self=#{self.inspect_pp} tabstops=#{tabstops.join('-')}"
     position_add = search.inspect.size-2       unless position_add
@@ -100,7 +103,7 @@ module Perception
   end # def   
   
   
-  
+  # @private  
   def spread(options={})
     # vorbereiten
     level_start =   options[:level_start]   || 1
@@ -129,6 +132,7 @@ module Perception
   end # module
 end # module
 
+# @private
 class String 
   include Perception::StringSpreadI
 end

data/test/test_numeric.rb

@@ -33,17 +33,17 @@ class TestPerceptionNumeric < UnitTest
                '      124     ',
                '      100     ',
                '      100     ',
-               '       99,9   ',
+               '       99.9   ',
                '       12     ',
                '       12     ',
-               '       12,6   ',
-               '        1,26  ',
-               '        1,5   ',
+               '       12.6   ',
+               '        1.26  ',
+               '        1.5   ',
                '        0     ',
-               '        0,126 ',
-               '        0,0126',
-               '       0,00126',
-               '      0,000126']    
+               '        0.126 ',
+               '        0.0126',
+               '       0.00126',
+               '      0.000126']    
     result= test.collect { |t| t.to_f.inspect_see }   
     assert_equal expect, result
     
@@ -79,7 +79,7 @@ class TestPerceptionNumeric < UnitTest
     assert_equal "\n" + result,              see_print(test);  setup       
 
     test   = -0.000314162353463463136537846595
-    result = '     -0,000314'
+    result = '     -0.000314'
     assert_equal "\n" + result,              see(test);        setup
     assert_equal "\n" + result,              see_pp(test);     setup
     assert_equal "\n" + result,              see_puts(test);   setup

data/version.rb

@@ -1,6 +1,6 @@
 
 
 module Perception #:nodoc
-  VERSION = '0.3.4'
+  VERSION = '0.3.5'
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: perception
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-18 00:00:00.000000000 Z
+date: 2012-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: drumherum
@@ -109,9 +109,11 @@ files:
 - Rakefile.rb
 - README.rdoc
 - version.rb
-- demo/demo_pp.rb
-- demo/demo_system_info.rb
-- demo/demo_zz.rb
+- demo/demo1.rb
+- demo/demo2.rb
+- demo/demo3.rb
+- demo/Example_Output_1.rb
+- demo/Example_Output_2.rb
 - init.rb
 - lib/perception.rb
 - lib/perception/const.rb

data/demo/demo_system_info.rb

@@ -1,28 +0,0 @@
-# ruby encoding: utf-8
-# ü
-if $0 == __FILE__ 
-  require 'drumherum'
-  smart_init
-  require 'perception'
-end
-
-require 'rbconfig'
-seee.out << :log
-see Config::CONFIG 
-see
-see
-see "------------------------------------------------------"
-
-# require 'awesome_print'
-# ap Config::CONFIG 
-
-
-
-
- 
-
-
-
-
-
-