roby 0.7.3 → 0.8.0

data/lib/roby/planning/loops.rb

@@ -1,5 +1,3 @@
-require 'roby/planning/task'
-
 module Roby
     # This class unrolls a loop in the plan. It maintains +lookahead+ patterns
     # developped at all times by calling an external planner, and manages them.
@@ -68,29 +66,40 @@ module Roby
 
 	# The planner model we should use
 	argument :planner_model
-	# The planner method name
-	argument :method_name
+
+        # The planner method name. This is not a mandatory argument as
+        # otherwise we would break logging and distributed Roby: this attribute
+        # can hold a MethodDefinition object that cannot be shared.
+        #
+        # Anyway, the only meaningful argument in distributed context is the
+        # method name itself. Event method_options could be removed in the
+        # future.
+	def planning_method
+            arguments[:planning_method]
+        end
 	# The planner method options
 	argument :method_options
 
+        # The method name. This can be nil a FreeMethod is used for planning
+        argument :method_name
+
 	# Filters the options in +options+, splitting between the options that
 	# are specific to the planning task and those that are to be forwarded
 	# to the planner itself
-	def self.filter_options(options) # :nodoc:
+	def self.filter_options(options)
 	    task_arguments, planning_options = Kernel.filter_options options, 
 		:period => nil,
 		:lookahead => 1,
 		:planner_model => nil,
+                :planning_method => nil,
 		:planned_model => Roby::Task,
 		:method_name => nil,
 		:method_options => {},
 		:planning_owners => nil
 
-	    if !task_arguments[:method_name]
-		raise ArgumentError, "required argument :method_name missing"
-	    elsif !task_arguments[:planner_model]
-		raise ArgumentError, "required argument :planner_model missing"
-	    elsif task_arguments[:lookahead] < 0
+            task_arguments = PlanningTask.validate_planning_options(task_arguments)
+
+	    if task_arguments[:lookahead] < 0
 		raise ArgumentError, "lookahead must be positive"
 	    end
 	    task_arguments[:period] ||= nil
@@ -109,7 +118,7 @@ module Roby
             if period && period > 0
                 @periodic_trigger = State.on_delta :t => period
                 periodic_trigger.disable
-                periodic_trigger.on event(:loop_start)
+                periodic_trigger.signals event(:loop_start)
             end
             
 	    @patterns = []
@@ -135,17 +144,17 @@ module Roby
 	# +context+ is forwarded to the planned task
 	def append_pattern(*context)
 	    # Create the new pattern
-	    task_arguments = arguments.slice(:planner_model, :planned_model, :method_name)
+	    task_arguments = arguments.slice(:planner_model, :planned_model, :planning_method)
 	    task_arguments[:method_options] = method_options.dup
 	    task_arguments[:method_options][:pattern_id] = @pattern_id
 	    @pattern_id += 1
 
 	    planning = PlanningTask.new(task_arguments)
 	    planned  = planning.planned_task
-	    planned.forward(:start,   self, :loop_start)
-	    planned.forward(:success, self, :loop_success)
-	    planned.forward(:stop,    self, :loop_end)
-	    main_task.realized_by planned
+	    planned.forward_to(:start,   self, :loop_start)
+	    planned.forward_to(:success, self, :loop_success)
+	    planned.forward_to(:stop,    self, :loop_end)
+	    main_task.depends_on planned, :model => planned.model
 	    
 	    # Schedule it. We start the new pattern when these three conditions are met:
 	    # * it has been planned (planning has finished)
@@ -175,13 +184,15 @@ module Roby
 		if last_planning.finished?
 		    planning.start!(*context) 
 		else
-		    last_planning.event(:success).filter(*context).on(planning.event(:start))
+		    last_planning.event(:success).
+                        filter(*context).
+                        signals(planning.event(:start))
 		end
 	    end
             command &= precondition
 
 	    patterns.unshift([planning, user_command])
-	    command.on(planned.event(:start))
+	    command.signals(planned.event(:start))
 	    planning
 	end
 
@@ -189,13 +200,9 @@ module Roby
         # as lookahead requires. Kills the currently running pattern (if there
         # is one).
 	event :reinit do |context|
-            unless running?
-                raise ArgumentError, "#reinit called, but the loop is not running"
-            end
-
             did_reinit = []
 
-            # Remove all realized_by relations and all pending patterns from
+            # Remove all depends_on relations and all pending patterns from
             # the pattern set.
             for pattern in patterns
                 old_planning, ev = pattern
@@ -216,7 +223,7 @@ module Roby
                 did_reinit.
                     map { |ev| ev.when_unreachable }.
                     inject { |a, b| a & b }.
-                    forward event(:reinit)
+                    forward_to event(:reinit)
             end
         end
         on :reinit do |ev|
@@ -242,7 +249,7 @@ module Roby
 		    new_planning = append_pattern
 		    first_planning ||= new_planning
 		end
-		on(:start, first_planning)
+		signals(:start, first_planning, :start)
 	    end
 
 	    emit :start

data/lib/roby/planning/model.rb

@@ -1,10 +1,3 @@
-require 'roby/planning/task'
-require 'roby/task'
-require 'roby/control'
-require 'roby/plan'
-require 'utilrb/module/ancestor_p'
-require 'set'
-
 module Roby
     # The Planning module provides basic tools to create plans (graph of tasks
     # and events)
@@ -19,6 +12,33 @@ module Roby
             end
         end
 
+        MethodArgDescription = Struct.new :name, :doc, :required
+        class MethodDescription
+            attr_reader :doc
+
+            attr_reader :arguments
+
+            attr_predicate :advanced?
+
+            def initialize(doc = nil)
+                @doc = doc
+                @arguments = []
+            end
+
+            def required_arg(name, doc)
+                arguments << MethodArgDescription.new(name, doc, true)
+                self
+            end
+            def optional_arg(name, doc)
+                arguments << MethodArgDescription.new(name, doc, false)
+                self
+            end
+            def advanced
+                @advanced = true 
+                self
+            end
+        end
+
 	# Raised a method has found no valid development
         class NotFound < PlanModelError
 	    # The name of the method which has failed
@@ -35,33 +55,43 @@ module Roby
                 super(planner)
             end
 
-	    def message
+            def pretty_print(pp)
 		if errors.empty?
-		    "no candidate for #{method_name}(#{method_options})"
+		    pp.text "no candidate for #{method_name}(#{method_options})"
 		else
-		    msg = "cannot develop a #{method_name}(#{method_options}) method"
-		    first, *rem = *Roby.filter_backtrace(backtrace)
+                    first, *rem = Roby.filter_backtrace(backtrace)
+                    pp.text "cannot develop a #{method_name}(#{method_options.to_s[1..-2]}) method"
+                    pp.breakable
+                    pp.group(4, "    ") do
+                        rem.each do |line|
+                            pp.text "from #{line}"
+                            pp.breakable
+                        end
+                    end
 
-		    full = "#{first}: #{msg}\n   from #{rem.join("\n  from ")}"
+                    pp.breakable
 		    errors.each do |m, error|
-			first, *rem = *Roby.filter_backtrace(error.backtrace)
-			full << "\n#{first}: #{m} failed with #{error.message}\n  from #{rem.join("\n  from ")}"
+                        if error.kind_of?(NotFound)
+                            first, *rem = *Roby.filter_backtrace(error.backtrace)
+                            pp.text "in method #{m}"
+                            pp.breakable
+                            error.pretty_print(pp)
+                        else
+                            first, *rem = *Roby.filter_backtrace(error.backtrace)
+                            pp.text "planning method #{m} failed"
+                            pp.breakable
+                            pp.text "#{first}: #{error.message}"
+                            pp.breakable
+                            pp.group(4, "    ") do
+                                rem.each do |line|
+                                    pp.text "from #{line}"
+                                    pp.breakable
+                                end
+                            end
+                        end
 		    end
-		    full
-		end
-	    end
-
-	    def full_message
-		msg = message
-		first, *rem = *Roby.filter_backtrace(backtrace)
-
-		full = "#{first}: #{msg}\n   from #{rem.join("\n    from ")}"
-		errors.each do |m, error|
-		    first     = error.backtrace.first
-		    full << "\n#{first} #{m} failed because of #{error.full_message}"
 		end
-		full
-	    end
+            end
         end
 
 	# Some common tools for Planner and Library
@@ -130,7 +160,15 @@ module Roby
             # Call the method definition
             def call(planner); body.call(planner) end
 
-            def to_s; "#{name}:#{id}(#{options})" end
+            def to_s
+                opts = options.dup
+                opts.delete :id
+                "#{name}:#{id}(#{opts.to_s[1..-2]})"
+            end
+        end
+
+        class FreeMethod < MethodDefinition
+            def call(planner); planner.instance_eval(&body) end
         end
 
         # The model of a planning method. This does not define an actual
@@ -151,7 +189,9 @@ module Roby
             # The model options, as a Hash
             attr_reader :options
 
-            def initialize(name, options = Hash.new); @name, @options = name, options end
+            def initialize(name, options = Hash.new)
+                @name, @options = name, options
+            end
             def ==(model)
                 name == model.name && options == model.options
             end
@@ -210,6 +250,8 @@ module Roby
             def to_s; "#{name}(#{options})" end
         end
 
+        PlanningMethod = Struct.new :name, :model, :description, :instances
+
 	# A planner searches a suitable development for a set of methods. 
 	# Methods are defined using Planner::method. You can then ask
 	# for a plan by sending your method name to the Planner object
@@ -321,6 +363,25 @@ module Roby
 		end
 	    end
 
+            # call-seq:
+            #   describe(first_line, second_line, ...).
+            #       required_arg(arg_name, arg_doc).
+            #       optional_arg(arg_name, arg_doc)
+            #
+            # Describes the next method or method model. It adds a description
+            # text for the method, which can be shown for instance by the
+            # shell's "action" command. It is also possible to describe the
+            # expected method arguments.
+            def self.describe(*text)
+                if text.empty?
+                    text = ["(no description set)"]
+                else
+                    text.map! { |s| s.to_str }
+                end
+
+                @next_method_description = MethodDescription.new(text)
+            end
+
 	    # call-seq:
 	    #	method(name, option1 => value1, option2 => value2) { }	    => method definition
 	    #	method(name, option1 => value1, option2 => value2)	    => method model
@@ -410,7 +471,7 @@ module Roby
 	    def self.method(name, options = Hash.new, &body)
                 name, options = validate_method_query(name, options)
 		
-		# Define the method enumerator and the method selection
+		# Define the method enumerator and the method public interface
 		if !respond_to?("#{name}_methods")
 		    inherited_enumerable("#{name}_method", "#{name}_methods", :map => true) { Hash.new }
 		    class_eval <<-PLANNING_METHOD_END
@@ -421,7 +482,17 @@ module Roby
 		      cached_enum("#{name}_method", "#{name}_methods", true)
 		    end
 		    PLANNING_METHOD_END
+                    singleton_class.class_eval do
+                        attr_reader "#{name}_description"
+                    end
 		end
+                if @next_method_description
+                    if instance_variable_get("@#{name}_description")
+                        raise "#{name} already has a description"
+                    end
+                    instance_variable_set("@#{name}_description", @next_method_description)
+                    @next_method_description = nil
+                end
 
 		# We are updating the method model
                 if !body
@@ -463,7 +534,8 @@ module Roby
 		end
 		temp_method_name = "m#{@@temp_method_id += 1}"
 		define_method(temp_method_name, &body)
-		send("#{name}_methods")[method_id] = MethodDefinition.new(name, options, instance_method(temp_method_name))
+                mdef = MethodDefinition.new(name, options, instance_method(temp_method_name))
+		send("#{name}_methods")[method_id] = mdef
             end
 	    @@temp_method_id = 0
 
@@ -479,6 +551,33 @@ module Roby
 		names
 	    end
 
+            def self.planning_methods
+                names = methods.map do |method_name|
+                    if method_name =~ /^each_(\w+)_method$/
+                        $1
+                    end
+                end.compact.sort
+
+                names.map do |name|
+                    desc = PlanningMethod.new
+                    desc.name = name
+                    desc.description = planning_method_description(name)
+                    #desc.model = method_model(name)
+                    #desc.instances = Array.new
+                    #send("each_#{name}_method") do |instance|
+                    #    desc.instances << instance
+                    #end
+                    desc
+                end
+            end
+            
+            def self.planning_method_description(name)
+                return instance_variable_get("@#{name}_description") || MethodDescription.new
+            end
+            def planning_method_description(name)
+                self.class.planning_method_description(name)
+            end
+
 	    def self.clear_model
 		planning_methods_names.each do |name|
 		    remove_planning_method(name)
@@ -608,6 +707,13 @@ module Roby
 		MethodModel.new(name, :returns => Task)
 	    end
 
+            # Creates a TaskSequence with the given tasks
+            def sequence(*tasks)
+                seq = Sequence.new
+                tasks.each { |t| seq << t }
+                seq
+            end
+
 	    # Creates a planning task which will call the same planning method
 	    # than the one currently being generated.
 	    #
@@ -653,9 +759,8 @@ module Roby
 		elsif planning_options[:args] && !planning_options[:args].empty?
 		    raise ArgumentError, "provided method-specific options through both :args and the option hash"
 		end
-		@arguments.push(method_options)
 
-		Planning.debug { "planning #{name}[#{arguments}]" }
+		Planning.debug { "planning #{name}[#{method_options}]" }
 
 		# Check for recursion
                 if (options[:id] && @stack.include?([name, options[:id]])) || (!options[:id] && @stack.find { |n, _| n == name })
@@ -678,7 +783,7 @@ module Roby
 		    all_returns.compact!
 				      
 		    for return_type in all_returns
-			if task = find_reusable_task(return_type)
+			if task = find_reusable_task(return_type, method_options)
 			    return task
 			end
 		    end
@@ -689,7 +794,7 @@ module Roby
 		end
 
 		# Call the methods
-		call_planning_methods(Hash.new, options, *methods)
+		call_planning_methods(Hash.new, method_options, *methods)
 
             rescue Interrupt
                 raise
@@ -697,22 +802,19 @@ module Roby
             rescue NotFound => e
                 e.method_name       = name
                 e.method_options    = options
-                raise e
-		
-	    ensure
-		@arguments.pop
+                raise e.dup, e.message, caller(1)
             end
 	    
-	    def find_reusable_task(return_type)
+	    def find_reusable_task(return_type, method_options)
 		query = plan.find_tasks.
-		    which_fullfills(return_type, arguments).
+		    which_fullfills(return_type, method_options).
 		    self_owned.
 		    not_abstract.
 		    not_finished.
 		    roots(TaskStructure::Hierarchy)
 
 		for candidate in query
-		    Planning.debug { "selecting task #{candidate} instead of planning #{return_type}[#{arguments}]" }
+		    Planning.debug { "selecting task #{candidate} instead of planning #{return_type}[#{method_options}]" }
 		    return candidate
 		end
 		nil
@@ -724,9 +826,10 @@ module Roby
             # Tries to find a successfull development in the provided method list.
             #
             # It raises NotFound if none of the methods returned successfully
-            def call_planning_methods(errors, options, method, *methods)
+            def call_planning_methods(errors, method_options, method, *methods)
                 begin
                     @stack.push [method.name, method.id]
+                    @arguments.push(method_options)
 		    Planning.debug { "calling #{method.name}:#{method.id} with arguments #{arguments}" }
 		    begin
 			result = method.call(self)
@@ -742,7 +845,7 @@ module Roby
 		    end
 		    
 		    # Insert resulting tasks in +plan+
-		    plan.discover(result)
+		    plan.add(result)
 
 		    expected_return = method.returns
 		    if expected_return 
@@ -762,6 +865,7 @@ module Roby
 		    result
 
                 ensure
+                    @arguments.pop
                     @stack.pop
                 end
 
@@ -771,7 +875,7 @@ module Roby
                 if methods.empty?
                     raise NotFound.new(self, errors)
                 else
-                    call_planning_methods(errors, options, *methods)
+                    call_planning_methods(errors, method_options, *methods)
                 end
             end
 
@@ -782,20 +886,22 @@ module Roby
 	    def make_loop(options = {}, &block)
 		raise ArgumentError, "no block given" unless block
 
-		options.merge! :planner_model => self.class, :method_name => 'loops'
-		_, planning_options = PlanningLoop.filter_options(options)
-
                 loop_id = Planner.next_id
                 if !@stack.empty?
                     loop_id = "#{@stack.last[1]}_#{loop_id}"
                 end
+                loop_method = FreeMethod.new 'loops', {}, lambda(&block)
+
+                options[:planner_model] = self.class
+                options[:planning_method] = loop_method
+		_, planning_options = PlanningLoop.filter_options(options)
                 planning_options[:id] = loop_id
                 planning_options[:reuse] = false
-                m = self.class.method('loops', planning_options, &block)
+                loop_method.options.merge!(planning_options)
 
 		options[:method_options] ||= {}
 		options[:method_options].merge!(arguments || {})
-		options[:method_options][:id] = m.id
+		options[:method_options][:id] = loop_method.id
 		PlanningLoop.new(options)
 	    end
         end