hexy 0.1.0

data/LICENSE

@@ -0,0 +1,58 @@
+This package is copyrighted free software by Tim Becker <tim@kuriositaet.de>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README

@@ -0,0 +1,79 @@
+
+= hexy -- utility to create hex dumps 
+
+`hexy` is a ruby library that's easy to use to create hex dumps from 
+within your ruby scripts. It contains a number of options to configure
+how the hex dumb will end up looking.
+
+It should create a pleasant looking hex dumb by default:
+
+   b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789"
+   puts b.to_s
+
+results in this dump:
+
+	0000000: 00 01 03 05 1f 0a 09 62   63 64 65 66 67 68 69 6a  .......b cdefghij 
+	0000010: 6b 6c 6d 6e 6f 70 71 72   73 74 75 76 77 78 79 7a  klmnopqr stuvwxyz 
+	0000020: 30 31 32 33 34 35 36 37   38 39                    01234567 89
+
+but it's also possible to configure:
+
+* Line numbering
+* Line width
+* Format
+* Case of hex decimals
+* Presence of the ASCII annotation in the right column.
+
+This mean you can do exciting dumps like:
+
+	0000000: 0001 0305 1f0a 0962  .... ...b 
+	0000008: 6364 6566 6768 696a  cdef ghij 
+	0000010: 6b6c 6d6e 6f70 7172  klmn opqr 
+	0000018: 7374 7576 7778 797a  stuv wxyz 
+	0000020: 3031 3233 3435 3637  0123 4567 
+	0000028: 3839                 89
+
+or even:
+
+	0000000: 00 01 03 05 1f 0a 09 62   63 64 65 66 67 68 69 6a 
+	0000010: 6b 6c 6d 6e 6f 70 71 72   73 74 75 76 77 78 79 7a 
+	0000020: 30 31 32 33 34 35 36 37   38 39
+
+with hexy!
+   
+
+== Installing
+
+Having a "Installing" section is a bit of a chicken or egg question.
+Someone reading this README has, in all likelyhood already installed the
+package. 
+
+ You can install the +hexy+ package by executing:
+
+	gem install hexy -r
+
+alternatively, you can download +.tar.gz+ or +.zip+ archives from 
+Rubyforge[http://rubyforge.org/frs/?group_id=2203].
+
+
+== Mail
+
+In case you discover bugs, spelling errors, offer suggestions for
+improvements or would like to help out with the project, you can contact
+me directly (tim@kuriositaet.de).	
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+=

data/Rakefile

@@ -0,0 +1,124 @@
+require "rake/rdoctask"
+require "rake/gempackagetask"
+require "rake/testtask"
+require "rake/clean"
+require "rubygems"
+
+# Some definitions that you'll need to edit in case you reuse this
+# Rakefile for your own project.
+
+SHORTNAME	='hexy'	# this should be the rubyforge project name
+DESC		='Utility for hexdumps'
+PKG_VERSION 	='0.1.0'
+LONG_DESC	= <<END_DESC
+	This is a short project description.
+END_DESC
+RUBYFORGE_USER	='a2800276'
+
+# Specifies the default task to execute. This is often the "test" task
+# and we'll change things around as soon as we have some tests.
+
+task  :default => [:rdoc]
+
+# The directory to generate +rdoc+ in.
+RDOC_DIR="doc/html"
+
+# This global variable contains files that will be erased by the `clean` task.
+# The `clean` task itself is automatically generated by requiring `rake/clean`.
+
+CLEAN << RDOC_DIR << "pkg"
+
+
+# This is the task that generates the +rdoc+ documentation from the
+# source files. Instantiating Rake::RDocTask automatically generates a
+# task called `rdoc`.
+
+Rake::RDocTask.new do |rd|
+	# Options for documenation generation are specified inside of
+	# this block. For example the following line specifies that the
+	# content of the README file should be the main page of the
+	# documenation.
+	rd.main = "README" 
+	
+	# The following line specifies all the files to extract
+	# documenation from.
+	rd.rdoc_files.include(	"README", "AUTHORS", "LICENSE", "TODO",
+				"CHANGELOG", "bin/**/*", "lib/**/*.rb", 
+				"examples/**/*rb","test/**/*.rb", "doc/*.rdoc")
+	# This one specifies the output directory ...
+	rd.rdoc_dir 	= "doc/html"
+
+	# Or the HTML title of the generated documentation set.
+	rd.title 	= "#{SHORTNAME}: #{DESC}"
+
+	# These are options specifiying how source code inlined in the
+	# documentation should be formatted.
+	
+	rd.options 	= ["--line-numbers", "--inline-source"]
+
+	# Check:
+	# `rdoc --help` for more rdoc options
+	# the {rdoc documenation home}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
+	# or the documentation for the +Rake::RDocTask+ task[http://rake.rubyforge.org/classes/Rake/RDocTask.html]
+end
+
+# The GemPackageTask facilitates getting all your files collected
+# together into gem archives. You can also use it to generate tarball
+# and zip archives.
+
+# First you'll need to assemble a gemspec
+
+PKG_FILES 	= FileList['lib/**/*.rb', 'bin/**/*', 'examples/**/*', '[A-Z]*', 'test/**/*'].to_a
+
+spec = Gem::Specification.new do |s|
+	s.platform = Gem::Platform::RUBY
+	s.summary = "#{SHORTNAME}: #{DESC}"
+	s.name = SHORTNAME
+	s.version = PKG_VERSION
+	s.files = PKG_FILES
+	s.requirements << "none"
+	s.require_path = 'lib'
+	s.description = LONG_DESC
+end
+
+# Adding a new GemPackageTask adds a task named `package`, which generates
+# packages as gems, tarball and zip archives.
+Rake::GemPackageTask.new(spec) do |pkg|
+	pkg.need_zip = true
+	pkg.need_tar_gz = true
+end
+
+
+# This task is used to demonstrate how to upload files to Rubyforge.
+# Calling `upload_page` creates a current version of the +rdoc+
+# documentation and uploads it to the Rubyforge homepage of the project,
+# assuming it's hosted there and naming conventions haven't changed.
+#
+# This task uses `sh` to call the `scp` binary, which is plattform
+# dependant and may not be installed on your computer if you're using
+# Windows. I'm currently not aware of any pure ruby way to do scp
+# transfers.
+
+RubyForgeProject=SHORTNAME
+
+desc "Upload the web pages to the web."
+task :upload_pages => ["rdoc"] do
+  if RubyForgeProject then
+    path = "/var/www/gforge-projects/#{RubyForgeProject}"
+    sh "scp -r doc/html/* #{RUBYFORGE_USER}@rubyforge.org:#{path}"
+    sh "scp doc/images/*.png #{RUBYFORGE_USER}@rubyforge.org:#{path}/images"
+  end
+end
+
+# This task will run the unit tests provided in files called
+# `test/test*.rb`. The task itself can be run with a call to `rake test`
+
+Rake::TestTask.new do |t| 
+	t.libs << "test" 
+	t.libs << "lib" 
+	t.test_files = FileList['test/*.rb'] 
+	t.verbose = true 
+end
+
+
+

data/TODO

@@ -0,0 +1,5 @@
+* Unit Tests
+* Utility to call hexy from the command line not just as a lib
+* More line numbering options (line numbers)
+* character encodings for right hand side
+* import of hexdumps (?)

data/lib/hexy.rb

@@ -0,0 +1,136 @@
+
+
+class Hexy
+  
+  def self.dump bytes, config={}
+    Hexy.new(bytes, config).to_s
+  end
+  
+  #
+  # Constructor is passed the bytes to format as a hex dump and
+  # an optinal configuration hash. Configuration parameters are:
+  #
+  # [:+width+]      how many bytes per line (default: 16)
+  # [:+numbering+]  currently the only supported options are <tt>:hex_bytes</tt> and <tt>:none</tt>. Default is <tt>:hex_bytes</tt>
+  # [:+format+]     currently supported are :+twos+ (every two hex digits are separated by a space, default), :+fours+ or :+none+
+  # [:+case+]       :+upper+ or :+lower+, default :+lower+
+  # [:+annotate+]   :+ascii+ or :+none+, default :+ascii+
+  # [:+prefix+]     a prefix to include literally in front of each line, default ""
+  # [:+indent+]     number of spaces to prefix in front of each line, default 0
+  #
+  # 
+  #
+  #
+  #
+  # ==Examples
+  # (Width = 16, Line Numbers = :hex_bytes, Format = :twos)
+  #   0000000: 00 01 03 05 1f 0a 09 62   63 64 65 66 67 68 69 6a  .......b cdefghij 
+  #   0000010: 6b 6c 6d 6e 6f 70 71 72   73 74 75 76 77 78 79 7a  klmnopqr stuvwxyz 
+  #   0000020: 30 31 32 33 34 35 36 37   38 39                    01234567 89
+  #   
+  # (Width = 16, Line Numbers = :none, Format = :fours)
+  #   0001 0305 1f0a 0962 6364 6566 6768 696a  .......b cdefghij 
+  #   6b6c 6d6e 6f70 7172 7374 7576 7778 797a  klmnopqr stuvwxyz 
+  #   3031 3233 3435 3637 3839                 01234567 89
+  #
+  # ==Usage
+  #
+  # The examples above were generated with the following:
+  #
+  #   b = Hexy.new "\x00\x01\x03(...)"
+  #   puts p.to_s
+  #
+  #   b = Hexy.new "\x00\x01\x03(...)", :numbering=>:none, :format=>:fours
+  #   puts p.to_s
+  #            
+  def initialize bytes, config = {}
+    @bytes     = bytes
+    @width     = config[:width] || 16 
+    @numbering = config[:numbering] == :none  ? :none : :hex_bytes
+    @format = case config[:format]
+                when :none, :fours
+                  config[:format]
+                else
+                  :twos
+              end
+    @case      = config[:case]      == :upper ? :upper: :lower
+    @annotate  = config[:annotate]  == :none  ? :none : :ascii
+    @prefix    = config[:prefix]    ||= ""
+    @indent    = config[:indent]    ||= 0
+    1.upto(@indent) {@prefix += " "}
+  end
+
+  def to_s
+    str = ""
+    0.step(@bytes.length, @width) {|i|
+      string = @bytes[i,@width]
+
+      hex = string.unpack("H*")[0]
+      hex.upcase! if @case == :upper
+      
+
+      if @format == :fours
+        hex.gsub!(/(.{4})/) {|m|
+          m+" "
+        }
+      elsif @format == :twos
+        hex.sub!(/(.{#{@width}})/) { |m|
+          m+"  "
+        }
+        hex.gsub!(/(\S\S)/) { |m| 
+          m+" "
+        }
+      end
+
+      string.gsub!(/[\000-\040\177-\377]/, ".")
+      string.gsub!(/(.{#{@width/2}})/) { |m|
+        m+" "
+      }
+      len = case @format
+              when :fours 
+                (@width*2)+(@width/2) 
+              when :twos
+                (@width * 3)+2
+              else
+                @width *2
+            end  
+      str << @prefix
+      str << "%07X: " % (i) if @numbering == :hex_bytes 
+      str << ("%-#{len}s" % hex)
+      str << " #{string}" if @annotate == :ascii
+      str << "\n" 
+      
+    }
+    str << "\n"
+  end
+end
+
+if $0 == __FILE__
+  
+  b = Hexy.new "abc"
+  puts b.to_s
+  b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789"
+  puts b.to_s
+  b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :format=>:none
+  puts b.to_s
+  b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :annotate=>:none
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :format=>:fours)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :format=>:fours, :case=>:upper)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :format=>:fours)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :width=>8)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=> 8)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=> 8, :format=>:fours)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :width=>32)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=>32)
+  puts b.to_s
+  b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=>32, :format=>:fours)
+  puts b.to_s
+end

data/test/hexy_text.rb

@@ -0,0 +1,127 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/hexy'
+
+# The way these tests are grouped is more or less arbitary, it more or less follows 
+# the features available in the config hash and tries to cover several permutations.
+# The tests in the current form are taken from runs of the actual code:
+# they're devoped until the results are satisfactory and then transfered back into 
+# these test cases.
+#
+# There's probably a nicer way to do to this, but this way does ensure that new features don't mess up the old results.
+class TestHexy < Test::Unit::TestCase
+
+  def setup
+  end
+  
+  def test_class_meth
+    bytes = "\123\234\345\456\123\321\012"
+    h = Hexy.new bytes
+
+    assert_equal h.to_s, Hexy.dump(bytes,{}) 
+
+  end 
+  def test_dump
+        b = Hexy.new "abc"
+        assert_equal %Q(0000000: 61 62 63                                           abc
+
+), b.to_s
+
+        b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789"
+        assert_equal %Q(0000000: 00 01 03 05 1f 0a 09 62   63 64 65 66 67 68 69 6a  .......b cdefghij 
+0000010: 6b 6c 6d 6e 6f 70 71 72   73 74 75 76 77 78 79 7a  klmnopqr stuvwxyz 
+0000020: 30 31 32 33 34 35 36 37   38 39                    01234567 89
+
+), b.to_s
+        
+        
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=> 8)
+        assert_equal %Q(0000000: 00 01 03 05   1f 0a 09 62  .... ...b 
+0000008: 63 64 65 66   67 68 69 6a  cdef ghij 
+0000010: 6b 6c 6d 6e   6f 70 71 72  klmn opqr 
+0000018: 73 74 75 76   77 78 79 7a  stuv wxyz 
+0000020: 30 31 32 33   34 35 36 37  0123 4567 
+0000028: 38 39                      89
+
+), b.to_s
+        
+        
+        
+        
+  end
+
+  def test_numbering
+    
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :format=>:fours)
+        assert_equal %Q(0001 0305 1f0a 0962 6364 6566 6768 696a  .......b cdefghij \n6b6c 6d6e 6f70 7172 7374 7576 7778 797a  klmnopqr stuvwxyz \n3031 3233 3435 3637 3839                 01234567 89\n\n), b.to_s
+
+
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :width=>32)
+        assert_equal %Q(00 01 03 05 1f 0a 09 62 63 64 65 66 67 68 69 6a   6b 6c 6d 6e 6f 70 71 72 73 74 75 76 77 78 79 7a  .......bcdefghij klmnopqrstuvwxyz \n30 31 32 33 34 35 36 37 38 39                                                                      0123456789\n\n), b.to_s
+
+  end
+  def test_format
+
+        b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :format=>:none
+        assert_equal %Q(0000000: 000103051f0a0962636465666768696a .......b cdefghij 
+0000010: 6b6c6d6e6f707172737475767778797a klmnopqr stuvwxyz 
+0000020: 30313233343536373839             01234567 89
+
+), b.to_s
+        
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :format=>:fours)
+        assert_equal %Q(0000000: 0001 0305 1f0a 0962 6364 6566 6768 696a  .......b cdefghij 
+0000010: 6b6c 6d6e 6f70 7172 7374 7576 7778 797a  klmnopqr stuvwxyz 
+0000020: 3031 3233 3435 3637 3839                 01234567 89
+
+), b.to_s
+
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=>32, :format=>:fours)
+        assert_equal %Q(0000000: 0001 0305 1f0a 0962 6364 6566 6768 696a 6b6c 6d6e 6f70 7172 7374 7576 7778 797a  .......bcdefghij klmnopqrstuvwxyz 
+0000020: 3031 3233 3435 3637 3839                                                         0123456789
+
+), b.to_s
+  end
+
+  def test_case
+
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :format=>:fours, :case=>:upper)
+        assert_equal %Q(0001 0305 1F0A 0962 6364 6566 6768 696A  .......b cdefghij 
+6B6C 6D6E 6F70 7172 7374 7576 7778 797A  klmnopqr stuvwxyz 
+3031 3233 3435 3637 3839                 01234567 89
+
+), b.to_s
+  end
+
+  def test_annotate
+
+        b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :annotate=>:none
+        assert_equal %Q(0000000: 00 01 03 05 1f 0a 09 62   63 64 65 66 67 68 69 6a 
+0000010: 6b 6c 6d 6e 6f 70 71 72   73 74 75 76 77 78 79 7a 
+0000020: 30 31 32 33 34 35 36 37   38 39                   \n\n), b.to_s
+  end
+  def test_width
+
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=> 8, :format=>:fours)
+        assert_equal %Q(0000000: 0001 0305 1f0a 0962  .... ...b \n0000008: 6364 6566 6768 696a  cdef ghij \n0000010: 6b6c 6d6e 6f70 7172  klmn opqr \n0000018: 7374 7576 7778 797a  stuv wxyz \n0000020: 3031 3233 3435 3637  0123 4567 \n0000028: 3839                 89\n\n), b.to_s
+
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:none, :width=>8)
+        assert_equal %Q(00 01 03 05   1f 0a 09 62  .... ...b \n63 64 65 66   67 68 69 6a  cdef ghij \n6b 6c 6d 6e   6f 70 71 72  klmn opqr \n73 74 75 76   77 78 79 7a  stuv wxyz \n30 31 32 33   34 35 36 37  0123 4567 \n38 39                      89\n\n), b.to_s
+
+        b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :numbering=>:hex_bytes, :width=>32)
+        assert_equal %Q(0000000: 00 01 03 05 1f 0a 09 62 63 64 65 66 67 68 69 6a   6b 6c 6d 6e 6f 70 71 72 73 74 75 76 77 78 79 7a  .......bcdefghij klmnopqrstuvwxyz \n0000020: 30 31 32 33 34 35 36 37 38 39                                                                      0123456789\n\n), b.to_s
+  end
+
+  def test_prefix_indent
+    b = Hexy.new("\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", 
+                  :numbering=>:hex_bytes, 
+                  :width=> 8, 
+                  :format=>:fours,
+                  :prefix=>"yo! :"
+                 )
+    assert_equal %Q(yo! :0000000: 0001 0305 1f0a 0962  .... ...b \nyo! :0000008: 6364 6566 6768 696a  cdef ghij \nyo! :0000010: 6b6c 6d6e 6f70 7172  klmn opqr \nyo! :0000018: 7374 7576 7778 797a  stuv wxyz \nyo! :0000020: 3031 3233 3435 3637  0123 4567 \nyo! :0000028: 3839                 89\n\n), b.to_s
+
+    b = Hexy.new "\000\001\003\005\037\012\011bcdefghijklmnopqrstuvwxyz0123456789", :annotate=>:none, :indent=>4
+    assert_equal %Q(    0000000: 00 01 03 05 1f 0a 09 62   63 64 65 66 67 68 69 6a \n    0000010: 6b 6c 6d 6e 6f 70 71 72   73 74 75 76 77 78 79 7a \n    0000020: 30 31 32 33 34 35 36 37   38 39                   \n\n), b.to_s
+
+  end
+end