sixword 0.3.1 → 0.3.2

data/lib/sixword/cli.rb

@@ -1,9 +1,33 @@
 module Sixword
+
+  # The Sixword::CLI class implements all of the complex processing needed for
+  # the sixword Command Line Interface.
   class CLI
+
+    # Exception for certain input validation errors
     class CLIError < StandardError; end
 
-    attr_reader :filename, :options, :stream, :mode
+    # @return [String] Input filename
+    attr_reader :filename
+
+    # @return [Hash] Options hash
+    attr_reader :options
+
+    # @return [File, IO] Stream opened from #filename
+    attr_reader :stream
+
+    # @return [:encode, :decode]
+    attr_reader :mode
 
+    # Create a Sixword CLI to operate on filename with options
+    #
+    # @param filename [String] Input file name (or '-' for stdin)
+    # @param options [Hash]
+    #
+    # @option options [:encode, :decode] :mode (:encode)
+    # @option options [Boolean] :pad (false)
+    # @option options [String] :hex_style
+    #
     def initialize(filename, options)
       @filename = filename
       @options = {mode: :encode, pad: false}.merge(options)
@@ -24,18 +48,25 @@ module Sixword
       end
     end
 
+    # Return the value of the :pad option.
+    # @return [Boolean]
     def pad?
       options.fetch(:pad)
     end
 
+    # Return true if we are in encoding mode, false otherwise (decoding).
+    # @return [Boolean]
     def encoding?
       mode == :encode
     end
 
+    # Return the value of the :hex_style option.
+    # @return [String, nil]
     def hex_style
       options[:hex_style]
     end
 
+    # Format data as hex in various styles.
     def print_hex(data, chunk_index, cols=80)
       case hex_style
       when 'lower', 'lowercase'
@@ -59,6 +90,7 @@ module Sixword
       end
     end
 
+    # Run the encoding/decoding operation, printing the result to stdout.
     def run!
       if encoding?
         do_encode! do |encoded|
@@ -87,7 +119,6 @@ module Sixword
         raise ArgumentError.new("block is required")
       end
 
-      arr = []
       read_input_by_6_words do |arr|
         yield Sixword.decode(arr, padding_ok: pad?)
       end
@@ -140,7 +171,7 @@ module Sixword
       while true
         buf = stream.read(block_size)
         if buf.nil?
-          break #EOF
+          break # EOF
         end
 
         buf.scan(/\S+/) do |word|

data/lib/sixword/hex.rb

@@ -1,12 +1,24 @@
 module Sixword
+  # Various hexadecimal string encoding and decoding functions
   module Hex
     HexValid = /\A[a-fA-F0-9]+\z/
     HexStrip = /[\s:.-]+/
 
+    # Return whether string is entirely hexadecimal.
+    # @param string [String]
+    # @return [Boolean]
+    # @see [HexValid]
+    #
     def self.valid_hex?(string)
       !!(string =~ HexValid)
     end
 
+    # Return whether single character string is one of the fill characters that
+    # are OK to strip from a hexadecimal string.
+    # @param char [String] String of length == 1
+    # @return [Boolean]
+    # @see [HexStrip]
+    #
     def self.strip_char?(char)
       unless char.length == 1
         raise ArgumentError.new("Must pass single character string")
@@ -14,22 +26,71 @@ module Sixword
       !!(char =~ HexStrip)
     end
 
+    # Encode a byte string as hexadecimal.
+    #
+    # @param bytes [String]
+    # @return [String] hexadecimal string
+    #
     def self.encode(bytes)
       bytes.unpack('H*').fetch(0)
     end
 
+    # Encode a byte string as hexadecimal, returning it in slices joined by a
+    # delimiter. This is useful for generating colon or space separated strings
+    # like those commonly used in fingerprints.
+    #
+    # @param bytes [String]
+    # @param slice [Integer]
+    # @param delimiter [String]
+    #
+    # @return [String]
+    #
+    # @example
+    #   >> encode_slice("9T]B\xF0\x039\xFF", 2, ':')
+    #   => "39:54:5d:42:f0:03:39:ff"
+    #
     def self.encode_slice(bytes, slice, delimiter)
       encode(bytes).each_char.each_slice(slice).map(&:join).join(delimiter)
     end
 
+    # Encode a byte string as a GPG style fingerprint: uppercase in slices of 4
+    # separated by spaces.
+    #
+    # @param bytes [String]
+    # @return [String]
+    #
+    # @example
+    #   >> encode_fingerprint("9T]B\xF0\x039\xFF")
+    #   => "3954 5D42 F003 39FF"
+    #
     def self.encode_fingerprint(bytes)
       encode_slice(bytes, 4, ' ').upcase
     end
 
+    # Encode a byte string in hex with colons: lowercase in slices of 2
+    # separated by colons.
+    #
+    # @param bytes [String]
+    # @return [String]
+    #
+    # @example
+    #   >> encode_colons("9T]B\xF0\x039\xFF")
+    #   => "39:54:5d:42:f0:03:39:ff"
+    #
+    #
     def self.encode_colons(bytes)
       encode_slice(bytes, 2, ':')
     end
 
+    # Decode a hexadecimal string to a byte string.
+    #
+    # @param hex_string [String]
+    # @param strip_chars [Boolean] Whether to accept and strip whitespace and
+    #   other delimiters (see {HexStrip})
+    # @return [String]
+    #
+    # @raise ArgumentError on invalid hex input
+    #
     def self.decode(hex_string, strip_chars=true)
       if strip_chars
         hex_string = hex_string.gsub(HexStrip, '')
@@ -39,7 +100,7 @@ module Sixword
         raise ArgumentError.new("Invalid value for hex: #{hex_string.inspect}")
       end
 
-      unless hex_string.length % 2 == 0
+      unless hex_string.length.even?
         raise ArgumentError.new("Odd length hex: #{hex_string.inspect}")
       end
 

data/lib/sixword/lib.rb

@@ -1,5 +1,26 @@
 module Sixword
+
+  # The Lib module contains various internal utility functions. They are not
+  # really part of the public API and will probably not be useful to external
+  # callers.
   module Lib
+
+    # Encode an array of 8 bytes as an array of 6 words.
+    #
+    # @param byte_array [Array<Fixnum>] An array of length 8 containing
+    #   integers in 0..255
+    #
+    # @return [Array<String>] An array of length 6 containing String words from
+    #   {Sixword::WORDS}
+    #
+    # @example
+    #   >> Sixword::Lib.encode_64_bits([0] * 8)
+    #   => ["A", "A", "A", "A", "A", "A"]
+    #
+    # @example
+    #   >> Sixword::Lib.encode_64_bits([0xff] * 8)
+    #   => ["YOKE", "YOKE", "YOKE", "YOKE", "YOKE", "YEAR"]
+    #
     def self.encode_64_bits(byte_array)
       unless byte_array.length == 8
         raise ArgumentError.new("Must pass an 8-byte array")
@@ -23,6 +44,22 @@ module Sixword
       encoded
     end
 
+    # Decode an array of 6 words into a 64-bit integer (representing 8 bytes).
+    #
+    # @param word_array [Array<String>] A 6 element array of String words
+    # @param padding_ok [Boolean]
+    #
+    # @return [Array(Integer, Integer)] a 64-bit integer (the data) and the
+    # length of the byte array that it represents (will always be 8 unless
+    # padding_ok)
+    #
+    # @example
+    #   >> Sixword::Lib.decode_6_words(%w{COAT ACHE A A A ACT6}, true)
+    #   => [26729, 2]
+    #
+    #   >> Sixword::Lib.decode_6_words(%w{ACRE ADEN INN SLID MAD PAP}, false)
+    #   => [5217737340628397156, 8]
+    #
     def self.decode_6_words(word_array, padding_ok)
       unless word_array.length == 6
         raise ArgumentError.new("Must pass a six-word array")
@@ -68,7 +105,15 @@ module Sixword
       [int, 8 - padding]
     end
 
-    # Extract the padding from a word, e.g. 'WORD3' => 'WORD', 3
+    # Extract the numeric padding from a word.
+    #
+    # @param word [String]
+    # @return [Array(String, Integer)] The String word, the Integer padding
+    #
+    # @example
+    #   >> Sixword::Lib.extract_padding("WORD3")
+    #   => ["WORD", 3]
+    #
     def self.extract_padding(word)
       unless word[-1] =~ /[1-7]/
         raise ArgumentError.new("Not a valid padded word: #{word.inspect}")
@@ -77,11 +122,34 @@ module Sixword
       return word[0...-1], Integer(word[-1])
     end
 
+    # Decode an array of 6 words into a String of bytes.
+    #
+    # @param word_array [Array<String>] A 6 element array of String words
+    # @param padding_ok [Boolean]
+    #
+    # @return [String]
+    #
+    # @see Sixword.decode_6_words
+    # @see Sixword.int_to_byte_array
+    #
+    # @example
+    #   >> Lib.decode_6_words_to_bstring(%w{COAT ACHE A A A ACT6}, true)
+    #   => "hi"
+    #
+    #   >> Lib.decode_6_words_to_bstring(%w{ACRE ADEN INN SLID MAD PAP}, false)
+    #   => "Hi world"
+    #
     def self.decode_6_words_to_bstring(word_array, padding_ok)
       int_to_byte_array(*decode_6_words(word_array, padding_ok)).
         map(&:chr).join
     end
 
+    # Given a word, return the 11 bits it represents as an integer (i.e. its
+    # index in the WORDS list).
+    #
+    # @param word [String]
+    # @return [Fixnum] An integer 0..2047
+    #
     def self.word_to_bits(word)
       word = word.upcase
       return WORDS_HASH.fetch(word)
@@ -94,6 +162,13 @@ module Sixword
     end
 
     # Compute two-bit parity on a byte array by summing each pair of bits.
+    # TODO: figure out which is faster
+    #
+    # @param byte_array [Array<Fixnum>]
+    # @return [Fixnum] An integer 0..3
+    #
+    # @see parity_int
+    #
     def self.parity_array(byte_array)
 
       # sum pairs of bits through the whole array
@@ -109,7 +184,15 @@ module Sixword
       parity & 0b11
     end
 
-    # Compute parity in a different way. TODO: figure out which is faster
+    # Compute two-bit parity on a 64-bit integer representing an 8-byte array
+    # by summing each pair of bits.
+    # TODO: figure out which is faster
+    #
+    # @param int [Integer] A 64-bit integer representing 8 bytes
+    # @return [Fixnum] An integer 0..3
+    #
+    # @see parity_array
+    #
     def self.parity_int(int)
       parity = 0
       while int > 0
@@ -122,14 +205,14 @@ module Sixword
 
     # Given an array of bytes, pack them into a single Integer.
     #
-    # For example:
+    # @example
     #
     #     >> byte_array_to_int([1, 2])
     #     => 258
     #
     # @param byte_array [Array<Fixnum>]
     #
-    # @return Integer
+    # @return [Integer]
     #
     def self.byte_array_to_int(byte_array)
       int = 0
@@ -142,19 +225,19 @@ module Sixword
 
     # Given an Integer, unpack it into an array of bytes.
     #
-    # For example:
-    #
+    # @example
     #     >> int_to_byte_array(258)
     #     => [1, 2]
     #
+    # @example
     #     >> int_to_byte_array(258, 3)
     #     => [0, 1, 2]
     #
     # @param int [Integer]
-    # @param length [Integer] (nil) Left zero padded size of byte array to
-    #   return. If not provided, no leading zeroes will be added.
+    # @param length [Integer] Left zero padded size of byte array to return. If
+    #   not provided, no leading zeroes will be added.
     #
-    # @return Array<Fixnum>
+    # @return [Array<Fixnum>]
     #
     def self.int_to_byte_array(int, length=nil)
       unless int >= 0

data/lib/sixword/version.rb

@@ -1,3 +1,4 @@
 module Sixword
-  VERSION = '0.3.1'
+  # version string
+  VERSION = '0.3.2'
 end

data/lib/sixword/words.rb

@@ -264,6 +264,7 @@ module Sixword
   WORDS.freeze
   WORDS.each(&:freeze)
 
+  # A mapping from Word => Integer index in the word list
   WORDS_HASH = Hash[WORDS.each_with_index.to_a]
   WORDS_HASH.freeze
 end

data/sixword.gemspec

@@ -28,8 +28,11 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'pry'
   spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0'
+  spec.add_development_dependency 'yard'
 
   spec.required_ruby_version = '>= 1.9.3'
 end

data/spec/sixword/hex_spec.rb

@@ -1,7 +1,6 @@
 # coding: binary
-require_relative '../rspec_helper'
 
-describe Sixword::Hex do
+RSpec.describe Sixword::Hex do
   TestCases = {
     "\x73\xe2\x16\xb5\x36\x3f\x23\x77" => [
       "73e216b5363f2377",
@@ -88,38 +87,38 @@ describe Sixword::Hex do
 
   it 'should decode and encode random hex strings correctly' do
     TestCases.each do |binary, hexes|
-      lower, finger, colons = hexes
-      Sixword::Hex.encode(binary).should == lower
-      Sixword::Hex.decode(lower).should == binary
+      lower, _finger, _colons = hexes
+      expect(Sixword::Hex.encode(binary)).to eq(lower)
+      expect(Sixword::Hex.decode(lower)).to eq(binary)
     end
   end
 
   it 'should decode and encode random hex fingerprints correctly' do
     TestCases.each do |binary, hexes|
-      lower, finger, colons = hexes
-      Sixword::Hex.encode_fingerprint(binary).should == finger
-      Sixword::Hex.decode(finger).should == binary
+      _lower, finger, _colons = hexes
+      expect(Sixword::Hex.encode_fingerprint(binary)).to eq(finger)
+      expect(Sixword::Hex.decode(finger)).to eq(binary)
     end
   end
 
   it 'should decode and encode random colon hexes correctly' do
     TestCases.each do |binary, hexes|
-      lower, finger, colons = hexes
-      Sixword::Hex.encode_colons(binary).should == colons
-      Sixword::Hex.decode(colons).should == binary
+      _lower, _finger, colons = hexes
+      expect(Sixword::Hex.encode_colons(binary)).to eq(colons)
+      expect(Sixword::Hex.decode(colons)).to eq(binary)
     end
   end
 
   it 'should accept all valid hex characters' do
-    Sixword::Hex.valid_hex?('abcdefABCDEF0123456789').should == true
+    expect(Sixword::Hex.valid_hex?('abcdefABCDEF0123456789')).to eq(true)
   end
 
   it 'should reject invalid hex characters' do
     ('g'..'z').each do |c|
-      Sixword::Hex.valid_hex?(c).should == false
+      expect(Sixword::Hex.valid_hex?(c)).to eq(false)
     end
     ('G'..'Z').each do |c|
-      Sixword::Hex.valid_hex?(c).should == false
+      expect(Sixword::Hex.valid_hex?(c)).to eq(false)
     end
   end
 end