hex_string 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+pkg/*
+*.gem
+.bundle
+doc
+.yardoc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --readme README.md --hide-void-return

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in hex_string.gemspec
+gemspec

data/README.md

@@ -0,0 +1,46 @@
+Description
+===========
+HexString provides two String extension methods: 
+
+* `String#to_hex_string` explodes a string of binary data into human-readable hex tuples, and 
+* `String#to_byte_string` converts a string of human-readable hex digits into the corresponding bytes.
+
+Examples
+--------
+
+    # Convert data to human-readable hex tuples:
+    >> "hello".to_hex_string
+    => "68 65 6c 6c 6f"
+
+    # Compact a hex string into its data equivalent:
+    >> "77 6f 72 6c 64".to_byte_string
+    => "world"
+
+    # (#to_byte_string is space and case-insensitive:)
+    >> "776F726C64".to_byte_string
+    => "world"
+
+    # Peek at the first 4 bytes of an executable on OS X:
+    >> File.read("/bin/ls")[0..3].to_hex_string
+    => "ca fe ba be"
+
+Motivation
+----------
+When working with binary message or file formats, we often want to have a peek
+at some segment of binary data and talk about individual byte values in
+human-relatable terms.
+
+This sort of thing comes in handy during testing, debugging and data
+introspection, especially when it's inconvenient or impractical to capture the
+desired binary data to file in order to view it with a hex editor or other
+binary file reader.
+
+We were inspired to publish this humble Gem after we found ourselves copying it
+by hand from project to project over the course of several years.
+
+Authors
+=======
+* Micah Alles (alles@atomicobject.com)
+* David Crosby (crosby@atomicobject.com)
+* © 2011 [Atomic Object](http://www.atomicobject.com/)
+* More Atomic Object [open source](http://www.atomicobject.com/pages/Software+Commons) projects

data/Rakefile

@@ -0,0 +1,19 @@
+require "bundler"
+require "rake/testtask"
+require "rake/clean"
+require "yard"
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList["test/*_test.rb"]
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = %w[ lib/hex_string.rb ]
+end
+
+CLEAN.include "pkg"
+CLEAN.include "doc"
+CLEAN.include ".yardoc"
+
+task :default => :test

data/hex_string.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name        = "hex_string"
+  s.version     = "1.0.0"
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["David Crosby", "Micah Alles"]
+  s.email       = ["crosby@atomicobject.com", "alles@atomicobject.com"]
+  s.homepage    = ""
+  s.summary     = %q{String extensions to convert binary data to / from human readable hex tuples.}
+  s.description = %q{String extensions to convert binary data to / from human readable hex tuples.}
+
+  s.rubyforge_project = "hex_string"
+
+  s.add_development_dependency("bundler", ">= 1.0.0")
+  s.add_development_dependency("rake", ">= 0.8.0")
+  s.add_development_dependency("yard", "~> 0.6.4")
+  s.add_development_dependency("bluecloth", "~> 2.0.11")
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/hex_string.rb

@@ -0,0 +1,43 @@
+# String extensions providing to_hex_string and to_byte_string.
+# Requiring hex_string will automatically include HexString in the String class.
+module HexString
+
+  # Convert a human-readable hex string into binary data.
+  #
+  # Assumes the target String is an ASCII, human readable sequence of hexadecimal 
+  # tuples depicting a sequence of 8-bit byte values.
+  # Whitespace between tuples is allowed and will be removed before packing.
+  #
+  # Returns a newly created string containing binary data -- the target string will not be modified.
+  #
+  # Eg:
+  #   >> "68 65 6c 6c 6f".to\_byte\_string
+  #   => "hello"
+	def to_byte_string
+		stripped = self.gsub(/\s+/,'')
+		unless stripped.size % 2 == 0
+			raise "Can't translate a string unless it has an even number of digits"
+		end
+    raise "Can't translate non-hex characters" if stripped =~ /[^0-9A-Fa-f]/
+    [stripped].pack('H*')
+	end
+
+  # Convert binary data into a human-readable hex string.
+  #
+  # Whatever data is contained in the target string will be "exploded" into a sequence of 
+  # hexadecimal tuples, one space between each tuple, for ease of debugging and reading.
+  # 
+  # Returns a newly created string containing the hex string -- the target binary string will not be modified.
+  #
+  # Eg:
+  #   >> "hello world".to\_hex\_string
+  #   => "68 65 6c 6c 6f 20 77 6f 72 6c 64"
+	def to_hex_string
+    self.unpack('H*').first.gsub(/(..)/,'\1 ').rstrip
+	end
+end
+
+# Include HexString extensions in the String class
+class String
+	include HexString
+end

data/test/hex_string_test.rb

@@ -0,0 +1,57 @@
+require 'test/unit'
+require File.expand_path(File.dirname(__FILE__) + '/../lib/hex_string')
+
+class HexStringTest < Test::Unit::TestCase
+	def self.should(behave,&block)
+		mname = "test_should_#{behave}"
+		if block
+			define_method mname, &block
+		else
+			puts ">>> UNIMPLEMENTED CASE: #{name.sub(/Test$/,'')} should #{behave}"
+		end
+	end
+
+  should "allow human readable hex strings to become actual byte strings" do
+		human = "0102030405060708090a0b0c0d0e0f"
+		expect = "\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f"
+		assert_equal expect, human.to_byte_string
+	end
+
+	should "not care about case of a-f or A-F" do
+		human = "aabbccddeeffAABBCCDDEEFF"
+		expect = "\xaa\xbb\xcc\xdd\xee\xff\xaa\xbb\xcc\xdd\xee\xff"
+		assert_equal expect, human.to_byte_string
+	end
+
+	should "ignore whitespace of all kinds" do
+		human = "\t\t\taa   \t\t bb c\nc d\tdee  ffAABBCCDDEEFF\t \n\r"
+		expect = "\xaa\xbb\xcc\xdd\xee\xff\xaa\xbb\xcc\xdd\xee\xff"
+		assert_equal expect, human.to_byte_string
+	end
+
+	should "reject odd lengths of digits" do
+		human = "abbccddeeffAABBCCDDEEFF"
+		err = assert_raise(RuntimeError) do 
+		  human.to_byte_string 
+	  end
+		assert_match(/even/,err.message)
+		assert_match(/digits/,err.message)
+	end
+
+	should "reject non-hex digits" do
+		human = "aabbccddXKeeffAABBCCDDEEFF"
+		err = assert_raise(RuntimeError) do 
+		  human.to_byte_string 
+	  end
+		assert_match(/hex/,err.message)
+	end
+
+	should "convert byte strings into human readable hex strings" do
+		assert_equal "68 65 6c 6c 6f", "hello".to_hex_string
+	end
+
+	should "provide empty hex strings when operating on empty strings" do 
+	  assert_equal "", "".to_hex_string
+	end
+
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification 
+name: hex_string
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- David Crosby
+- Micah Alles
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-06 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 63
+        segments: 
+        - 0
+        - 8
+        - 0
+        version: 0.8.0
+  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 
+        hash: 15
+        segments: 
+        - 0
+        - 6
+        - 4
+        version: 0.6.4
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 25
+        segments: 
+        - 2
+        - 0
+        - 11
+        version: 2.0.11
+  type: :development
+  version_requirements: *id004
+description: String extensions to convert binary data to / from human readable hex tuples.
+email: 
+- crosby@atomicobject.com
+- alles@atomicobject.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .yardopts
+- Gemfile
+- README.md
+- Rakefile
+- hex_string.gemspec
+- lib/hex_string.rb
+- test/hex_string_test.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: hex_string
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: String extensions to convert binary data to / from human readable hex tuples.
+test_files: 
+- test/hex_string_test.rb