roby 0.8.0 → 3.0.0

data/lib/roby/cli/exceptions.rb

@@ -0,0 +1,17 @@
+module Roby
+    module CLI
+        # Base class for all exceptions that are considered the user's fault by
+        # the CLI
+        class CLIException < RuntimeError
+        end
+
+        # The user passed wrong arguments to a command
+        class CLIInvalidArguments < CLIException
+        end
+
+        # The CLI command failed
+        class CLICommandFailed < CLIException
+        end
+
+    end
+end

data/lib/roby/cli/gen/actions/class.rb

@@ -0,0 +1,5 @@
+<% indent, open_code, close_code = ::Roby::CLI::Gen.in_module(*class_name[0..-2]) %>
+<%= open_code %>
+<%= indent %>class <%= class_name.last %> < Roby::Actions::Interface
+<%= indent %>end
+<%= close_code %>

data/lib/roby/cli/gen/actions/test.rb

@@ -0,0 +1,6 @@
+require '<%= require_path %>'
+<% indent, open, close = ::Roby::CLI::Gen.in_module(*class_name[0..-2]) %>
+<%= open %>
+<%= indent %>describe <%= class_name.last %> do
+<%= indent %>end
+<%= close %>

data/lib/roby/cli/gen/app/.yardopts

@@ -0,0 +1,6 @@
+--plugin utilrb
+--plugin metaruby
+--plugin roby
+--plugin syskit
+--embed-mixins
+

data/lib/roby/cli/gen/app/README.md

@@ -0,0 +1,28 @@
+# App Folder Structure
+
+An app configuration can be split in so-called `robot` configurations. Robot
+configuration files are stored in `config/robots/`, and the list of files in that
+directory defines which robots are available in a given app. New robots can be generated with
+
+```
+roby gen myrobot
+```
+
+A basic Roby application has the following directories:
+
+config:: configuration files. config/init.rb is the main configuration file (loaded
+	by all robots). Robot-specific configuration is in config/robots/ROBOTNAME.rb.
+	The main Roby configuration file is config/roby.yml. The default file
+  describes all available configuration options.
+lib:: helper, non-Roby, code
+models:: where the models are defined. Models are segregated per type (tasks,
+  …) and robot (e.g. models/tasks/myrobot/* contains the task models for the
+  myrobot robot)
+scripts:: helper scripts
+test:: test files
+
+Use `roby gen` to create new models or robot configuration files. Running the
+command without further arguments shows which generators are available, and
+then adding `--help` provides detailed help for a given generator, e.g. `roby
+gen robot --help`
+

data/lib/roby/cli/gen/app/Rakefile

@@ -0,0 +1,15 @@
+require 'yard'
+require 'yard/rake/yardoc_task'
+require 'roby/app/rake'
+
+task :default
+
+Roby.app.load_base_config
+Roby::App::Rake::TestTask.new
+
+YARD::Rake::YardocTask.new do |yard|
+    yard.files = ['models/**/*.rb', 'lib/**/*.rb']
+end
+desc "Generate YARD documentation (alias for 'yard')"
+task :doc => :yard
+

data/{app → lib/roby/cli/gen/app}/config/app.yml

@@ -1,12 +1,15 @@
-# Control configuration
-engine:
-  # The length of a cycle (in seconds). It defaults to 100ms.
-  # cycle: 0.1
-
 # Logging configuration
 log:
-  # Where log files go
-  # dir: log/
+  # Where log files go. If relative, it is relative to the app's root dir,
+  # unless the environment variable ROBY_BASE_LOG_DIR is set in which case it is
+  # relative to this directory.
+  # dir: logs/
+  
+  # Whether backtraces should be filtered (i.e. call sites from the framework
+  # are hidden)
+  # The default is true
+  #
+  # filter_backtraces: false
   
   # Log system events. It can be either true, false or stats. If true, all
   # plan-level events are logged, allowing to use the roby-log GUI to replay
@@ -20,21 +23,7 @@ log:
   #
   # The default is stats
   #
-  # events: true
-  
-  # Set to false to disables the log server and true to enable it (it is enabled by
-  # default). The log server allows to display the controller state remotely by using the
-  # <tt>roby-log</tt> tool. Note that it is completely separated from the Roby remote
-  # shell, which is always enabled.
-  #
-  # server: false
-  #
-  # ... or configure it
-  # server:
-  #     # The port to listen on (for service discovery)
-  #     port: 48933
-  #     # The discovery period
-  #     period: 10
+  events: true
 
   # Logging levels.
   #
@@ -62,24 +51,25 @@ log:
   #
   # Log files are saved in the log directory (controlled by the 'dir' option above, it is
   # 'log' by default).
+  
+  # Set to false to disables the log server and true to enable it (it is enabled by
+  # default). The log server allows to display the controller state remotely by using the
+  # <tt>roby-log</tt> tool. Note that it is completely separated from the Roby remote
+  # shell, which is always enabled.
+  #
+  # server: false
+  #
+  # ... or configure it
+  # server:
+  #     # The port to listen on (for service discovery)
+  #     port: 48933
+  #     # The discovery period
+  #     period: 10
 
-# dRoby neighbour discovery
-discovery:
-  # The host:port at which we can connect to a discovery tuplespace
-  # (default: no discovery tuplespace)
-  # tuplespace: "localhost:29568"
-  # The port at which we do ring discovery (default: disabled)
-  # ring: 42865
-
-# dRoby host configuration
-droby:
-  # How many errors are allowed before disconnecting from a peer
-  # max_errors: 1
-  # The ring discovery period if we do ring discovery
-  # period: 0.5
-  # The hostname at the dRoby server must listen to. It is either
-  # 'host:port', or just ':port'
-  # host: ":48902"
+# Control configuration
+engine:
+  # The length of a cycle (in seconds). It defaults to 100ms.
+  # cycle: 0.1
 
 # Per-robot configuration. In these, you can override global options, or set
 # new options.

data/lib/roby/cli/gen/app/models/.gitattributes

@@ -0,0 +1 @@
+# Only to keep this directory in the git repository

data/lib/roby/cli/gen/class/class.rb

@@ -0,0 +1,6 @@
+<% indent, open_code, close_code = ::Roby::CLI::Gen.in_module(*class_name[0..-2]) %>
+<%= open_code %>
+<%= indent %>class <%= class_name.last %>
+<%= indent %>end
+<%= close_code %>
+

data/lib/roby/cli/gen/class/test.rb

@@ -0,0 +1,7 @@
+require '<%= require_path %>'
+<% indent, open, close = ::Roby::CLI::Gen.in_module(*class_name[0..-2]) %>
+<%= open %>
+<%= indent %>describe <%= class_name.last %> do
+<%= indent %>end
+<%= close %>
+

data/lib/roby/cli/gen/helpers.rb

@@ -0,0 +1,203 @@
+require 'roby/cli/exceptions'
+
+module Roby
+    module CLI
+        module Gen
+            # Helper methods for generator actions and templates
+            #
+            # The module is used to extend {Gen}. Its methods are usually
+            # accessed as singletong methods on {Gen}, e.g. {Gen.resolve_name}.
+            module Helpers
+                # Resolve a user-given model name into the corresponding file path
+                # and namespace path
+                #
+                # Both paths are returned relative to the given roots
+                #
+                # @raise InconsistenName if parts of the given name are inconsistent with the given
+                #   roots
+                #
+                # @example
+                #   resolve_names('models/actions/navigation.rb',
+                #                 ['models', 'actions'],
+                #                 ['Actions']) # => [['navigation.rb'], ['Navigation']]
+                #   resolve_names('models/tasks/navigation/goto.rb',
+                #                 ['models', 'tasks'],
+                #                 ['Tasks']) # => [['navigation/goto.rb'], ['Navigation', 'Goto']]
+                #   resolve_names('models/tasks/navigation/goto.rb',
+                #                 ['models', 'actions'],
+                #                 ['Actions']) # => raise, as models/actions must be the path root
+                def resolve_name(gen_type, given_name, robot_name, file_root, namespace_root)
+                    if given_name =~ /\// || given_name[0, 1] !~ /[A-Z]/
+                        resolve_name_as_path(gen_type, given_name, robot_name, file_root, namespace_root)
+                    else
+                        resolve_name_as_constant(gen_type, given_name, robot_name, file_root, namespace_root)
+                    end
+                end
+
+                # @api private
+                #
+                # Helper for {#resolve_name}
+                def resolve_name_as_path(gen_type, given_name, robot_name, file_root, namespace_root)
+                    robot_module =
+                        if robot_name
+                            [robot_name.camelcase(:upper)]
+                        else
+                            []
+                        end
+
+                    file_name = given_name.split('/')
+                    non_matching_prefix = file_root.each_with_index.find do |p, i|
+                        file_name[i] != p
+                    end
+                    if non_matching_prefix
+                        if non_matching_prefix[1] != 0
+                            raise CLIInvalidArguments, "attempted to create a #{gen_type} model outside of #{file_root.join("/")}"
+                        else
+                            file_name = file_root + file_name
+                        end
+                    end
+
+                    if robot_name && file_name[-2] != robot_name
+                        raise CLIInvalidArguments, "attempted to create a model for robot #{robot_name} outside a #{robot_name}/ subfolder"
+                    end
+
+                    file_name[-1] = File.basename(file_name[-1], '.rb')
+                    file_name_without_root = file_name[file_root.size..-1]
+
+                    app_module_name = Roby.app.module_name.split("::")
+                    class_without_app =
+                        namespace_root +
+                        file_name_without_root.map { |n| n.camelcase(:upper) }
+                    class_name = app_module_name + class_without_app
+                    return file_name_without_root, class_name
+                end
+
+                # @api private
+                #
+                # Helper for {#resolve_name}
+                def resolve_name_as_constant(gen_type, given_name, robot_name, file_root, namespace_root)
+                    robot_module =
+                        if robot_name
+                            [robot_name.camelcase(:upper)]
+                        else
+                            []
+                        end
+
+                    given_class_name = given_name.split("::")
+                    app_module_name = Roby.app.module_name.split("::")
+                    full_namespace_root = app_module_name + namespace_root
+
+                    non_matching_full_prefix = full_namespace_root.each_with_index.find do |p, i|
+                        given_class_name[i] != p
+                    end
+                    if non_matching_full_prefix
+                        if non_matching_full_prefix[1] != 0
+                            raise CLIInvalidArguments, "attempted to create a #{gen_type} model outside of its expected namespace #{full_namespace_root.join("::")}"
+                        else
+                            non_matching_app_prefix = namespace_root.each_with_index.find do |p, i|
+                                given_class_name[i] != p
+                            end
+                            if non_matching_app_prefix
+                                if non_matching_app_prefix[1] != 0
+                                    raise CLIInvalidArguments, "attempted to create a #{gen_type} model outside of its expected namespace #{full_namespace_root.join("::")}"
+                                else
+                                    given_class_name = full_namespace_root + given_class_name
+                                end
+                            else
+                                given_class_name = app_module_name + given_class_name
+                            end
+                        end
+                    end
+
+
+                    if robot_name && given_class_name[-2, 1] != robot_module
+                        raise CLIInvalidArguments, "attempted to create a model for robot #{robot_name} outside the expected namespace #{robot_module.join("::")} (e.g. #{given_class_name[0..-2].join("::")}::#{robot_module.join("::")}::#{given_class_name[-1]})"
+                    end
+
+                    file_name = *given_class_name[full_namespace_root.size..-1].map do |camel|
+                        pathize(camel)
+                    end
+                    return file_name, given_class_name
+                end
+
+                # @api private
+                #
+                # Helper class to render a template in a controlled context
+                class Context
+                    def initialize(vars)
+                        @vars = vars
+                    end
+
+                    def method_missing(m)
+                        @vars.fetch(m.to_s)
+                    end
+
+                    def context
+                        binding
+                    end
+                end
+
+                # @api private
+                #
+                # Generate a context that be given to the context: argument to
+                # Thor's template action
+                def make_context(vars)
+                    Context.new(vars).context
+                end
+
+                # Helper to handle opening and closing modules
+                #
+                # @return [(String,String,String)] the indentation string for the
+                #   module's content, the code necessary to open the module and the
+                #   code to close it
+                #
+                # @example usually used in e.g. ERB with
+                #   <% indent, open, close = Roby::App::GenBase.in_module("A", "Module") %>
+                #   <%= open %>
+                #   <%= indent %>class MyClass
+                #   <%= indent %>    it_does_something
+                #   <%= indent %>end
+                #   <%= close %>
+                #
+                def in_module(*module_path)
+                    indent = ""
+                    open_code  = []
+                    close_code = []
+                    module_path.each do |m|
+                        open_code.push "#{indent}module #{m}"
+                        close_code.unshift "#{indent}end"
+                        indent = indent + "    "
+                    end
+                    return indent, open_code.join("\n"), close_code.join("\n")
+                end
+
+                # Converts an input string that is in camelcase into a path string
+                #
+                # NOTE: Facets' String#pathize and String#snakecase have corner
+                # cases that really don't work for us:
+                #   '2D'.snakecase => '2_d'
+                #   'GPS'.pathize => 'gp_s'
+                #
+                def pathize(string)
+                    string.
+                        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+                        gsub(/([a-z])([A-Z][a-z])/,'\1_\2').
+                        gsub('__','/').
+                        gsub('::','/').
+                        gsub(/\s+/, '').                # spaces are bad form
+                        gsub(/[?%*:|"<>.]+/, '').   # reserved characters
+                        downcase
+                end
+
+                class Base
+                    def initialize(robot_name)
+                        @robot_name = robot_name
+                    end
+                end
+            end
+
+            extend Helpers
+        end
+    end
+end
+

data/lib/roby/cli/gen/module/module.rb

@@ -0,0 +1,5 @@
+<% indent, open_code, close_code = ::Roby::CLI::Gen.in_module(*module_name[0..-2]) %>
+<%= open_code %>
+<%= indent %>module <%= module_name.last %>
+<%= indent %>end
+<%= close_code %>

data/lib/roby/cli/gen/module/test.rb

@@ -0,0 +1,6 @@
+require '<%= require_path %>'
+<% indent, open, close = ::Roby::CLI::Gen.in_module(*module_name[0..-2]) %>
+<%= open %>
+<%= indent %>describe <%= module_name.last %> do
+<%= indent %>end
+<%= close %>

data/lib/roby/cli/gen/roby_app/config/init.rb

@@ -0,0 +1,17 @@
+# This file is called to do application-global configuration. For configuration
+# specific to a robot, edit config/NAME.rb, where NAME is the robot name.
+# 
+# Here are some of the most useful configuration options
+
+# Use backward-compatible naming and behaviour, when applicable
+#
+# For instance, a Syskit app will get the task context models defined at
+# toplevel as well as within the OroGen namespace
+Roby.app.backward_compatible_naming = false
+
+# Set the module's name. It is normally inferred from the app name, and the app
+# name is inferred from the base directory name (e.g. an app located in
+# bundles/flat_fish would have an app name of flat_fish and a module name of
+# FlatFish
+# 
+# Roby.app.module_name = 'Override'

data/lib/roby/cli/gen/roby_app/config/robots/robot.rb

@@ -0,0 +1,40 @@
+<% if robot_name != 'default' %>## A common pattern is to load the 'default' robot configuration
+require_relative './default'<% end %>
+
+## One can require the configuration from another robot, for instance if one has
+## a common robot class with minor modifications
+#
+# require 'config/robots/robot_class'
+
+# Block evaluated at the very beginning of the Roby app initialization
+Robot.init do
+    ## You could also change the Roby search path
+    # Roby.app.search_path << "separate path"
+end
+
+# Block evaluated to load the models this robot requires
+Robot.requires do
+end
+
+# Block evaluated to configure the system, that is set up values in Roby's Conf
+# and State
+Robot.config do
+end
+
+# Setup of the robot's main action interface
+#
+# Add use statements here, as e.g.
+#
+#   use <%= Roby.app.module_name %>::Actions::MyActionInterface
+#
+# or, if you're using syskit
+#
+#   use_profile <%= Roby.app.module_name %>::Profiles::BaseProfile
+#
+Robot.actions do
+end
+
+# Block evaluated when the Roby app is fully setup, and the robot ready to
+# start. This is where one usually adds permanent tasks and/or status lines
+Robot.controller do
+end