rotor_machine 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9b724da9efeeb1cb707e1b455a0cca97b9a911ce0b8bf11824e786c044135d6
-  data.tar.gz: 844f9bc228874dc922369d00a3e2ae6caec69c14c63491961e21fb5b32988873
+  metadata.gz: 547ab156c985ce0df5dad34665d7705456ff34993b84cc738c887fce7144783f
+  data.tar.gz: 6d2211b04113a15757706928e3b572bc09bd2781036fb0317344984f774bd82e
 SHA512:
-  metadata.gz: 3da1a7af7b05149bb3ba3bbb2e514e548ea8f6b7727a1b35858a9c381372f01c2cec692e95d20cd0a435b7a21d5cfa1e1f3ec659806aba9862a7c2b7ddfa6900
-  data.tar.gz: 04a238d1393e0b9ca931f6af190e1813ee9251b299c829ba1df7928a1a94fc2479149576aaef3505fac2ce02d5b1ba7afa347ed3400a2fc500137e15fdac5f76
+  metadata.gz: d3d3e224d89bdc1531cfe50f40cf66cec543b693da2547ebf4fd4a3892fc125f5a86c60c96d0912c0161f28e2c353772a5987da99a1d2872d2ee163e49616321
+  data.tar.gz: a85cec802ad9a032b8348f5311bd686428d8e23c183182db4dcf9827c831d272b4bb2df1d14716e3749b94928c7c9fd7920d98b18d649ffd6db947d73b17ecf4

data/README.md

@@ -2,17 +2,17 @@
 
 ![German Enigma machine](https://github.com/tammycravit/rotor_machine/blob/master/images/Bundesarchiv_Enigma.jpg?raw=1)
 
-The `RotorMachine` gem provides a simple Ruby implementation of the 
+The `RotorMachine` gem provides a simple Ruby implementation of the
 [Enigma](https://en.wikipedia.org/wiki/Enigma_machine) rotor encryption machine.
 
-I wrote RotorMachine primarily as an exercise in Test-Driven Development with 
-RSpec. It is not intended to be efficient or performant, and I wasn't striving much 
-for idiomatic conciseness. My aims were fairly modular code and a relatively 
+I wrote RotorMachine primarily as an exercise in Test-Driven Development with
+RSpec. It is not intended to be efficient or performant, and I wasn't striving much
+for idiomatic conciseness. My aims were fairly modular code and a relatively
 complete RSpec test suite.
 
-Many thanks to Kevin Sylvestre, whose 
-[blog post](https://ksylvest.com/posts/2015-01-03/the-enigma-machine-using-ruby) 
-helped me understand some aspects of the internal workings of the Enigma and 
+Many thanks to Kevin Sylvestre, whose
+[blog post](https://ksylvest.com/posts/2015-01-03/the-enigma-machine-using-ruby)
+helped me understand some aspects of the internal workings of the Enigma and
 how the signals flowed through the pieces of the machine.
 
 ## Installation
@@ -33,89 +33,89 @@ Or install it yourself as:
 
 ## Architecture
 
-The [`RotorMachine::Machine`](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Machine) 
+The [`RotorMachine::Machine`](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Machine)
 class serves as the entrypoint and orchestrator for an Enigma machine.
-  
+
 ### Components of an Enigma machine
-  
-The Enigma machine, as represented by the [RotorMachine](http://www.rubydoc.info/github/tammycravit/rotor_machine/master) 
+
+The Enigma machine, as represented by the [RotorMachine](http://www.rubydoc.info/github/tammycravit/rotor_machine/master)
 module, consists of the following components:
-  
-* One or more [rotors](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Rotor), which 
-  perform the transposition ciphering and also rotate to produce a polyalphabetic (rather 
+
+* One or more [rotors](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Rotor), which
+  perform the transposition ciphering and also rotate to produce a polyalphabetic (rather
   than simple substitution) cipher.
-  
-* A [reflector](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Reflector), which 
+
+* A [reflector](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Reflector), which
   performs a simple symmetric substitution of letters
-  
-* A [plugboard](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Plugboard), which 
+
+* A [plugboard](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Plugboard), which
   allows pairs of letters to be transposed on a per-message basis.
-  
-On an actual Enigma machine, these components are all electromechanical, and 
-the Enigma also included a keyboard, a grid of lights to show the results, and 
-in some cases a printer. Since this is a simulated Enigma, obviously, no 
+
+On an actual Enigma machine, these components are all electromechanical, and
+the Enigma also included a keyboard, a grid of lights to show the results, and
+in some cases a printer. Since this is a simulated Enigma, obviously, no
 keyboard/printer are supplied here. In this simulation, the
 [Machine](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/RotorMachine/Machine)
 class serves to encapsulate all of these components.
-  
+
 The polyalphabetic encryption of the Enigma comes from the fact that the
 rotors are linked (mechanically in a real Enigma) so that they rotate
 one or more "steps" after each character, changing the signal paths and
 transpositions. This means that a sequence of the same plaintext character
 will encipher to different ciphertext characters.
-  
+
 The rotors are designed to advance such that each time a rotor completes
 a full revolution, it will advance the rotor to its left once. The rotors
 allow you to configure how many positions they advance when they do. So,
 assuming all rotors are advancing one position at a time, if the rotors
 have position "AAZ", their state after the next character is typed will
 be "ABA".
-  
+
 To learn much more about the inner workings of actual Enigma machines,
 visit [Enigma Machine (Wikipedia)](https://en.wikipedia.org/wiki/Enigma_machine).
-  
+
 ###  The Signal Path of Letters
-  
+
 Here's a visual depiction of the signal path of a single character through
 a (physical) Enigma machine:
 
 ![Enigma signal path](https://github.com/tammycravit/rotor_machine/blob/master/images/File:Enigma_wiring_kleur.png?raw=1)
 
-As you can see, the electrical signal from a keypress is routed through the 
-plugboard, then through each of the rotors in sequence from left to right. 
-The signal then passes through the reflector (where it is transposed again), 
-then back through the rotors in reverse order, and finally back through the 
-plugboard a second time before being displayed on the light grid and/or 
+As you can see, the electrical signal from a keypress is routed through the
+plugboard, then through each of the rotors in sequence from left to right.
+The signal then passes through the reflector (where it is transposed again),
+then back through the rotors in reverse order, and finally back through the
+plugboard a second time before being displayed on the light grid and/or
 printer.
-  
+
 The result of the machine's signal path being a loop is that encryption and
 decryption are the same operation. That is to say, if you set the rotors
 and plugboard, and then type your plaintext into the machine, you'll get
 a string of ciphertext. If you then reset the machine to its initial state
 and type the ciphertext characters into the machine, you'll produce your
 original plaintext.
-  
-One consequence of the Enigma's design is that a plaintext letter will never 
-encipher to itself. The Allies were able to exploit this property to help 
-[break the Enigma's encryption](https://en.wikipedia.org/wiki/Cryptanalysis_of_the_Enigma) 
+
+One consequence of the Enigma's design is that a plaintext letter will never
+encipher to itself. The Allies were able to exploit this property to help
+[break the Enigma's encryption](https://en.wikipedia.org/wiki/Cryptanalysis_of_the_Enigma)
 during World War II.
-  
+
 ## Usage
 
 To use the RotorMachine Enigma machine, you need to perform the following
 steps:
-  
+
 1. Create a new `RotorMachine::Machine` object.
 2. Add one or more `RotorMachine::Rotor`s  to the `rotors` array.
 3. Set the `reflector` to an instance of the `RotorMachine::Reflector` class.
 4. Make any desired connections in the Plugboard.
 5. Optionally, set the rotor positions with `#set_rotors`.
-  
+
 You're now ready to encipher and decipher your text using the `#encipher`
 method to encode/decode, and `#set_rotors` to reset the machine state.
-  
+
 The `#default_machine` and `#empty_machine` class methods are shortcut
-factory methods whcih set up, respectively, a fully configured machine 
+factory methods whcih set up, respectively, a fully configured machine
 with a default set of rotors and reflector, and an empty machine with
 no rotors or reflector.
 
@@ -134,7 +134,7 @@ machine.rotors << RotorMachine::Rotor.new(RotorMachine::Rotor::ROTOR_II, "A", 1)
 machine.rotors << RotorMachine::Rotor.new(RotorMachine::Rotor::ROTOR_III, "A", 1)
 machine.reflector = RotorMachine::Reflector.new(RotorMachine::Reflector::REFLECTOR_A)
 
-machine.plugboard.connect("A", "M") 
+machine.plugboard.connect("A", "M")
 machine.plugboard.connect("Q", "K")
 
 machine.set_rotors("CFL")
@@ -145,7 +145,7 @@ machine.set_rotors("CFL")
 new_plaintext = machine.encipher(ciphertext)  # => "THISI SASUP ERSEC RETME SSAGE"
 ```
 
-## Example - Simplified Setup Using the Factory 
+## Example - Simplified Setup Using the Factory
 
 ```ruby
 require 'rotor_machine'
@@ -164,58 +164,83 @@ machine.set_rotors("CFL")
 new_plaintext = machine.encipher(ciphertext)  # => "THISI SASUP ERSEC RETME SSAGE"
 ```
 
+## Using the Wrapper DSL
+
+A simple wrapper DSL (domain-specific language) is provided, primarily for
+testing and other "conversational" or interactive uses. This DSL is defined in
+the `RotorMachine::Session` class. Usage is similar to the following:
+
+```ruby
+RotorMachine.Session do
+  default_machine
+
+  set_rotors "AAA"
+  connect "A", "G"
+  encipher "THIS IS A SUPER SECRET MESSAGE"
+  ct = last_result
+
+  set_rotors "AAA"
+  encipher ct
+  puts last_result    # THISI SASUP ERSEC RETME SSAGE
+end
+```
+
+After the operations in the block are executed, the `RotorMachine.Session` method
+will return the `RotorMachine::Session` object, which can be further reused if
+needed.
+
 ## Documentation
 
-The classes in 
-[`lib/rotor_machine/`](https://github.com/tammycravit/rotor_machine/tree/master/lib/rotor_machine) 
-all contain [documentation](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/) that 
-pretty exhaustively describe their operation. 
-The RSpec tests in the [`spec/`](https://github.com/tammycravit/rotor_machine/tree/master/spec) 
+The classes in
+[`lib/rotor_machine/`](https://github.com/tammycravit/rotor_machine/tree/master/lib/rotor_machine)
+all contain [documentation](http://www.rubydoc.info/github/tammycravit/rotor_machine/master/) that
+pretty exhaustively describe their operation.
+The RSpec tests in the [`spec/`](https://github.com/tammycravit/rotor_machine/tree/master/spec)
 directory are also instructive for how the library works and how to use it.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, 
-run `rake spec` to run the tests. You can also run `bin/console` for an 
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `rake spec` to run the tests. You can also run `bin/console` for an
 interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. 
+To install this gem onto your local machine, run `bundle exec rake install`.
 
-To release a new version, update the version number in `version.rb`, and then 
-run `bundle exec rake release`, which will create a git tag for the version, 
+To release a new version, update the version number in `version.rb`, and then
+run `bundle exec rake release`, which will create a git tag for the version,
 push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-This gem depends on the [`tcravit_ruby_lib`](https://github.com/tammycravit/tcravit_ruby_lib) 
-gem, which provides Rake tasks to update the version number. You can use the 
-`bundle exec rake version:bump:build`, `bundle exec version:bump:minor` and 
-`bundle exec rake version:bump:major` tasks to increment the parts of 
+This gem depends on the [`tcravit_ruby_lib`](https://github.com/tammycravit/tcravit_ruby_lib)
+gem, which provides Rake tasks to update the version number. You can use the
+`bundle exec rake version:bump:build`, `bundle exec version:bump:minor` and
+`bundle exec rake version:bump:major` tasks to increment the parts of
 the version number. (These tasks rewrite the file
-[`lib/rotor_machine/version.rb`](https://github.com/tammycravit/rotor_machine/blob/master/lib/rotor_machine/version.rb). 
-After using them, you'll need to run a `git add lib/rotor_machine/version.rb` 
+[`lib/rotor_machine/version.rb`](https://github.com/tammycravit/rotor_machine/blob/master/lib/rotor_machine/version.rb).
+After using them, you'll need to run a `git add lib/rotor_machine/version.rb`
 and `git commit -m "version bump"`.
 
 ### Contributing
 
-Bug reports and pull requests are welcome on GitHub at 
-[https://github.com/tammycravit/rotor_machine]. Pull requests for code changes 
+Bug reports and pull requests are welcome on GitHub at
+[https://github.com/tammycravit/rotor_machine]. Pull requests for code changes
 should include [RSpec](http://rspec.info) tests for the new/changed features.
 Pull requests for documentation and other updates are also welcome.
 
-This project is intended to be a safe, welcoming space for collaboration, and 
-contributors are expected to adhere to the 
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the
 [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-Contributions from people who identify as women, BIPOC folx, LGBT folx, 
+Contributions from people who identify as women, BIPOC folx, LGBT folx,
 and members of other marginalized communities are especially welcomed.
 
 ### Code of Conduct
 
-Everyone interacting in the RotorMachine project’s codebases, issue trackers, 
-chat rooms and mailing lists is expected to follow the 
+Everyone interacting in the RotorMachine project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
 [code of conduct](https://github.com/tammycravit/rotor_machine/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the 
+The gem is available as open source under the terms of the
 [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license.
 
 ## Image Credits
@@ -223,6 +248,6 @@ The gem is available as open source under the terms of the
 * Enigma image - from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Bundesarchiv_Bild_183-2007-0705-502,_Chiffriermaschine_%22Enigma%22.jpg),
   provided by Das Bundesarchiv (German Federal Archives).
 
-* Enigma signal path image - from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Enigma_wiring_kleur.svg), 
+* Enigma signal path image - from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Enigma_wiring_kleur.svg),
   by [MesserWoland](https://commons.wikimedia.org/wiki/User:MesserWoland)
 

data/lib/rotor_machine/session.rb

@@ -0,0 +1,161 @@
+module RotorMachine
+  ##
+  # The {Session} object provides a very simple DSL for "conversational" interactions
+  # with the {RotorMachine::Machine} and its subordinate classes. This is useful for
+  # interactive and experimental applications, for testing, and so forth.
+  #
+  # Eventually, a {Pry}-based REPL loop might be added to the project, but this
+  # functionality does not exist yet.
+  #
+  # Instance methods are a loose wrapper around the rest of the library and are only
+  # loosely documented here. Argument validation is handled by simply bubbling up
+  # exceptions raised by the implementatation method.
+  #
+  # == Example Usage
+  #
+  #   RotorMachine.Session do
+  #     default_machine
+  #     
+  #     set_rotors "AAA"
+  #     connect "A", "G"
+  #     encipher "THIS IS A SUPER SECRET MESSAGE"
+  #     ct = last_result
+  #     
+  #     set_rotors "AAA"
+  #     encipher ct
+  #     puts last_result    # THISI SASUP ERSEC RETME SSAGE
+  #   end
+  class Session
+    ##
+    # Initialize the {RotorMachine::Session} instance. The methods of this object,
+    # except for {#machine} and {#last_result}, are primarily intended to be
+    # called within the {Session} block (via {instance_eval}).
+    #
+    # @param opts [Hash] The setup options hash. Currently unused, but any options
+    #                    provided are stored.
+    # @param block [Block] The operations block. If provided, it is executed via
+    #                      {instance_eval}. The instance is returned following
+    #                      execution of the block.
+    def initialize(opts={}, &block)
+      @opts = opts
+      @machine = RotorMachine::Factory.empty_machine()
+      @last_result = nil
+      instance_eval(&block) if block_given?
+      return self
+    end
+
+    ##
+    # Create a rotor and add it to the machine.
+    def rotor(kind, position=0, step_size=1)
+      r = RotorMachine::Factory.build_rotor rotor_kind: kind,
+        initial_position: position,
+        step_size: step_size
+      @machine.rotors << r if r.is_a?(RotorMachine::Rotor)
+    end
+
+    ##
+    # Set the machine's reflector.
+    def reflector(kind, position="A")
+      r = RotorMachine::Factory.build_reflector reflector_kind: kind,
+        initial_position: position
+      @machine.reflector = r if r.is_a?(RotorMachine::Reflector)
+    end
+
+    ##
+    # Connect a pair of letters on the machine's plugboard.
+    def connect(from, to)
+      @machine.plugboard.connect(from, to)
+    end
+
+    ##
+    # Disconnect a letter (and its inverse) from the machine's plugboard.
+    def disconnect(from)
+      @machine.plugboard.disconnect(from)
+    end
+
+    ##
+    # Encipher a string.
+    def encipher(the_string="")
+      res = @machine.encipher(the_string)
+      @last_result = res
+      res
+    end
+
+    ##
+    #Set the positions of the rotors.
+    def set_positions(pos_string)
+      @machine.set_rotors(pos_string)
+    end
+
+    ##
+    # Remove all rotors from the machine.
+    def clear_rotors
+      @machine.rotors = []
+    end
+
+    ##
+    # Remove all connections from the plugboard.
+    def clear_plugboard
+      @machine.plugboard = RotorMachine::Plugboard.new
+    end
+
+    ##
+    # Configure the machine to its default state (as in the {RotorMachine::Factory}
+    # object's {default_machine} method.)
+    def default_machine
+      @machine = RotorMachine::Factory.default_machine
+    end
+
+    ##
+    # Configure the machine to its empty state (as in the {RotorMachine::Factory}
+    # object's {empty_machine} method.)
+    def empty_machine
+      @machine = RotorMachine::Factory.empty_machine
+    end
+
+    ##
+    # Return the inner {RotorMachine::Machine} object.
+    def machine
+      @machine
+    end
+
+    ##
+    # Return the results of the last {encipher} operation, or nil.
+    def last_result
+      @last_result
+    end
+
+    ##
+    # {plug} is a convenience alias for {connect}
+    alias_method "plug", "connect"
+
+    ##
+    # {unplug} is a convenience alias for {disconnect}
+    alias_method "unplug", "disconnect"
+
+    ##
+    # {set_rotors} is a convenience alias for {set_positions}
+    alias_method "set_rotors", "set_positions"
+
+    ##
+    # {encode} is a convenience alias for {encipher}
+    alias_method "encode", "encipher"
+
+    ##
+    # {cipher} is a convenience alias for {encipher}
+    alias_method "cipher", "encipher"
+
+    ##
+    # {the_machine} is a convenience alias for {machine}
+    alias_method "the_machine", "machine"
+  end
+
+  ##
+  # The class method Session is the entrypoint for the DSL. When invoked with a
+  # block, it creates a new {RotorMachine::Session} object, passes the block to
+  # it to be run with {instance_eval}, and then the {RotorMachine::Session} object
+  # is returned to the caller.
+  def self.Session(opts={}, &block)
+    RotorMachine::Session.new(opts, &block)
+  end
+end

data/lib/rotor_machine/version.rb

@@ -1,4 +1,4 @@
 module RotorMachine
-	VERSION_DATA = [1, 1, 1]
+	VERSION_DATA = [1, 2, 0]
 	VERSION = VERSION_DATA.join(".")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rotor_machine
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Tammy Cravit
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-22 00:00:00.000000000 Z
+date: 2018-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tcravit_ruby_lib
@@ -195,6 +195,7 @@ files:
 - lib/rotor_machine/plugboard.rb
 - lib/rotor_machine/reflector.rb
 - lib/rotor_machine/rotor.rb
+- lib/rotor_machine/session.rb
 - lib/rotor_machine/string_extensions.rb
 - lib/rotor_machine/version.rb
 - rotor_machine.gemspec