Module: Orocos::Scripts

Defined in:
lib/orocos/scripts.rb

Overview

Common command-line option handling for Ruby scripts

Its main functionality is to allow the override of run configuration with command line options, such as running under gdb or valgrind

The following command-line options are implemented:

–host=HOSTNAME sets the hostname and IP of the CORBA name server to

connect to

–attach do not start deployment processes given to Scripts.run if it

appears that they are already running

–conf-dir=DIR loads the given configuration directory

–conf=TASKNAME,conf0,conf1 apply the configuration [conf0, conf1]

to the task whose name or model name is TASKNAME. This option is handled
when {Scripts.conf} is called. If TASKNAME is omitted, the configuration
becomes the default for all tasks.

–gdbserver make Scripts.run start everything under gdb

–valgrind make Scripts.run start everything under valgrind

Examples:

require 'orocos'
require 'orocos/scripts'
options = OptionParser.new do |opt|
    opt.banner = "myscript [options]"
    Orocos::Scripts.common_optparse_setup(opt)
end
arguments = options.parse(ARGV)
...
Orocos::Scripts.run 'my::Task' => 'task' do
    task = Orocos.get 'task'

    # Replaces Orocos.apply_conf, taking into account the command
    # line options
    Orocos::Scripts.conf(task)

    Orocos::Scripts.watch(task)
end

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.conf_default ⇒ Object (readonly)

Returns the value of attribute conf_default



144
145
146
 
# File 'lib/orocos/scripts.rb', line 144

def conf_default
  @conf_default
end

.conf_setup ⇒ Object (readonly)

The configuration specifications stored so far, as a mapping from a task descriptor (either a task name or a task model name) to a list of configurations to apply.

The task name takes precedence on the model



143
144
145
 
# File 'lib/orocos/scripts.rb', line 143

def conf_setup
  @conf_setup
end

.run_options ⇒ Object (readonly)

Options that should be passed to Orocos.run



146
147
148
 
# File 'lib/orocos/scripts.rb', line 146

def run_options
  @run_options
end

Class Method Details

.common_optparse_setup(optparse) ⇒ Object 



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/orocos/scripts.rb', line 152

def self.common_optparse_setup(optparse)
    @attach = false
    @gui = false
    @run_options = Hash.new
    optparse.on('--host=HOSTNAME', String) do |hostname|
        Orocos::CORBA.name_service = hostname.to_str
    end
    optparse.on('--gui', "start vizkit's task inspector instead of having a text state monitoring") do
        @gui = true
    end
    optparse.on('--attach', "do not actually start the components, simply attach to running ones") do
        @attach = true
    end
    optparse.on('--conf-dir=DIR', String, "load the configuration files in this directory (not needed when using bundles)") do |conf_source|
        Orocos.conf.load_dir(conf_source)
    end
    optparse.on('--conf=TASK[:FILE],conf0,conf1', String, "load this specific configuration for the given task. The task is given by its deployed name") do |conf_setup|
        task, *conf_sections = conf_setup.split(',')
        task, *file = task.split(':')
        if !file.empty?
            task = "#{task}:#{file[0..-2].join(":")}"
            file = file.pop

            if !File.file?(file)
                raise ArgumentError, "no such file #{file}"
            end
        else file = nil
        end
        if conf_sections.empty?
            conf_sections = ['default']
        end
        if !task
            @conf_default = conf_sections
        else
            @conf_setup[task] = [file, conf_sections]
        end
    end
    optparse.on '--gdbserver', 'start the component(s) with gdb' do
        run_options[:gdb] = true
    end
    optparse.on '--valgrind', 'start the component(s) with gdb' do
        run_options[:valgrind] = true
    end
    optparse.on '--help', 'show this help message' do
        puts optparse
        exit 0
    end
end

.conf(task) ⇒ Object 



201
202
203
204
205
206
207
208
209
210
 
# File 'lib/orocos/scripts.rb', line 201

def self.conf(task)
    file, sections = conf_setup[task.name] || conf_setup[task.model.name]
    sections ||= conf_default

    if file
        Orocos.apply_conf(task, file, sections, true)
    else
        Orocos.conf.apply(task, sections, true)
    end
end

.parse_stream_option(opt, type_name = nil) ⇒ Object 



212
213
214
215
216
217
218
219
220
221
 
# File 'lib/orocos/scripts.rb', line 212

def self.parse_stream_option(opt, type_name = nil)
    logfile, stream_name = opt.split(':')
    if !stream_name && type_name
        Pocolog::Logfiles.open(logfile).stream_from_type(type_name)
    elsif !stream_name
        raise ArgumentError, "no stream name, and no type given"
    else
        Pocolog::Logfiles.open(logfile).stream(stream_name)
    end
end

.run(*options, &block) ⇒ Object 



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/orocos/scripts.rb', line 223

def self.run(*options, &block)
    deployments, models = Orocos::Process.partition_run_options(*options)

    if attach?
        deployments.delete_if do |depl, _|
            Process.new(depl).task_names.any? do |task_name|
                TaskContext.reachable?(task_name) # assume the deployment is started
            end
        end
        models.delete_if do |model, task_name|
            TaskContext.reachable?(task_name) # assume the deployment is started
        end
    end

    if deployments.empty? && models.empty?
        yield
    else
        Orocos.run(deployments.merge(models).merge(run_options), &block)
    end
end

.watch(*objects, &block) ⇒ Object

Watch for a set of tasks, ports or port readers and display information about them during execution

This method will display:

  • the current state of all the listed tasks. This display is updated only when the state of one of the tasks changed

  • whether new data arrived on one of the ports. By default, the new samples are pretty-printed. This can be changed by setting the :display option to false

The update period can be changed with the :sleep option. It defaults to 0.1. Note that all state changes are displayed regardless of the period chosen.

If a task is given to the :main option, the loop will automatically quit if that task has finished execution.

If a block is given, it is called at each loop with the set of tasks whose state changed and the set of ports which got new data (either or both can be empty). This block should return true if the loop should quit and false otherwise.

Parameters:

  • [Array<Port,TaskContext,Hash>] (Hash) —

    a customizable set of options



273
274
275
276
 
# File 'lib/orocos/scripts.rb', line 273

def self.watch(*objects, &block)
    # TODO: move the code here and truly deprecate Orocos.watch
    Orocos.watch(*objects, &block)
end