perception 0.3.4 → 0.3.5

data/History.rdoc

@@ -1,3 +1,5 @@
+== 0.3.5 2012-10-19
+* Yard documentation
 
 == 0.3.2 2012-10-08
 * smart_init 

data/Manifest.txt

@@ -5,9 +5,11 @@ Manifest.txt
 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/README.rdoc

@@ -1,23 +1,39 @@
+= Perception: Human perceptible printouts
+http://bklippstein.github.com/perception/frames.html
 
-= Perception - Readable Printouts For Logs And Console
+Welcome to Perception. It's a intuitive toolkit for simple everyday debugging. 
+Perception offers a powerfull replacement for print, puts and pp and is an alternative to 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.
 
-http://bklippstein.github.com/perception/frames.html
 
-Powerfull replacement for print, puts and pp. Intuitive toolkit for simple everyday debugging. 
+== see: Powerfull replacement for print, puts and pp
+{include:Object#see}
+More: {Object#see}
 
-You get auto-intended and structured output on your console without any configuration. 
+== log: use logging without configuration
+You can use log instead of see, the formating is the same. 
+The log directory and the logfile are automatically created if necessary.
 
-Perception also offers temporary printouts (overwritten by the next print). So you can print
-two informations in one place without destroying the structure. 
+More: {Object#log log}, {Object#rawlog rawlog}, {Perception::SeeSession#logger seee.logger}
 
-Perception optionally slows down printing to readable speed, depending on the complexity of the output.
+== Intelligent round: slash needless digits 
+{include:Perception::NumericI#significant}
+More: {Perception::NumericI#significant significant}
 
+== Easily human readable numbers 
+{include:Perception::NumericI#inspect_see}
+More: {Perception::NumericI#inspect_see inspect_see}
 
 
-== Usage
-  require 'perception'
-use +see+ instead of pp, puts, print.
-[] There are demos included. Run them.  
+== Examples and Demos
+* {file:demo/Example_Output_1.rb}
+* {file:demo/Example_Output_2.rb} 
+* {file:demo/demo3.rb} (interactive)
 
 
 == More Info

data/demo/Example_Output_1.rb

@@ -0,0 +1,183 @@
+# See source code and run it for yourself: {file:demo/demo1.rb}
+
+
+    Basic Types
+    ===========
+
+
+    1dim Arrays are printed verticaly, if their size is not too big:
+
+
+    ['this', 'is', 'an', 'array', '1']
+    ['this', 'is', 'another', 'array', '2']
+    ['complex array', [1, 2, 3], {:key=>:value, :love=>:baby}, 4.0, :four]
+    []
+
+
+    Other Objects:
+    ordinary string (without "")
+    (next one is empty)
+    empty
+            1
+            2
+            3     
+    nil
+    true
+    false
+    :a_symbol
+
+
+
+
+
+
+    2dimensional Arrays
+    ===================
+
+
+    2dim Arrays are printed like a table:
+
+
+    [['this',   'is',           'an',      'array',   '1'], 
+     ['this',   'is',           'another', 'array',   '2'], 
+     ['and',    'this',         'is',      'another', :tree], 
+     ['no',     {:key=>:value}, 'just',    'another', 'array']]
+
+
+
+
+    [['one',     'a',                                    'b',                                    'c'],
+     ['two',     'long_longlong_long_long',              'also_long, also_long, also_long_also', 'hallo'],
+     ['three',   'also_long, also_long, also_long_also', 'also_long, also_long, also_long_also', 'long_longlong_long_long']]
+
+
+
+
+
+
+    Nested Objects
+    ==============
+
+
+    Nested objects reveal their structure. Lower hierary levels may be reduced for this:
+
+
+    #<Perception::SeeSession:0x2aa0cc8
+     @call_stack_last =  5,
+     @call_stack_now =   6,
+     @cursor_now =       1148,
+     @delayed_clear =    false,
+     @delayed_newlines = 0,
+     @indent =           false,
+     @level =            1,
+     @logger =           #<Logger:0x2ae80c8  @default_formatter=#<>,  @formatter=nil,  @level=0,  @logdev=#<<><<>>>,  @progname=nil>,
+     @method_last =      :puts,
+     @method_now =       :pp,
+     @out =              {:console, :log},
+     @speed =            nil,
+     @string_last =      '
+    ',
+     @time_last =        2012-10-18 Thursday 23:27:03>
+
+
+    The Logger has been reduced. This is its detail view:
+
+
+    #<Logger:0x2ae80c8
+     @default_formatter = #<Logger::Formatter:0x2ae8020  @datetime_format=nil>,
+     @formatter =         nil,
+     @level =             0,
+     @logdev =            #<Logger::LogDevice:0x2af3750  @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>
+
+
+
+
+    PrettyPrint shows all at one, but its very hard to read:
+
+
+    PrettyPrint shows all at one, but its very hard to read:
+
+    #<Perception::SeeSession:0x2aa0cc8
+     @call_stack_last=5,
+     @call_stack_now=5,
+     @cursor_now=2196,
+     @delayed_clear=false,
+     @delayed_newlines=1,
+     @indent=false,
+     @level=1,
+     @logger=
+      #<Logger:0x2ae80c8
+       @default_formatter=#<Logger::Formatter:0x2ae8020 @datetime_format=nil>,
+       @formatter=nil,
+       @level=0,
+       @logdev=
+        #<Logger::LogDevice:0x2af3750
+         @dev=#<File:C:/Ruby-Projekte/perception/log/see.log>,
+         @filename='C:/Ruby-Projekte/perception/log/see.log',
+         @mutex=
+          #<Logger::LogDevice::LogDeviceMutex:0x2af3738
+           @mon_count=0,
+           @mon_mutex=#<Mutex:0x2af36c0>,
+           @mon_owner=nil>,
+         @shift_age=0,
+         @shift_size=1048576>,
+       @progname=nil>,
+     @method_last=:puts,
+     @method_now=:puts,
+     @out={:console, :log},
+     @speed=nil,
+     @string_last='',
+     @time_last=2012-10-18 Thursday 23:27:03>
+
+
+
+
+
+
+
+    Hash
+    ====
+
+
+    {:this=>:hash,  :in=>:one,  :see=>'short hash in one line'}
+
+
+
+
+    {:this         =>  :hash,
+     :size         =>  '> 3',
+     :see          =>  'longer hash in multiple lines',
+     :another_key  =>  'another value'}
+
+
+
+
+    {: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'}}
+
+
+
+
+
+
+    Dictionary
+    ==========
+
+
+    {:a_dictionary     =>  true,
+     :b_init           =>  true,
+     :c_symbol         =>  :symbol,
+     :d_array          =>  [1,  2,  3],
+     :e_integer        =>  1,
+     :f_string         =>  'hallo',
+     :g_subdictionary  =>  {:a=>:value,  :b=>'blubb',  :c=>2,  :d=>[:a, :b, :c],  :e=>{:key=>:value},  :f=>'hallo'}}
+     
+     

data/demo/Example_Output_2.rb

@@ -0,0 +1,63 @@
+
+    see (Perception)
+    ================
+    
+    see RbConfig::CONFIG
+    =>
+    {'DESTDIR'               =>  'C:',
+     'MAJOR'                 =>  '1',
+     'MINOR'                 =>  '9',
+     'TEENY'                 =>  '1',
+     'PATCHLEVEL'            =>  '125',
+     'INSTALL'               =>  '/usr/bin/install -c',
+     'EXEEXT'                =>  '.exe',
+     'prefix'                =>  'C:/Rails/Ruby1.9.3',
+     'ruby_install_name'     =>  'ruby',
+     'RUBY_INSTALL_NAME'     =>  'ruby',
+     'RUBY_SO_NAME'          =>  'msvcrt-ruby191',
+     'exec'                  =>  'exec',
+     'ruby_pc'               =>  'ruby-1.9.pc',
+     'PACKAGE'               =>  'ruby',
+     'BUILTIN_TRANSSRCS'     =>  ' newline.c',
+     'USE_RUBYGEMS'          =>  'YES',
+     'MANTYPE'               =>  'man',
+     'NROFF'                 =>  '/bin/false',
+     'vendorhdrdir'          =>  'C:/Rails/Ruby1.9.3/include/ruby-1.9.1/vendor_ruby',
+     'sitehdrdir'            =>  'C:/Rails/Ruby1.9.3/include/ruby-1.9.1/site_ruby',
+     'rubyhdrdir'            =>  'C:/Rails/Ruby1.9.3/include/ruby-1.9.1',
+     'UNIVERSAL_INTS'        =>  '',
+     ...
+
+     
+     pp (PrettyPrint)
+     ================
+
+    pp RbConfig::CONFIG
+    =>
+    {'DESTDIR'=>'C:',
+     'MAJOR'=>'1',
+     'MINOR'=>'9',
+     'TEENY'=>'1',
+     'PATCHLEVEL'=>'125',
+     'INSTALL'=>'/usr/bin/install -c',
+     'EXEEXT'=>'.exe',
+     'prefix'=>'C:/Rails/Ruby1.9.3',
+     'ruby_install_name'=>'ruby',
+     'RUBY_INSTALL_NAME'=>'ruby',
+     'RUBY_SO_NAME'=>'msvcrt-ruby191',
+     'exec'=>'exec',
+     'ruby_pc'=>'ruby-1.9.pc',
+     'PACKAGE'=>'ruby',
+     'BUILTIN_TRANSSRCS'=>' newline.c',
+     'USE_RUBYGEMS'=>'YES',
+     'MANTYPE'=>'man',
+     'NROFF'=>'/bin/false',
+     'vendorhdrdir'=>'C:/Rails/Ruby1.9.3/include/ruby-1.9.1/vendor_ruby',
+     'sitehdrdir'=>'C:/Rails/Ruby1.9.3/include/ruby-1.9.1/site_ruby',
+     'rubyhdrdir'=>'C:/Rails/Ruby1.9.3/include/ruby-1.9.1',
+     'UNIVERSAL_INTS'=>'',
+     ...
+     
+     
+     
+     

data/demo/{demo_pp.rb → demo1.rb}

@@ -1,5 +1,9 @@
 # ruby encoding: utf-8
-# ü
+# 
+# This generates Example_Output_1.
+# --------------------------------
+#
+#
 if $0 == __FILE__ 
   require 'drumherum'
   smart_init
@@ -13,7 +17,7 @@ module Perception #:nodoc
     @@initialized_count = 0
   
     def initialize( announce_first=true )
-      #seee.out << :log
+      seee.out << :log
       @@initialized_count += 1
       return  if (@@initialized_count == 1  &&  !announce_first)
       #seee.slow!(0.5)
@@ -32,18 +36,21 @@ module Perception #:nodoc
       # wait_for_key('Press any key to start')
       
       
-    end # def
+    end # defü
   
   
   
     # Printing basic types
     def demo_see_basic_types
-      see '1dim Arrays:'
-      seee.indent!
+      see '1dim Arrays are printed verticaly, if their size is not too big:'
       see
+      seee.left!
+      see a=['this','is','an','array','1']
+      see b=['this','is','another','array','2']
+      see d=['complex array', [1,2,3], {:key => :value, :love => :baby}, 4.0, :four]
+      see []        
       see
       see 'Other Objects:'
-      see []      
       see 'ordinary string (without "")'
       see '(next one is empty)'
       see ''
@@ -55,17 +62,30 @@ module Perception #:nodoc
       see false
       see :a_symbol
  
-      see ['complex array', [1,2,3], {:key => :value, :love => :baby}, 3.0 , '']
     end # def
     
     
     def demo_see_pp_object
+      see 'Nested objects reveal their structure. Lower hierary levels may be reduced for this:'
+      see    
       seee.logger
       see seee
+      see
+      see 'The Logger has been reduced. This is it''s detail view:'
+      see
+      see seee.logger
+      see
+      see
+      see 'PrettyPrint shows all at one, but it''s very hard to read:' 
+      see
+      pp seee
     end
     
     
+    
     def demo_see_pp_array  
+      see '2dim Arrays are printed like a table:'
+      see      
       @array1 = []
       @array1 << ['this','is','an','array','1']
       @array1 << ['this','is','another','array','2']
@@ -129,13 +149,14 @@ module Perception #:nodoc
     
     
     def self.see_all_demos
-      Perception::DemoSee.new('PrettyPrint Array').demo_see_pp_array     
-      Perception::DemoSee.new('PrettyPrint Object').demo_see_pp_object  
-      Perception::DemoSee.new('PrettyPrint Hash').demo_see_pp_hash       
-      Perception::DemoSee.new('PrettyPrint Dictionary').demo_see_pp_dictionary      
+      Perception::DemoSee.new('Basic Types').demo_see_basic_types      
+      Perception::DemoSee.new('2dimensional Arrays').demo_see_pp_array     
+      Perception::DemoSee.new('Nested Objects').demo_see_pp_object  
+      Perception::DemoSee.new('Hash').demo_see_pp_hash       
+      Perception::DemoSee.new('Dictionary').demo_see_pp_dictionary      
 
       
-      Perception::DemoSee.new('PrettyPrint div').demo_see_basic_types  
+
  
     end
 
@@ -147,6 +168,7 @@ end # class
 
 if $0 == __FILE__ then
 
+# seee.out << :log
 Perception::DemoSee.see_all_demos
 
    

data/demo/demo2.rb

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

data/demo/demo3.rb

@@ -0,0 +1,201 @@
+# ruby encoding: utf-8
+# ü
+if $0 == __FILE__ 
+  require 'drumherum'
+  smart_init
+  require 'perception'
+end
+ 
+ 
+module Perception #:nodoc
+
+  class DemoSee
+    @@initialized_count = 0
+  
+    def initialize( announce_first=true )
+      #seee.out << :log
+      @@initialized_count += 1
+      return  if (@@initialized_count == 1  &&  !announce_first)
+      #seee.slow!(0.5)
+      seee.left!
+      #seee.indent!
+      see ("\n" * 5)   if @@initialized_count > 1  
+      
+      if announce_first.kind_of?(String)
+        see announce_first
+        see '='*announce_first.size
+      else
+        see "Perception Demo ##{@@initialized_count}"
+        see "=================="
+      end
+      see
+      wait_for_key('Press any key to start')
+    end # def
+  
+  
+      
+    def demo_level
+      seee.slow!
+      see "The printout is automaticaly indented. This is the printout of a nested structure of #see's:"
+      see
+      see
+      seee.indent!
+      sub_demo_level
+      see
+      see      
+      #wait_for_key
+      see 'You can force left printout with seee.left!. Reactivate indention with seee.indent!.'
+      seee.left!
+      see
+      see
+      sub_demo_level
+    end
+    
+    
+    def sub_demo_level
+      see "Hello world. This is level zero. "
+      (1..1).each do 
+      see "This is the beginning of level one."
+        1.downto(1) do 
+        see "This is the beginning of level two."
+          1.upto(1) do 
+          see "This is the beginning of level three."
+            1.times do 
+            see "This is the beginning of level four." 
+            see "This is the end of level four." 
+            end    
+          see "This is the end of level three."        
+          end  
+        see "This is the end of level two."        
+        end 
+      see "This is the end of level one."      
+      end
+      see "This is level zero again. Bye. "      
+    end # def    
+    
+    
+    
+    
+    
+    
+    # slow printing
+    def demo_see_slowdown1
+      seee.slow!
+      see "You can slow down printing with seee.slow!"
+      see 
+      see 'This is a string'
+      see 'and here we have a longer one.'
+      see 'so we need even longeer strings, but they all have to be different.'
+      see '#see has forgotten the first string. So I will tell him again: This is a string. and here we have a longer one. '
+      see 'In slow mode #see waits for you to read the lines. More words, longer waiting.'
+      see 'short prints...' 
+      see '...short waiting.' 
+      see 'short prints...' 
+      see '...short waiting.' 
+      see
+      see
+      string = 'This string is getting longer.' 
+      (1..10).each do |i|
+        see string
+        string += ' But it repeats.' 
+      end
+      see
+      see '#see only counts those words you have to read.'
+      see
+      see
+      see 'You can choose the speed. seee.slow!(0.5) is faster: '
+      
+      wait_for_key
+      see
+      seee.slow!(0.5)
+      see 'This is a string'
+      see 'and here we have a longer one.'
+      see 'so we need even longeer strings, but they all have to be different.'
+      see '#see has forgotten the first string. So I will tell him again: This is a string. and here we have a longer one. '
+      see 'In slow mode #see waits for you to read the lines. More words, longer waiting.'
+      see 'short prints...' 
+      see '...short waiting.' 
+      see '...short waiting.' 
+      string = 'This string is getting longer.' 
+      (1..10).each do |i|
+        see string
+        string += ' But it repeats.' 
+      end
+      see
+      see '#see only counts those words you have to read.'
+      see      
+    end  
+    
+    
+    
+    
+    # Simple benchmarking
+    def demo_bench
+      see 'You always get the time since last print with seee.bench.'    
+      see 'You can use this for simple benchmarking:'      
+      see "I'm counting to 50 000 000, please wait."
+      50000000.downto(0) {}
+      see "it took #{seee.bench} seconds." 
+
+    end    
+    
+    
+    # temporary printing
+    def demo_see_temp_and_clear_last
+      seee.slow!
+      see_print "countdown: "
+      10.downto(0) do |i|
+        see_temp i
+      end 
+      see 'finished!'
+      sleep 1
+      seee.clear!
+      see 'You can clear the last print with seee.clear!'      
+      see 'And you can print temporary informations with see_temp'      
+    end
+      
+    
+    
+    # print two informations on one line
+    def demo_alternate_see
+      see ['horst.maierman','PW-AEerSDFs', 'addional', 'information', :one]
+      see ['claudia.hoppe','27546522sdfgdz3s', 'addional', 'information', :two]
+      see ['nadja.hirsch','Minnie', 'addional', 'information', :three]
+      seee.flash! '    Bad password!     ' 
+      see ['tom.flupper','Gs3Kkd2', 'addional', 'information', :five]
+      see ['anna.chevrezonk','2sdtg&fH', 'addional', 'information', :six]
+      see ['hardy.schwarzer','dfjhRfDdtis', 'addional', 'information', :seven]
+    end    
+    
+    
+    
+    
+    def self.see_all_demos
+      Perception::DemoSee.new('Automatic Indenting').demo_level 
+      Perception::DemoSee.new('Slowing down').demo_see_slowdown1    
+      Perception::DemoSee.new('Simple Benchmarking').demo_bench   
+      Perception::DemoSee.new('Progress Indicator').demo_see_temp_and_clear_last  
+      Perception::DemoSee.new('Two layers of information in one line').demo_alternate_see      
+    end
+
+  
+  
+  end # class
+end # class
+
+
+if $0 == __FILE__ then
+
+Perception::DemoSee.see_all_demos
+   
+end
+
+  
+
+    
+
+
+
+
+
+  

data/lib/perception/date_and_time.rb

@@ -8,6 +8,8 @@ end
 
 
 module Perception 
+
+
  module TimeI