Class: Roby::Actions::Models::Action

Inherits:
Object
  • Object
show all
Includes:
DRoby::V5::Actions::Models::ActionDumper
Defined in:
lib/roby/actions/models/action.rb,
lib/roby/droby/enable.rb

Overview

Basic description of an action

Defined Under Namespace

Classes: Argument

Constant Summary collapse

VoidClass = 
Roby::VoidClass
Void = 
Roby::Void

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from DRoby::V5::Actions::Models::ActionDumper

#droby_dump, #droby_dump!, #proxy, #proxy!

Constructor Details

#initialize(doc = nil) ⇒ Action

Returns a new instance of Action.



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/roby/actions/models/action.rb', line 78

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

Instance Attribute Details

#arguments ⇒ Array<Argument> (readonly)

The description of the action arguments

Returns:



38
39
40
 
# File 'lib/roby/actions/models/action.rb', line 38

def arguments
  @arguments
end

#doc ⇒ Object

The action description



34
35
36
 
# File 'lib/roby/actions/models/action.rb', line 34

def doc
  @doc
end

#name ⇒ Object

The action name



32
33
34
 
# File 'lib/roby/actions/models/action.rb', line 32

def name
  @name
end

#returned_type ⇒ Model<Roby::Task>, Model<Roby::TaskService> (readonly)

The return type for this method, as a task or task service model. It is Roby::Task by default

Returns:



48
49
50
 
# File 'lib/roby/actions/models/action.rb', line 48

def returned_type
  @returned_type
end

Instance Method Details

#==(other) ⇒ Object 



56
57
58
59
60
61
 
# File 'lib/roby/actions/models/action.rb', line 56

def ==(other)
    other.kind_of?(self.class) &&
        other.name == name &&
        other.arguments == arguments &&
        other.returned_type == returned_type
end

#advanced ⇒ Object

Sets the advanced flag to true. See #advanced?



184
185
186
187
 
# File 'lib/roby/actions/models/action.rb', line 184

def advanced
    @advanced = true
    self
end

#as_plan(**arguments) ⇒ Object 



208
209
210
 
# File 'lib/roby/actions/models/action.rb', line 208

def as_plan(**arguments)
    plan_pattern(**arguments)
end

#each_arg {|arg| ... } ⇒ Object

Enumerate this action’s arguments

Yield Parameters:



179
180
181
 
# File 'lib/roby/actions/models/action.rb', line 179

def each_arg(&block)
    arguments.each(&block)
end

#find_arg(name) ⇒ Argument?

Find the argument from its name

Parameters:

  • name (String) —

    the argument name

Returns:



171
172
173
174
 
# File 'lib/roby/actions/models/action.rb', line 171

def find_arg(name)
    name = name.to_s
    arguments.find { |arg| arg.name == name }
end

#has_arg?(name) ⇒ Boolean

Return true if a argument with the given name is specified

Returns:

  • (Boolean) 


163
164
165
 
# File 'lib/roby/actions/models/action.rb', line 163

def has_arg?(name)
    find_arg(name)
end

#has_required_arg? ⇒ Boolean

Return true if this action has at least one required argument

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/roby/actions/models/action.rb', line 158

def has_required_arg?
    arguments.any?(&:required?)
end

#initialize_copy(old) ⇒ Object 



94
95
96
97
 
# File 'lib/roby/actions/models/action.rb', line 94

def initialize_copy(old)
    super
    @arguments = arguments.map(&:dup)
end

#new(**arguments) ⇒ Action

Returns an action using this action model and the given arguments.

Returns:

  • (Action) —

    an action using this action model and the given arguments



52
53
54
 
# File 'lib/roby/actions/models/action.rb', line 52

def new(**arguments)
    Actions::Action.new(self, **normalize_arguments(arguments))
end

#normalize_arguments(arguments) ⇒ Object 



204
205
206
 
# File 'lib/roby/actions/models/action.rb', line 204

def normalize_arguments(arguments)
    Kernel.validate_options arguments, self.arguments.map(&:name)
end

#optional_arg(name, doc = nil, default = nil) ⇒ Object

Documents a new optional argument to the method



148
149
150
151
152
153
154
155
 
# File 'lib/roby/actions/models/action.rb', line 148

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
    arg.example = Void
    arguments << arg
    self
end

#overloads(parent) ⇒ Object

Update this action model with information from another, to reflect that self overloads the other model

Parameters:

  • parent (Action) —

    the action model that is being overloaded

Raises:

  • (ArgumentError) —

    if the actions return types are not compatible



132
133
134
135
136
137
 
# File 'lib/roby/actions/models/action.rb', line 132

def overloads(parent)
    validate_can_overload(parent)

    self.doc ||= parent.doc
    @arguments.concat(parent.arguments.find_all { |a| !has_arg?(a.name) })
end

#pretty_print(pp) ⇒ Object 



212
213
214
215
216
217
218
219
220
221
 
# File 'lib/roby/actions/models/action.rb', line 212

def pretty_print(pp)
    pp.text "Action #{self}"
    pp.nest(2) do
        pp.breakable
        pp.text "Returns "
        returned_type.pretty_print(pp)
        pp.breakable
        pretty_print_arguments(pp)
    end
end

#pretty_print_arguments(pp) ⇒ Object 



223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/roby/actions/models/action.rb', line 223

def pretty_print_arguments(pp)
    if arguments.empty?
        pp.text "No arguments."
    else
        pp.text "Arguments:"
        pp.nest(2) do
            arguments.sort_by(&:name).each do |arg|
                pp.breakable
                arg.pretty_print(pp)
            end
        end
    end
end

#required_arg(name, doc = nil, example: Void) ⇒ Object

Documents a new required argument to the method



140
141
142
143
144
145
 
# File 'lib/roby/actions/models/action.rb', line 140

def required_arg(name, doc = nil, example: Void)
    arg = Argument.new(name.to_s, doc, true)
    arg.example = example
    arguments << arg
    self
end

#returned_task_type ⇒ Object

Task model that can be used to represent this action in a plan



64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/roby/actions/models/action.rb', line 64

def returned_task_type
    return @returned_task_type if @returned_task_type

    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

#returns(type) ⇒ Object

Sets the type of task returned by the action



190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/roby/actions/models/action.rb', line 190

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

#to_action ⇒ Object 



241
242
243
 
# File 'lib/roby/actions/models/action.rb', line 241

def to_action
    new
end

#to_action_model ⇒ Object 



237
238
239
 
# File 'lib/roby/actions/models/action.rb', line 237

def to_action_model
    self
end

#validate_can_overload(parent) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Validates that the information provided in the argument can safely be used to update self

Raises:

  • (ArgumentError) 


105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/roby/actions/models/action.rb', line 105

def validate_can_overload(parent)
    overloaded_return  = parent.returned_type
    overloading_return = returned_type

    return 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