james 0.1.1-universal-darwin-10 → 0.2.0-universal-darwin-10

data/aux/james/cli.rb

@@ -5,9 +5,7 @@ module James
   class CLI
 
     def execute *patterns
-      silent        = patterns.delete '-s'
-      silent_input  = patterns.delete '-si'
-      silent_output = patterns.delete '-so'
+      options = extract_options patterns
 
       dialogs = find_dialogs_for patterns
 
@@ -16,16 +14,35 @@ module James
 
       load_all dialogs
 
+      James.listen options
+    end
+
+    # Defines default options and extracts options from
+    # command line.
+    #
+    # Sadly needs to be run before processing the dialog file names.
+    #
+    def extract_options patterns
+      silent        = patterns.delete '-s'
+      silent_input  = patterns.delete '-si'
+      silent_output = patterns.delete '-so'
+
       options = {}
       options[:input]  = Inputs::Terminal  if silent || silent_input
       options[:output] = Outputs::Terminal if silent || silent_output
 
-      James.listen options
+      options
     end
+
+    #
+    #
     def find_dialogs_for patterns
       patterns = ["**/*_dialog{,ue}.rb"] if patterns.empty?
       Dir[*patterns]
     end
+
+    #
+    #
     def load_all dialogs
       dialogs.each do |dialog|
         load File.expand_path dialog, Dir.pwd

data/lib/james/builtin/core_dialog.rb

@@ -9,6 +9,10 @@ class CoreDialog
 
   include James::Dialog
 
+  # This core dialog starts at awake.
+  #
+  initially :awake
+
   # The alert state.
   # When James is in this state, he should be
   # open for user dialogs.

data/lib/james/controller.rb

@@ -2,7 +2,7 @@ module James
 
   class Controller
 
-    attr_reader :visitor, :listening
+    attr_reader :conversation, :listening, :initial
 
     # Singleton reader.
     #
@@ -10,63 +10,33 @@ module James
       @controller ||= new
     end
 
-    # This puts together the core dialog and the user
+    # This puts together the initial dialog and the user
     # ones that are hooked into it.
     #
-    # TODO Rewrite this. Design needs some refactoring.
-    #      Should the user visitor be created dynamically? (Probably yes.)
+    # The initial dialog needs an state defined as initially.
+    # This is where it will start.
     #
-    def initialize
-      @user_dialogs = Dialogs.new
-      @visitor      = Visitors.new system_visitor, user_visitor
-    end
-    def system_visitor
-      Visitor.new CoreDialog.new.state_for(:awake)
-    end
-    def user_visitor
-      @user_dialogs.visitor
-    end
-
-    # MacRuby callback functions.
+    # Example:
+    #   initially :awake
+    #   state :awake do
+    #     # ...
+    #   end
     #
-    def applicationDidFinishLaunching notification
-      start_output
-      start_input
-    end
-    def windowWillClose notification
-      exit
-    end
-
-    # Add a dialog to the current system.
+    # If you don't give it an initial dialog,
+    # James will simply use the built-in CoreDialog.
     #
-    def add_dialog dialog
-      @user_dialogs << dialog
+    def initialize dialog = nil
+      @initial      = dialog || CoreDialog.new
+      @conversation = Conversation.new @initial.current
     end
 
-    # Start recognizing words.
+    # Convenience method to add a dialog to the current system.
     #
-    def start_input
-      @input = @input_class.new self
-      @input.listen
-    end
-    # Start speaking.
+    # Will add the dialog to the initial dialog passed into the
+    # controller.
     #
-    def start_output
-      @output = @output_class.new @output_options
-    end
-
-    # Callback method from dialog.
-    #
-    def say text
-      @output.say text
-    end
-    def hear text
-      visitor.hear text do |response|
-        say response
-      end
-    end
-    def expects
-      visitor.expects
+    def << dialog
+      @initial << dialog
     end
 
     # Start listening using the provided options.
@@ -78,6 +48,8 @@ module James
     def listen options = {}
       return if listening
 
+      @listening = true
+
       @input_class    = options[:input]  || Inputs::Audio
       @output_class   = options[:output] || Outputs::Audio
 
@@ -87,11 +59,48 @@ module James
       app = NSApplication.sharedApplication
       app.delegate = self
 
-      @listening = true
-
       app.run
     end
 
+    # The naughty privates of this class.
+    #
+
+      # MacRuby callback functions.
+      #
+      def applicationDidFinishLaunching notification
+        start_output
+        start_input
+      end
+      def windowWillClose notification
+        exit
+      end
+
+      # Start recognizing words.
+      #
+      def start_input
+        @input = @input_class.new self
+        @input.listen
+      end
+      # Start speaking.
+      #
+      def start_output
+        @output = @output_class.new @output_options
+      end
+
+      # Callback method from dialog.
+      #
+      def say text
+        @output.say text
+      end
+      def hear text
+        conversation.hear text do |response|
+          say response
+        end
+      end
+      def expects
+        conversation.expects
+      end
+
   end
 
 end

data/lib/james/conversation.rb

@@ -0,0 +1,62 @@
+module James
+
+  # A conversation has a number of markers (position in dialog),
+  # whose dialogs are visited in order of preference.
+  #
+  # Why?
+  # Conversations have multiple points where they can be.
+  # (Politics, then this joke, then back again, finally "Oh, bye I have to go!")
+  #
+  class Conversation
+
+    attr_accessor :markers
+
+    # A Conversation keeps a stack of markers with
+    # an initial one.
+    #
+    def initialize initial
+      @markers = [initial]
+    end
+
+    # Hear tries all visitors in order
+    # until one hears a phrase he knows.
+    #
+    # If a dialog boundary has been crossed:
+    # A new visitor is added with the target
+    # state of that heard phrase at the position.
+    #
+    # After that, all remaining visitors are
+    # removed from the current stack (since
+    # we are obviously not in one of the later
+    # dialogs anymore).
+    #
+    def hear phrase, &block
+      self.markers = markers.inject([]) do |remaining, marker|
+        markers = marker.hear phrase, &block
+        remaining = remaining + markers
+        break remaining if remaining.last && remaining.last.current?
+        remaining
+      end
+    end
+
+    # Enter enters the first visitor.
+    #
+    def enter
+      markers.first.enter
+    end
+
+    # Simply returns the sum of what phrases all dialogs do expect, front-to-back.
+    #
+    # Stops as soon as a marker is not on a chainable state anymore.
+    #
+    def expects
+      markers.inject([]) do |expects, marker|
+        total = marker.expects + expects
+        break total unless marker.chainable?
+        total
+      end
+    end
+
+  end
+
+end

data/lib/james/dialog_internals.rb

@@ -9,35 +9,88 @@ module James
       into.extend ClassMethods
     end
 
+    # Returns a state instance for the given state / or state name.
     #
+    # Note: Lazily creates the state instances.
     #
-    def state_for name
-      self.class.state_for name, self
+    def state_for possible_state
+      return possible_state if possible_state.respond_to?(:expects)
+      self.class.state_for possible_state, self
+    end
+
+    # Chain (the states of) this dialog to the given state.
+    #
+    # Creates state instances if it is given names.
+    #
+    # Note: Be careful not to create circular
+    #       state chaining. Except if you really
+    #       want that.
+    #
+    def chain_to state
+      warn "Define a hear => :some_state_name in a dialog to have it be able to chain to another." && return unless respond_to?(:entry_phrases)
+      entry_phrases.each do |(phrases, entry_state)|
+        state.hear phrases => state_for(entry_state)
+      end
+    end
+
+    # Chain the given Dialog(s) to all chainable
+    # states in this Dialog.
+    #
+    # Note: If you only want one state to chain,
+    #       then get it from the otiginating dialog
+    #       using dialog.state_for(:name) and
+    #       append the dialog there:
+    #       dialog.follows preceding_dialog.state_for(:name)
+    #
+    def << dialog_s
+      self.class.states.each do |(name, definition)|
+        state = state_for name # TODO Do not call this everywhere.
+        dialog_s.chain_to(state) if state.chainable?
+      end
     end
 
     module ClassMethods
 
-      # Defines the entry sentences.
+      def initially state_name
+        define_method :current do
+          Markers::Current.new state_for(state_name)
+        end
+      end
+
+      # Defines the entry phrases into this dialog.
+      #
+      # Example:
+      #   hear 'Hello, James!' => :start
       #
       def hear definition
-        define_method :entries do
+        define_method :entry_phrases do
           definition
         end
       end
 
       # Defines a state with transitions.
       #
-      # state :name do
-      #   # state properties (hear, into, exit) go here.
-      # end
+      # Example:
+      #   state :name do
+      #     # state properties (hear, into, exit) go here.
+      #   end
       #
-      attr_reader :states
       def state name, &block
         @states       ||= {}
         @states[name] ||= block if block_given?
+        define_method name do
+          state_for name
+        end unless instance_methods.include? name
       end
+
+      #
+      #
+      attr_reader :states
+
+      # Return a state for this name (and dialog instance).
+      #
       def state_for name, instance
-        # Lazily wrap.
+        # Lazily wrap in State instance.
         #
         if states[name].respond_to?(:call)
           states[name] = State.new(name, instance, &states[name])

data/lib/james/dialogs.rb

@@ -1,41 +1,19 @@
 module James
 
-  # Registers dialogs and connects their states.
+  # Bundles a bunch of dialogs.
   #
   class Dialogs
 
-    attr_reader :initial
+    attr_reader :dialogs
 
-    def initialize
-      @initial = State.new :__initial_plugin_state__, nil
+    def initialize *dialogs
+      @dialogs = dialogs
     end
 
-    # Generate the graph for the dialogs.
     #
-    # Hooks up the entry phrases of the dialog
-    # into the main dialog.
     #
-    # It raises if the hook phrase of a dialog
-    # is already used.
-    #
-    def << dialog
-      resolved_entries = {}
-
-      dialog.entries.each do |(phrases, state)|
-        resolved_entries[phrases] = state.respond_to?(:phrases) ? state : dialog.state_for(state)
-      end
-
-      # Hook the dialog into the initial state.
-      #
-      initial.hear resolved_entries
-    end
-
-    # Get the visitor.
-    #
-    # Initialized on the initial state.
-    #
-    def visitor
-      @visitor ||= Visitor.new initial
+    def chain_to incoming_dialog
+      dialogs.each { |dialog| incoming_dialog << dialog }
     end
 
   end

data/lib/james/markers/current.rb

@@ -0,0 +1,34 @@
+module James
+
+  module Markers
+
+    # The visitor knows where in the conversation we are.
+    #
+    class Current < Marker
+
+      # Hear a phrase.
+      #
+      # Returns a new marker and self if it crossed a boundary.
+      # Returns itself if not.
+      #
+      def hear phrase, &block
+        return [self] unless hears? phrase
+        last = current
+        process(phrase, &block) ? [Memory.new(last), self] : [self]
+      end
+
+      # Expects all phrases, not just internal.
+      #
+      def expects
+        current.expects
+      end
+
+      def current?
+        true
+      end
+
+    end
+
+  end
+
+end

data/lib/james/markers/marker.rb

@@ -0,0 +1,92 @@
+module James
+
+  module Markers
+
+    # A marker is a point in conversation
+    # where we once were and might go back.
+    #
+    # TODO: Rename to ?.
+    #
+    class Marker
+
+        attr_accessor :current
+
+        # Pass in an current state.
+        #
+        def initialize current
+          @current = current
+        end
+
+        # Resets the current state back to the initial.
+        #
+        def reset
+          # Never moves, thus never reset.
+        end
+
+        # We hear a phrase.
+        #
+        # Also used to start the whole process.
+        #
+        def enter
+          result = current.__into__
+          yield result if result && block_given?
+          result
+        end
+
+        #
+        #
+        def exit
+          result = current.__exit__
+          yield result if result && block_given?
+          result
+        end
+
+        #
+        #
+        def transition phrase
+          state_or_lambda = current.next_for phrase
+          if state_or_lambda.respond_to?(:call)
+            current.__transition__ &state_or_lambda # Don't transition.
+          else
+            self.current = state_or_lambda
+          end
+        end
+
+        #
+        #
+        def check
+          yield("Whoops. That led nowhere. Perhaps you didn't define the target state?") unless self.current
+        end
+
+        # Returns falsy if it stays the same.
+        #
+        def process phrase, &block
+          exit_text = exit &block
+          last_context = current.context
+          transition phrase
+          check &block
+          into_text = enter &block
+          last_context != current.context
+        end
+
+        #
+        #
+        def hears? phrase
+          expects.include? phrase
+        end
+
+        # Does the current state allow penetration into another dialog?
+        #
+        def chainable?
+          current.chainable?
+        end
+
+        def to_s
+          "#{self.class.name}(#{initial}, current: #{current})"
+        end
+
+      end
+
+    end
+
+end

data/lib/james/markers/memory.rb

@@ -0,0 +1,37 @@
+module James
+
+  module Markers
+
+    # A marker is a point in conversation
+    # where we once were and might go back.
+    #
+    # TODO: Rename to ?.
+    #
+    class Memory < Marker
+
+        # Hear a phrase.
+        #
+        # Returns a new Current if it heard.
+        # Returns itself if not.
+        #
+        def hear phrase, &block
+          return [self] unless hears? phrase
+          last = current
+          process(phrase, &block) ? [Memory.new(last), Current.new(current)] : [Current.new(current)]
+        end
+
+        # A marker does not care about phrases that cross dialog boundaries.
+        #
+        def expects
+          current.internal_expects
+        end
+
+        def current?
+          false
+        end
+
+      end
+
+    end
+
+end

data/lib/james/state_api.rb

@@ -43,26 +43,42 @@ module James
     #
     def hear transitions
       transitions = { transitions => name } unless transitions.respond_to?(:to_hash)
-      @transitions.merge! expand(transitions)
+      @transitions = expand(transitions).merge @transitions
     end
 
-    # Execute this block when entering this state.
+    # Execute this block or say the text when entering this state.
     #
-    def into &block
-      @into_block = block
+    # Examples:
+    #   into "Yes, Sir?"
+    #   into { "A random number is #{rand(10)}" }
+    #
+    def into text = nil, &block
+      @into_block = block ||
+                    text && lambda { text } ||
+                    raise_no_text_or_block(__method__)
     end
 
-    # Execute this block when exiting this state.
+    # Execute this block or say the text when exiting this state.
+    #
+    # Examples:
+    #   exit "Yes, Sir?"
+    #   exit { "A random number is #{rand(10)}" }
     #
-    def exit &block
-      @exit_block = block
+    def exit text = nil, &block
+      @exit_block = block ||
+                    text && lambda { text } ||
+                    raise_no_text_or_block(__method__)
     end
 
-    # By default, a state is not chainable.
+    # Chain the given dialog to this state.
     #
-    def chainable?
-      !!@chainable
+    def << dialog
+      dialog.chain_to self
     end
+
+    # A chainable state is a state from which other
+    # Dialogs can be reached.
+    #
     def chainable
       @chainable = true
     end
@@ -70,7 +86,7 @@ module James
     # Description of self using name and transitions.
     #
     def to_s
-      "#{self.class.name}(#{name}, #{context}, #{transitions})"
+      "#{self.class.name}(#{name}, #{context}, #{@transitions})"
     end
 
     # The naughty privates of this class.
@@ -90,6 +106,18 @@ module James
         results
       end
 
+      # Raise an ArgumentError for the given method if it needs either a text or a block.
+      #
+      def raise_no_text_or_block on_method
+        raise ArgumentError.new("Neither block nor text given to ##{on_method} call in #{caller[1]}.")
+      end
+
+      # By default, a state is not chainable.
+      #
+      def chainable?
+        !!@chainable
+      end
+
   end
 
 end