roby 0.8.0 → 3.0.0

data/lib/roby/planning.rb

@@ -1,13 +0,0 @@
-require 'roby'
-
-module Roby
-    module Planning
-        extend Logger::Hierarchy
-        extend Logger::Forward
-    end
-end
-
-require 'roby/planning/task'
-require 'roby/planning/loops'
-require 'roby/planning/model'
-

data/lib/roby/planning/loops.rb

@@ -1,309 +0,0 @@
-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.
-    # This documentation will start by describing the general behaviour of this
-    # task, and then we will detail different specific modes of operation.
-    #
-    # == Behaviour description
-    # The task unrolls the loop by generating /patterns/, which are a
-    # combination of a task representing the operation to be done during one
-    # pass of the loop, and a planning task which will generate the subplan for
-    # this operation. These patterns are developped as children of either the
-    # PlanningLoop task itself, or its planned_task if there is one.
-    #
-    # During the execution of this suite of patterns, the following constraints
-    # are always met:
-    #
-    # * the planning task of a pattern is started after the one of the previous
-    #   pattern has finished.
-    # * a pattern is started after the previous one has finished.
-    #
-    # The #start! command do not starts the loop per-se. It only makes the
-    # first +lookahead+ patterns to be developped. You have to call
-    # #loop_start! once to start the generated patterns themselves.
-    #
-    # == Periodic and nonperiodic loops
-    # On the one hand, if the +:period+ option of #initialize is non-nil, it is
-    # expected to be a floating-point value representing a time in seconds. In
-    # that case, the loop is *periodic* and each pattern in the loop is started
-    # at the given periodic rate, triggered by the #periodic_trigger event.
-    # Note that the 'zero-period' case is a special situation where the loop
-    # runs as fast as possible. 
-    #
-    # On the other hand, if +:period+ is nil, the loop is nonperiodic, and each
-    # pattern must be explicitely started by calling #loop_start!.  Finally,
-    # #loop_start! can also be called to bypass the period value (i.e.  to
-    # start a pattern earlier than expected). Repetitive calls to #loop_start!
-    # will make the loop develop and start at most one pattern.
-    #
-    # == Zero lookahead
-    # When the loop lookahead is nonzero, patterns are planend ahead-of-time: they
-    # are planned as soon as possible. In some cases, it is non desirable, for instance
-    # because some information is available only at a later time.
-    #
-    # For these situations, one can use a zero lookahead. In that case, the
-    # patterns are not pre-planned, but instead the planning task is started
-    # only when the pattern itself should have been started: either when the
-    # period timeouts, or when #loop_start! is explicitely called.
-    #
-    # TODO: make figures.
-    #
-    class PlanningLoop < Roby::Task
-	terminates
-
-	# An array of [planning_task, user_command]. The *last* element is the
-	# *first* arrived
-	attr_reader :patterns
-
-	# For periodic updates. If false, the next loop is started when the
-	# 'loop_start' command is called
-	argument :period
-	# How many loops should we have unrolled at all times
-	argument :lookahead
-
-	# The task model we should produce
-	argument :planned_model
-
-	# The planner model we should use
-	argument :planner_model
-
-        # 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)
-	    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
-
-            task_arguments = PlanningTask.validate_planning_options(task_arguments)
-
-	    if task_arguments[:lookahead] < 0
-		raise ArgumentError, "lookahead must be positive"
-	    end
-	    task_arguments[:period] ||= nil
-	    [task_arguments, planning_options]
-	end
-
-        # If this loop is periodic of nonzero period, the state event which
-        # represents that period.
-        attr_reader :periodic_trigger
-
-	def initialize(options)
-	    task_arguments, planning_options = PlanningLoop.filter_options(options)
-	    task_arguments[:method_options].merge!(planning_options)
-	    super(task_arguments)
-
-            if period && period > 0
-                @periodic_trigger = State.on_delta :t => period
-                periodic_trigger.disable
-                periodic_trigger.signals event(:loop_start)
-            end
-            
-	    @patterns = []
-            @pattern_id = 0
-	end
-
-	# The task on which the children are added
-	def main_task; planned_task || self end
-	
-	def planned_task # :nodoc:
-	    planned_tasks.find { true } 
-	end
-
-	# The PlanningTask object for the last pattern
-	def last_planning_task
-	    if pattern = patterns.first
-		pattern.first
-	    end
-	end
-
-	# Appends a new unplanned pattern after all the patterns already developped
-	#
-	# +context+ is forwarded to the planned task
-	def append_pattern(*context)
-	    # Create the new pattern
-	    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_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)
-	    # * the previous one (if any) has finished
-            # * the period (if any) has expired or an external event required
-            #   the explicit start of the pattern (call done to user_command,
-            #   for instance through a call to #loop_start!)
-            #
-            # The +precondition+ event represents a situation where the new pattern
-            # *can* be started, while +command+ is the situation asking for the
-            # pattern to start.
-	    precondition = planning.event(:success)
-	    user_command = EventGenerator.new(true)
-            command      = user_command
-
-	    if last_planning = last_planning_task
-		last_planned = last_planning.planned_task
-
-                if !last_planned.finished?
-		    precondition &= last_planned.event(:stop)
-		end
-
-                if period && !periodic_trigger
-                    command |= planned.event(:success)
-                end
-
-		if last_planning.finished?
-		    planning.start!(*context) 
-		else
-		    last_planning.event(:success).
-                        filter(*context).
-                        signals(planning.event(:start))
-		end
-	    end
-            command &= precondition
-
-	    patterns.unshift([planning, user_command])
-	    command.signals(planned.event(:start))
-	    planning
-	end
-
-        # Remove all pending patterns and starts unrolling as much new patterns
-        # as lookahead requires. Kills the currently running pattern (if there
-        # is one).
-	event :reinit do |context|
-            did_reinit = []
-
-            # Remove all depends_on relations and all pending patterns from
-            # the pattern set.
-            for pattern in patterns
-                old_planning, ev = pattern
-                old_task = old_planning.planned_task
-                main_task.remove_child old_task
-
-                if old_task && old_task.running?
-                    did_reinit << old_task.event(:stop)
-                elsif old_planning.running?
-                    did_reinit << old_planning.event(:stop)
-                end
-            end
-            patterns.clear
-
-            if did_reinit.empty?
-                emit :reinit
-            else
-                did_reinit.
-                    map { |ev| ev.when_unreachable }.
-                    inject { |a, b| a & b }.
-                    forward_to event(:reinit)
-            end
-        end
-        on :reinit do |ev|
-	    @pattern_id = 0
-	    if lookahead > 0
-		first_planning = nil
-		while patterns.size < lookahead
-		    new_planning = append_pattern
-		    first_planning ||= new_planning
-		end
-		first_planning.start!
-	    end
-            loop_start!
-        end
-
-        # Generates the first +lookahead+ patterns and start planning. The
-        # patterns themselves are started when +loop_start+ is called the first
-        # time.
-	event :start do
-	    if lookahead > 0
-		first_planning = nil
-		while patterns.size < lookahead
-		    new_planning = append_pattern
-		    first_planning ||= new_planning
-		end
-		signals(:start, first_planning, :start)
-	    end
-
-	    emit :start
-	end
-        
-
-        # The first time, start executing the patterns. During the loop
-        # execution, force starting the next pending pattern, bypassing the
-        # period if there is one. In case of zero-lookahead loops, the next
-        # pattern will be planned before it is executed.
-	event :loop_start do |context|
-            # Start the periodic trigger if there is one
-            if periodic_trigger && periodic_trigger.disabled?
-                periodic_trigger.enable
-            end
-
-            # Find the first non-running pattern and start it. In case of
-            # zero-lookahead, if no task is already pending, we should add one
-            # and start it explicitely
-	    if new_pattern = patterns.reverse.find { |task, ev| task.planned_task.pending? }
-                t, ev = new_pattern
-                ev.call(*context)
-                command = ev.enum_child_objects(EventStructure::Signal).find { true }
-            elsif lookahead == 0
-		start_planning = !last_planning_task
-		planning = append_pattern(*context)
-		if start_planning
-		    planning.start!(*context)
-		end
-                _, ev = patterns[0]
-                ev.call(*context)
-	    end
-	end
-
-	on :loop_start do |event| 
-	    return unless self_owned?
-            if event.task.lookahead != 0
-                append_pattern 
-            end
-
-	    main_task.remove_finished_children
-	end
-
-	event :loop_success
-
-	event :loop_end
-	on :loop_end do |event|
-	    return unless self_owned?
-	    patterns.pop
-	end
-
-	# For ordering during event propagation
-	causal_link :loop_start   => :loop_end
-	causal_link :loop_success => :loop_end
-    end
-end
-

data/lib/roby/planning/model.rb

@@ -1,1012 +0,0 @@
-module Roby
-    # The Planning module provides basic tools to create plans (graph of tasks
-    # and events)
-    module Planning
-        # Violation of plan models, for instance if a method returns a Task object
-	# which is of a wrong model
-        class PlanModelError < RuntimeError
-            attr_accessor :planner
-            def initialize(planner = nil)
-                @planner = planner 
-		super()
-            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
-            attr_accessor :method_name
-	    # The planning options
-	    attr_accessor :method_options
-	    # A method => error hash of all the method that have
-	    # been tried. +error+ can either be a NotFound exception
-	    # or another exception
-            attr_reader :errors
-
-            def initialize(planner, errors)
-                @errors = errors
-                super(planner)
-            end
-
-            def pretty_print(pp)
-		if errors.empty?
-		    pp.text "no candidate for #{method_name}(#{method_options})"
-		else
-                    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
-
-                    pp.breakable
-		    errors.each do |m, error|
-                        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
-		end
-            end
-        end
-
-	# Some common tools for Planner and Library
-	module Tools
-	    def using(*modules)
-		modules.each do |mod|
-		    if mod.respond_to?(:planning_methods)
-			include mod
-		    elsif planning_mod = (mod.const_get('Planning') rescue nil)
-			include planning_mod
-		    else
-			raise ArgumentError, "#{mod} is not a planning library and has no Planning module which is one"
-		    end
-		end
-	    end
-	end
-
-        # This mixin defines the method inheritance validation method. This is
-        # then used by MethodDefinition and MethodModel
-        module MethodInheritance
-            # Checks that options in +options+ can be used to overload +self+.
-            # Updates options if needed
-            def validate(options)
-                if returns 
-                    if options[:returns] && !(options[:returns] <= returns)
-                        raise ArgumentError, "return task type #{options[:returns]} forbidden since it overloads #{returns}"
-                    else
-                        options[:returns] ||= returns
-                    end
-                end
-
-                if self.options.has_key?(:reuse)
-                    if options.has_key?(:reuse) && options[:reuse] != self.options[:reuse]
-                        raise ArgumentError, "the :reuse option is already set on the #{name} model"
-                    end
-                    options[:reuse] = self.options[:reuse]
-                else
-                    options[:reuse] = true unless options.has_key?(:reuse)
-                end
-
-                options
-            end
-        end
-
-        # An implementation of a planning method.
-        class MethodDefinition
-            include MethodInheritance
-
-            attr_reader :name, :options, :body
-            def initialize(name, options, body)
-                @name, @options, @body = name, options, body
-            end
-
-            # The method ID
-            def id;         options[:id] end
-            # If this method handles recursion
-            def recursive?; options[:recursive] end
-            # What kind of task this method returns
-            #
-            # If this is nil, the method may return a task array or a task
-            # aggregation
-            def returns;    options[:returns] end
-            # If the method allows reusing tasks already in the plan
-            # reuse? is always false if there is no return type defined
-            def reuse?; (!options.has_key?(:reuse) || options[:reuse]) if returns end
-            # Call the method definition
-            def call(planner); body.call(planner) 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
-        # implementation of the method, only the model methods should abide to.
-        class MethodModel
-            include MethodInheritance
-
-            # The return type the method model defines
-            #
-            # If this is nil, methods of this model may return a task array
-            # or a task aggregation
-            def returns;    options[:returns] end
-            # If the model allows reusing tasks already in the plan
-            def reuse?; !options.has_key?(:reuse) || options[:reuse] end
-
-            # The model name
-            attr_reader :name
-            # The model options, as a Hash
-            attr_reader :options
-
-            def initialize(name, options = Hash.new)
-                @name, @options = name, options
-            end
-            def ==(model)
-                name == model.name && options == model.options
-            end
-
-            # call-seq:
-            #   merge(new_options)	    => self
-            #
-            # Add new options in this model. Raises ArgumentError if the
-            # new options cannot be merged because they are incompatible
-            # with the current model definition
-            def merge(new_options)
-                validate_options(new_options, [:returns, :reuse])
-                validate_option(new_options, :returns, false) do |rettype| 
-                    if options[:returns] && options[:returns] != rettype
-                        raise ArgumentError, "return type already specified for method #{name}"
-                    end
-                    options[:returns] = rettype
-                end
-                validate_option(new_options, :reuse, false) do |flag|
-                    if options.has_key?(:reuse) && options[:reuse] != flag
-                        raise ArgumentError, "the reuse flag is already set to #{options[:reuse]} on #{name}"
-                    end
-                    options[:reuse] = flag
-                    true
-                end
-
-                self
-            end
-
-            def overload(old_model)
-                if old_returns = old_model.returns
-                    if returns && !(returns < old_returns)
-                        raise ArgumentError, "new return type #{returns} is not a subclass of the old one #{old_returns}"
-                    elsif !returns
-                        options[:returns] = old_returns
-                    end
-                end
-                if options.has_key?(:reuse) && old_model.options.has_key?(:reuse) && options[:reuse] != old_model.reuse
-                    raise ArgumentError, "the reuse flag for #{name}h as already been set to #{options[:reuse]} on our parent model"
-                elsif !options.has_key?(:reuse) && old_model.options.has_key?(:reuse)
-                    options[:reuse] = old_model.reuse
-                end
-            end
-                    
-            # Do not allow changing this model anymore
-            def freeze
-                options.freeze
-                super
-            end
-
-            def initialize_copy(from) # :nodoc:
-                @name    = from.name.dup
-                @options = from.options.dup
-            end
-
-            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
-	#
-	# For instance
-	#   
-	#   class MyPlanner < Planner
-	#	method(:do_it) {  }
-	#	method(:do_sth_else) { ... }
-	#   end
-	#
-	#   planner = MyPlanner.new
-	#   planner.do_it		=> result of the do_it block
-	# 
-	# See Planner::method for a detailed description of the development
-	# search
-	#
-        class Planner
-	    extend Tools
-
-	    # The resulting plan
-	    attr_reader :plan
-
-	    # Creates a Planner object which acts on +plan+
-            def initialize(plan)
-		@plan	   = plan
-                @stack     = Array.new
-		@arguments = Array.new
-            end
-
-	    # A list of options on which the methods are selected
-	    # in find_methods
-	    # 
-	    # When calling a planning method, only the methods for
-	    # which these options match the user-provided options
-	    # are called. The other options are not considered
-	    METHOD_SELECTION_OPTIONS = [:id, :recursive, :returns]
-	    KNOWN_OPTIONS = [:lazy, :reuse, :args] + METHOD_SELECTION_OPTIONS
-
-            def self.validate_method_query(name, options)
-                name = name.to_s
-		roby_options, method_arguments = 
-		    filter_options options, KNOWN_OPTIONS
-
-                validate_option(options, :returns, false, 
-                                "the ':returns' option must be a task model") do |opt| 
-                    opt.is_a?(Roby::TaskModelTag) ||
-			opt.has_ancestor?(Roby::Task)
-                end
-
-		[name, roby_options, method_arguments]
-            end
-
-	    # Return the method model for +name+, or nil
-            def self.method_model(name)
-		model = send("#{name}_model")
-	    rescue NoMethodError
-	    end
-
-            class << self
-		def last_id; @@last_id ||= 0 end
-		def last_id=(new_value); @@last_id = new_value end
-                def next_id; self.last_id += 1 end
-            end
-
-	    # Some validation on the method IDs
-	    # * an integer represented as a string is converted to integer form
-	    # * a symbol is converted to string
-	    def self.validate_method_id(method_id)
-		method_id = method_id.to_s if Symbol === method_id
-
-		if method_id.respond_to?(:to_str) && method_id.to_str =~ /^\d+$/
-		    Integer(method_id)
-		else
-		    method_id
-		end
-	    end
-
-	    # Creates, overloads or updates a method model
-	    # Returns the MethodModel object
-	    def self.update_method_model(name, options)
-		name = name.to_s
-		unless send("enum_#{name}_methods", nil).empty?
-		    raise ArgumentError, "cannot change the method model for #{name} since methods are already using it"
-		end
-
-		old_model = method_model(name)
-		new_model = MethodModel.new(name)
-		new_model.merge(options)
-
-		if old_model == new_model
-		    if !instance_variable_get("@#{name}_model")
-			instance_variable_set("@#{name}_model", new_model)
-		    end
-		    return new_model
-		elsif instance_variable_get("@#{name}_model")
-		    # old_model is defined at this level
-		    return old_model.merge(options)
-		else
-		    unless respond_to?("#{name}_model")
-			singleton_class.class_eval <<-EOD
-			    def #{name}_model
-				@#{name}_model || superclass.#{name}_model
-			    end
-			EOD
-		    end
-		    new_model.overload(old_model) if old_model
-		    instance_variable_set("@#{name}_model", new_model)
-		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
-	    #
-	    # In the first form, define a new method +name+. The given block
-	    # is used as method definition. It shall either return a Task
-	    # object or an object whose #each method yields task objects, or
-	    # raise a PlanModelError exception, or of one of its subclasses.
-	    #
-	    # The second form defines a method model, which defines
-	    # constraints on the method defined with this name
-	    #
-	    # == Overloading: using the +id+ option
-	    # The +id+ option defines the method ID. The ID can be used 
-	    # to override a method definition in submodels. For instance, 
-	    # if you do
-	    # 
-	    #	class A < Planner
-	    #	    method(:do_it, :id => 'first') { ... }
-	    #	    method(:do_it, :id => 'second') { ... }
-	    #	end
-	    #	class B < A
-	    #	    method(:do_it, :id => 'first') { ... }
-	    #	end
-	    #
-	    # Then calling B.new.do_it will call the +first+ method defined
-	    # in B and the +second+ defined in A
-	    #
-	    # If no method ID is given, an unique number is allocated. Try not
-	    # using numbers as method IDs yourself, since you could overload
-	    # an automatic ID.
-	    #
-	    # == Constraining the returned object
-	    # The +returns+ option defines what kind of Task object this method
-	    # shall return. 
-	    #
-	    # For instance, in
-	    # 
-       	    #	class A < Planner
-	    #	    method(:do_it, :id => 'first', :returns => MyTask) { ... }
-	    #	    method(:do_it, :id => 'second') { ... }
-	    #	end
-	    #	class B < A
-	    #	    method(:do_it, :id => 'first') { ... }
-	    #	end
-	    #
-	    # The +do_it+ method defined in B will have to return a MyTask-derived
-	    # Task object. Method models can be used to put a constraint on all
-	    # methods of a given name. For instance, in the following example, all
-	    # +do_it+ methods would have to return MyTask-based objects
-	    # 
-	    #	class A < Planner
-	    #	    method(:do_it, :returns => MyTask)
-	    #	    method(:do_it, :id => 'first') { ... }
-	    #	    method(:do_it, :id => 'second') { ... }
-	    #	end
-	    #
-	    # == Recursive call to methods
-	    # If the +recursive+ option is true, then the method can be called back even if it
-	    # currently being developed. The default is false
-	    #
-	    # For instance, the following example will raise a NoMethodError:
-	    #
-	    #	class A < Planner
-	    #	    method(:do_it) { do_it }
-	    #	end
-	    #	A.new.do_it
-	    #
-	    # while this one will behave properly
-	    #
-	    #	class A < Planner
-	    #	    method(:do_it) { do_it }
-	    #	    method(:do_it, :recursive => true) { ... }
-	    #	end
-	    #
-	    # == Reusing already existing tasks in plan
-	    # If the +reuse+ flag is set (the default), instead of calling a method
-	    # definition, the planner will try to find a suitable task in the current 
-	    # plan if the developed method defines a :returns attribute. Compatibility
-	    # is checked using Task#fullfills?
-	    #
-	    # == Defined attributes
-	    # For each method +name+, the planner class gets a few attributes and methods:
-	    # * each_name_method iterates on all MethodDefinition objects for +name+
-	    # * name_model returns the method model. It is not defined if no method model exists
-	    # * each_name_filter iterates on all filters for +name+
-	    def self.method(name, options = Hash.new, &body)
-                name, options = validate_method_query(name, options)
-		
-		# 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
-		    def #{name}(options = Hash.new)
-			plan_method("#{name}", options)
-		    end
-		    class << self
-		      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
-                    return update_method_model(name, options)
-                end
-                
-		# Handle the method ID
-		if method_id = options[:id]
-		    method_id = validate_method_id(method_id)
-		    if method_id.respond_to?(:to_int)
-			self.last_id = method_id if self.last_id < method_id
-		    end
-		else
-		    method_id = next_id
-		end
-		options[:id] = method_id
-		
-		# Get the method model (if any)
-                if model = method_model(name)
-                    options = model.validate(options)
-		    model.freeze
-                end
-
-		# Check if we are overloading an old method
-		if send("#{name}_methods")[method_id]
-		    raise ArgumentError, "method #{name}:#{method_id} is already defined on this planning model"
-                elsif old_method = find_methods(name, :id => method_id)
-                    old_method = *old_method
-                    options = old_method.validate(options)
-                    Planning.debug { "overloading #{name}:#{method_id}" } 
-                end
-
-		# Register the method definition
-		#
-		# First, define an "anonymous" method on this planner model to
-		# avoid calling instance_eval during planning
-		if body.arity > 0
-		    raise ArgumentError, "method body must accept zero arguments calls"
-		end
-		temp_method_name = "m#{@@temp_method_id += 1}"
-		define_method(temp_method_name, &body)
-                mdef = MethodDefinition.new(name, options, instance_method(temp_method_name))
-		send("#{name}_methods")[method_id] = mdef
-            end
-	    @@temp_method_id = 0
-
-	    # Returns an array of the names of all planning methods
-	    def self.planning_methods_names
-		names = Set.new
-		methods.each do |method_name|
-		    if method_name =~ /^each_(\w+)_method$/
-			names << $1
-		    end
-		end
-
-		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)
-		end
-	    end
-
-	    # Undefines all the definitions for the planning method +name+ on
-	    # this model. Definitions available on the parent are not removed
-	    def self.remove_planning_method(name)
-		remove_method(name)
-		remove_inherited_enumerable("#{name}_method", "#{name}_methods")
-		if method_defined?("#{name}_filter")
-		    remove_inherited_enumerable("#{name}_filter", "#{name}_filters")
-		end
-	    end
-
-	    def self.remove_inherited_enumerable(enum, attr = enum)
-		if instance_variable_defined?("@#{attr}")
-		    remove_instance_variable("@#{attr}")
-		end
-		singleton_class.class_eval do
-		    remove_method("each_#{enum}")
-		    remove_method(attr)
-		end
-	    end
-
-	    # Add a selection filter on the +name+ method. When developing the
-	    # +name+ method, the filter is called with the method options and
-	    # the MethodDefinition object, and should return +false+ if the
-	    # method is to be discarded, and +true+ otherwise
-	    #
-	    # Example
-	    #    class MyPlanner < Planning::Planner
-	    #	    method(:m, :id => 1) do
-	    #	      raise
-	    #	    end
-	    #
-	    #	    method(:m, :id => 2) do
-	    #	      Roby::Task.new
-	    #	    end
-	    #
-	    #	    # the id == 1 version of m fails, remove it of the set
-	    #	    # of valid methods
-	    #	    filter(:m) do |opts, m|
-	    #	      m.id == 2
-	    #	    end
-	    #    end
-	    #
-	    # This is mainly useful for external selection of methods (for
-	    # instance to implement some kind of dependency injection), or for
-	    # testing
-	    def self.filter(name, &filter)
-                check_arity(filter, 2)
-
-		if !respond_to?("#{name}_filters")
-		    inherited_enumerable("#{name}_filter", "#{name}_filters") { Array.new }
-		    class_eval <<-EOD
-			class << self
-			    cached_enum("#{name}_filter", "#{name}_filters", false)
-			end
-		    EOD
-		end
-		send("#{name}_filters") << filter
-	    end
-
-	    def self.each_method(name, id, &iterator)
-		send("each_#{name}_method", id, &iterator)
-	    end
-
-	    # Find all methods that can be used to plan +[name, options]+. The selection is
-	    # done in two steps:
-	    # * we search all definition of +name+ that are compatible with +options. In this
-	    #   stage, only the options listed in METHOD_SELECTION_OPTIONS are compared
-	    # * we call the method filters (if any) to remove unsuitable methods
-            def self.find_methods(name, options = Hash.new)
-		# validate the options hash, and split it into the options that are used for
-		# method selection and the ones that are ignored here
-                name, options = validate_method_query(name, options)
-		method_selection = options.slice(*METHOD_SELECTION_OPTIONS)
-
-		if method_id = method_selection[:id]
-		    method_selection[:id] = method_id = validate_method_id(method_id)
-		    result = send("enum_#{name}_methods", method_id).find { true }
-		    result = if result && result.options.merge(method_selection) == result.options
-				 [result]
-			     end
-		else
-		    result = send("enum_#{name}_methods", nil).collect do |id, m|
-			if m.options.merge(method_selection) == m.options 
-			    m
-			end
-		    end.compact
-		end
-
-		return nil if !result
-
-		filter_method = "enum_#{name}_filters"
-		if respond_to?(filter_method)
-		    # Remove results for which at least one filter returns false
-		    result.reject! { |m| send(filter_method).any? { |f| !f[options, m] } }
-		end
-
-		if result.empty?; nil
-		else; result
-		end
-            end
-
-	    # If there is method definitions for +name+
-	    def has_method?(name); singleton_class.has_method?(name) end
-	    def self.has_method?(name); respond_to?("#{name}_methods") end
-
-	    # Returns the method model that should be considered when using
-	    # the result of the method +name+ with options +options+
-	    #
-	    # This model should be used for instance when adding a new
-	    # hierarchy relation between a parent and the result of 
-	    # <tt>plan.#{name}(options)</tt>
-	    def self.model_of(name, options = {})
-		model = if options[:id]
-			    enum_for("each_method", name, options[:id]).find { true }
-			end
-		model ||= method_model(name)
-		model || default_method_model(name)
-	    end
-
-	    def self.default_method_model(name)
-		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.
-	    #
-	    # +options+ is an option hash. These options are used to override
-	    # the current method options. Only one option is recognized by
-	    # +replan_task+:
-	    #
-	    # strict:: if true, we use the current method name and id for 
-	    #          the planning task. If false, use only the method name.
-	    #	       defaults to true.
-	    def replan_task(options = nil)
-		method_options = arguments.dup
-		if !options.has_key?(:strict) || options.delete(:strict)
-		    method_options.merge!(:id => @stack.last[1])
-		end
-
-		if options
-		    method_options.merge!(options)
-		end
-
-		Roby::PlanningTask.new :planner_model => self.class,
-		    :method_name => @stack.last[0], 
-		    :method_options => method_options
-	    end
-
-            def stop; @stop_required = true end
-            def interruption_point; raise Interrupt, "interrupted planner" if @stop_required end
-
-            # Find a suitable development for the +name+ method.
-            def plan_method(name, options = Hash.new)
-                if @stack.empty?
-                    @stop_required = false
-                end
-                interruption_point
-
-                name    = name.to_s
-
-		planning_options, method_options = 
-		    filter_options options, KNOWN_OPTIONS
-
-		if method_options.empty?
-		    method_options = planning_options.delete(:args) || {}
-		elsif planning_options[:args] && !planning_options[:args].empty?
-		    raise ArgumentError, "provided method-specific options through both :args and the option hash"
-		end
-
-		Planning.debug { "planning #{name}[#{method_options}]" }
-
-		# Check for recursion
-                if (options[:id] && @stack.include?([name, options[:id]])) || (!options[:id] && @stack.find { |n, _| n == name })
-                    options[:recursive] = true
-                end
-
-		# Get all valid methods. If no candidate are found, still try 
-		# to get a task to re-use
-                methods = singleton_class.find_methods(name, options)
-		
-		# Check if we can reuse a task already in the plan
-		if !options.has_key?(:reuse) || options[:reuse]
-		    all_returns = if methods
-				      methods.map { |m| m.returns if m.reuse? }
-				  else []
-				  end
-		    if (model = singleton_class.method_model(name)) && !options[:id]
-			all_returns << model.returns if model.reuse?
-		    end
-		    all_returns.compact!
-				      
-		    for return_type in all_returns
-			if task = find_reusable_task(return_type, method_options)
-			    return task
-			end
-		    end
-		end
-
-                if !methods || methods.empty?
-                    raise NotFound.new(self, Hash.new)
-		end
-
-		# Call the methods
-		call_planning_methods(Hash.new, method_options, *methods)
-
-            rescue Interrupt
-                raise
-
-            rescue NotFound => e
-                e.method_name       = name
-                e.method_options    = options
-                raise e.dup, e.message, caller(1)
-            end
-	    
-	    def find_reusable_task(return_type, method_options)
-		query = plan.find_tasks.
-		    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}[#{method_options}]" }
-		    return candidate
-		end
-		nil
-	    end
-
-	    def arguments; @arguments.last end
-	    private :arguments
-
-            # 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, 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)
-		    rescue PlanModelError, Interrupt
-			raise
-		    rescue Exception => e
-			raise PlanModelError.new(self), e.message, e.backtrace
-		    end
-
-		    # Check that result is a task or a task collection
-		    unless result && (result.respond_to?(:to_task) || result.respond_to?(:each) || !result.respond_to?(:each_task))
-			raise PlanModelError.new(self), "#{method} returned #{result}, which is neither a task nor a task collection"
-		    end
-		    
-		    # Insert resulting tasks in +plan+
-		    plan.add(result)
-
-		    expected_return = method.returns
-		    if expected_return 
-			if !result.respond_to?(:to_task) || 
-			    !result.fullfills?(expected_return, arguments.slice(*expected_return.arguments))
-
-			    if !result then result = "nil"
-			    elsif result.respond_to?(:each)
-				result = result.map { |t| "#{t}(#{t.arguments})" }.join(", ")
-			    else result = "#{result}(#{result.arguments})"
-			    end
-			    raise PlanModelError.new(self), "#{method} returned #{result} which does not fullfill #{method.returns}(#{arguments})"
-			end
-		    end
-		    Planning.debug { "found #{result}" }
-
-		    result
-
-                ensure
-                    @arguments.pop
-                    @stack.pop
-                end
-
-            rescue PlanModelError => e
-                e.planner = self unless e.planner
-                errors[method] = e
-                if methods.empty?
-                    raise NotFound.new(self, errors)
-                else
-                    call_planning_methods(errors, method_options, *methods)
-                end
-            end
-
-            private :call_planning_methods
-
-	    # Builds a loop in a plan (i.e. a method which is generated in
-	    # loop)
-	    def make_loop(options = {}, &block)
-		raise ArgumentError, "no block given" unless block
-
-                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
-                loop_method.options.merge!(planning_options)
-
-		options[:method_options] ||= {}
-		options[:method_options].merge!(arguments || {})
-		options[:method_options][:id] = loop_method.id
-		PlanningLoop.new(options)
-	    end
-        end
-
-	# A planning Library is only a way to gather a set of planning
-	# methods. It is created by
-	#   module MyLibrary
-	#      planning_library
-	#      method(:bla) do
-	#      end
-	#   end
-	# or 
-	#   my_library = Roby::Planning::Library.new do
-	#       method(:bla) do end
-	#   end
-	#
-	# It is then used by simply including the library in another library
-	# or in a Planner class 
-	# 
-	#	module AnotherLibrary
-	#	    include MyLibrary
-	#	end
-	#
-	#	class MyPlanner < Planner
-	#	    include AnotherLibrary
-	#	end
-	#
-	# Alternatively, you can use Planner::use and Library::use, which search
-	# for a Planning module in the given module. For instance
-	#
-	#	module Namespace
-	#	    module Planning
-	#	    planning_library
-	#	    [...]
-	# 	    end
-	# 	end
-	#
-	# can be used with
-	#	    
-	#	class MyPlanner < Planner
-	#	    using Namespace
-	#	end
-	#
-	module Library
-	    include Tools
-
-	    attr_reader :default_options
-
-	    def planning_methods; @methods ||= Array.new end
-	    def method(name, options = Hash.new, &body)
-		if body && default_options
-		    options = default_options.merge(options)
-		end
-		planning_methods << [name, options, body]
-	    end
-
-	    def self.clear_model
-		planning_methods.clear
-	    end
-
-	    # Cannot use included here because included() is called *after* the module
-	    # has been included
-	    def append_features(klass)
-		new_libraries = ancestors.enum_for.
-		    reject { |mod| klass < mod }.
-		    find_all { |mod| mod.respond_to?(:planning_methods) }
-
-		super
-
-		unless klass < Planner
-		    if Class === klass
-			Roby.debug "including a planning library in a class which is not a Planner, which is useless"
-		    else
-			klass.extend Library
-		    end
-		    return
-		end
-
-		new_libraries.reverse_each do |mod|
-		    mod.planning_methods.each do |name, options, body| 
-			begin
-			    klass.method(name, options, &body)
-			rescue ArgumentError => e
-			    raise ArgumentError, "cannot include the #{self} library in #{klass}: when inserting #{name}#{options}, #{e.message}", caller(0)
-			end
-		    end
-		end
-	    end
-
-	    def self.new(&block)
-		Module.new do
-		    extend Library
-		    class_eval(&block)
-		end
-	    end
-	end
-
-    end
-end
-
-
-class Module
-    def planning_library(default_options = Hash.new)
-	extend Roby::Planning::Library
-	instance_variable_set(:@default_options, default_options)
-    end
-end
-