indented_io 0.7.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0a203a65d6293b629e37b0e6f37f00b5c010c4d38acac313d481a44b0a50b8b
-  data.tar.gz: 68df73e9433c325c8e6597d416222977f25e877a41ec142d7fecaa5aedee877c
+  metadata.gz: f678cdfa6edee19dad6a5256367071ceea8d1ca7ebb5dd4556330f260250e0e1
+  data.tar.gz: a2cb615747e62ca14ed25b872ae501c9f6b0dbaadd1a9ec73f3a2dbfcd519f61
 SHA512:
-  metadata.gz: 0b01a78e6633ccca02ede79d880f3c4aec6168b11ddebbbcdc6773a48ef11abe4761919acd623386f1a3fd3cdeb0653dc0bc8f64fd587e3ca97b544fac62751c
-  data.tar.gz: 05b55ba617d47d7b9bedfc784efec9d23f9f7284c7691baa0edca8a85f35d64eb1dd55577c1a190b9db675304b7acae7f0db584607762e3a151a3da23e84cef9
+  metadata.gz: 914ca7aef4d7017fc4899c2f1cc19da8a7cf6bacc7c0937bd28033bef7cb2350f3878bd0ac9380301d4e2b0cb7df6aded579085a7a52c0f48206e80dbe6b3a7a
+  data.tar.gz: 5dcf284b39596f7faaff975d2e703125caa157c133646a1aa9a2147bb95b7c4c852de61c3bcdc872208c08d79a7d4acc42a0170d168d66e9a56199082ed5d328

data/README.md

@@ -1,12 +1,10 @@
 # IndentedIO
 
-Print indented text
-
 `IndentedIO` extends `Kernel`, `IO`, and `StringIO` with an `#indent` method
 that returns an `IndentedIO` object. The `IndentedIO` object acts as the
-original object but redefines the output methods `#print`, `#printf`, `#puts`,
-and `#p` to print their output indented.  Indentations are stacked so that each
-new indentation adds to the previous indendation
+original object but redefines `#print`, `#printf`, `#puts`, and `#p` to print
+their output indented. Indentations are stacked so that each new indentation
+adds to the previous indendation
 
 ## Usage
 
@@ -54,10 +52,10 @@ instead:
 
 ```ruby
 $stdout.puts "Not indented"
-$stdout.indent(2, "> ") { |f|
+$stdout.indent(2, "> ") do |f|
   f.indent(string: "* ").puts "Indented three levels"
   f.indent(-1).puts "Indented one level"
-}
+end
 
 # Not indented
 # > > * Indented three levels
@@ -74,13 +72,13 @@ indented within that block:
 
 ```ruby
 puts "Not indented"
-indent {
+indent do
   puts "Indented one level"
-  indent {
+  indent do
     puts "Indented two levels"
-  }
+  end
   puts "Indented one level"
-}
+end
 puts "Not indented"
 
 # Not indented
@@ -140,7 +138,7 @@ to get a different indentation for a part of the program
 
 In case of errors an `IndentedIO::Error` exception is raised
 
-## Add support for other classes
+## Adding support for other classes
 
 You can add support for your own IO objects by including
 `IndentedIO::IndentedIOInterface` in your class.  All that is required is that
@@ -155,7 +153,11 @@ class MyIO
 end
 
 my_io = MyIO.new
+my_io.puts "Not indented"
 my_io.indent.puts "It works!"
+
+# Not indented
+#   It works!
 ```
 
 ## Implementation & performance
@@ -165,10 +167,14 @@ my_io.indent.puts "It works!"
 with a block without parameters manipulates `$stdout`, replacing it with an
 `IndentedIO` object for the duration of the block
 
-The implementation carries no overhead if it is not used but the core indentation
-mechanism processes characters one-by-one which is slow compared to what could
-be achived with a native C implementation
-
+The implementation carries no overhead if it is not used but the core
+indentation mechanism processes characters one-by-one which is about 10-15
+times slower than a handwritten implementation (scripts/perf.rb is a script to
+check performance). It would be much faster if the inner loop was implemented
+in C. However, we're talking micro-seconds here: Printing without using
+IndentedIO range from around 0.25ms to 1ms while using IndentedIO slows it down
+to between 4 and 12 microseconds, so IndentedIO won't cause a noticeable slow
+down of your application
 
 ## Installation
 

data/TODO

@@ -2,6 +2,13 @@
 TODO
   o Check if IO object is writable - no good solution ?
   o better name for @this_indent ? 'string' ?
+  o Change dependency in IndentedIOInterface from #print to #write and bump
+    version to 0.8 as this is the last user-visible change to be made
+  o Reimplement core loop in C
+  o Create BaseIndentedIO to hold bol status and remove it from IndentedIO
+  o Transmogrify instances variables and protected methods in IndentedIO to 
+    avoid collision with names from the underlying device
+  o Explain name collision issues in the docs
 
   + explain bol
   + Allow a symbolic :string argument
@@ -15,5 +22,3 @@ TODO
   + Rename Device -> IndentedIO
 
   - Make Kernel.indent behave like Kernel ?
-
-  ? Create a BaseIndentedIO class ?

data/indented_io.gemspec

@@ -11,13 +11,11 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{Print indented text}
   spec.description   = %q{
-                          IndentedIO extends Kernel, IO, and StringIO
-                          with an #indent method that returns an IndentedIO
-                          object. The IndentedIO object acts as the original
-                          object but redefines the output methods #print,
-                          #printf, #puts, and #p to print their output
-                          indented. Indentations are stacked so that each new
-                          indentation adds to the previous indendation
+                          IndentedIO extends Kernel, IO, and StringIO with an
+                          #indent method that redefines #print, printf, #puts,
+                          and #p to print their output indented. Indentations 
+                          are stacked so that each new indentation adds to the
+                          previous indendation
                        }
   spec.homepage      = "https://github.com/clrgit/indented_io"
   spec.license       = "MIT"

data/lib/indented_io.rb

@@ -7,8 +7,9 @@ require 'indented_io/kernel'
 require 'indented_io/io'
 require 'indented_io/stringio'
 
-# IndentedIO module
-
+# IndentedIO module. See {IndentedIO::IndentedIO} for documentation on how to 
+# use this module
+#
 module IndentedIO
   # Returns default indentation. Two spaces is the default but it can be set by
   # #default_indent

data/lib/indented_io/error.rb

@@ -1,11 +1,11 @@
 
 module IndentedIO
-  # Error class. To rescue errors form IndentedIO do
+  # Error class derived from RuntimeError. To rescue errors from IndentedIO do
   #
   #   begin
-  #     do_some_stuff()
+  #     # do_some_stuff
   #   rescue IndentedIO::Error => ex
-  #     handle_error()
+  #     # handle_error
   #   end
   #
   class Error < RuntimeError; end

data/lib/indented_io/indented_io.rb

@@ -8,7 +8,7 @@ module IndentedIO
   # levels rise or fall IndentedIO objects are moved on and off the stack
   #
   # Note that #new is private. The only way to create a IndentedIO object is to
-  # call #indent on an object that supports it
+  # call #indent on an object that supports it ({Kernel}, {IO}, or {StringIO})
   class IndentedIO
     include IndentedIOInterface
 

data/lib/indented_io/indented_io_interface.rb

@@ -1,6 +1,6 @@
 module IndentedIO
-  # IndentedIO interface that provides the #indent method. Used by IO,
-  # StringIO, and IndentedIO. It can be included in any class that define a
+  # IndentedIO interface that provides the #indent method. It is used by IO,
+  # StringIO, and IndentedIO but can be included in any class that define a
   # #print method like this:
   #
   #   require 'indented_io'

data/lib/indented_io/kernel.rb

@@ -6,12 +6,12 @@ module Kernel
   # and argument. In that case it manipulates $stdout to print indented:
   #
   #   puts "Not indented
-  #   indent {
+  #   indent do
   #     puts "Indented"
-  #     indent {
+  #     indent do
   #       puts "Even more indented"
-  #     }
-  #   }
+  #     end
+  #   end
   #
   #   # Not indented
   #   #   Indented

data/lib/indented_io/version.rb

@@ -1,4 +1,4 @@
 module IndentedIO
   # Version number
-  VERSION = "0.7.2"
+  VERSION = "0.7.3"
 end

data/scripts/perf.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+
+exec("bundle exec #$0 '#{ARGV.join("' '")}'") if !ENV.key?('BUNDLE_BIN_PATH')
+
+RUNS = 1_000_000
+
+saved_stdout = $stdout
+$stdout = File.open("/dev/null", "w")
+
+def timeit(&block)
+  t0 = Time.now
+  RUNS.times {
+    yield
+  }
+  t1 = Time.now
+  (1000 * (t1 - t0)).round(0)
+end
+
+def report(title, wo_indent, w_indent)
+  times = (w_indent / wo_indent).round(1)
+  if times < 1.1
+    slower = "same speed"
+  else
+    slower = "#{times} times slower"
+  end
+
+  puts title
+  indent {
+    puts "w/o indented_io: #{wo_indent}ms"
+    puts "w/indented_io  : #{w_indent}ms (#{slower})"
+  }
+end
+
+# No indent
+# 
+flat_output_wo_indent = timeit { puts "Not indented" }
+
+require 'indented_io'
+
+flat_output_w_indent = timeit { puts "Not indented" }
+
+# Indented one level
+#
+static_wo_indent = timeit { puts "  Indented" }
+
+static_w_indent = nil
+indent {
+  static_w_indent = timeit { puts "Indented" }
+}
+
+# Indented by a dynamic string
+#
+indent = "  "
+dynamic_wo_indent = timeit {
+  puts "#{indent}Indented"
+}
+
+dynamic_w_indent = nil
+indent("  ") {
+  dynamic_w_indent = timeit { puts "Indented" }
+}
+
+# Recursive indentation
+#
+def recur_wo_indent(level, indent)
+  puts "#{indent}Indented"
+  if level > 0
+    recur_wo_indent(level - 1, "#{indent}  ")
+  end
+end
+
+def recur_w_indent(level)
+  puts "Indented"
+  if level > 0
+    indent { recur_w_indent(level - 1) }
+  end
+end
+
+recursive_wo_indent = timeit { recur_wo_indent(2, "  ") }
+recursive_w_indent = timeit { recur_w_indent(2) }
+
+$stdout = saved_stdout
+
+puts "Performance with #{RUNS} runs"
+puts
+
+report "Flat output", flat_output_wo_indent, flat_output_w_indent
+report "Static indent", static_wo_indent, static_w_indent
+report "Dynamic indent", dynamic_wo_indent, dynamic_w_indent
+report "Recursive indent", recursive_wo_indent, recursive_w_indent
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: indented_io
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.7.3
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-11 00:00:00.000000000 Z
+date: 2018-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,13 +52,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: "\n                          IndentedIO extends Kernel, IO, and StringIO\n
-  \                         with an #indent method that returns an IndentedIO\n                          object.
-  The IndentedIO object acts as the original\n                          object but
-  redefines the output methods #print,\n                          #printf, #puts,
-  and #p to print their output\n                          indented. Indentations are
-  stacked so that each new\n                          indentation adds to the previous
-  indendation\n                       "
+description: "\n                          IndentedIO extends Kernel, IO, and StringIO
+  with an\n                          #indent method that redefines #print, printf,
+  #puts,\n                          and #p to print their output indented. Indentations
+  \n                          are stacked so that each new indentation adds to the\n
+  \                         previous indendation\n                       "
 email:
 - claus.l.rasmussen@gmail.com
 executables: []
@@ -85,6 +83,7 @@ files:
 - lib/indented_io/kernel.rb
 - lib/indented_io/stringio.rb
 - lib/indented_io/version.rb
+- scripts/perf.rb
 homepage: https://github.com/clrgit/indented_io
 licenses:
 - MIT