expletive 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 82f14df20cd14e764a80e8faa5d70419d4e748be
+  data.tar.gz: e4ef058f3e28c80be86145406c0fbc3bec3a89d2
+SHA512:
+  metadata.gz: 8bb284dee6a30cccdb2da53d0286941c681cd41e6ed2981b5f7bacf0a4a72fa2356482145e8b17964ce0372a5010be2cf844c006371ed23eabc3cf2cedba5101
+  data.tar.gz: 4af5fd6d6a3ca6da5fe7b4eeeb7b807e60ae989f5e2a647b4b0a1aa2b3d43c74710d10eec178deccc5d5b0097c05ab68cd6065693c14f8adbbb5dc45d99ced9e

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rspec
+.ruby_version
+README.html
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'minitest'

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Russ Olsen
+
+MIT License
+
+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,162 @@
+# Expletive
+
+
+© 2015 Russ Olsen
+
+**Expletive** is a simple pair of utilities that allow you to dump a file -- presumably a binary file -- into a 
+a plain text format that you can edit. The trick is that as long as you follow the expletive conventions as
+you edit you can turn your plain text back into a binary file. So expletive has all the charm of your typical
+hex editor, *without having to learn a new editor*. Just use vim or emacs or lightTable or any other editor
+of your choice.
+
+And the name... Well typically by the time I come to having to edit a binary file I'm usually muttering some bad words.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'expletive'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install expletive
+
+## Usage
+
+Expletive is really just two commands, `exdump` and `exundump`. The `exdump` command will take your binary file and
+turn it into something you can edit with an ordinary text editor. For example, if I wanted to
+edit the `ls` command, I would do something like:
+
+```sh
+$ dump < /bin/ls >ls.dump
+```
+
+What you will end up with in `ls.dump` will be plain text, albeit somewhat intimidating plain text:
+
+    \cf\fa\ed\fe\07\00\00\01\03\00\00\80\02\00\00\00\13\00\00\00\18
+    \07\00\00\85\00 \00\00\00\00\00\19\00\00\00H\00\00\00__PAGEZE
+    RO\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\01\00
+    \00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00\00
+    \00\00\00\00\00\00\00\00\00\00\00\00\00\19\00\00\00(\02\00\00
+    __TEXT\00\00\00\00\00\00\00\00\00\00\00\00\00\00\01\00\00\00\00
+
+ 
+You can then edit the `ls.dump` file, making any changes you desire. Once you are
+done you can turn your modified text back into binary with `exundump`.
+
+
+```sh
+$ undump < ls.dump > ls.new
+```
+
+### The Dump File Format
+
+The format of the dumped files is as simple as my small mind can make it:
+
+* Backslashes get converted to double backslashes, so \ becomes \\\\.
+
+* Newlines get converted to \n - that's a backslash character followed by an "n".
+
+* Any byte that looks like a simple, human readable single byte character is written as is.
+
+* Otherwise the byte is written as a backslash followed by a two digit hex number. Note
+that this number is zero filled: It's always \03, never \3.
+
+* The `exdump` command will periodically insert actual newlines into the output to make
+it more readable. Actual newlines are ignored by `exundump`.
+
+That's it!
+
+### An Example
+
+Have you ever noticed that when you do `ls -l` in your terminal, `ls` prints
+the total number of bytes at the top of the output?
+
+```shell
+~/projects/ruby/expletive: ls -l
+
+total 304
+-rw-r--r--  1 russolsen  staff    347 Jun 10 08:56 CHANGELOG.md
+-rw-r--r--  1 russolsen  staff     55 Jun 10 09:20 Gemfile
+-rw-r--r--  1 russolsen  staff    672 Jun 10 08:56 Gemfile.lock
+-rw-r--r--  1 russolsen  staff   1067 Jun 10 08:56 LICENSE
+...
+```
+
+Now imagine that for some obscure reason you wanted to make that
+*total* show up as *YOOO!*. Nothing to it. First dump the contents
+of the (very binary) `ls` command to some file:
+
+```shell
+exdump </bin/ls >ls.dump
+```
+
+Then edit the resulting dump file with the editor of your choice:
+
+```shell
+vi ls.dump
+```
+
+And look for the string *total*. Here is what I see when I do that:
+
+    llu\00%lu\00printscol\00/SourceCache/file_cmds/file_cmds-242/
+    ls/print.c\00dp\00total %qu\n\00%*llu \00%*qu \00%s%s %*u   \00
+    %s%s %*u %-*s  \00%s%s %*u %-*s  %-*s  \00%-*s \00%3d, 0x%08x
+     \00%3d, %3d \00%*s%*qu \00, \00printcol\00dp->list\00base <·
+
+Notice the *total* on the second line. Now all you need to do is
+change *total* to *YOOO!* or some other amusing string:
+
+    llu\00%lu\00printscol\00/SourceCache/file_cmds/file_cmds-242/
+    ls/print.c\00dp\00YOOO! %qu\n\00%*llu \00%*qu \00%s%s %*u   \00
+    %s%s %*u %-*s  \00%s%s %*u %-*s  %-*s  \00%-*s \00%3d, 0x%08x
+     \00%3d, %3d \00%*s%*qu \00, \00printcol\00dp->list\00base <·
+
+
+Note that you need to make sure that your new string is the same length as the
+old one (e.g. total) because executables contain counts and offsets
+that you don't want to mess up.
+
+Having made your change, you just need to convert your dump file back
+to a binary. But don't overwrite your system's `ls` command!
+
+```shell
+exundump <ls.dump >ls.new
+```
+
+Make your new `ls.new` file executable:
+
+```shell
+chmod +x ls.new
+```
+
+And run your hacked binary:
+
+```shell
+./ls.new -l
+
+YOOO! 312
+-rw-r--r--  1 russolsen  staff    347 Jun 10 08:56 CHANGELOG.md
+-rw-r--r--  1 russolsen  staff     55 Jun 10 09:20 Gemfile
+-rw-r--r--  1 russolsen  staff    672 Jun 10 08:56 Gemfile.lock
+
+```
+
+One final note: With the power to edit binaries, easily and with your favorite text editor,
+comes great responsibility.
+
+## Contributors
+
+* Russ Olsen (@russolsen)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,19 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+
+Rake::TestTask.new do |t|
+    t.pattern = "spec/*_spec.rb"
+end
+
+task :clean do
+    rm_rf "pkg"
+end
+
+task :default => [:test, :build]
+
+task :irb do
+  sh "irb -I lib -r expletive"
+  sh "reset"
+end

data/bin/exdump

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'expletive'
+
+Expletive::Dump.new.run

data/bin/exundump

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'expletive'
+
+Expletive::Undump.new.run

data/expletive.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/expletive/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Russ Olsen"]
+  gem.email         = ["russ@russolsen.com"]
+  gem.description   = %q{'Handy scripts to convert binary files to and from an editable plaintext form.'}
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/russolsen/expletive"
+  gem.license       = "MIT"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "expletive"
+  gem.require_paths = ["lib"]
+  gem.version       = Expletive::VERSION
+
+  gem.add_development_dependency 'pry', '~> 0.9.10'
+  gem.add_development_dependency 'rspec', '~> 2.11.0'
+  gem.add_development_dependency 'rantly', '~> 0.3.1'
+  gem.add_development_dependency 'rake', '~> 10.0.3'
+end

data/lib/expletive.rb

@@ -0,0 +1,3 @@
+require 'expletive/version'
+require 'expletive/filters'
+

data/lib/expletive/filters.rb

@@ -0,0 +1,83 @@
+module Expletive
+  SPACE = ' '.ord
+  TILDE = '~'.ord
+  NEWLINE = "\n".ord
+  BACKSLASH = "\\".ord
+
+  class Dump
+    def initialize(in_io=$stdin, out_io=$stdout)
+      @in = in_io
+      @out = out_io
+      @current_width = 0
+    end
+
+    def run
+      n = 0
+      until @in.eof?
+        byte = @in.readbyte
+        case 
+        when byte ==  BACKSLASH
+          write_string "\\\\"
+        when byte == NEWLINE
+          write_string "\\n"
+        when human_readable?(byte)
+          write_string byte.chr 
+        else
+          write_string  "\\%02x" % byte
+        end
+      end
+    end
+
+    def start_new_line
+      @out.print("\n")
+      @current_width = 0
+    end
+
+    def write_string(s)
+      @out.print(s)
+      @current_width += s.size
+      start_new_line if @current_width > 60
+    end
+
+    def human_readable?(byte)
+      (byte >= SPACE) && (byte <= TILDE)
+    end
+  end
+
+  class Undump
+    def initialize(in_io=$stdin, out_io=$stdout)
+      @in = in_io
+      @out = out_io
+    end
+
+    def run
+      until @in.eof?
+        ch = @in.getc
+        if ch == "\n"
+          # do nothing
+        elsif ch != "\\"
+          @out.write ch.chr
+        else
+          handle_escape
+        end
+      end
+    end
+
+    def handle_escape
+      nextc = @in.getc
+      case 
+      when nextc == '\\'
+        @out.write "\\"
+      when nextc == 'n'
+        @out.write "\n"
+      when nextc =~ /\h/
+        otherc = @in.getc
+        hex = nextc + otherc
+        @out.write hex.to_i(16).chr
+      else
+        raise "Dont know what to do with \\ #{nextc}"
+      end
+    end
+  end
+end
+

data/lib/expletive/version.rb

@@ -0,0 +1,3 @@
+module Expletive
+    VERSION = "0.0.1"
+end

data/spec/dump_spec.rb

@@ -0,0 +1,36 @@
+require 'minitest/autorun'
+require 'expletive'
+require 'stringio'
+
+include Expletive
+
+describe Dump do
+  def endump(input)
+    in_io = StringIO.new(input)
+    out_io = StringIO.new
+    Dump.new(in_io, out_io).run
+    out_io.string
+  end
+ 
+  describe "#dump" do
+    it "passes text unchanged" do
+      input = "hello world"
+      assert_equal input, endump(input)
+    end
+
+    it "encodes binary into hex" do
+      input = "\01\02\03xyz"
+      assert_equal '\\01\\02\\03xyz', endump(input)
+    end
+
+    it "escapes backslashes" do
+      input = 'abc\\def'
+      assert_equal 'abc\\\\def', endump(input)
+    end
+
+    it "escapes newlines" do
+      input = "abc\ndef"
+      assert_equal 'abc\\ndef', endump(input)
+    end
+  end
+end

data/spec/undump_spec.rb

@@ -0,0 +1,39 @@
+require 'minitest/autorun'
+require 'expletive'
+require 'stringio'
+
+include Expletive
+
+describe Undump do
+  def dedump(input)
+    in_io = StringIO.new(input)
+    out_io = StringIO.new
+    Undump.new(in_io, out_io).run
+    out_io.string
+  end
+ 
+  describe "#run" do
+    it "passes text unchanged" do
+      input = "hello world"
+      assert_equal input, dedump(input)
+    end
+
+    it "decodes hex into equivalent binary" do
+      input = "\\01\\02\\03xyz"
+      output = "\01\02\03xyz"
+      assert_equal output, dedump(input)
+    end
+
+    it "turns backslash backslash into a single backslash" do
+      input = 'abc\\\\def'
+      output = 'abc\\def'
+      assert_equal output, dedump(input)
+    end
+
+    it "turns backslash n into a real newline" do
+      input = "abc\\ndef"
+      output = "abc\ndef"
+      assert_equal output, dedump(input)
+    end
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: expletive
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Russ Olsen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.10
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.10
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+- !ruby/object:Gem::Dependency
+  name: rantly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 10.0.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 10.0.3
+description: "'Handy scripts to convert binary files to and from an editable plaintext
+  form.'"
+email:
+- russ@russolsen.com
+executables:
+- exdump
+- exundump
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/exdump
+- bin/exundump
+- expletive.gemspec
+- lib/expletive.rb
+- lib/expletive/filters.rb
+- lib/expletive/version.rb
+- spec/dump_spec.rb
+- spec/undump_spec.rb
+homepage: https://github.com/russolsen/expletive
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: "'Handy scripts to convert binary files to and from an editable plaintext
+  form.'"
+test_files:
+- spec/dump_spec.rb
+- spec/undump_spec.rb