This class implements the 'cursor' and the 'repeat' (loop) expressions.

The cursor expression is a kind of enhanced 'sequence'. Like a sequence it will execute its child expression one by one, sequentially. Unlike a sequence though, it will obey 'commands'.

cursor do
  author
  reviewer
  rewind :if => '${f:not_ok}'
  publisher
end

In this simplistic example, the process will flow from author to reviewer and back until the reviewer sets the workitem field 'not_ok' to something else than the value 'true'.

There are two ways to pass commands to a cursor either directly from the process definition with a cursor command expression, either via the workitem '__command__' [special] field.

cursor commands

The commands that a cursor understands are listed here. The most powerful ones are 'rewind' and 'jump'.

rewind

Rewinds the cursor up to its first child expression.

cursor do
  author
  reviewer
  rewind :if => '${f:not_ok}'
  publisher
end

stop, over & break

Exits the cursor.

cursor do
  author
  reviewer
  rewind :if => '${f:review} == fix'
  stop :if => '${f:review} == abort'
  publisher
end

'_break' or 'over' can be used instead of 'stop'.

skip & back

Those two commands jump forth and back respectively. By default, they skip 1 child, but they accept a numeric parameter holding the number of children to skip.

cursor do
  author
  reviewer
  rewind :if => '${f:review} == fix'
  skip 2 :if => '${f:review} == publish'
  reviewer2
  rewind :if => '${f:review} == fix'
  publisher
end

jump

Jump is probably the most powerful of the cursor commands. It allows to jump to a specified expression that is a direct child of the cursor.

cursor do
  author
  reviewer
  jump :to => 'author', :if => '${f:review} == fix'
  jump :to => 'publisher', :if => '${f:review} == publish'
  reviewer2
  jump :to => 'author', :if => '${f:review} == fix'
  publisher
end

Note that the :to accepts the name of an expression or the value of its :ref attribute or the value of its :tag attribute.

cursor do
  participant :ref => 'author'
  participant :ref => 'reviewer'
  jump :to => 'author', :if => '${f:review} == fix'
  participant :ref => 'publisher'
end

cursor command with :ref

It's OK to tag a cursor/repeat/loop with the :tag attribute and then point a command to it via :ref :

concurrence do

  cursor :tag => 'main' do
    author
    editor
    publisher
  end

  # meanwhile ...

  sequence do
    sponsor
    rewind :ref => 'main', :if => '${f:stop}'
  end
end

This :ref technique may also be used with nested cursor/loop/iterator constructs :

cursor :tag => 'main' do
  cursor do
    author
    editor
    rewind :if => '${f:not_ok}'
    _break :ref => 'main', :if => '${f:abort_everything}'
  end
  head_of_edition
  rewind :if => '${f:not_ok}'
  publisher
end

this example features two nested cursors. There is a "_break" in the inner cursor, but it will break the main 'cursor' (and thus break the whole review process).

:break_if / :rewind_if

As an attribute of the cursor/repeat expression, you can set a :break_if. It tells the cursor (loop) if it has to break.

cursor :break_if => '${f:completed}' do
  participant 'alpha'
  participant 'bravo'
  participant 'charly'
end

If alpha or bravo replies and the field 'completed' is set to true, this cursor will break.

:break_unless is accepted. :over_if and :over_unless are synonyms for :break_if and :break_unless respectively.

:rewind_if / :rewind_unless behave the same, but the cursor/loop, instead of breaking, is put back in its first step.

repeat (loop)

A 'cursor' expression exits implicitely as soon as its last child replies to it. a 'repeat' expression will apply (again) the first child after the last child replied. A 'break' cursor command might be necessary to exit the loop (or a cancel_process, but that exits the whole process instance).

sequence do
  repeat do
    author
    reviewer
    _break :if => '${f:review} == ok'
  end
  publisher
end