moory 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48186775b1c7f9b85822f58dadc0f2f355b1fc872e6ab7abcb1883da9b9d74e9
-  data.tar.gz: 4edd7b2f0a957aaeb6d016d25b9fc7f638f69dc20e2d925c9a11b0a13863a092
+  metadata.gz: 28123aa5014d091460be8427c963f0cba5516dd319eca1e4e14ebcfed6fa4040
+  data.tar.gz: a6bfbc1b04c2ec1f2910f5eb01dc17515f99fe3ae6040ae4e5c48d03b39e5703
 SHA512:
-  metadata.gz: a5c5a11ad922e36aa09687535e52273661520b64b42c0867a6d0f5c9b9b120a2408e98737515f10be6dfeffc83ee55b55a3699c8dc007e2c7b59b1b9b09b8a06
-  data.tar.gz: 62c3df5b0cd326376f1434d2d6a8c3b3f3b7c1a3abdd05a0c9425f3f118bde51cccad786d48186d2155d7b32e900ef455858014fef72a9e581a8b367d19eae67
+  metadata.gz: 2e57244347beccfa883a776443b56b3beaed903a06582fec89810896546a180c191cb301384e1ebabac460b887f61706540c4fb6677ce0e1e0f6d70eea714138
+  data.tar.gz: 4cf05c5208129d257b6b3c7e4a5b139af5f64500c9aed726d1bcf1a53c8f8cd504af5756c5736dd023d0dab67dbe0fd22ba50212a3e88226dc1f8c8f0b75955c

data/Gemfile.lock

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

data/README.md

@@ -1,14 +1,13 @@
 # Moory
 Welcome to the Moory gem!
 
-You can use this gem to create various kinds of finite machines using a simple specification language.
+You can use this gem to create various kinds of finite machines, and even teach objects manners using a simple plain-text specification language.
 
-The [wiki](https://github.com/elclavijero/moory/wiki) is where to go if you are for looking for tutorial material.  Perhaps also look in the examples directory.  Therein you'll find use of the Acceptor, Decoder (Mealy machine), and something useless but (hopefully) illuminating.
+The [wiki](https://github.com/elclavijero/moory/wiki) is where to go if you are for looking for tutorial material.  Perhaps also look in the examples directory.
 
-Until you do, here is an example showing how you might use the Acceptor.
+Until you do, here are two examples: the first is an acceptor, and the second is a **well mannered** object.
 
-
-## Example: Creating an acceptor for ab*
+## Example: An acceptor for ab*
 
 ### Motivation
 
@@ -88,9 +87,117 @@ ab_star.accepts?(string: "abcbb")
 
 That's better.
 
+## Example: A well mannered object
+If you haven't already, open up `irb` and create an uncouth object
+
+```ruby
+uncouth = Object.new
+```
+
+and teach it how to speak
+
+```ruby
+def uncouth.say_foo
+  p 'foo'
+end
+def uncouth.say_bar
+  p 'bar'
+end
+def uncouth.say_something_nice(name)
+  p "Hello, #{name}. You look nice."
+end
+```
+
+Do you see anything wrong here? Doesn't that object seem a little dangerous? Everybody knows that `"foo"` comes before `"bar"` in code examples.  That absurd object might ruin everything! Is there anything we can do to prevent it from doing the unthinkable?
+
+```ruby
+uncouth.say_bar
+uncouth.say_foo
+```
+
+Yes. We can filter calls to the uncouth object using Moory's WellMannered class.  We need it's methods to be called according to foo-bar-etiquette:
+
+![ab_star](images/foo_bar_etiquette.png)
+
+Let's describe those rules using a language Moory understands:
+
+```ruby
+the_rules_of_foo_bar_etiquette = """
+  start        : say_foo  : said_foo
+    
+  said_foo     : say_foo  : said_foo
+  said_foo     : say_bar  : said_foo_bar
+
+  said_foo_bar : say_foo  : said_foo_bar
+  said_foo_bar : say_bar  : said_foo_bar
+"""
+```
+
+Let's make a postive change, and hereon refer to the uncouth object as the `well_mannered_object`.
+It will be our `protege`:
+
+```ruby
+require 'moory'
+
+well_mannered_object = Moory::WellMannered.new(
+  protege: uncouth,
+  rules:   the_rules_of_foo_bar_etiquette
+)
+```
+Now let's have a conversation with our protege.
+```ruby
+well_mannered_object.say_something_nice('Adam')
+# "Hello, Adam. You look nice."
+```
+That is nice.
+```ruby
+well_mannered_object.say_bar
+```
+So far so good. Our well mannered object is proving to be polite.  If someone asks it to depart from protocol, it will just quietly refuse.  But what if that isn't enough? What should it do if someone asks it to do something really bad?  The trouble is that well mannered objects are so well-behaved, they won't do depart from the protocol unless we say its OK. Let's do that.
+
+```ruby
+well_mannered_object.response_to_rule_breaking = proc { |msg|
+  p "You shouldn't ask me to #{msg}! I'm telling!"
+}
+```
+
+Now when we ask it to do something it out of turn
+```ruby
+well_mannered_object.say_bar
+# "You shouldn't ask me to say_bar! I'm telling!"
+```
+it will tell on you.  What a nice object!  Now don't be such a telltale.
+```ruby
+well_mannered_object.response_to_rule_breaking = nil
+```
+Let's continue
+```ruby
+well_mannered_object.say_bar
+```
+Good. You didn't complain.
+```ruby
+well_mannered_object.say_foo
+# "foo"
+```
+Promising.  You haven't yet spoken out of turn.
+```ruby
+well_mannered_object.say_foo
+# "foo"
+```
+A perfectly acceptable reptition.
+```ruby
+well_mannered_object.say_bar
+# "bar"
+```
+Wonderful!
+```ruby
+well_mannered_object.say_something_nice('Adam')
+```
+Yes. Thank you.
+
 ### Before you go...
 
-There's more to Moory than its Acceptor.  I'll show you how to use its other features in the [wiki](https://github.com/elclavijero/moory/wiki).
+There's more to Moory than its Acceptors and WellMannered objects.  I'll show you how to use its other features in the [wiki](https://github.com/elclavijero/moory/wiki).
 
 
 ## Installation

data/examples/well_mannered_objects.rb

@@ -0,0 +1,81 @@
+# Well-mannered objects
+
+# Suppose we have an uncouth object 
+uncouth = Object.new
+
+# and it can speak
+def uncouth.say_foo
+  p 'foo'
+end
+def uncouth.say_bar
+  p 'bar'
+end
+def uncouth.say_something_nice(name)
+  p "Hello, #{name}. You look nice."
+end
+
+# Do you see anything wrong here?
+# Doesn't that object seem a little dangerous? Everybody knows that "foo" comes before "bar" in 
+# code examples.  That absurd object might ruin everything! Is there anything we can do to prevent 
+# it from doing the unthinkable?
+# 
+# uncouth.say_bar
+# uncouth.say_foo
+#
+
+# Yes, of course there is!  We can filter calls to the uncouth object using Moory's WellManered 
+# class.
+require 'moory'
+
+# We can go no further until we write down the rules of foo-bar-etiquette
+
+the_rules_of_foo_bar_etiquette = """
+  start        : say_foo  : said_foo
+    
+  said_foo     : say_foo  : said_foo
+  said_foo     : say_bar  : said_foo_bar
+
+  said_foo_bar : say_foo  : said_foo_bar
+  said_foo_bar : say_bar  : said_foo_bar
+"""
+
+# Let's make a postive change, and hereon refer to the uncouth object as the `well_mannered_object`.
+# It will be our `protege`, and the instantiation of a WellMannered object won't surprise us:
+
+well_mannered_object = Moory::WellMannered.new(
+  protege: uncouth,
+  rules:   the_rules_of_foo_bar_etiquette
+)
+
+# Now let's have a conversation with our protege.
+well_mannered_object.say_something_nice('Adam')
+# That is nice.
+well_mannered_object.say_bar    
+# Good.  I'm glad you didn't fall for that
+
+# So far so good. Our well mannered object is proving to be polite.  If someone asks it 
+# to depart from protocol, it will just quietly refuse.  But what if that isn't enough?
+# What should it do if someone asks it to do something really bad?  The trouble is,
+# well-mannered objects are so well-behaved, they won't do anything unless we say its OK.
+# Let's do that.
+
+well_mannered_object.response_to_rule_breaking = proc { |msg|
+  pp "You shouldn't ask me to #{msg}! I'm telling!"
+}
+
+# Now when we ask it to do something it out of turn
+well_mannered_object.say_bar
+# it will tell on you.  What a nice object!  Now don't be such a telltale.
+well_mannered_object.response_to_rule_breaking = nil
+# Let's continue
+well_mannered_object.say_bar
+# Good. You didn't complain.
+well_mannered_object.say_foo    
+# Promising.  You haven't yet spoken out of turn.
+well_mannered_object.say_foo
+# A perfectly acceptable reptition.
+well_mannered_object.say_bar
+# Wonderful!
+well_mannered_object.say_something_nice('Adam')
+# Yes. Thank you.
+

data/lib/moory.rb

@@ -3,6 +3,7 @@ require "moory/interpreter"
 require "moory/parser"
 require "moory/acceptor"
 require "moory/decoder"
+require "moory/wellmannered"
 
 module Moory
   # Your code goes here...

data/lib/moory/version.rb

@@ -1,3 +1,3 @@
 module Moory
-  VERSION = "0.3.3"
+  VERSION = "0.4.0"
 end

data/lib/moory/wellmannered.rb

@@ -0,0 +1,54 @@
+module Moory
+  class WellMannered
+    attr_reader :response_to_rule_breaking
+
+    IGNORE = proc {}
+
+    def initialize(protege:, rules:, initial:'start', response_to_rule_breaking: IGNORE)
+      @protege  = protege
+      @rules    = rules
+      @initial  = initial
+      @response_to_rule_breaking = response_to_rule_breaking
+      prepare
+    end
+
+    def restricted_messages
+      interpreter.alphabet
+    end
+
+    def response_to_rule_breaking=(obj)
+      @response_to_rule_breaking = obj.respond_to?(:call) ? obj : IGNORE
+    end
+  
+    private
+  
+    def prepare
+      interpreter.load(@rules)
+      interpreter.state = @initial
+    end
+  
+    def interpreter
+      @interpreter ||= Moory::Interpreter.new
+    end
+  
+    def method_missing(*args)
+      protected?(*args) ? 
+        filter_first(*args) : 
+        forward(*args)
+    end
+  
+    def protected?(*args)
+      interpreter.alphabet.include?(args.first.to_s)
+    end
+  
+    def filter_first(*args)
+      interpreter.putm(args.first.to_s) ? 
+        forward(*args) : 
+        response_to_rule_breaking.call(*args)
+    end
+  
+    def forward(*args)
+      @protege.send(*args)
+    end
+  end
+end

data/moory.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Adam W. Grant"]
   spec.email         = ["adam_grnt@yahoo.co.uk"]
 
-  spec.summary       = %q{Use plain text to define finite machines.}
+  spec.summary       = %q{Use plain text to define finite machines (and even teach objects manners) using a simple plain-text specification language.}
   spec.license       = "MIT"
 
   spec.homepage = 'https://github.com/elclavijero/moory'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moory
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Adam W. Grant
@@ -73,13 +73,16 @@ files:
 - examples/readme_example.rb
 - examples/silly.rb
 - examples/single_as_and_bs.rb
+- examples/well_mannered_objects.rb
 - images/ab_star.png
+- images/foo_bar_etiquette.png
 - lib/moory.rb
 - lib/moory/acceptor.rb
 - lib/moory/decoder.rb
 - lib/moory/interpreter.rb
 - lib/moory/parser.rb
 - lib/moory/version.rb
+- lib/moory/wellmannered.rb
 - moory.gemspec
 homepage: https://github.com/elclavijero/moory
 licenses:
@@ -104,5 +107,6 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Use plain text to define finite machines.
+summary: Use plain text to define finite machines (and even teach objects manners)
+  using a simple plain-text specification language.
 test_files: []