hexdump 0.1.0

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.*
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "hexdump Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,10 @@
+### 0.1.0 / 2011-03-05
+
+* Initial release:
+  * Can hexdump any Object supporting the `each_byte` method.
+  * Can send the hexdump output to any Object supporting the `<<` method.
+  * Can yield each line of hexdump, instead of printing the output.
+  * Supports printing hexadecimal, decimal, octal and binary bytes.
+  * Makes {String}, {StringIO}, {IO}, {File} objects hexdumpable.
+  * Fast-ish.
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# hexdump
+
+* [Homepage](http://github.com/postmoderm/hexdump)
+* [Issues](http://github.com/postmoderm/hexdump/issues)
+* [Documentation](http://rubydoc.info/gems/hexdump/frames)
+* [Email](mailto:postmodern.mod3 at gmail.com)
+
+## Description
+
+Simple and Fast hexdumping for Ruby.
+
+## Features
+
+* Can hexdump any Object supporting the `each_byte` method.
+* 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.
+* 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'
+
+    data = "hello\x00"
+
+    Hexdump.dump(data)
+    # 00000000  68 65 6c 6c 6f 00                                |hello.|
+    
+    data.hexdump
+    # 00000000  68 65 6c 6c 6f 00                                |hello.|
+
+    # iterate over the hexdump lines
+    data.hexdump do |index,hex,printable|
+      index     # => 0
+      hex       # => ["68", "65", "6c", "6c", "6f", "00"]
+      printable # => ["h", "e", "l", "l", "o", "."]
+    end
+
+    # configure the width of the hexdump
+    Hexdump.dump('A' * 30, :width => 10)
+    # 00000000  41 41 41 41 41 41 41 41 41 41  |AAAAAAAAAA|
+    # 0000000a  41 41 41 41 41 41 41 41 41 41  |AAAAAAAAAA|
+    # 00000014  41 41 41 41 41 41 41 41 41 41  |AAAAAAAAAA|
+
+    Hexdump.dump(data, :ascii => true)
+    # 00000000  h e l l o 00                                     |hello.|
+
+    Hexdump.dump(data, :base => 16)
+    # 00000000  68 65 6c 6c 6f 00                                |hello.|
+
+    Hexdump.dump(data, :base => :decimal)
+    # 00000000  104 101 108 108 111   0                                          |hello.|
+
+    Hexdump.dump(data, :base => :octal)
+    # 00000000  0150 0145 0154 0154 0157 0000                                                    |hello.|
+
+    Hexdump.dump(data, :base => :binary)
+    # 00000000  01101000 01100101 01101100 01101100 01101111 00000000                                                                                            |hello.|
+
+## Install
+
+    $ gem install hexdump
+
+## Copyright
+
+Copyright (c) 2011 Hal Brodigan
+
+See {file:LICENSE.txt} for details.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  gem 'ore-tasks', '~> 0.4'
+  require 'ore/tasks'
+
+  Ore::Tasks.new
+rescue LoadError => e
+  STDERR.puts e.message
+  STDERR.puts "Run `gem install ore-tasks` to install 'ore/tasks'."
+end
+
+begin
+  gem 'rspec', '~> 2.4'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new
+rescue LoadError => e
+  task :spec do
+    abort "Please run `gem install rspec` to install RSpec."
+  end
+end
+
+task :test => :spec
+task :default => :spec
+
+begin
+  gem 'yard', '~> 0.6.0'
+  require 'yard'
+
+  YARD::Rake::YardocTask.new  
+rescue LoadError => e
+  task :yard do
+    abort "Please run `gem install yard` to install YARD."
+  end
+end
+task :doc => :yard

data/benchmarks/hexdump.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__),'..','lib'))
+
+require 'hexdump'
+require 'benchmark'
+
+DATA = ((0..255).map { |b| b.chr }.join) * 10000
+OUTPUT = Class.new { def <<(data); end }.new
+
+Benchmark.bm(26) do |b|
+  b.report('hexdump (block)') do
+    Hexdump.dump(DATA) { |index,hex,print| }
+  end
+
+  b.report('hexdump') do
+    Hexdump.dump(DATA, :output => OUTPUT)
+  end
+
+  b.report('hexdump width=256 (block)') do
+    Hexdump.dump(DATA, :width => 256) { |index,hex,print| }
+  end
+
+  b.report('hexdump width=256') do
+    Hexdump.dump(DATA, :width => 256, :output => OUTPUT)
+  end
+
+  b.report('hexdump ascii=true (block)') do
+    Hexdump.dump(DATA, :ascci => true) { |index,hex,print| }
+  end
+
+  b.report('hexdump ascii=true') do
+    Hexdump.dump(DATA, :ascci => true, :output => OUTPUT)
+  end
+end

data/gemspec.yml

@@ -0,0 +1,14 @@
+name: hexdump
+version: 0.1.0
+summary: Simple and Fast hexdumping for Ruby.
+description: Simple and Fast hexdumping for Ruby.
+license: MIT
+authors: hal
+email: postmodern.mod3@gmail.com
+homepage: http://github.com/postmodern/hexdump
+has_yard: true
+
+development_dependencies:
+  ore-tasks: ~> 0.4
+  rspec: ~> 2.4
+  yard: ~> 0.6.0

data/hexdump.gemspec

@@ -0,0 +1,15 @@
+# -*- encoding: utf-8 -*-
+
+begin
+  Ore::Specification.new do |gemspec|
+    # custom logic here
+  end
+rescue NameError
+  begin
+    require 'ore/specification'
+    retry
+  rescue LoadError
+    STDERR.puts "The '#{__FILE__}' file requires Ore."
+    STDERR.puts "Run `gem install ore-core` to install Ore."
+  end
+end

data/lib/hexdump.rb

@@ -0,0 +1,2 @@
+require 'hexdump/hexdump'
+require 'hexdump/extensions'

data/lib/hexdump/extensions.rb

@@ -0,0 +1,4 @@
+require 'hexdump/extensions/string'
+require 'hexdump/extensions/string_io'
+require 'hexdump/extensions/io'
+require 'hexdump/extensions/file'

data/lib/hexdump/extensions/file.rb

@@ -0,0 +1,22 @@
+require 'hexdump/hexdump'
+
+class File
+
+  #
+  # Hexdumps the contents of a file.
+  #
+  # @param [String] path
+  #   The path of the file.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @see Hexdump.dump
+  #
+  def self.hexdump(path,options={},&block)
+    self.open(path,'rb') do |file|
+      Hexdump.dump(file,options,&block)
+    end
+  end
+
+end

data/lib/hexdump/extensions/io.rb

@@ -0,0 +1,7 @@
+require 'hexdump/hexdump'
+
+class IO
+
+  include Hexdump
+
+end

data/lib/hexdump/extensions/string.rb

@@ -0,0 +1,7 @@
+require 'hexdump/hexdump'
+
+class String
+
+  include Hexdump
+
+end

data/lib/hexdump/extensions/string_io.rb

@@ -0,0 +1,9 @@
+require 'hexdump/hexdump'
+
+require 'stringio'
+
+class StringIO
+
+  include Hexdump
+
+end

data/lib/hexdump/hexdump.rb

@@ -0,0 +1,139 @@
+#
+# Provides the {Hexdump.dump} method and can add hexdumping to other classes
+# by including the {Hexdump} module.
+#
+#     class AbstractData
+#     
+#       include Hexdump
+#       
+#       def each_byte
+#         # ...
+#       end
+#     
+#     end
+#     
+#     data = AbstractData.new
+#     data.hexdump
+#
+module Hexdump
+  #
+  # Hexdumps the given data.
+  #
+  # @param [#each_byte] data
+  #   The data to be hexdumped.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Integer] :width (16)
+  #   The number of bytes to dump for each line.
+  #
+  # @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.
+  #
+  # @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.
+  #
+  # @yieldparam [Integer] index
+  #   The index of the hexdumped segment.
+  #
+  # @yieldparam [Array<String>] hex_segment
+  #   The hexadecimal-byte representation of the segment.
+  #
+  # @yieldparam [Array<String>] print_segment
+  #   The print-character 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.
+  #
+  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
+
+      index += width
+    end
+
+    # flush the hexdump buffer
+    return nil
+  end
+
+  #
+  # Hexdumps the object.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @see Hexdump.dump
+  #
+  def hexdump(options={},&block)
+    Hexdump.dump(self,options,&block)
+  end
+end

data/spec/extensions_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+require 'hexdump/extensions'
+
+describe "Hexdump extensions" do
+  it "should include Hexdump into String" do
+    String.should include(Hexdump)
+  end
+
+  it "should include Hexdump into StringIO" do
+    StringIO.should include(Hexdump)
+  end
+
+  it "should include Hexdump into IO" do
+    IO.should include(Hexdump)
+  end
+
+  it "should define File.hexdump" do
+    File.should respond_to(:hexdump)
+  end
+end

data/spec/hexdump_spec.rb

@@ -0,0 +1,171 @@
+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
+    subject do
+      obj = Object.new.extend(Hexdump)
+      obj.stub!(:each_byte).and_return(bytes.enum_for(:each))
+
+      obj
+    end
+
+    it "should hexdump the object" do
+      chars = []
+
+      subject.hexdump do |index,hex,print|
+        chars += hex
+      end
+
+      chars.should == hex_chars
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+gem 'rspec', '~> 2.4'
+require 'rspec'

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: hexdump
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- hal
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-05 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ore-tasks
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "0.4"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.4"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.6.0
+  type: :development
+  version_requirements: *id003
+description: Simple and Fast hexdumping for Ruby.
+email: 
+- postmodern.mod3@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+- ChangeLog.md
+- LICENSE.txt
+files: 
+- .document
+- .gemtest
+- .rspec
+- .yardopts
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmarks/hexdump.rb
+- gemspec.yml
+- hexdump.gemspec
+- lib/hexdump.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/extensions_spec.rb
+- spec/hexdump_spec.rb
+- spec/spec_helper.rb
+has_rdoc: yard
+homepage: http://github.com/postmodern/hexdump
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: hexdump
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Simple and Fast hexdumping for Ruby.
+test_files: 
+- spec/hexdump_spec.rb
+- spec/extensions_spec.rb