sixword 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fc9f0517fd216584e553dc2e71e960bdd0b25848
-  data.tar.gz: 31a69ccaf02db205bf290d384fe705491ac6be11
+  metadata.gz: 412a951ad1786d3f978ebc77305e6b7094004b36
+  data.tar.gz: 1a70321549259a131a8a10a536117d29a529110a
 SHA512:
-  metadata.gz: 6d6cfc2a72925aaa382748c85d7e803668f5df4b9a41a6a1421ea3a26ffa738650f04013bb33ee6a6f9f5957cb09d1bf2c87610825249291d158d7d1846374c9
-  data.tar.gz: 952b8f2e92c338863d39e39e59a83c41aae3e5c24e592ea770426d7353561624474be41a96869fd67c833b5f4963cda738d79e58cc89d9731c3b5700322c7c10
+  metadata.gz: 9a2ca1765246ff2b0df8e4ae6b6f8554abec1fbbf7c07478b5e9b36ea38e7b34cb22e352b8c49c4786e9ebaf85927a3d270c48f005fa7e8fba4a00ab24ea09b0
+  data.tar.gz: 0b44ad6d9bd5c7d2b7d0c5ddf9272357be00bf4e1917a46321c595afd72d754a33eae2eda1af3c503539f388427345b59d8ffc81e0505e544b139e910845d760

data/.rspec

@@ -1,2 +1,3 @@
 --color
+--require spec_helper
 --format progress

data/.rubocop-disables.yml

@@ -0,0 +1,174 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2015-11-21 23:48:38 -0800 using RuboCop version 0.35.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/StringLiterals:
+  Enabled: false
+
+# Offense count: 3
+Lint/LiteralInCondition:
+  Enabled: false
+
+# Offense count: 6
+Metrics/AbcSize:
+  Max: 50
+
+# Offense count: 1
+Metrics/BlockNesting:
+  Max: 4
+
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/ClassLength:
+  Enabled: false
+
+# Offense count: 4
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+# Offense count: 12
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 45
+  Exclude:
+    - bin/sixword
+
+# Offense count: 2
+# Configuration parameters: CountComments.
+Metrics/ModuleLength:
+  Enabled: false
+
+# Offense count: 3
+Metrics/PerceivedComplexity:
+  Max: 15
+
+# Offense count: 256
+# Cop supports --auto-correct.
+Style/AlignArray:
+  Exclude:
+    - 'lib/sixword/words.rb'
+
+# Offense count: 5
+Style/ConstantName:
+  Enabled: false
+
+# Configuration parameters: Exclude.
+#
+# We could re-enable this if it understood that the top level module should
+# *not* be documented in files that are not the first to define it.
+#
+Style/Documentation:
+  Enabled: false
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+# ********************************
+# Disagree with these style points
+# ********************************
+
+Style/DotPosition:
+  Enabled: false
+Style/DoubleNegation:
+  Enabled: false
+Style/EmptyLines:
+  Enabled: false
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+Style/EmptyLinesAroundMethodBody:
+  Enabled: false
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+Style/GuardClause:
+  Enabled: false
+
+# Don't favor modifier style ever.
+Style/IfUnlessModifier:
+  Enabled: false
+Style/WhileUntilModifier:
+  Enabled: false
+
+Style/InfiniteLoop:
+  Enabled: false
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%w': '{}'
+    '%W': '{}'
+Style/RaiseArgs:
+  EnforcedStyle: compact
+Style/RedundantReturn:
+  Enabled: false
+Style/Alias:
+  Enabled: false
+Style/SignalException:
+  EnforcedStyle: only_raise
+Style/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: no_space
+
+# Arguable
+# Configuration parameters: EnforcedStyle, SupportedStyles, EnforcedStyleForEmptyBraces, SpaceBeforeBlockParameters.
+Style/SpaceInsideBlockBraces:
+  Enabled: false
+
+# Arguable
+# Configuration parameters: EnforcedStyle, EnforcedStyleForEmptyBraces, SupportedStyles.
+Style/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
+# TODO this is affected by rubocop bug
+# https://github.com/bbatsov/rubocop/issues/2448
+#
+# Offense count: 27
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyleForMultiline, SupportedStyles.
+Style/TrailingComma:
+  # SupportedStyles:
+  #   - comma
+  #   - no_comma
+  EnforcedStyleForMultiline: comma
+
+# Don't favor %w for arrays of words.
+Style/WordArray:
+  Enabled: false
+
+# ********************************
+
+# Configuration parameters: AllowedVariables.
+Style/GlobalVars:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+# I disagree with this cop for the specific case of
+#   if !foo.empty?
+# because I think it's a shame that ruby has no nonempty? predicate, and it's
+# clearer if the double negative is all on the RHS.
+#
+Style/NegatedIf:
+  Exclude:
+    - 'lib/sixword/cli.rb'
+
+# Torn on this one, not really sure what improves clarity.
+# TODO
+# Offense count: 7
+# Cop supports --auto-correct.
+Style/SpaceAfterColon:
+  Exclude:
+    - 'lib/sixword.rb'
+    - 'lib/sixword/cli.rb'
+
+# Offense count: 2
+Style/SpaceInsideBrackets:
+  Exclude:
+    - 'lib/sixword/words.rb'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+Style/SpecialGlobalVars:
+  Exclude:
+    - 'bin/sixword'
+    - 'sixword.gemspec'

data/.rubocop.yml

@@ -0,0 +1,3 @@
+---
+inherit_from:
+- .rubocop-disables.yml

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Change Log
+All notable changes to Sixword should be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org).
+
+## [Unreleased]
+
+## [0.3.2] -- 2015-11-25
+
+- Add lots of documentation and a change log!
+- Upgrade tests to rspec 3.
+- Introduce rubocop style config and fix lots of warnings.
+- Make `sixword --version` actually work.
+
+## [0.3.1] -- 2015-03-21
+
+- Run tests on travis on various ruby versions.
+- Fix tests on ruby 2.0+
+- Add `-e` option flag to the CLI.
+
+## [0.3.0] -- 2014-07-10
+
+- Fix handling of leading null bytes.
+
+## [0.2.0] -- 2013-09-27
+
+- Add a command line interface, `sixword`.
+- Handle various forms of hexadecimal notations, including colon or whitespace
+  delimited fingerprints.
+
+## [0.1.0] -- 2013-09-26
+
+- Add and implement custom padding scheme for strings that are not a multiple
+  of 8 bytes.
+- Add lots of tests and refactor the code.
+
+## [0.0.1] -- 2013-09-25
+
+- Initial public release
+
+<!-- vim: set tw=79 : -->

data/README.md

@@ -1,6 +1,9 @@
 # Sixword
 
-![Build status](https://travis-ci.org/ab/sixword.svg)
+[![Gem Version](https://badge.fury.io/rb/sixword.svg)](https://rubygems.org/gems/sixword)
+[![Build status](https://travis-ci.org/ab/sixword.svg)](https://travis-ci.org/ab/sixword)
+[![Code Climate](https://codeclimate.com/github/ab/sixword.svg)](https://codeclimate.com/github/ab/sixword)
+[![Inline Docs](http://inch-ci.org/github/ab/sixword.svg?branch=master)](http://www.rubydoc.info/github/ab/sixword/master)
 
 Sixword implements the 6-word binary encoding created for S/Key (tm) and
 standardized by RFC 2289, RFC 1760, and RFC 1751. Binary data may be
@@ -46,9 +49,69 @@ Or install it yourself as:
 
     $ gem install sixword
 
-## Usage
+## Usage: Command Line
 
-TODO: Write usage instructions here
+Sixword operates similarly to `base64(1)`, it operates on a file or on STDIN in two modes:
+
+- encode: accept binary data (or hexadecimal in hex modes) and print six-word
+  encoded data on stdout.
+- decode: accept six-word encoded data and print binary data (or hex) on
+  stdout.
+
+### Examples
+
+Normal encoding and decoding
+
+    $ sixword <<< 'Testing'
+    BEAK NET SITE ROTH SWIM FORM
+
+    $ sixword -d <<< 'BEAK NET SITE ROTH SWIM FORM'
+    Testing
+
+    $ sixword -d <<< 'beak net site roth swim form'
+    Testing
+
+The same data, but hex encoded
+
+    $ sixword -H <<< '54:65:73:74:69:6e:67:0a'
+    BEAK NET SITE ROTH SWIM FORM
+
+    $ sixword -dH <<< 'BEAK NET SITE ROTH SWIM FORM'
+    54657374696e670a
+
+    $ sixword -dF <<< 'BEAK NET SITE ROTH SWIM FORM'
+    5465 7374 696E 670A
+
+    $ sixword -d -S colons <<< 'BEAK NET SITE ROTH SWIM FORM'
+    54:65:73:74:69:6e:67:0a
+
+Error handling
+
+    $ sixword -d <<< 'BEAK NET SITE ROTH SWIM FOR'
+    sixword: Parity bits do not match
+    [exit status 3]
+
+    $ sixword -p <<< '.'
+    sixword: Must pad bytes to multiple of 8 or use pad_encode
+
+## Usage: Library
+
+See the [YARD documentation](http://www.rubydoc.info/github/ab/sixword/master).
+The top-level `Sixword` module contains the main API (`Sixword.encode` and
+`Sixword.decode`), while various utilities can be found in `Sixword::Hex` and
+`Sixword::Lib`. Most of the code powering the command line interface is in
+`Sixword::CLI`.
+
+    >> require 'sixword'
+
+    >> Sixword.encode('Hi world')
+    => ["ACRE", "ADEN", "INN", "SLID", "MAD", "PAP"]
+
+    >> Sixword.decode(["ACRE", "ADEN", "INN", "SLID", "MAD", "PAP"])
+    => 'Hi world'
+
+    >> Sixword.decode("acre aden inn slid mad pap")
+    => 'Hi world'
 
 ## Contributing
 

data/Rakefile

@@ -13,4 +13,3 @@ def alias_task(alias_task, original)
   task alias_task, Rake.application[original].arg_names => original
 end
 alias_task(:test, :spec)
-

data/bin/sixword

@@ -55,6 +55,10 @@ Options:
       $stderr.puts opts, ''
       exit 0
     end
+    opts.on('-v', '--version', 'Print version number', ' ') do
+      puts 'sixword ' + Sixword::VERSION
+      exit 0
+    end
 
     #
 
@@ -87,7 +91,12 @@ Options:
     end
   end
 
-  optparse.parse!
+  begin
+    optparse.parse!
+  rescue OptionParser::InvalidOption => err
+    puts_err(err.message)
+    exit 1
+  end
 
   case ARGV.length
   when 0

data/lib/sixword.rb

@@ -4,43 +4,158 @@ require_relative 'sixword/lib'
 require_relative 'sixword/version'
 require_relative 'sixword/words'
 
+# Sixword, a binary encoder using the 6-word scheme from S/key standardized by
+# RFC 2289, RFC 1760, and RFC 1751.
+#
+# All of the public methods are static methods on the Sixword module, for
+# example {Sixword.encode} and {Sixword.decode}.
+#
+# The <tt>sixword</tt> command line interface and corresponding {Sixword::CLI}
+# class is also very convenient for more complex use. It supports a variety of
+# different styles for translating binary data and hexadecimal fingerprints.
+#
+# These hexadecimal methods are implemented in the {Sixword::Hex} module.
+#
 module Sixword
 
   # Parent class for inputs that could plausibly occur at runtime.
   class InputError < ArgumentError; end
 
+  # Raised when the parity check fails
   class InvalidParity < InputError; end
+
+  # Raised in decoding when an unrecognized word is encountered
   class UnknownWord < InputError; end
+
+  # Raised in decoding when a word of invalid format is encountered
   class InvalidWord < InputError; end
 
+  # Encode a string of bytes in six-word encoding. If you want to use the
+  # custom padding scheme for inputs that are not a multiple of 8 in length,
+  # use Sixword.pad_encode instead.
+  #
+  # @param byte_string [String] Length must be a multiple of 8
+  # @return [Array<String>] an array of string words
+  #
+  # @raise Sixword::InputError
+  #
+  # @see Sixword.encode_iter
+  #
+  # @example
+  #   >> Sixword.encode('Hi world')
+  #   => ["ACRE", "ADEN", "INN", "SLID", "MAD", "PAP"]
+  #
   def self.encode(byte_string)
-    encode_to_a(byte_string)
+    encode_iter(byte_string).to_a
   end
 
+  # Encode a string of bytes in six-word encoding, using the custom padding
+  # scheme established by this library. The output will be identical to
+  # {Sixword.encode} for strings that are a multiple of 8 in length.
+  #
+  # @param byte_string [String] A string of any length
+  # @return [Array<String>] an array of string words
+  #
+  # @see Sixword.encode_iter
+  #
+  # @example
+  #   >> Sixword.encode('Hi wor')
+  #   => ["ACRE", "ADEN", "INN", "SLID", "MAD", "PAP"]
+  #
   def self.pad_encode(byte_string)
-    pad_encode_to_a(byte_string)
+    encode_iter(byte_string, words_per_slice:1, pad:true).to_a
   end
 
+  # aliases for clarity on what the default encode(), pad_encode() return
+  class << self
+    alias_method :encode_to_a, :encode
+    alias_method :pad_encode_to_a, :pad_encode
+  end
+
+  # Like {Sixword.encode}, but return six words at a time (a complete block).
+  #
+  # @param byte_string [String] Length must be a multiple of 8
+  # @return [Array<String>] an array of 6-word string sentences
+  #
+  # @raise Sixword::InputError
+  #
+  # @example
+  #   Sixword.encode_to_sentences('Hi world' * 2)
+  #   => ["ACRE ADEN INN SLID MAD PAP",
+  #       "ACRE ADEN INN SLID MAD PAP"]
+  #
+  # @see Sixword.encode
+  #
   def self.encode_to_sentences(byte_string)
     encode_iter(byte_string, words_per_slice:6).to_a
   end
 
+  # Like {Sixword.encode}, but return a single string.
+  #
+  # @param byte_string [String] Length must be a multiple of 8
+  # @return [String] a string of words separated by spaces
+  #
+  # @raise Sixword::InputError
+  #
+  # @example
+  #   Sixword.encode_to_s('Hi world' * 2)
+  #   => "ACRE ADEN INN SLID MAD PAP ACRE ADEN INN SLID MAD PAP"
+  #
+  # @see Sixword.encode
+  #
   def self.encode_to_s(byte_string)
     encode(byte_string).join(' ')
   end
 
-  def self.encode_to_a(byte_string)
-    encode_iter(byte_string).to_a
-  end
-
-  def self.pad_encode_to_a(byte_string)
-    encode_iter(byte_string, words_per_slice:1, pad:true).to_a
-  end
-
+  # Like {Sixword.encode_to_sentences}, but allow variable length input.
+  #
+  # @param byte_string [String] A string of any length
+  # @return [Array<String>] an array of 6-word string sentences
+  #
+  # @example
+  #   >> Sixword.pad_encode_to_sentences('Hi worl' * 2)
+  #   => ["ACRE ADEN INN SLID MAD LEW", "CODY AS SIGH SUIT MUDD ABE2"]
+  #
   def self.pad_encode_to_sentences(byte_string)
     encode_iter(byte_string, words_per_slice:6, pad:true).to_a
   end
 
+  # Like {Sixword.encode_to_s}, but allow variable length input.
+  #
+  # @param byte_string [String] A string of any length
+  # @return [String] a string of words separated by spaces
+  #
+  # @example
+  #   >> Sixword.pad_encode_to_s('Hi worl' * 2)
+  #   => "ACRE ADEN INN SLID MAD LEW CODY AS SIGH SUIT MUDD ABE2"
+  #
+  def self.pad_encode_to_s(byte_string)
+    pad_encode(byte_string).join(' ')
+  end
+
+  # Encode a string of bytes in six-word encoding (full API). This is the
+  # relatively low level method that supports all the major options. See the
+  # various other top-level methods for convenience helpers.
+  #
+  # @param byte_string [String] A byte string to encode
+  # @param options [Hash]
+  #
+  # @option options [Boolean] :pad (false) Whether to use the custom padding
+  #   scheme established by this library. If false, then byte_string length
+  #   must be a multiple of 8.
+  # @option options [Integer] :words_per_slice (1) The number of words to
+  #   yield together in each iteration. By default, yield only a single word at
+  #   a time. You can yield up to 6 words together, which will be joined by a
+  #   space ` ` character.
+  #
+  # @yield [String] A String word (or String of space separated words, if
+  #   :words_per_slice is given)
+  #
+  # @return [Enumerator, nil] If no block is given, return an Enumerator
+  #
+  # @raise Sixword::InputError on incorrectly padded inputs
+  # @raise ArgumentError on bad argument types
+  #
   def self.encode_iter(byte_string, options={})
     options = {words_per_slice: 1, pad: false}.merge(options)
     words_per_slice = options.fetch(:words_per_slice)
@@ -51,7 +166,7 @@ module Sixword
     end
 
     unless block_given?
-      return Enumerator.new(self, :encode_iter, byte_string, options)
+      return to_enum(__method__, byte_string, options)
     end
 
     if !pad && byte_string.bytesize % 8 != 0
@@ -87,6 +202,39 @@ module Sixword
     end
   end
 
+  # Decode a six-word encoded string or string array.
+  #
+  # @param string_or_words [String, Array<String>] Either a String containing
+  #   whitespace separated words or an Array of String words
+  # @param options [Hash]
+  #
+  # @option options [Boolean] :padding_ok (false) Whether to accept the custom
+  #   padding format established by this library
+  #
+  # @return [String] A binary string of bytes
+  #
+  # @raise InputError if the input is malformed or invalid in various ways
+  #
+  # @example
+  #   >> Sixword.decode("ACRE ADEN INN SLID MAD PAP")
+  #   => "Hi world"
+  #
+  # @example
+  #   >> Sixword.decode("acre aden inn slid mad pap")
+  #   => "Hi world"
+  #
+  # @example
+  #   Sixword.decode(%w{ACRE ADEN INN SLID MAD PAP})
+  #   => "Hi world"
+  #
+  # @example
+  #   Sixword.decode([])
+  #   => ""
+  #
+  # @example
+  #   Sixword.decode("COAT ACHE A A A ACT6", padding_ok: true)
+  #   => "hi"
+  #
   def self.decode(string_or_words, options={})
     options = {padding_ok: false}.merge(options)
     padding_ok = options.fetch(:padding_ok)
@@ -110,6 +258,21 @@ module Sixword
     bstring
   end
 
+  # Like {Sixword.decode}, but allow input to contain custom padding scheme.
+  #
+  # @see Sixword.decode
+  #
+  # @param string_or_words [String, Array<String>] Either a String containing
+  #   whitespace separated words or an Array of String words
+  #
+  # @return [String] A binary string of bytes
+  #
+  # @raise InputError if the input is malformed or invalid in various ways
+  #
+  # @example
+  #   Sixword.decode("COAT ACHE A A A ACT6", padding_ok: true)
+  #   => "hi"
+  #
   def self.pad_decode(string_or_words)
     decode(string_or_words, padding_ok: true)
   end