roby 0.8.0 → 3.0.0

data/doc/guide/attic/plans/code.page

@@ -0,0 +1,192 @@
+---
+title: Executing code
+sort_info: 125
+---
+Roby allows you to mix model-based descriptions (the tasks, the plan, ...) with
+model-free code.
+
+The first forms an __explicit__ representation of the system's activity, on which other
+tools can reason. That's the interest: one can reason on it, and -- for instance
+-- detect problems before they actually appear, or provide information about the
+future to other systems, or ...
+
+The second allows to iron out the "gory details". While model-oriented
+development is all nice on the paper, real systems are usually not "sticking" to
+the model willingly. This aspect of Roby allows to adapt the model to the real
+thing.
+
+This page will cover how you can have some code executed at runtime, and in
+which conditions
+
+Event commands and event handlers
+---------------------------------
+These have already been described (see [here](tasks.html) and
+[there](events.html)).
+
+Executing an event command through a subtask (or subplan)
+---------------------------------------------------------
+It is, sometimes, desired that the command of an event is realized by a task
+itself, instead of simply using a code block.
+
+At execution time, this can be done with
+
+{coderay:: ruby}
+event.achieve_with(task)
+{coderay}
+
+The corresponding task will be started, and the event is going to be emitted as
+soon as the task's success event is emitted. The task can, obviously, be the
+root task of a complete Roby subplan.
+
+Polling handlers
+----------------
+Poll handlers are code blocks attached to tasks. These code blocks are executed
+__if the task is running__ at each of the system's execution cycle (by default,
+it means once every 100ms).
+
+A single polling block can be defined on task models:
+
+{coderay:: ruby}
+class MyTask < Roby::Task
+  poll do
+    # Code executed if any instance of class MyTask
+    # is running
+    #
+    # In here, +self+ refers to the task instance
+  end
+end
+{coderay}
+
+It can also be attached to a task instance with
+
+{coderay:: ruby}
+task = MyTask.new
+task.poll do
+  # Code executed if +task+ is running
+  # In here, +self+ refers to the caller object (i.e. the object that added the
+  # poll block). Use +task+ to refer to the task instance
+end
+{coderay}
+
+While there can be only one class-level polling block, there can be more than
+one instance-level polling blocks.
+
+State machines
+--------------
+Users can detail a Roby task using a state machine concept. The interface described in the following
+embeds the [state_machine gem](http://github.com/pluginaweek/state_machine). 
+When defining a Roby task the user can inject substates to the 'running' state. The initial state is 'running' by default.
+
+With each state a poll block can be associated. This block is repeatedly called, as long as the task remain in the corresponding state.
+{coderay:: ruby}
+class MyTask < Roby::Task
+    ..
+    refine_running_state do
+        state :running do
+            def poll(task)
+                # check for success condition and then
+                emit :success
+            end
+        end
+    
+        event :pause do 
+            transition [:running] => :paused
+        end
+    
+        event :resume do 
+            transition [:paused] => :running
+        end
+   
+        # In this simple example, 'pause' causes the task to sleep 4 second
+        # and then resumes
+        def :paused do
+            def poll(task)
+                sleep 4
+                task.emit :resume
+            end
+        end
+    end
+
+    on :pause do |ev|
+        # stop running actions
+    end
+    ....
+end
+{coderay}
+
+
+Events which are defined in the 'refine_running_state' are transparently converted to roby events. This allows you to apply the usual syntax to include event actions or to emit events. 
+{coderay:: ruby}
+on(:yourevent) do |ev|
+    # The event context will be a instance of StateMachine::Event
+end
+{coderay}
+
+
+Due to the current implementation you are required to call 'emit' on the task object within the poll block. 
+{: .warning}
+
+In order to define your statemachine behaviour you have to specify when to transition from one state to another (as a reaction to an event). These transitions should be specified in the event definition (alternatively in the event handler). See [state_machine documentation](https://github.com/pluginaweek/state_machine) for an detailed example on the syntax which can be used. A simple example is given in the following:
+
+{coderay:: ruby}
+event :repair do
+    # First transition which matches the current state applies
+    transition [:exception, :fatal] => :running
+    transition [:running] => :halted
+end
+
+event :halt do
+   transition all => :halted
+end
+{coderay}
+
+The current state of a task can be retrieved (as usual), however the list of states will be extended given the newly introduced substates of running:
+{coderay:: ruby}
+mytask = MyTask.new
+if mytask.current_state? == :paused
+    ...
+end
+{coderay}
+
+A statemachine transition will be only executed if it is a valid transition, otherwise an InvalidTransition error is raised.
+{: .note}
+
+
+
+
+Scripts
+-------
+Scripts offer a more script-like (i.e. step-by-step) representation of code
+blocks, in ways that can interact with other. For instance:
+
+{coderay:: ruby}
+task = MyTask.new
+task.script do
+  # Redirect log messages to the logger on Robot
+  setup_logger(Robot)
+  # Wait for the ready event of the task's localization child to
+  # be emitted. It returns immediately if the event has been
+  # emitted in the past
+  wait_any(localization_child.ready_event)
+  # Send a log message
+  info "localization ready, starting to move"
+  # Start the movement task
+  poll_until(movement_child.start_event) do
+    movement_child.start!
+  end
+  # Wait for the target position to be reached
+  poll do
+    if State.position.x > 10
+      transition! # exit from the poll loop
+    end
+  end
+  # Emit success
+  execute do
+    task.success!
+  end
+end
+{coderay}
+
+The commands available in scripts are detailed [in the API
+documentation](../../api/Roby/TaskScripting/Script)
+

data/doc/guide/{src/basics → attic/plans}/events.page

@@ -1,11 +1,10 @@
 ---
 title: Events
-sort_info: 100
---- name:content pipeline:tags,markdown,blocks
+sort_info: 75
+---
 
 This page will present the basic tools that allow to define and manipulate
-events. In {link: {path: /basics/plan_objects.html, attr:
-{:link_text: the overview of plan objects}}}, we saw that
+events. In , we saw that
 events are two sided objects: one the one hand, they represent the
 situations the system is in (event _emission_). On the other hand, they
 represent the commands that the system accepts (event _commands_).

data/doc/guide/attic/plans/index.page

@@ -0,0 +1,7 @@
+---
+title: Plans
+sort_info: 25
+---
+
+This section deals with describing what a Roby plan is, how it can be built,
+modified. The next section will deal with how it gets executed.

data/doc/guide/{plan_modifications.rdoc → attic/plans/plan_modifications.rdoc}

@@ -1,4 +1,7 @@
-= Plan representation and modifications to plans
+---
+title: Plan representation and modifications to plans
+sort_info: 200
+---
 
 Understanding the plan model, and how to modify it, is central to the use of
 Roby. In effect, the plan *is* the information on which the controller bases
@@ -45,12 +48,11 @@ Modifying the plan therefore boils down to two things:
    or between events).
 
 The first point is done by the following methods:
-* Roby::Plan#discover: simply add tasks and events
+* Roby::Plan#add: simply add tasks and events
 * Roby::Plan#add_mission: adds special tasks, called missions. Missions are the
   tasks the robot is supposed to execute. They are not subject to the plan's
   garbage collection, and the tasks that are useful to them are not either.
 
-
 To ease the plan management process, some synthetic
 operations are defined on Roby::Plan:
 * the _replacement_ operation: Roby::Plan#replace_task and

data/doc/guide/{src/basics → attic/plans}/plan_objects.page

@@ -1,7 +1,8 @@
 ---
 title: Overview of Plan Objects
 sort_info: 50
---- pipeline:tags,rdoc
+---
+
 There are two basic objects in Roby plans, both objects being equally important.
 * *events*. They are both the basic command interface and the way to follow what
   happens in and outside of the robot.

data/doc/guide/attic/plans/querying_plans.page

@@ -0,0 +1,5 @@
+---
+title: Querying Plans
+sort_info: 200
+---
+

data/doc/guide/{src/basics → attic/plans}/tasks.page

@@ -1,7 +1,7 @@
 ---
 title: Tasks
-sort_info: 200
---- pipeline:tags,markdown,blocks
+sort_info: 100
+---
 {include_file: {filename: src/basics_shell_header.txt, escape_html: false}}
 
 Definition of Tasks
@@ -57,15 +57,12 @@ instanciated_:
  => false
 {coderay}
 
-Of course, it is possible to set default arguments by defining a #initialize
-method (like with all Ruby classes)
+Arguments can have default values. In this case, the argument's value is set
+automatically when the task is started. The default argument can be nil.
+
 {coderay:: ruby}
  >> class MoveTo
- ?>   argument :max_speed
- ?>   def initialize(arguments)
- ?>     arguments[:max_speed] ||= 1
- ?>     super(arguments)
- ?>   end
+ ?>   argument :max_speed, :default => 1
  ?> end
  >> task = MoveTo.new(:x => 10, :y => 20)
  >> task.max_speed
@@ -100,26 +97,29 @@ my\_task.rb file.
         puts "start event called"
         emit :start
      end
-     event :controlable do
+     event :controlable do |ev|
         puts "controlable event called"
         emit :controlable
      end
      event :contingent
  
-     on(:start) { puts "start event emitted" }
-     on(:controlable) { puts "controlable event emitted" }
-     on(:contingent) { puts "contingent event emitted" }
-     on(:failed) { puts "failed event emitted" }
-     on(:stop) { puts "stop event emitted" }
-
-     event :finished, :terminal => true
-     on(:finished) { puts "finished event emitted" }
+     on(:start) { |ev| puts "start event emitted" }
+     on(:controlable) { |ev| puts "controlable event emitted" }
+     on(:contingent) { |ev| puts "contingent event emitted" }
+     on(:failed) { |ev| puts "failed event emitted" }
+     on(:stop) { |ev| puts "stop event emitted" }
+
+     event :finished
+     forward :finished => :success
+     on(:finished) { |ev| puts "finished event emitted" }
  end
 {coderay}
 
 Finally, an event can be *terminal*: its emission means the end of the task's
-execution. __failed__ and __success__ are examples of terminal events. To declare a
-terminal event, one does as for the "finished" event above.
+execution. __failed__ and __success__ are examples of terminal events. Events
+can be declared terminal explicitely by adding :terminal => true to the event
+declaration (see below) or by forwarding the event to another terminal event (as
+for :finished above).
 
 Now, read that code into the ruby shell with
 {coderay:: ruby}

data/doc/guide/config.yaml

@@ -15,13 +15,11 @@
 # The available configuration options can be listed using the `webgen config`
 # command, for example: `webgen config sourcehandler` will list all options starting
 # with sourcehandler.
-default_processing_pipeline:
-    Page: rdoc,tags,blocks
-
-
 default_meta_info:
     Webgen::SourceHandler::Page:
         in_menu: true
+        link:
+            css: /style_screen.css
 
 tag.menu.nested: false
 
@@ -32,3 +30,8 @@ rdoclinks.base_module: Roby
 
 tag.coderay.line_numbers: false
 tag.coderay.lang: ruby
+
+contentprocessor.kramdown.options:
+    :entity_output: :symbolic
+    :coderay_line_numbers: ~
+

data/doc/guide/ext/extended_menu.rb

@@ -0,0 +1,29 @@
+module Webgen::Tag
+    class Menu
+        alias __specific_menu_tree_for__ specific_menu_tree_for
+
+        def specific_menu_tree_for(content_node)
+            tree = __specific_menu_tree_for__(content_node)
+            return if !tree
+
+            tree.children.delete_if do |menu_info|
+                si = menu_info.node['sort_info']
+                next if !si
+
+                if param('tag.menu.range_start') && si < param('tag.menu.range_start')
+                    true
+                elsif param('tag.menu.range_end') && si > param('tag.menu.range_end')
+                    true
+                else
+                    false
+                end
+            end
+            tree
+        end
+    end
+end
+
+config = Webgen::WebsiteAccess.website.config
+config.tag.menu.range_start nil, mandatory: false
+config.tag.menu.range_end   nil, mandatory: false
+

data/doc/guide/ext/init.rb

@@ -8,7 +8,13 @@
 # The +config+ variable below can be used to access the Webgen::Configuration object for the current
 # website.
 config = Webgen::WebsiteAccess.website.config
+config['sourcehandler.patterns']['Webgen::SourceHandler::Copy'] << '**/autoproj_bootstrap'
+config['sourcehandler.patterns']['Webgen::SourceHandler::Copy'] << '**/manifest.xml'
+config['sourcehandler.patterns']['Webgen::SourceHandler::Copy'] << '**/*.svg'
+config['sourcehandler.patterns']['Webgen::SourceHandler::Copy'] << '**/*.pdf'
+config['sourcehandler.patterns']['Webgen::SourceHandler::Copy'] << '**/*.rb'
 
 $LOAD_PATH.unshift File.expand_path('..', File.dirname(__FILE__))
 require 'ext/rdoc_links'
 require 'ext/previous_next'
+require 'ext/extended_menu'

data/doc/guide/ext/rdoc_links.rb

@@ -19,15 +19,16 @@ def call(tag, body, context)
         path[-1] += ".html"
         url = "#{param('rdoclinks.base_url')}/#{path.join("/")}"
 
-        "<a href=\"#{context.ref_node.route_to(url)}\">#{param('rdoclinks.name')}</a>"
+        "<a href=\"#{context.ref_node.route_to(url)}\">#{param('rdoclinks.text') || param('rdoclinks.name')}</a>"
     end
 end
 
 config = Webgen::WebsiteAccess.website.config
-config.rdoclinks.name        "", :mandatory => 'default'
-config.rdoclinks.base_webgen "", :mandatory => false
-config.rdoclinks.base_url    "", :mandatory => false
-config.rdoclinks.base_module nil, :mandatory => false
-config.rdoclinks.full_name   false, :mandatory => false
+config.rdoclinks.name        "", mandatory: 'default'
+config.rdoclinks.base_webgen "", mandatory: false
+config.rdoclinks.base_url    "", mandatory: false
+config.rdoclinks.base_module nil, mandatory: false
+config.rdoclinks.full_name   false, mandatory: false
+config.rdoclinks.text   nil, mandatory: false
 config['contentprocessor.tags.map']['rdoc_class'] = 'RdocLinks'
 

data/doc/guide/src/advanced_concepts/history.page

@@ -0,0 +1,5 @@
+---
+title: Tracking History
+sort_info: 40
+draft: true
+---

data/doc/guide/src/advanced_concepts/index.page

@@ -0,0 +1,11 @@
+---
+title: Advanced Concepts
+sort_info: 0
+---
+This section will present some of the more advanced Roby concepts. It assumes
+that you have a good understanding of the basics of Roby, namely that you have
+read the [concepts](../concepts) section and followed the
+[tutorial](../tutorial).
+
+It is a bit a list of things, but some of them will refer to others for a better
+understanding. Have a look on the left menu for the different topics.

data/doc/guide/src/advanced_concepts/recognizing_patterns.page

@@ -0,0 +1,83 @@
+---
+title: Recognizing patterns in plans
+sort_info: 20
+---
+
+Plan Queries and Task Matchers {#plan-queries}
+-----------------------------
+Roby plan structure is semantically very rich: it allows to very finely
+represent the relationships that tasks and events have with each other. In
+principle, one could use __plan patterns__ to recognize situations or specific
+behaviours in a plan (and act upon it).
+
+Defining a pattern in the plan and testing for it is done by task matchers
+({rdoc_class: TaskMatcher}). Task matchers are objects that allow to test
+whether a certain task object match some criteria.  The task matchers are
+created by calling #match on the type of tasks that we want to match. For
+instance, to create a match object for running Localization tasks, one would do
+
+{coderay:: ruby}
+matcher = Localization.match.running
+{coderay}
+
+One can also match the task's surroundings
+
+{coderay:: ruby}
+matcher = MoveTo.match.with_child(Localization.match.running).pending
+{coderay}
+
+An extension of task matchers are plan queries. Plan queries are ways to
+enumerate all tasks, in a plan, that match a given task match object. The big
+difference with simply enumerating all tasks is that, for some of the match
+predicates, queries are O(1) instead of O(n), namely:
+
+ * task model
+ * task state (running, pending, finished)
+
+For instance, to match all running tasks that fullfill the MoveTo model:
+
+{coderay:: ruby}
+set = plan.find_tasks(MoveTo).
+  running
+set.each do |task|
+  pp task
+end
+{coderay}
+
+To match all tasks that fullfill the MoveTo model and have a pending (not yet
+running) child that fullfill the Localization model
+
+{coderay:: ruby}
+plan.find_tasks(MoveTo).
+  running.
+  with_child(Localization.match.pending)
+{coderay}
+
+Event Predicates {#event-predicates}
+----------------
+Event predicates (or, in full, unbounded event predicates) are a tool that
+allows to decide whether the history of a certain task matches a pattern or not.
+The event predicate being the representation of that pattern.
+
+They are created from symbols (which are the names of the events that should be
+matched). For instance:
+
+{coderay:: ruby}
+:start.followed_by(:blocked)
+{coderay}
+
+will return an instance of {rdoc_class: EventConstraints::UnboundTaskPredicate}
+or of one of its subclasses that can then be evaluated on a task. See
+{rdoc_class: EventConstraints::UnboundPredicateSupport} for the list of methods
+available on symbols and {rdoc_class: EventConstraints::UnboundTaskPredicate}
+for the predicate interface, which allows to logically combine predicates with
+each other.
+
+One very important aspects of these predicates is the ability to say whether the
+predicate may change its value in the future or not
+(UnboundTaskPredicate#static?). This is done through the notion of event
+unreachability. Moreover, the predicates can give an __explanation__ of why they
+have the value they have and/or why they won't change value anymore. This
+explanation is formed as a set of events, a set of non-emitted events (i.e.
+generators that should have emitted an event and did not) and a set of
+unreachable events.