hexdump 0.1.0 → 0.2.1

data/ChangeLog.md

@@ -1,3 +1,17 @@
+### 0.2.1 / 2011-06-11
+
+* Fixed a major bug in {Hexdump::Dumper#dump}, where the line buffers
+  were not being cleared.
+
+### 0.2.0 / 2011-06-11
+
+* Added {Hexdump::Dumper}.
+* Added support for hexdumping 1, 2, 4, 8 byte words.
+* Added support for hexdumping Little and Big Endian words.
+* Optimized the hexdump algorithm to not use Arrays, use a lookup table
+  of printable characters and cache formatted numbers.
+* Opted into [test.rubygems.org](http://test.rubygems.org/).
+
 ### 0.1.0 / 2011-03-05
 
 * Initial release:

data/README.md

@@ -15,53 +15,11 @@ Simple and Fast hexdumping for Ruby.
 * Can send the hexdump output to any Object supporting the `<<` method.
 * Can yield each line of hexdump, instead of printing the output.
 * Supports printing ASCII, hexadecimal, decimal, octal and binary bytes.
+* Supports hexdumping 1, 2, 4, 8 byte words.
+* Supports hexdumping Little and Big Endian words.
 * Makes {String}, {StringIO}, {IO}, {File} objects hexdumpable.
 * Fast-ish.
 
-## Benchmarks
-
-Benchmarks show {Hexdump.dump} processing 2.4M of data.
-
-### Ruby 1.9.2-p180
-
-                                    user     system      total        real
-    hexdump (block)             7.740000   0.030000   7.770000 (  8.138029)
-    hexdump                     9.590000   0.050000   9.640000 ( 10.178203)
-    hexdump width=256 (block)   7.280000   0.020000   7.300000 (  7.534507)
-    hexdump width=256           8.130000   0.030000   8.160000 (  8.342448)
-    hexdump ascii=true (block)  7.740000   0.030000   7.770000 (  7.958550)
-    hexdump ascii=true          9.550000   0.050000   9.600000 (  9.803758)
-
-### Ruby 1.8.7-p334
-
-                                    user     system      total        real
-    hexdump (block)            10.520000   0.010000  10.530000 ( 10.692901)
-    hexdump                    11.580000   0.010000  11.590000 ( 11.873978)
-    hexdump width=256 (block)   9.960000   0.110000  10.070000 ( 11.592033)
-    hexdump width=256          10.660000   0.010000  10.670000 ( 10.987417)
-    hexdump ascii=true (block) 10.620000   0.010000  10.630000 ( 10.899925)
-    hexdump ascii=true         11.590000   0.030000  11.620000 ( 12.765259)
-
-### Jruby 1.5.6
-
-                                    user     system      total        real
-    hexdump (block)             6.690000   0.000000   6.690000 (  6.517000)
-    hexdump                     8.234000   0.000000   8.234000 (  8.234000)
-    hexdump width=256 (block)   4.488000   0.000000   4.488000 (  4.488000)
-    hexdump width=256           5.462000   0.000000   5.462000 (  5.462000)
-    hexdump ascii=true (block)  4.456000   0.000000   4.456000 (  4.456000)
-    hexdump ascii=true          5.039000   0.000000   5.039000 (  5.039000)
-
-### Rubinius 1.2.3
-
-                                    user     system      total        real
-    hexdump (block)            10.013478   0.018997  10.032475 ( 11.148450)
-    hexdump                    13.153001   0.015997  13.168998 ( 13.740888)
-    hexdump width=256 (block)   8.845656   0.008999   8.854655 (  9.022673)
-    hexdump width=256           9.894496   0.008999   9.903495 ( 10.121070)
-    hexdump ascii=true (block)  9.576544   0.021996   9.598540 (  9.810846)
-    hexdump ascii=true         13.088011   0.015998  13.104009 ( 13.390532)
-
 ## Examples
 
     require 'hexdump'
@@ -74,6 +32,10 @@ Benchmarks show {Hexdump.dump} processing 2.4M of data.
     data.hexdump
     # 00000000  68 65 6c 6c 6f 00                                |hello.|
 
+    File.open('dump.txt','w') do |file|
+      data.hexdump(:output => file)
+    end
+
     # iterate over the hexdump lines
     data.hexdump do |index,hex,printable|
       index     # => 0
@@ -102,10 +64,82 @@ Benchmarks show {Hexdump.dump} processing 2.4M of data.
     Hexdump.dump(data, :base => :binary)
     # 00000000  01101000 01100101 01101100 01101100 01101111 00000000                                                                                            |hello.|
 
+    ("ABC" * 10).hexdump(:word_size => 2)
+    # 00000000  4241 4143 4342 4241 4143 4342 4241 4143  |䉁䅃䍂䉁䅃䍂䉁䅃|
+    # 00000010  4342 4241 4143 4342 4241 4143 4342       |䍂䉁䅃䍂䉁䅃䍂|
+
 ## Install
 
     $ gem install hexdump
 
+## Benchmarks
+
+Benchmarks show {Hexdump.dump} processing 2.4M of data.
+
+### Ruby 1.9.2-p180
+
+                                     user     system      total        real
+    hexdump (block)              3.010000   0.010000   3.020000 (  3.529396)
+    hexdump                      5.430000   0.030000   5.460000 (  6.216174)
+    hexdump width=256 (block)    3.010000   0.020000   3.030000 (  3.308961)
+    hexdump width=256            4.700000   0.040000   4.740000 (  5.520189)
+    hexdump ascii=true (block)   3.050000   0.010000   3.060000 (  3.501436)
+    hexdump ascii=true           5.450000   0.040000   5.490000 (  6.352144)
+    hexdump word_size=2 (block)  7.420000   0.050000   7.470000 (  9.174734)
+    hexdump word_size=2          9.500000   0.070000   9.570000 ( 11.228204)
+    hexdump word_size=4 (block)  4.110000   0.030000   4.140000 (  4.849785)
+    hexdump word_size=4          5.380000   0.060000   5.440000 (  6.209022)
+    hexdump word_size=8 (block)  3.350000   0.070000   3.420000 (  4.147304)
+    hexdump word_size=8          4.430000   0.040000   4.470000 (  5.930758)
+
+### Ruby 1.8.7-p334
+
+                                     user     system      total        real
+    hexdump (block)              8.470000   0.020000   8.490000 (  9.585524)
+    hexdump                     11.080000   0.050000  11.130000 ( 12.542401)
+    hexdump width=256 (block)    8.360000   0.030000   8.390000 (  9.431877)
+    hexdump width=256           10.310000   0.050000  10.360000 ( 12.278973)
+    hexdump ascii=true (block)   8.550000   0.030000   8.580000 ( 10.502437)
+    hexdump ascii=true          11.140000   0.040000  11.180000 ( 12.752712)
+    hexdump word_size=2 (block) 12.680000   0.060000  12.740000 ( 14.657269)
+    hexdump word_size=2         13.560000   0.080000  13.640000 ( 16.368675)
+    hexdump word_size=4 (block)  8.500000   0.040000   8.540000 (  9.687623)
+    hexdump word_size=4          9.340000   0.040000   9.380000 ( 10.657158)
+    hexdump word_size=8 (block)  7.520000   0.040000   7.560000 (  8.565246)
+    hexdump word_size=8          8.240000   0.040000   8.280000 (  9.475693)
+
+### JRuby 1.6.0
+
+                                     user     system      total        real
+    hexdump (block)              6.742000   0.000000   6.742000 (  6.495000)
+    hexdump                      7.498000   0.000000   7.498000 (  7.498000)
+    hexdump width=256 (block)    4.601000   0.000000   4.601000 (  4.601000)
+    hexdump width=256            5.569000   0.000000   5.569000 (  5.569000)
+    hexdump ascii=true (block)   5.198000   0.000000   5.198000 (  5.198000)
+    hexdump ascii=true           5.799000   0.000000   5.799000 (  5.798000)
+    hexdump word_size=2 (block)  8.440000   0.000000   8.440000 (  8.440000)
+    hexdump word_size=2          8.698000   0.000000   8.698000 (  8.698000)
+    hexdump word_size=4 (block)  5.603000   0.000000   5.603000 (  5.602000)
+    hexdump word_size=4          5.999000   0.000000   5.999000 (  5.999000)
+    hexdump word_size=8 (block)  7.975000   0.000000   7.975000 (  7.975000)
+    hexdump word_size=8          5.255000   0.000000   5.255000 (  5.255000)
+
+### Rubinius 1.2.4
+
+                                     user     system      total        real
+    hexdump (block)              5.064230   0.029996   5.094226 (  6.236865)
+    hexdump                      7.401875   0.039993   7.441868 ( 10.154394)
+    hexdump width=256 (block)    4.149369   0.054992   4.204361 (  6.518306)
+    hexdump width=256            4.960246   0.089986   5.050232 (  8.647516)
+    hexdump ascii=true (block)   4.458322   0.026996   4.485318 (  5.570982)
+    hexdump ascii=true           6.961941   0.056992   7.018933 (  9.895088)
+    hexdump word_size=2 (block)  8.856653   0.078988   8.935641 ( 11.226360)
+    hexdump word_size=2         10.489405   0.083988  10.573393 ( 12.980509)
+    hexdump word_size=4 (block)  4.848263   0.047992   4.896255 (  6.526478)
+    hexdump word_size=4          6.649989   0.053992   6.703981 (  8.245247)
+    hexdump word_size=8 (block)  5.638143   0.047993   5.686136 ( 12.530454)
+    hexdump word_size=8          7.598844   0.066990   7.665834 ( 16.881667)
+
 ## Copyright
 
 Copyright (c) 2011 Hal Brodigan

data/benchmarks/hexdump.rb

@@ -8,7 +8,7 @@ require 'benchmark'
 DATA = ((0..255).map { |b| b.chr }.join) * 10000
 OUTPUT = Class.new { def <<(data); end }.new
 
-Benchmark.bm(26) do |b|
+Benchmark.bm(27) do |b|
   b.report('hexdump (block)') do
     Hexdump.dump(DATA) { |index,hex,print| }
   end
@@ -32,4 +32,14 @@ Benchmark.bm(26) do |b|
   b.report('hexdump ascii=true') do
     Hexdump.dump(DATA, :ascci => true, :output => OUTPUT)
   end
+
+  [2, 4, 8].each do |word_size|
+    b.report("hexdump word_size=#{word_size} (block)") do
+      Hexdump.dump(DATA, :word_size => word_size) { |index,hex,print| }
+    end
+
+    b.report("hexdump word_size=#{word_size}") do
+      Hexdump.dump(DATA, :word_size => word_size, :output => OUTPUT)
+    end
+  end
 end

data/gemspec.yml

@@ -1,13 +1,15 @@
 name: hexdump
-version: 0.1.0
-summary: Simple and Fast hexdumping for Ruby.
+version: 0.2.1
+summary: Hexdump Strings and IO objects.
 description: Simple and Fast hexdumping for Ruby.
 license: MIT
-authors: hal
+authors: Postmodern
 email: postmodern.mod3@gmail.com
 homepage: http://github.com/postmodern/hexdump
 has_yard: true
 
+required_ruby_version: ">= 1.8.7"
+
 development_dependencies:
   ore-tasks: ~> 0.4
   rspec: ~> 2.4

data/lib/hexdump/dumper.rb

@@ -0,0 +1,441 @@
+module Hexdump
+  #
+  # Handles the parsing of data and formatting of the hexdump.
+  #
+  # @since 0.2.0
+  #
+  class Dumper
+
+    # Widths for formatted numbers
+    WIDTHS = {
+      :hexadecimal => proc { |word_size| word_size * 2 },
+      :decimal => {
+        1 => 3,
+        2 => 5,
+        4 => 10,
+        8 => 20
+      },
+      :octal => {
+        1 => 3,
+        2 => 6,
+        4 => 11,
+        8 => 22
+      },
+      :binary => proc { |word_size| word_size * 8 }
+    }
+
+    # Format Strings for the various bases
+    FORMATS = {
+      :hexadecimal => proc { |width| "%.#{width}x" },
+      :decimal => proc { |width| "%#{width}.d" },
+      :octal => proc { |width| "%.#{width}o" },
+      :binary => proc { |width| "%.#{width}b" }
+    }
+
+    # Character to represent unprintable characters
+    UNPRINTABLE = '.'
+
+    # ASCII printable bytes and characters
+    PRINTABLE = {
+      0x20 => " ",
+      0x21 => "!",
+      0x22 => "\"",
+      0x23 => "#",
+      0x24 => "$",
+      0x25 => "%",
+      0x26 => "&",
+      0x27 => "'",
+      0x28 => "(",
+      0x29 => ")",
+      0x2a => "*",
+      0x2b => "+",
+      0x2c => ",",
+      0x2d => "-",
+      0x2e => ".",
+      0x2f => "/",
+      0x30 => "0",
+      0x31 => "1",
+      0x32 => "2",
+      0x33 => "3",
+      0x34 => "4",
+      0x35 => "5",
+      0x36 => "6",
+      0x37 => "7",
+      0x38 => "8",
+      0x39 => "9",
+      0x3a => ":",
+      0x3b => ";",
+      0x3c => "<",
+      0x3d => "=",
+      0x3e => ">",
+      0x3f => "?",
+      0x40 => "@",
+      0x41 => "A",
+      0x42 => "B",
+      0x43 => "C",
+      0x44 => "D",
+      0x45 => "E",
+      0x46 => "F",
+      0x47 => "G",
+      0x48 => "H",
+      0x49 => "I",
+      0x4a => "J",
+      0x4b => "K",
+      0x4c => "L",
+      0x4d => "M",
+      0x4e => "N",
+      0x4f => "O",
+      0x50 => "P",
+      0x51 => "Q",
+      0x52 => "R",
+      0x53 => "S",
+      0x54 => "T",
+      0x55 => "U",
+      0x56 => "V",
+      0x57 => "W",
+      0x58 => "X",
+      0x59 => "Y",
+      0x5a => "Z",
+      0x5b => "[",
+      0x5c => "\\",
+      0x5d => "]",
+      0x5e => "^",
+      0x5f => "_",
+      0x60 => "`",
+      0x61 => "a",
+      0x62 => "b",
+      0x63 => "c",
+      0x64 => "d",
+      0x65 => "e",
+      0x66 => "f",
+      0x67 => "g",
+      0x68 => "h",
+      0x69 => "i",
+      0x6a => "j",
+      0x6b => "k",
+      0x6c => "l",
+      0x6d => "m",
+      0x6e => "n",
+      0x6f => "o",
+      0x70 => "p",
+      0x71 => "q",
+      0x72 => "r",
+      0x73 => "s",
+      0x74 => "t",
+      0x75 => "u",
+      0x76 => "v",
+      0x77 => "w",
+      0x78 => "x",
+      0x79 => "y",
+      0x7a => "z",
+      0x7b => "{",
+      0x7c => "|",
+      0x7d => "}",
+      0x7e => "~"
+    }
+
+    PRINTABLE.default = UNPRINTABLE
+
+    # The base to dump words as.
+    attr_reader :base
+
+    # The size of the words parse from the data.
+    attr_reader :word_size
+
+    # The endianness of the words parsed from the data.
+    attr_reader :endian
+
+    # The width in words of each hexdump line.
+    attr_reader :width
+
+    # Whether to display ASCII characters alongside numeric values.
+    attr_reader :ascii
+
+    #
+    # Creates a new Hexdump dumper.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [Integer] :width (16)
+    #   The number of bytes to dump for each line.
+    #
+    # @option options [Integer] :word_size (1)
+    #   The number of bytes within a word.
+    #
+    # @option options [Symbol, Integer] :base (:hexadecimal)
+    #   The base to print bytes in. Supported bases include, `:hexadecimal`,
+    #   `:hex`, `16, `:decimal`, `:dec`, `10, `:octal`, `:oct`, `8`,
+    #   `:binary`, `:bin` and `2`.
+    #
+    # @option options [Boolean] :ascii (false)
+    #   Print ascii characters when possible.
+    #
+    # @raise [ArgumentError]
+    #   The values for `:base` or `:endian` were unknown.
+    #
+    # @since 0.2.0
+    #
+    def initialize(options={})
+      @base = case options[:base]
+              when :hexadecimal, :hex, 16
+                :hexadecimal
+              when :decimal, :dec, 10
+                :decimal
+              when :octal, :oct, 8
+                :octal
+              when :binary, :bin, 2
+                :binary
+              when nil
+                :hexadecimal
+              else
+                raise(ArgumentError,"unknown base #{options[:base].inspect}")
+              end
+
+      @word_size = options.fetch(:word_size,1)
+      @endian = case options[:endian]
+                when 'little', :little
+                  :little
+                when 'big', :big
+                  :big
+                when nil
+                  :little
+                else
+                  raise(ArgumentError,"unknown endian: #{options[:endian].inspect}")
+                end
+
+      @width = (options.fetch(:width,16) / @word_size)
+      @ascii = options.fetch(:ascii,false)
+
+      @format_width = (WIDTHS[@base][@word_size] || 1)
+      @format = FORMATS[@base][@format_width]
+
+      if @word_size == 1
+        @format_cache = Hash.new do |hash,key|
+          hash[key] = sprintf(@format,key)
+        end
+      end
+    end
+    
+    #
+    # Iterates over every word within the data.
+    #
+    # @param [#each_byte] data
+    #   The data containing bytes.
+    #
+    # @yield [word]
+    #   The given block will be passed each word within the data.
+    #
+    # @yieldparam [Integer]
+    #   An unpacked word from the data.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator will be returned.
+    #
+    # @raise [ArgumentError]
+    #   The given data does not define the `#each_byte` method.
+    #
+    # @since 0.2.0
+    #
+    def each_word(data,&block)
+      return enum_for(:each_word,data) unless block
+
+      unless data.respond_to?(:each_byte)
+        raise(ArgumentError,"the data to hexdump must define #each_byte")
+      end
+
+      if @word_size > 1
+        word = 0
+        count = 0
+
+        init_shift = if @endian == :big
+                       ((@word_size - 1) * 8)
+                     else
+                       0
+                     end
+        shift = init_shift
+
+        data.each_byte do |b|
+          word |= (b << shift)
+
+          if @endian == :big
+            shift -= 8
+          else
+            shift += 8
+          end
+
+          count += 1
+
+          if count >= @word_size
+            yield word
+
+            word = 0
+            count = 0
+            shift = init_shift
+          end
+        end
+
+        # yield the remaining word
+        yield word if count > 0
+      else
+        data.each_byte(&block)
+      end
+    end
+
+    #
+    # Iterates over the hexdump.
+    #
+    # @param [#each_byte] data
+    #   The data to be hexdumped.
+    #
+    # @yield [index,numeric,printable]
+    #   The given block will be passed the hexdump break-down of each
+    #   segment.
+    #
+    # @yieldparam [Integer] index
+    #   The index of the hexdumped segment.
+    #
+    # @yieldparam [Array<String>] numeric
+    #   The numeric representation of the segment.
+    #
+    # @yieldparam [Array<String>] printable
+    #   The printable representation of the segment.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator will be returned.
+    #
+    # @since 0.2.0
+    #
+    def each(data)
+      return enum_for(:each,data) unless block_given?
+
+      index = 0
+      count = 0
+
+      numeric = []
+      printable = []
+
+      each_word(data) do |word|
+        numeric << format_numeric(word)
+        printable << format_printable(word)
+
+        count += 1
+
+        if count >= @width
+          yield(index,numeric,printable)
+
+          numeric.clear
+          printable.clear
+
+          index += (@width * @word_size)
+          count = 0
+        end
+      end
+
+      if count > 0
+        # yield the remaining data
+        yield(index,numeric,printable)
+      end
+    end
+
+    #
+    # Dumps the hexdump.
+    #
+    # @param [#each_byte] data
+    #   The data to be hexdumped.
+    #
+    # @param [#<<] output
+    #   The output to dump the hexdump to.
+    #
+    # @return [nil]
+    #
+    # @raise [ArgumentError]
+    #   The output value does not support the `#<<` method.
+    #
+    # @since 0.2.0
+    #
+    def dump(data,output=STDOUT)
+      unless output.respond_to?(:<<)
+        raise(ArgumentError,"output must support the #<< method")
+      end
+
+      bytes_segment_width = ((@width * @format_width) + @width)
+      line_format = "%.8x  %-#{bytes_segment_width}s |%s|\n"
+
+      index = 0
+      count = 0
+
+      numeric = ''
+      printable = ''
+
+      each_word(data) do |word|
+        numeric << format_numeric(word) << ' '
+        printable << format_printable(word)
+
+        count += 1
+
+        if count >= @width
+          output << sprintf(line_format,index,numeric,printable)
+
+          numeric = ''
+          printable = ''
+
+          index += (@width * @word_size)
+          count = 0
+        end
+      end
+
+      if count > 0
+        # output the remaining line
+        output << sprintf(line_format,index,numeric,printable)
+      end
+    end
+
+    protected
+
+    #
+    # Converts the word into a numeric String.
+    #
+    # @param [Integer] word
+    #   The word to convert.
+    #
+    # @return [String]
+    #   The numeric representation of the word.
+    #
+    # @since 0.2.0
+    #
+    def format_numeric(word)
+      if @word_size == 1
+        if (@ascii && (word >= 0x20 && word <= 0x7e))
+          PRINTABLE[word]
+        else
+          @format_cache[word]
+        end
+      else
+        sprintf(@format,word)
+      end
+    end
+
+    #
+    # Converts a word into a printable String.
+    #
+    # @param [Integer] word
+    #   The word to convert.
+    #
+    # @return [String]
+    #   The printable representation of the word.
+    #
+    # @since 0.2.0
+    #
+    def format_printable(word)
+      if @word_size == 1
+        PRINTABLE[word]
+      elsif (RUBY_VERSION > '1.9.' && (word >= -2 && word <= 0x7fffffff))
+        word.chr(Encoding::UTF_8)
+      else
+        UNPRINTABLE
+      end
+    end
+
+  end
+end

data/lib/hexdump/hexdump.rb

@@ -1,3 +1,5 @@
+require 'hexdump/dumper'
+
 #
 # Provides the {Hexdump.dump} method and can add hexdumping to other classes
 # by including the {Hexdump} module.
@@ -28,6 +30,9 @@ module Hexdump
   # @option options [Integer] :width (16)
   #   The number of bytes to dump for each line.
   #
+  # @option options [Integer] :word_size (1)
+  #   The number of bytes within a word.
+  #
   # @option options [Symbol, Integer] :base (:hexadecimal)
   #   The base to print bytes in. Supported bases include, `:hexadecimal`,
   #   `:hex`, `16, `:decimal`, `:dec`, `10, `:octal`, `:oct`, `8`,
@@ -39,89 +44,36 @@ module Hexdump
   # @option options [#<<] :output (STDOUT)
   #   The output to print the hexdump to.
   #
-  # @yield [index,hex_segment,print_segment]
-  #   The given block will be passed the hexdump break-down of each segment.
+  # @yield [index,numeric,printable]
+  #   The given block will be passed the hexdump break-down of each
+  #   segment.
   #
   # @yieldparam [Integer] index
   #   The index of the hexdumped segment.
   #
-  # @yieldparam [Array<String>] hex_segment
-  #   The hexadecimal-byte representation of the segment.
+  # @yieldparam [Array<String>] numeric
+  #   The numeric representation of the segment.
   #
-  # @yieldparam [Array<String>] print_segment
-  #   The print-character representation of the segment.
+  # @yieldparam [Array<String>] printable
+  #   The printable representation of the segment.
   #
   # @return [nil]
   #
   # @raise [ArgumentError]
-  #   The given data does not define the `#each_byte` method, or
-  #   the `:output` value does not support the `#<<` method.
+  #   The given data does not define the `#each_byte` method,
+  #   the `:output` value does not support the `#<<` method or
+  #   the `:base` value was unknown.
   #
-  def Hexdump.dump(data,options={})
-    unless data.respond_to?(:each_byte)
-      raise(ArgumentError,"the data to hexdump must define #each_byte")
-    end
-
-    output = options.fetch(:output,STDOUT)
-
-    unless output.respond_to?(:<<)
-      raise(ArgumentError,":output must support the #<< method")
-    end
-
-    width = options.fetch(:width,16)
-    base = options.fetch(:base,:hexadecimal)
-    ascii = options.fetch(:ascii,false)
-    byte_width, byte_format = case base
-                              when :hexadecimal, :hex, 16
-                                [2, "%.2x"]
-                              when :decimal, :dec, 10
-                                [3, "%3.d"]
-                              when :octal, :oct, 8
-                                [4, "0%.3o"]
-                              when :binary, :bin, 2
-                                [8, "%.8b"]
-                              end
-
-    hex_byte = lambda { |byte|
-      if (ascii && (byte >= 0x20 && byte <= 0x7e))
-        byte.chr
-      else
-        byte_format % byte
-      end
-    }
-
-    print_byte = lambda { |byte|
-      if (byte >= 0x20 && byte <= 0x7e)
-        byte.chr
-      else
-        '.'
-      end
-    }
-
-    index = 0
-
-    hex_segment_width = ((width * byte_width) + (width - 1))
-    line_format = "%.8x  %-#{hex_segment_width}s  |%s|\n"
-
-    data.each_byte.each_slice(width) do |bytes|
-      hex_segment = bytes.map(&hex_byte)
-      print_segment = bytes.map(&print_byte)
-
-      if block_given?
-        yield(index,hex_segment,print_segment)
-      else
-        output << sprintf(
-          line_format,
-          index,
-          hex_segment.join(' '),
-          print_segment.join
-        )
-      end
+  def Hexdump.dump(data,options={},&block)
+    output = (options.delete(:output) || STDOUT)
+    dumper = Dumper.new(options)
 
-      index += width
+    if block
+      dumper.each(data,&block)
+    else
+      dumper.dump(data,output)
     end
 
-    # flush the hexdump buffer
     return nil
   end
 

data/spec/dumper_spec.rb

@@ -0,0 +1,260 @@
+require 'spec_helper'
+
+require 'hexdump/dumper'
+
+describe Hexdump::Dumper do
+  let(:bytes) { [104, 101, 108, 108, 111] }
+  let(:hex_chars) { ['68', '65', '6c', '6c', '6f'] }
+  let(:decimal_chars) { ['104', '101', '108', '108', '111'] }
+  let(:octal_chars) { ['150', '145', '154', '154', '157'] }
+  let(:binary_chars) { ['01101000', '01100101', '01101100', '01101100', '01101111'] }
+  let(:print_chars) { ['h', 'e', 'l', 'l', 'o'] }
+  let(:data) { print_chars.join }
+
+  it "should only accept known :base values" do
+    lambda {
+      described_class.new(data, :base => :foo)
+    }.should raise_error(ArgumentError)
+  end
+
+  it "should only accept known :endian values" do
+    lambda {
+      described_class.new(data, :endian => :foo)
+    }.should raise_error(ArgumentError)
+  end
+
+  describe "each_word" do
+    let(:data) { 'ABAB' }
+    let(:bytes) { [0x41, 0x42, 0x41, 0x42] }
+    let(:shorts_le) { [0x4241, 0x4241] }
+    let(:shorts_be) { [0x4142, 0x4142] }
+    let(:custom_words) { [0x414241, 0x42] }
+
+    it "should check if the data defines '#each_byte'" do
+      lambda {
+        subject.each_word(Object.new).to_a
+      }.should raise_error(ArgumentError)
+    end
+
+    it "should iterate over each byte by default" do
+      subject.each_word(data).to_a.should == bytes
+    end
+
+    it "should allow iterating over custom word-sizes" do
+      dumper = described_class.new(:word_size => 3)
+
+      dumper.each_word(data).to_a.should == custom_words
+    end
+
+    it "should iterate over little-endian words by default" do
+      dumper = described_class.new(:word_size => 2)
+
+      dumper.each_word(data).to_a.should == shorts_le
+    end
+
+    it "should iterate over big-endian words" do
+      dumper = described_class.new(:word_size => 2, :endian => :big)
+
+      dumper.each_word(data).to_a.should == shorts_be
+    end
+  end
+
+  describe "#each" do
+    it "should yield the parts of each hexdump line to the given block" do
+      lines = []
+
+      subject.each(data) do |index,hex,print|
+        lines << [index, hex, print]
+      end
+
+      lines.length.should == 1
+      lines[0][0].should == 0
+      lines[0][1].should == hex_chars
+      lines[0][2].should == print_chars
+    end
+
+    it "should provide the index within the data for each line" do
+      dumper = described_class.new(:width => 10)
+      indices = []
+
+      dumper.each('A' * 100) do |index,hex,print|
+        indices << index
+      end
+
+      indices.should == [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]
+    end
+
+    it "should allow configuring the width, in bytes, of each line" do
+      dumper = described_class.new(:width => 10)
+      widths = []
+
+      dumper.each('A' * 100) do |index,hex,print|
+        widths << hex.length
+      end
+
+      widths.should == ([10] * 10)
+    end
+
+    it "should hexdump the remaining bytes" do
+      dumper = described_class.new(:width => 10)
+      chars = (['B'] * 4)
+      string = chars.join
+      leading = ('A' * 100)
+      remainder = nil
+
+      dumper.each(leading + string) do |index,hex,print|
+        remainder = print
+      end
+
+      remainder.should == chars
+    end
+
+    it "should provide the hexadecimal characters for each line" do
+      dumper = described_class.new(:width => 10)
+      chars = []
+
+      dumper.each(data * 100) do |index,hex,print|
+        chars += hex
+      end
+
+      chars.should == (hex_chars * 100)
+    end
+
+    it "should allow printing ASCII characters in place of hex characters" do
+      dumper = described_class.new(:ascii => true)
+      chars = []
+
+      dumper.each(data) do |index,hex,print|
+        chars += hex
+      end
+
+      chars.should == print_chars
+    end
+
+    it "should provide the print characters for each line" do
+      dumper = described_class.new(:width => 10)
+      chars = []
+
+      dumper.each(data * 100) do |index,hex,print|
+        chars += print
+      end
+
+      chars.should == (print_chars * 100)
+    end
+
+    it "should map unprintable characters to '.'" do
+      unprintable = ((0x00..0x1f).map(&:chr) + (0x7f..0xff).map(&:chr)).join
+      chars = []
+
+      subject.each(unprintable) do |index,hex,print|
+        chars += print
+      end
+
+      chars.should == (['.'] * unprintable.length)
+    end
+
+    it "should support dumping bytes in decimal format" do
+      dumper = described_class.new(:base => :decimal)
+      chars = []
+
+      dumper.each(data) do |index,hex,print|
+        chars += hex
+      end
+
+      chars.should == decimal_chars
+    end
+
+    it "should support dumping bytes in octal format" do
+      dumper = described_class.new(:base => :octal)
+      chars = []
+
+      dumper.each(data) do |index,hex,print|
+        chars += hex
+      end
+
+      chars.should == octal_chars
+    end
+
+    it "should support dumping bytes in binary format" do
+      dumper = described_class.new(:base => :binary)
+      chars = []
+
+      dumper.each(data) do |index,hex,print|
+        chars += hex
+      end
+
+      chars.should == binary_chars
+    end
+
+    context ":word_size" do
+      let(:options) { {:word_size => 2, :endian => :little} }
+
+      let(:hex_words) { ['6568', '6c6c', '006f'] }
+      let(:decimal_words) { ['25960', '27756', '  111'] }
+      let(:octal_words) { ['062550', '066154', '000157'] }
+      let(:binary_words) { ['0110010101101000', '0110110001101100', '0000000001101111'] }
+
+      it "should dump words in hexadecimal" do
+        dumper = described_class.new(options)
+        words = []
+
+        dumper.each(data) do |index,hex,print|
+          words += hex
+        end
+
+        words.should == hex_words
+      end
+
+      it "should dump words in decimal" do
+        dumper = described_class.new(options.merge(:base => :decimal))
+        words = []
+
+        dumper.each(data) do |index,dec,print|
+          words += dec
+        end
+
+        words.should == decimal_words
+      end
+
+      it "should dump words in octal" do
+        dumper = described_class.new(options.merge(:base => :octal))
+        words = []
+
+        dumper.each(data) do |index,oct,print|
+          words += oct
+        end
+
+        words.should == octal_words
+      end
+
+      it "should dump words in binary" do
+        dumper = described_class.new(options.merge(:base => :binary))
+        words = []
+
+        dumper.each(data) do |index,bin,print|
+          words += bin
+        end
+
+        words.should == binary_words
+      end
+    end
+  end
+
+  describe "#dump" do
+    it "should check if the :output supports the '#<<' method" do
+      lambda {
+        subject.dump(data,Object.new)
+      }.should raise_error(ArgumentError)
+    end
+
+    it "should append each line of the hexdump to the output" do
+      lines = []
+
+      subject.dump(data,lines)
+
+      lines.length.should == 1
+      lines[0].should include(hex_chars.join(' '))
+      lines[0].should include(print_chars.join)
+    end
+  end
+end

data/spec/hexdump_spec.rb

@@ -1,159 +1,17 @@
 require 'spec_helper'
+
 require 'hexdump'
 
 describe Hexdump do
-  let(:bytes) { [104, 101, 108, 108, 111] }
-  let(:hex_chars) { ['68', '65', '6c', '6c', '6f'] }
-  let(:decimal_chars) { ['104', '101', '108', '108', '111'] }
-  let(:octal_chars) { ['0150', '0145', '0154', '0154', '0157'] }
-  let(:binary_chars) { ['01101000', '01100101', '01101100', '01101100', '01101111'] }
-  let(:print_chars) { ['h', 'e', 'l', 'l', 'o'] }
-  let(:data) { print_chars.join }
-
-  describe "dump" do
-    it "should check if the data defines '#each_byte'" do
-      lambda {
-        subject.dump(Object.new)
-      }.should raise_error(ArgumentError)
-    end
-
-    it "should check if the :output supports the '#<<' method" do
-      lambda {
-        subject.dump(data, :output => Object.new)
-      }.should raise_error(ArgumentError)
-    end
-
-    it "should append each line of the hexdump to the output" do
-      lines = []
-      subject.dump(data, :output => lines)
-
-      lines.length.should == 1
-      lines[0].should include(hex_chars.join(' '))
-      lines[0].should include(print_chars.join)
-    end
-
-    it "should yield the parts of each hexdump line to the given block" do
-      lines = []
-
-      subject.dump(data) do |index,hex,print|
-        lines << [index, hex, print]
-      end
-
-      lines.length.should == 1
-      lines[0][0].should == 0
-      lines[0][1].should == hex_chars
-      lines[0][2].should == print_chars
-    end
-
-    it "should provide the index within the data for each line" do
-      indices = []
-
-      subject.dump('A' * 100, :width => 10) do |index,hex,print|
-        indices << index
-      end
-
-      indices.should == [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]
-    end
-
-    it "should allow configuring the width, in bytes, of each line" do
-      widths = []
-
-      subject.dump('A' * 100, :width => 10) do |index,hex,print|
-        widths << hex.length
-      end
-
-      widths.should == ([10] * 10)
-    end
-
-    it "should hexdump the remaining bytes" do
-      chars = (['B'] * 4)
-      string = chars.join
-      leading = ('A' * 100)
-      remainder = nil
-
-      subject.dump(leading + string, :width => 10) do |index,hex,print|
-        remainder = print
-      end
-
-      remainder.should == chars
-    end
-
-    it "should provide the hexadecimal characters for each line" do
-      chars = []
-
-      subject.dump(data * 100, :width => 10) do |index,hex,print|
-        chars += hex
-      end
-
-      chars.should == (hex_chars * 100)
-    end
-
-    it "should allow printing ASCII characters in place of hex characters" do
-      chars = []
-
-      subject.dump(data, :ascii => true) do |index,hex,print|
-        chars += hex
-      end
-
-      chars.should == print_chars
-    end
-
-    it "should provide the print characters for each line" do
-      chars = []
-
-      subject.dump(data * 100, :width => 10) do |index,hex,print|
-        chars += print
-      end
-
-      chars.should == (print_chars * 100)
-    end
-
-    it "should map unprintable characters to '.'" do
-      unprintable = ((0x00..0x1f).map(&:chr) + (0x7f..0xff).map(&:chr)).join
-      chars = []
-
-      subject.dump(unprintable) do |index,hex,print|
-        chars += print
-      end
-
-      chars.should == (['.'] * unprintable.length)
-    end
-
-    it "should support dumping bytes in decimal format" do
-      chars = []
-
-      subject.dump(data, :base => :decimal) do |index,hex,print|
-        chars += hex
-      end
-
-      chars.should == decimal_chars
-    end
-
-    it "should support dumping bytes in octal format" do
-      chars = []
-
-      subject.dump(data, :base => :octal) do |index,hex,print|
-        chars += hex
-      end
-
-      chars.should == octal_chars
-    end
-
-    it "should support dumping bytes in binary format" do
-      chars = []
-
-      subject.dump(data, :base => :binary) do |index,hex,print|
-        chars += hex
-      end
-
-      chars.should == binary_chars
-    end
-  end
-
   describe "#hexdump" do
+    let(:bytes) { [104, 101, 108, 108, 111] }
+    let(:hex_chars) { ['68', '65', '6c', '6c', '6f'] }
+
     subject do
       obj = Object.new.extend(Hexdump)
-      obj.stub!(:each_byte).and_return(bytes.enum_for(:each))
+
+      stub = obj.stub!(:each_byte)
+      bytes.each { |b| stub = stub.and_yield(b) }
 
       obj
     end

metadata

@@ -2,16 +2,15 @@
 name: hexdump
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors: 
-- hal
+- Postmodern
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2011-03-05 00:00:00 -08:00
-default_executable: 
+date: 2011-06-11 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: ore-tasks
@@ -70,16 +69,17 @@ files:
 - gemspec.yml
 - hexdump.gemspec
 - lib/hexdump.rb
+- lib/hexdump/dumper.rb
 - lib/hexdump/extensions.rb
 - lib/hexdump/extensions/file.rb
 - lib/hexdump/extensions/io.rb
 - lib/hexdump/extensions/string.rb
 - lib/hexdump/extensions/string_io.rb
 - lib/hexdump/hexdump.rb
+- spec/dumper_spec.rb
 - spec/extensions_spec.rb
 - spec/hexdump_spec.rb
 - spec/spec_helper.rb
-has_rdoc: yard
 homepage: http://github.com/postmodern/hexdump
 licenses: 
 - MIT
@@ -93,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: "0"
+      version: 1.8.7
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
@@ -103,10 +103,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: hexdump
-rubygems_version: 1.5.2
+rubygems_version: 1.8.1
 signing_key: 
 specification_version: 3
-summary: Simple and Fast hexdumping for Ruby.
+summary: Hexdump Strings and IO objects.
 test_files: 
+- spec/dumper_spec.rb
 - spec/hexdump_spec.rb
 - spec/extensions_spec.rb