roby 0.8.0 → 3.0.0

data/lib/roby/queries/query.rb

@@ -0,0 +1,188 @@
+module Roby
+    module Queries
+    # A query is a TaskMatcher that applies on a plan. It should, in general, be
+    # preferred to TaskMatcher as it uses task indexes to be more efficient.
+    #
+    # Queries cache their result. I.e. once #each has been called to get the
+    # query results, the query will always return the same results until #reset
+    # has been called.
+    class Query < TaskMatcher
+        # The plan this query acts on
+        attr_reader :plan
+
+        # Create a query object on the given plan
+        def initialize(plan = nil)
+            @scope = :global
+            @plan = plan
+            super()
+            @plan_predicates = Set.new
+            @neg_plan_predicates = Set.new
+        end
+
+        def query
+            self
+        end
+
+        # Search scope for queries on transactions. If equal to :local, the
+        # query will apply only on the scope of the searched transaction,
+        # otherwise it applies on a virtual plan that is the result of the
+        # transaction stack being applied.
+        #
+        # The default is :global.
+        #
+        # See #local_scope and #global_scope
+        attr_reader :scope
+
+        # Changes the scope of this query. See #scope.
+        def local_scope
+            @scope = :local
+            self
+        end
+        # Changes the scope of this query. See #scope.
+        def global_scope
+            @scope = :global
+            self
+        end
+
+        # Changes the plan this query works on. This calls #reset (obviously)
+        def plan=(new_plan)
+            reset
+            @plan = new_plan
+        end
+
+        # The set of tasks which match in plan. This is a cached value, so use
+        # #reset to actually recompute this set.
+        def result_set
+            @result_set ||= plan.query_result_set(self)
+        end
+
+        def indexed_sets(index)
+            positive_sets, negative_sets = super
+
+            if plan_predicates.include?(:mission_task?)
+                positive_sets << plan.mission_tasks
+            elsif neg_plan_predicates.include?(:mission_task?)
+                negative_sets << plan.mission_tasks
+            end
+
+            if plan_predicates.include?(:permanent_task?)
+                positive_sets << plan.permanent_tasks
+            elsif neg_plan_predicates.include?(:permanent_task?)
+                negative_sets << plan.permanent_tasks
+            end
+            return positive_sets, negative_sets
+        end
+
+        # Reinitializes the cached query result.
+        #
+        # Queries cache their result, i.e. #each will always return the same
+        # task set. #reset makes sure that the next call to #each will return
+        # the same value.
+        def reset
+            @result_set = nil
+            self
+        end
+
+        # The set of predicates of Plan which must return true for #=== to
+        # return true
+        attr_reader :plan_predicates
+        # The set of predicates of Plan which must return false for #=== to
+        # return true.
+        attr_reader :neg_plan_predicates
+
+        class << self
+            # For each name in +names+, define the #name and #not_name methods
+            # on Query objects. When one of these methods is called on a Query
+            # object, plan.name?(task) must return true (resp. false) for the
+            # task to match.
+            def match_plan_predicates(names)
+                names.each do |name, predicate_name|
+                    predicate_name ||= name
+                    class_eval <<-EOD, __FILE__, __LINE__+1
+                    def #{name}
+                        if neg_plan_predicates.include?(:#{predicate_name})
+                            raise ArgumentError, "trying to match (#{name} & !#{name})"
+                        end
+                        plan_predicates << :#{predicate_name}
+                        self
+                    end
+                    def not_#{name}
+                        if plan_predicates.include?(:#{predicate_name})
+                            raise ArgumentError, "trying to match (#{name} & !#{name})"
+                        end
+                        neg_plan_predicates << :#{predicate_name}
+                        self
+                    end
+                    EOD
+                end
+            end
+        end
+
+        ##
+        # :method: mission
+        #
+        # Filters missions
+        #
+        # Matches tasks in plan that are missions
+
+        ##
+        # :method: not_mission
+        #
+        # Filters out missions
+        #
+        # Matches tasks in plan that are not missions
+
+        ##
+        # :method: permanent
+        #
+        # Filters permanent tasks
+        #
+        # Matches tasks in plan that are declared as permanent tasks.
+
+        ##
+        # :method: not_permanent
+        #
+        # Filters out permanent tasks
+        #
+        # Matches tasks in plan that are not declared as permanent tasks
+
+        match_plan_predicates mission: :mission_task?
+        match_plan_predicates permanent: :permanent_task?
+        
+        # Filters tasks which have no parents in the query itself.
+        #
+        # Will filter out tasks which have parents in +relation+ that are
+        # included in the query result.
+        def roots(relation)
+            @result_set = plan.query_roots(result_set, relation)
+            self
+        end
+
+        # True if +task+ matches the query. Call #result_set to have the set of
+        # tasks which match in the given plan.
+        def ===(task)
+            for pred in plan_predicates
+                return unless plan.send(pred, task)
+            end
+            for neg_pred in neg_plan_predicates
+                return if plan.send(neg_pred, task)
+            end
+
+            return unless super
+
+            true
+        end
+
+        # Iterates on all the tasks in the given plan which match the query
+        #
+        # This set is cached, i.e. #each will yield the same task set until
+        # #reset is called.
+        def each(&block)
+            return enum_for(__method__) if !block_given?
+            plan.query_each(result_set, &block)
+        end
+        include Enumerable
+    end
+    end
+end
+

data/lib/roby/queries/task_event_generator_matcher.rb

@@ -0,0 +1,86 @@
+module Roby
+    module Queries
+        # Object that allows to describe a task's event generator and match it
+        # in the plan
+        #
+        # It uses a task matcher to match the underlying task
+        class TaskEventGeneratorMatcher < PlanObjectMatcher
+            # @return [#===] the required event name
+            attr_reader :symbol
+            # @return [TaskMatcher] the task matcher that describes this event's
+            #   task
+            attr_reader :task_matcher
+            # @return [Boolean] if true, self will match the specified generator
+            #   as well as any other generator that is forwarded to it. If false
+            #   (the default) only the specified generator will match
+            attr_predicate :generalized?
+
+            def initialize(task_matcher = Roby::Task.match, symbol = Queries.any)
+                if symbol.respond_to?(:to_sym) # Probably a symbol, convert to string
+                    symbol = symbol.to_s
+                end
+                @symbol = symbol
+                @task_matcher = task_matcher
+                @generalized = false
+                super()
+            end
+
+            # Makes this matcher a generalized matcher
+            # @see #generalized?
+            # @return self
+            def generalized
+                @generalized = true
+                self
+            end
+
+            # Adds a matching object for the event's name
+            #
+            # @param [Regexp,Symbol,String,#===] symbol an object that will
+            #   allow to match the event's name
+            # @return self
+            def with_name(symbol)
+                @symbol =
+                    if symbol.respond_to?(:to_sym) then symbol.to_s
+                    else symbol
+                    end
+                self
+            end
+
+            # @raise [NotImplementedError] Cannot yet do plan queries on task
+            #   event generators
+            def filter(initial_set, index)
+                raise NotImplementedError
+            end
+
+            alias plan_object_match :===
+
+            def to_s
+                "#{task_matcher}.#{symbol}"
+            end
+
+            # Tests whether the given task event generator matches self
+            #
+            # @param [TaskEventGenerator] object
+            # @return [Boolean]
+            def ===(object)
+                return if !object.kind_of?(TaskEventGenerator)
+
+                if match_not_generalized(object)
+                    true
+                elsif generalized? && object.plan
+                    forwarding_graph = object.relation_graph_for(EventStructure::Forwarding)
+                    forwarding_graph.depth_first_visit(object) do |generator|
+                        return true if match_not_generalized(generator)
+                    end
+                    false
+                end
+            end
+
+            def match_not_generalized(object)
+                (symbol === object.symbol.to_s) &&
+                    plan_object_match(object) && (task_matcher === object.task)
+            end
+        end
+    end
+end
+

data/lib/roby/queries/task_matcher.rb

@@ -0,0 +1,344 @@
+module Roby
+    module Queries
+
+    # This class represents a predicate which can be used to filter tasks. To
+    # filter plan-related properties, use Query.
+    #
+    # A TaskMatcher object is a AND combination of various tests against tasks.
+    #
+    # For instance, if one does
+    #
+    #   matcher = TaskMatcher.new.which_fullfills(Tasks::Simple).pending
+    #
+    # Then
+    #  
+    #   matcher === task
+    #
+    # will return true if +task+ is an instance of the Tasks::Simple model and
+    # is pending (not started yet), and false if one of these two
+    # characteristics is not true.
+    class TaskMatcher < PlanObjectMatcher
+        # Set of arguments that should be tested on the task
+        #
+        # @return [Hash]
+        attr_reader :arguments
+
+        # Initializes an empty TaskMatcher object
+        def initialize
+            super
+            @arguments            = Hash.new
+            @interruptible        = nil
+        end
+
+        def to_s
+            result = super
+            if !arguments.empty?
+                result << ".with_arguments(#{arguments.map { |k, v| ":#{k} => #{v}" }.join(", ")})"
+            end
+            result
+        end
+
+        # Filters on task model and arguments
+        #
+        # Will match if the task is an instance of +model+ or one of its
+        # subclasses, and if parts of its arguments are the ones provided. Set
+        # +arguments+ to nil if you don't want to filter on arguments.
+        def which_fullfills(model, arguments = nil)
+            with_model(model)
+            if arguments
+                with_model_arguments(arguments)
+            end
+            self
+        end
+
+        # Filters on the arguments that are declared in the model
+        #
+        # Will match if the task arguments for which there is a value in
+        # +arguments+ are set to that very value, only looking at arguments that
+        # are defined in the model set by #with_model.
+        #
+        # See also #with_arguments
+        #
+        # Example:
+        #
+        #   class TaskModel < Roby::Task
+        #     argument :a
+        #     argument :b
+        #   end
+        #   task = TaskModel.new(a: 10, b: 20)
+        #
+        #   # Matches on :a, :b is ignored altogether
+        #   TaskMatcher.new.
+        #       with_model(TaskModel).
+        #       with_model_arguments(a: 10) === task # => true
+        #   # Looks for both :a and :b
+        #   TaskMatcher.new.
+        #       with_model(TaskModel).
+        #       with_model_arguments(a: 10, b: 30) === task # => false
+        #   # Matches on :a, :c is ignored as it is not an argument of +TaskModel+
+        #   TaskMatcher.new.
+        #       with_model(TaskModel).
+        #       with_model_arguments(a: 10, c: 30) === task # => true
+        #
+        # In general, one would use #which_fullfills, which sets both the model
+        # and the model arguments
+        def with_model_arguments(arguments)
+            valid_arguments = model.inject(Array.new) { |set, model| set | model.arguments.to_a }
+            with_arguments(arguments.slice(*valid_arguments))
+            self
+        end
+
+        # Filters on the arguments that are declared in the model
+        #
+        # Will match if the task arguments for which there is a value in
+        # +arguments+ are set to that very value. Unlike #with_model_arguments,
+        # all values set in +arguments+ are considered.
+        #
+        # See also #with_model_arguments
+        #
+        # Example:
+        #
+        #   class TaskModel < Roby::Task
+        #     argument :a
+        #     argument :b
+        #   end
+        #   task = TaskModel.new(a: 10, b: 20)
+        #
+        #   # Matches on :a, :b is ignored altogether
+        #   TaskMatcher.new.
+        #       with_arguments(a: 10) === task # => true
+        #   # Looks for both :a and :b
+        #   TaskMatcher.new.
+        #       with_arguments(a: 10, b: 30) === task # => false
+        #   # Looks for both :a and :c, even though :c is not declared in TaskModel
+        #   TaskMatcher.new.
+        #       with_arguments(a: 10, c: 30) === task # => false
+        def with_arguments(arguments)
+            @arguments ||= Hash.new
+            self.arguments.merge!(arguments) do |k, old, new| 
+                if old != new
+                    raise ArgumentError, "a constraint has already been set on the #{k} argument" 
+                end
+                old
+            end
+            self
+        end
+
+        ##
+        # :method: fully_instanciated
+        #
+        # Matches if the task is fully instanciated
+        #
+        # See also #partially_instanciated, Task#fully_instanciated?
+
+        ##
+        # :method: partially_instanciated
+        #
+        # Matches if the task is partially instanciated
+        #
+        # See also #fully_instanciated, Task#partially_instanciated?
+
+        ##
+        # :method: not_abstract
+        #
+        # Matches if the task is not abstract
+        #
+        # See also #abstract, Task#abstract?
+
+        ##
+        # :method: abstract
+        #
+        # Matches if the task is abstract
+        #
+        # See also #not_abstract, Task#abstract?
+
+        ##
+        # :method: not_abstract
+        #
+        # Matches if the task is not abstract
+        #
+        # See also #abstract, Task#abstract?
+
+        ##
+        # :method: pending
+        #
+        # Matches if the task is pending
+        #
+        # See also #not_pending, Task#pending?
+
+        ##
+        # :method: not_pending
+        #
+        # Matches if the task is not pending
+        #
+        # See also #pending, Task#pending?
+
+        ##
+        # :method: running
+        #
+        # Matches if the task is running
+        #
+        # See also #not_running, Task#running?
+
+        ##
+        # :method: not_running
+        #
+        # Matches if the task is not running
+        #
+        # See also #running, Task#running?
+
+        ##
+        # :method: finished
+        #
+        # Matches if the task is finished
+        #
+        # See also #not_finished, Task#finished?
+
+        ##
+        # :method: not_finished
+        #
+        # Matches if the task is not finished
+        #
+        # See also #finished, Task#finished?
+
+        ##
+        # :method: success
+        #
+        # Matches if the task is success
+        #
+        # See also #not_success, Task#success?
+
+        ##
+        # :method: not_success
+        #
+        # Matches if the task is not success
+        #
+        # See also #success, Task#success?
+
+        ##
+        # :method: failed
+        #
+        # Matches if the task is failed
+        #
+        # See also #not_failed, Task#failed?
+
+        ##
+        # :method: not_failed
+        #
+        # Matches if the task is not failed
+        #
+        # See also #failed, Task#failed?
+
+        ##
+        # :method: interruptible
+        #
+        # Matches if the task is interruptible
+        #
+        # See also #not_interruptible, Task#interruptible?
+
+        ##
+        # :method: not_interruptible
+        #
+        # Matches if the task is not interruptible
+        #
+        # See also #interruptible, Task#interruptible?
+
+        ##
+        # :method: finishing
+        #
+        # Matches if the task is finishing
+        #
+        # See also #not_finishing, Task#finishing?
+
+        ##
+        # :method: not_finishing
+        #
+        # Matches if the task is not finishing
+        #
+        # See also #finishing, Task#finishing?
+
+        match_predicates :abstract?, :partially_instanciated?, :fully_instanciated?,
+            :starting?, :pending?, :running?, :finished?, :success?, :failed?, :interruptible?
+
+        # Finishing tasks are also running task, use the index on 'running'
+        match_predicate :finishing?, [[:running?], []]
+
+        # Reusable tasks must be neither finishing nor finished
+        match_predicate :reusable?, [[], [:finished?]]
+
+
+        # Helper method for #with_child and #with_parent
+        def handle_parent_child_arguments(other_query, relation, relation_options) # :nodoc:
+            if !other_query.kind_of?(TaskMatcher) && !other_query.kind_of?(Task)
+                if relation.kind_of?(Hash)
+                    arguments = relation
+                    relation         = (arguments.delete(:relation) || arguments.delete('relation'))
+                    relation_options = (arguments.delete(:relation_options) || arguments.delete('relation_options'))
+                else
+                    arguments = Hash.new
+                end
+                other_query = TaskMatcher.which_fullfills(other_query, arguments)
+            end
+            return relation, [other_query, relation_options]
+        end
+        # True if +task+ matches all the criteria defined on this object.
+        def ===(task)
+            return unless task.kind_of?(Roby::Task)
+            return unless task.arguments.slice(*arguments.keys) == arguments
+            return super
+        end
+
+        # Returns true if filtering with this TaskMatcher using #=== is
+        # equivalent to calling #filter() using a Index. This is used to
+        # avoid an explicit O(N) filtering step after filter() has been called
+        def indexed_query?
+            arguments.empty? && super
+        end
+
+        def find_event(event_name)
+            event_name = event_name.to_sym
+            models = if !@model.empty?
+                         @model
+                     else [Roby::Task]
+                     end
+            models.each do |m|
+                if event_m = m.find_event(event_name)
+                    return TaskEventGeneratorMatcher.new(self, event_name)
+                end
+            end
+            nil
+        end
+
+        def respond_to_missing?(m, include_private)
+            m =~ /_event$/ || super
+        end
+
+        def method_missing(m, *args)
+            if m =~ /_event$/
+                event_name = $`
+                model = find_event(event_name)
+                if !model
+                    task_models =
+                        if !@model.empty?
+                            @model
+                        else [Roby::Task]
+                        end
+                    raise NoMethodError.new(m), "no event '#{event_name}' in match model #{task_models.map(&:to_s).join(", ")}, use #which_fullfills to narrow the task model"
+                elsif !args.empty?
+                    raise ArgumentError, "#{m} expected zero arguments, got #{args.size}"
+                else
+                    return TaskEventGeneratorMatcher.new(self, event_name)
+                end
+            else
+                super
+            end
+        end
+
+        # Define singleton classes. For instance, calling TaskMatcher.which_fullfills is equivalent
+        # to TaskMatcher.new.which_fullfills
+        declare_class_methods :which_fullfills, :with_arguments
+    end
+    end
+end
+
+