moory 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c1c7aee3a878c285ee3469cba5bd8ee30cc422cf60740c8a2b95626970a3d23
-  data.tar.gz: 80efb57ff7a92638b72e27b0be65045ac408ccfe72e669716b3ce5ea35a58ed5
+  metadata.gz: 73b9daed021ae037a29e58725761a7d3cab583d3b85adf38f33eeda231f34aac
+  data.tar.gz: c582208c25b69c71f0b10d3fea858eee59189756d79d15fea9a6b7344483293d
 SHA512:
-  metadata.gz: c00b8597b73b4af0d5ca0127865bcc6f4df63199bf22d606edd8138663ad1b76d66426f7e13dbc93bd4864a68b6dfea6ce189b699fdeae4be93e788d16678488
-  data.tar.gz: bebda3ba5ef82ed632b51ffe7090b56882ea3eb2be71f5ff7d2f6d8b07c44c01ab065b75adfc4aeb51d2b0cc38de1a687793ab5917611276790efc36362cdf2a
+  metadata.gz: 91a92a25f4585c8e232a7e49f07d9be7e922ba68a336a94b7ea34da1e318758a4b22f1567d7ade42ab03dbf7aafb4314428e027c1b313e68e16f9c0c819a9912
+  data.tar.gz: b0282b7fc84c174549448fd13107136347ae7bfa5b879c49be0b0931fcdf9272602df2f2ad82813a279133742b084e7c908035b2875fe3fbf00b06119fc27aaa

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    moory (0.2.0)
+    moory (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -3,7 +3,83 @@ Welcome to the Moory gem!
 
 You can use this gem to create various kinds of finite machines using a simple specification language.
 
-Until I can get some tutorial material together, please take a look at the examples directory.  Therein you'll find a Finite Acceptor, a Decoder (Mealy machine), and something useless but (hopefully) illuminating.  Reading the spec files might also help.
+Below is an example of of how you might use the Acceptor, but until I can get some tutorial material together, please take a look at the examples directory.  Therein you'll find the Acceptor, a Decoder (Mealy machine), and something useless but (hopefully) illuminating.  Reading the spec files might also help.
+
+## Example: Creating an acceptor for ab*
+
+### Motivation
+
+Imagine that you want to create an incredible machine; one capable of determining whether a given character string belongs to the language described by the regular expression `ab*`.  Naturally, 
+you would not reach for a Regexp. That would be far too easy.  Instead you derive from
+the regular expression a Deterministic Finite Automaton (DFA) that does the job.  Here's what it 
+might look like:
+
+![ab_star](images/ab_star.png)
+
+Of course, you've set up and solved a system of equations verifying that the design is correct.  But how do we implement this in Ruby?  We won't bother trying to apply the State design pattern, because it is a pain.  Instead, we will employ Moory which is one of the 200+ gems that exist to make creating finite machines easy.
+
+### Implementing the Acceptor
+
+The first step is to install the Moory gem, achieved by issuing the following command:
+
+```
+gem install moory
+```
+
+When that's done, start up `irb` and paste the following:
+
+```ruby
+require 'moory'
+
+ab_star = Moory::Acceptor.create(
+  initial: '0',
+  transitions: %q{
+    0 : a : 1
+    0 : b : 2
+    1 : a : 2
+    1 : b : 1
+    2 : a : 2
+    2 : b : 2
+  },
+  final: %w{ 1 }
+)
+```
+
+I'll explain the syntax of the transitions later, but, you have done enough to confidently type:
+
+```ruby
+ab_star.accepts?(string: "ab")
+```
+
+and be delighted to see that the answer is `true`.
+
+If you are naturally curious, then you might want to put `ab_star` through its paces with further candidates:
+
+```ruby
+ab_star.accepts?(string: "abbb") # => true
+ab_star.accepts?(string: "aab")  # => false
+ab_star.accepts?(string: "aba")  # => false
+```
+
+We aren't stuck with testing the strings against the initial state.  We can ask the machine to begin its match in any state:
+
+```ruby
+ab_star.accepts?(string: "bbb", in_state: '1') 
+# => true
+```
+
+But what about including characters that don't belong to the machine's alphabet?
+
+```ruby
+ab_star.accepts?(string: "bbc", in_state: '1')
+```
+
+Well this one will be uncermenoiously rejected with a runtime error (unless you are using version 0.1.0, where I forgot to handle bad input, sorry!)
+
+### Before you go...
+
+There's more to Moory than its Acceptor.  I'll show you how to use its other features in another memo.
+
 
 ## Installation
 
@@ -21,10 +97,6 @@ Or install it yourself as:
 
     $ gem install moory
 
-## Usage
-
-Please see the examples directory, for now.
-
 ## 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 interactive prompt that will allow you to experiment.

data/lib/moory/version.rb

@@ -1,3 +1,3 @@
 module Moory
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moory
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Adam W. Grant
@@ -72,6 +72,7 @@ files:
 - examples/ab_star.rb
 - examples/silly.rb
 - examples/single_as_and_bs.rb
+- images/ab_star.png
 - lib/moory.rb
 - lib/moory/acceptor.rb
 - lib/moory/decoder.rb