enigma_machine 0.0.1 → 0.0.2

data/.gitignore

@@ -3,3 +3,5 @@
 Gemfile.lock
 pkg/*
 .rvmrc
+doc/*
+.yardoc

data/Rakefile

@@ -5,3 +5,6 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/enigma_machine.gemspec

@@ -18,4 +18,6 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency "rspec"
   s.add_development_dependency "rake"
+  s.add_development_dependency "yard", '~> 0.8.2'
+  s.add_development_dependency "redcarpet"
 end

data/lib/enigma_machine.rb

@@ -1,8 +1,47 @@
 class EnigmaMachine
-  ConfigurationError = Class.new(StandardError)
+  class ConfigurationError < StandardError; end
 
   ALPHABET = ('A'..'Z').to_a
 
+  # Constructs an enigma machine with given reflector, rotors and plugboard settings.
+  #
+  # Examples:
+  #
+  # You can use the standard reflectors and rotors:
+  #
+  #   EnigmaMachine.new(
+  #     :reflector => :B,
+  #     :rotors => [[:i, 10], [:ii, 14], [:iii, 21]],
+  #     :plug_pairs => %w(AP BR CM FZ GJ IL NT OV QS WX)
+  #   )
+  #
+  # Or you can use custom reflector and rotor configurations:
+  #
+  #   EnigmaMachine.new(
+  #     :reflector => %w(AF BV CP DJ EI GO HY KR LZ MX NW TQ SU),
+  #     :rotors => [
+  #       ['BDFHJLCPRTXVZNYEIWGAKMUSQO_V', 10],
+  #       ['JPGVOUMFYQBENHZRDKASXLICTW_MZ', 14],
+  #       ['ABCDEFGHIJKLMNOPQRSTUVWXYZ_AHT', 21]
+  #     ],
+  #     :plug_pairs => %w(AP BR CM FZ GJ IL NT OV QS WX)
+  #   )
+  #
+  # When specifying a custom rotor, the letters after the _ indicate the notch positions.
+  #
+  # @param config [Hash] A Hash of configuration params
+  # @option config [Symbol,Array<String>] :reflector Which reflector to use.  Reference one of the
+  #   standard ones by Symbol, or pass in an array of
+  #   letter pairs for a custom configuration.
+  # @option config [Array<Array>] :rotors Array of details for 3 or more rotors.  Specified from
+  #   left to right. Each one is specified as a tuple of the rotor spec,
+  #   and ring setting.  The rotor_spec can be one of the standard rotors
+  #   referenced by Symbol, or a custom rotor described by a config string
+  #   (see Examples).
+  # @option config [Array<String>] :plug_pairs an Optional array of letter pairs specifying the plugboard
+  #   configuration.  If omitted, no plugboard substitutions will be performed.
+  #
+  # @raise [ConfigurationError] if an invalid configuration was specified
   def initialize(config)
     @reflector = Reflector.new config[:reflector]
     @rotors = []
@@ -12,17 +51,35 @@ class EnigmaMachine
     @plugboard = Plugboard.new(config[:plug_pairs] || [], @rotors.last)
   end
 
+  # Set the rotors to the given positions.
+  #
+  # Pass in Positions for the rotors from left to right
+  #
+  # @param positions [List<String>] the positions to set the rotors to
+  # @return [void]
   def set_rotors(*positions)
     positions.each_with_index do |position, i|
       @rotors[i].position = position
     end
   end
 
+  # Simulates pressing a given key on the machine keyboard.
+  #
+  # Advances the rotors, and then translates the letter
+  #
+  # @param letter [String] the letter to be translated
+  # @return [String] the translated letter
   def press_key(letter)
     advance_rotors
     @plugboard.translate(letter)
   end
 
+  # Translates the given message using the current settings
+  #
+  # This will pass through space and - unmodified, and discard any other non-alpha characters.
+  #
+  # @param message [String] the message to be translated
+  # @return [String] the translated message
   def translate(message)
     message.upcase.each_char.map do |letter|
       case letter

data/lib/enigma_machine/plugboard.rb

@@ -1,16 +1,35 @@
 class EnigmaMachine
   class Plugboard
-    def initialize(mapping_pairs, decorated)
+    # Construct a new plugboard
+    #
+    # Example:
+    #
+    #   Plugboard.new(%w(AB CD EF GH), @rotor)
+    #
+    # @param mapping_pairs [Array<String>] A list of letter pairs to be connected
+    # @param rotor [#translate] the rightmost rotor that will be called next in the processing chain
+    # @raise [ConfigurationError] if an invalid mapping passed in (not pairs of leters, or a letter connected more than once)
+    def initialize(mapping_pairs, rotor)
       build_mapping(mapping_pairs)
-      @decorated = decorated
+      @decorated = rotor
     end
 
+    # Translate a letter
+    #
+    # This performs a substitution, calls the rotor to do the rest of the translation, and then
+    # substitutes the result on the way back out.
+    #
+    # @param letter [String] the letter to be translated
+    # @return [String] the translated letter
     def translate(letter)
       step = substitute(letter)
       step = @decorated.translate(step)
       substitute(step)
     end
 
+    # Substitutes a letter according the configured plug pairs
+    # @param letter [String] the letter to be substituted
+    # @return [String] the substituted letter
     def substitute(letter)
       @mapping[letter] || letter
     end

data/lib/enigma_machine/reflector.rb

@@ -8,6 +8,17 @@ class EnigmaMachine
       :Cthin => %w(AR BD CO EJ FN GT HK IV LM PW QZ SX UY),
     }
 
+    # Construct a new reflector
+    #
+    # Examples:
+    #
+    #   Reflector.new(:B)
+    #   Reflector.new(%w(AY BR CU DH EQ FS GL IP JX KN MO TZ VW))
+    #
+    # @param mapping [Symbol,Array<String>] A symbol representing one of the standard reflectors or
+    #   an array of 13 letter pairs to be swapped by the reflector
+    # @raise [ConfigurationError] if an invalid mapping is passed in (unrecognised standard reflector,
+    #   not 13 pairs of letters, or a letter appearing more than once)
     def initialize(mapping)
       if mapping.is_a?(Symbol)
         raise ConfigurationError unless STANDARD_MAPPINGS.has_key?(mapping)
@@ -17,6 +28,11 @@ class EnigmaMachine
       build_mapping(mapping)
     end
 
+    # @!method translate(letter)
+    #   simply perform a substitution
+    #
+    #   @param letter [String] the letter to be substituted
+    #   @return [String] the substituted letter
     alias :translate :substitute
   end
 end

data/lib/enigma_machine/rotor.rb

@@ -13,6 +13,20 @@ class EnigmaMachine
       :gamma  => "FSOKANUERHMBTIYCWLQPZXVGJD_", # in position 4, and hence have no notches.
     }
 
+    # Construct a new rotor
+    #
+    # Examples:
+    #
+    #   Rotor.new(:ii, 12, @next)
+    #   Rotor.new("BDFHJLCPRTXVZNYEIWGAKMUSQO_V", 15, @next)
+    #
+    # When specifying a custom rotor_spec, the letters after the _ indicate the notch positions
+    #
+    # @param rotor_spec [Symbol, String] A symbol representing one of the standard rotors or
+    #   a string specifying the mapping and notch positions (see Examples)
+    # @param ring_setting [Integer] The ring setting for the rotor.
+    # @param decorated [#translate] The next component in the processing chain (the next rotor, or the reflector)
+    # @raise [ConfigurationError] if an invalid rotor_spec is passed in (unrecognised standard rotor)
     def initialize(rotor_spec, ring_setting, decorated)
       if rotor_spec.is_a?(Symbol)
         raise ConfigurationError unless STANDARD_ROTORS.has_key?(rotor_spec)
@@ -26,33 +40,56 @@ class EnigmaMachine
       self.position = 'A'
     end
 
+    # Set the position of the rotor
+    #
+    # @param letter [String] the letter position to set the rotor to
+    # @return [void]
     def position=(letter)
       @position = ALPHABET.index(letter)
     end
+    # @return [String] the current position of the rotor
     def position
       ALPHABET[@position]
     end
 
+    # Advance the position of the rotor.
+    # @return [void]
     def advance_position
       @position = (@position + 1).modulo(26)
     end
 
+    # Is the rotor currently at a notch position.
     def at_notch?
       @notch_positions.include?(self.position)
     end
 
+    # Perform the forward translation of a letter (i.e. the path towards the reflector)
+    #
+    # @param letter [String] the letter to be translated
+    # @return [String] the translated letter
     def forward(letter)
       index = add_offset ALPHABET.index(letter)
       new_index = sub_offset @mapping[index]
       ALPHABET[new_index]
     end
 
+    # Perform the reverse translation of a letter (i.e. the path returning from the reflector)
+    #
+    # @param letter [String] the letter to be translated
+    # @return [String] the translated letter
     def reverse(letter)
       index = add_offset ALPHABET.index(letter)
       new_index = sub_offset @mapping.index(index)
       ALPHABET[new_index]
     end
 
+    # Translate a letter
+    #
+    # This performs a forward substitution, calls the next component to do the rest of the translation, and then
+    # reverse substitutes the result on the way back out.
+    #
+    # @param letter [String] the letter to be translated
+    # @return [String] the translated letter
     def translate(input)
       step = forward(input)
       step = @decorated.translate(step)

data/lib/enigma_machine/version.rb

@@ -1,3 +1,3 @@
 class EnigmaMachine
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enigma_machine
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-22 00:00:00.000000000 Z
+date: 2012-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &18339180 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,47 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18339180
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &18357640 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.2
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +69,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *18357640
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Enigma machine simulator
 email:
 - alex@tomlins.org.uk
@@ -71,7 +113,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2207890655996414444
+      hash: -1642108846997951420
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -80,11 +122,18 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2207890655996414444
+      hash: -1642108846997951420
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Enigma machine simulator
-test_files: []
+test_files:
+- spec/enigma_machine_spec.rb
+- spec/integration_spec.rb
+- spec/plugboard_spec.rb
+- spec/reflector_spec.rb
+- spec/rotor_spec.rb
+- spec/spec_helper.rb
+has_rdoc: