roby 0.8.0 → 3.0.0

data/lib/roby/actions.rb

@@ -0,0 +1,17 @@
+module Roby
+    module Actions
+        extend Logger::Hierarchy
+    end
+end
+
+require 'roby/actions/models/action'
+require 'roby/actions/models/method_action'
+require 'roby/actions/models/coordination_action'
+require 'roby/actions/models/interface_base'
+require 'roby/actions/models/interface'
+require 'roby/actions/models/library'
+
+require 'roby/actions/action'
+require 'roby/actions/interface'
+require 'roby/actions/task'
+require 'roby/actions/library'

data/lib/roby/actions/action.rb

@@ -0,0 +1,80 @@
+module Roby
+    module Actions
+        # The representation of an action, as a model and arguments
+        class Action
+            # The action model
+            # @return [Models::Action]
+            attr_accessor :model
+            # The action arguments
+            # @return [Hash]
+            attr_reader :arguments
+
+            def initialize(model, **arguments)
+                @model, @arguments = model, arguments
+            end
+
+            def name
+                model.name
+            end
+
+            def ==(other)
+                other.kind_of?(Action) &&
+                    model == other.model &&
+                    arguments == other.arguments
+            end
+
+            # Update this object with new arguments and returns it
+            #
+            # @param [Hash] arguments new arguments
+            # @return [self]
+            def with_arguments(**arguments)
+                @arguments.merge!(arguments)
+                self
+            end
+
+            def has_missing_required_arg?
+                model.arguments.any? do |arg|
+                    arg_sym = arg.name.to_sym
+                    if arguments.has_key?(arg_sym)
+                        TaskArguments.delayed_argument?(arguments.fetch(arg_sym))
+                    else
+                        arg.required?
+                    end
+                end
+            end
+
+            # The task model returned by this action
+            def returned_type
+                model.returned_type
+            end
+
+            # Returns a plan pattern that would deploy this action in the plan
+            # @return [Roby::Task] the task, with a planning task of type
+            #   {Actions::Task}
+            def as_plan(**arguments)
+                model.plan_pattern(**self.arguments.merge(arguments))
+            end
+
+            def rebind(action_interface_model)
+                model.rebind(action_interface_model).new(**arguments)
+            end
+
+            # Deploys this action on the given plan
+            def instanciate(plan, **arguments)
+                model.instanciate(plan, self.arguments.merge(arguments))
+            end
+
+            def to_s
+                "#{model}(#{arguments.map { |k,v| "#{k} => #{v}" }.sort.join(", ")})"
+            end
+
+            def to_coordination_task(task_model = Roby::Task)
+                Coordination::Models::TaskFromAction.new(self)
+            end
+
+            def to_action
+                self
+            end
+        end
+    end
+end

data/lib/roby/actions/interface.rb

@@ -0,0 +1,45 @@
+module Roby
+    module Actions
+        # Functionality to gather information about the actions available on a
+        # given Roby app
+        #
+        # Actions are simply methods of arity zero or one, preceded by a call to
+        # #describe. The methods can modify the current plan (available as
+        # #plan) and must return the Roby::Task instance that will be used to
+        # represent the action during execution
+        #
+        #     class Iface < Roby::Actions::Interface
+        #         describe "makes the robot turn"
+        #         def robot_turn
+        #         end
+        #     end
+        class Interface
+            extend Models::Interface
+            extend Logger::Hierarchy
+
+            # The plan to which this action interface adds tasks
+            attr_reader :plan
+
+            def initialize(plan)
+                @plan = plan
+            end
+
+            def model; self.class end
+
+            def action_state_machine(task, &block)
+                model = Coordination::ActionStateMachine.
+                    new_submodel(action_interface: self.model, root: task.model)
+                model.parse(&block)
+                model.new(task)
+            end
+
+            def action_script(task, &block)
+                model = Coordination::ActionScript.
+                    new_submodel(action_interface: self.model, root: task.model)
+                model.parse(&block)
+                model.new(task)
+            end
+        end
+    end
+end
+

data/lib/roby/actions/library.rb

@@ -0,0 +1,23 @@
+module Roby
+    module Actions
+        Library = Models::Library.new
+        Library.root = true
+    end
+end
+
+class Module
+    def action_library(name = nil, &block)
+        if name
+            create_and_register_submodel(self, name, Roby::Actions::Library, &block)
+        else
+            extend Roby::Actions::Models::Interface
+            extend MetaRuby::ModelAsModule
+            extend MetaRuby::Registration
+            self.supermodel = Roby::Actions::Library
+            Roby::Actions::Library.register_submodel(self)
+        end
+    end
+end
+
+
+

data/lib/roby/actions/models/action.rb

@@ -0,0 +1,224 @@
+module Roby
+    module Actions
+        module Models
+        # Basic description of an action
+        class Action
+            # Structure that stores the information about planning method arguments
+            #
+            # See MethodDescription
+            Argument = Struct.new :name, :doc, :required, :default do
+                def pretty_print(pp)
+                    pp.text "#{name}: #{doc}"
+                    if required then pp.text ' (required)'
+                    else pp.text ' (optional)'
+                    end
+                    if default
+                        pp.text " default=#{default}"
+                    end
+                end
+
+                def required?
+                    !!required
+                end
+            end
+
+            # The action name
+            attr_accessor :name
+            # The action description
+            attr_accessor :doc
+            # The description of the action arguments
+            #
+            # @return [Array<Argument>]
+            attr_reader :arguments
+            # If true, the method is flagged as advanced. I.e., it won't be
+            # listed by default in the shell when the 'actions' command is
+            # called
+            attr_predicate :advanced?, true
+            # The return type for this method, as a task or task service model.
+            # It is Roby::Task by default
+            #
+            # @return [Model<Roby::Task>,Model<Roby::TaskService>]
+            attr_reader :returned_type
+
+            # @return [Action] an action using this action model and the given
+            #   arguments
+            def new(**arguments)
+                Actions::Action.new(self, normalize_arguments(arguments))
+            end
+
+            def ==(other)
+                other.kind_of?(self.class) &&
+                    other.name == name &&
+                    other.arguments == arguments &&
+                    other.returned_type == returned_type
+            end
+
+
+            # Task model that can be used to represent this action in a plan
+            def returned_task_type
+                if @returned_task_type
+                    return @returned_task_type
+                end
+
+                if returned_type.kind_of?(Roby::Models::TaskServiceModel)
+                    model = Class.new(Roby::Task)
+                    model.provides returned_type
+                    model.fullfilled_model = [returned_type]
+                    @returned_task_type = model
+                else
+                    # Create an abstract task which will be planned
+                    @returned_task_type = returned_type
+                end
+            end
+
+            def initialize(doc = nil)
+                if doc.kind_of?(Action)
+                    @name = doc.name
+                    @doc = doc.doc
+                    @arguments = doc.arguments.map(&:dup)
+                    @returned_type = doc.returned_type
+                    @advanced = doc.advanced?
+                else
+                    @name = nil
+                    @doc = doc
+                    @arguments = []
+                    @returned_type = Roby::Task
+                    @advanced = false
+                end
+            end
+
+            def initialize_copy(old)
+                super
+                @arguments = arguments.map(&:dup)
+            end
+
+            # @api private
+            #
+            # Validates that the information provided in the argument can safely
+            # be used to update self
+            #
+            # @raise [ArgumentError]
+            def validate_can_overload(parent)
+                overloaded_return  = parent.returned_type
+                overloading_return = self.returned_type
+
+                if !overloading_return.fullfills?(overloaded_return)
+                    if overloading_return.kind_of?(Class)
+                        raise ArgumentError, "overloading return type #{overloading_return} does not fullfill #{overloaded_return}, cannot merge the action models"
+                    elsif overloaded_return != Roby::Task
+                        raise ArgumentError, "overloading return type #{overloading_return} is a service model which does not fullfill #{overloaded_return}, and Roby does not support return type specifications that are composite of services and tasks"
+                    end
+                end
+            end
+
+            # Update this action model with information from another, to reflect
+            # that self overloads the other model
+            #
+            # @param [Action] parent the action model that is being overloaded
+            # @raise [ArgumentError] if the actions return types are not
+            #   compatible
+            def overloads(parent)
+                validate_can_overload(parent)
+
+                self.doc ||= parent.doc
+                @arguments.concat(parent.arguments.find_all { |a| !has_arg?(a.name) })
+            end
+
+            # Documents a new required argument to the method
+            def required_arg(name, doc = nil)
+                arguments << Argument.new(name.to_s, doc, true)
+                self
+            end
+
+            # Documents a new optional argument to the method
+            def optional_arg(name, doc = nil, default = nil)
+                doc = doc.to_str if doc
+                arg = Argument.new(name.to_s, doc, false)
+                arg.default = default
+                arguments << arg
+                self
+            end
+
+            # Return true if this action has at least one required argument
+            def has_required_arg?
+                arguments.any?(&:required?)
+            end
+
+            # Return true if a argument with the given name is specified
+            def has_arg?(name)
+                !!find_arg(name)
+            end
+
+            # Find the argument from its name
+            #
+            # @param [String] name the argument name
+            # @return [Argument,nil]
+            def find_arg(name)
+                name = name.to_s
+                arguments.find { |arg| arg.name == name }
+            end
+
+            # Enumerate this action's arguments
+            #
+            # @yieldparam [Argument] arg
+            def each_arg(&block)
+                arguments.each(&block)
+            end
+
+            # Sets the advanced flag to true. See #advanced?
+            def advanced
+                @advanced = true 
+                self
+            end
+
+            # Sets the type of task returned by the action
+            def returns(type)
+                if !type.kind_of?(Class) && !type.kind_of?(Roby::Models::TaskServiceModel)
+                    raise ArgumentError, "#{type} is neither a task model nor a task service model"
+                elsif type.kind_of?(Class) && !(type <= Roby::Task)
+                    raise ArgumentError, "#{type} is neither a task model nor a task service model"
+                end
+                @returned_type = type
+                self
+            end
+
+            def normalize_arguments(arguments)
+                Kernel.validate_options arguments, self.arguments.map(&:name)
+            end
+
+            def as_plan(**arguments)
+                plan_pattern(**arguments)
+            end
+
+            def pretty_print(pp)
+                pp.text "Action #{to_s}"
+                pp.nest(2) do
+                    pp.breakable
+                    pp.text "Returns "
+                    returned_type.pretty_print(pp)
+                    pp.breakable
+                    if arguments.empty?
+                        pp.text "No arguments."
+                    else
+                        pp.text "Arguments:"
+                        pp.nest(2) do
+                            pp.seplist(arguments.sort_by(&:name)) do |arg|
+                                arg.pretty_print(pp)
+                            end
+                        end
+                    end
+                end
+            end
+
+            def to_action_model
+                self
+            end
+
+            def to_action
+                new
+            end
+        end
+        end
+    end
+end
+

data/lib/roby/actions/models/coordination_action.rb

@@ -0,0 +1,58 @@
+module Roby
+    module Actions
+        module Models
+            # Action defined by a coordination model
+            class CoordinationAction < Action
+                # If this action is actually a coordination model, returns it
+                #
+                # @return [nil,Coordination::Models::Base]
+                attr_accessor :coordination_model
+
+                def initialize(coordination_model, doc = nil)
+                    super(doc)
+                    @coordination_model = coordination_model
+                end
+
+                # The underlying action interface model
+                def action_interface_model
+                    coordination_model.action_interface
+                end
+
+                def ==(other)
+                    other.kind_of?(self.class) &&
+                        other.coordination_model == coordination_model
+                end
+
+                # (see MethodAction#rebind)
+                def rebind(action_interface_model)
+                    rebound = dup
+                    if action_interface_model < self.action_interface_model
+                        rebound.coordination_model = coordination_model.
+                            rebind(action_interface_model)
+                    end
+                    rebound
+                end
+
+                def instanciate(plan, arguments = Hash.new)
+                    plan.add(root = coordination_model.task_model.new)
+                    coordination_model.new(root, arguments)
+                    root
+                end
+
+                # Returns the plan pattern that will deploy this action on the plan
+                def plan_pattern(arguments = Hash.new)
+                    job_id, arguments = Kernel.filter_options arguments, :job_id
+
+                    planner = Roby::Actions::Task.new(
+                        Hash[action_model: self,
+                             action_arguments: arguments].merge(job_id))
+                    planner.planning_result_task
+                end
+
+                def to_s
+                    "#{action_interface_model.name}.#{name}[#{coordination_model}]"
+                end
+            end
+        end
+    end
+end