The Qfsm User Manual

Binary packages for Windows and Linux are available on the Qfsm Sourceforge website. Other packages (e.g. for Mac OS X) can be found on third-party websites.

The installation of binary packages should be straightforward. On Linux, use RPM. On Windows, just click on the executable file and follow the instructions.

There are two ways of compiling the source code of Qfsm. The first one is to use the tool qmake included in the Qt library package and the provided project file qfsm.pro. See the qmake documentation for details. The second way is by using CMake.

On Linux/Unix platforms go to the console and type the following:

On Windows platforms there is also a graphical application called CMakeSetup where you just have to specify the input directory (i.e. the extracted Qfsm source directory) and output directory (i.e. where the compiled code will be put in). A project file of the specified development environment (e.g. MS Visual Studio) is created and you can then compile the code. Refer to the CMake documentation for more details.

In this mode, when clicking with the left mouse button on a state or a transition you select it. Holding down the shift key allows you to select several states or transitions at the same time. You can then apply further actions on selected items, i.e. copy or edit, by using the menu. Clicking on the background unselects all selected items.

When you click with the right mouse button on a state or a transition the context menu for it will be shown.

Double-clicking on a state or transition opens a dialog that lets you modify the state/transition properties.

Dragging the mouse pointer (holding the left mouse button) can have different effects. When you start dragging from the background you can select multiple items (those that are contained in the rectangle you drag). When you start dragging over a state you can move it around and when multiple objects are selected you can move them all at the same time. You can also drag transition control points. These are indicated by small red and green points when a transition is selected. The red points control the form of the transition, i.e. the bend. The green ones are used to attach them to a starting and end state.

When your diagram is larger than the working area of the window you can move the view to a different part of your diagram by dragging the mouse pointer.

In this mode you can zoom in the view by clicking with the left mouse button on the working area. You can zoom out by keeping the CTRL key pressed at the same time you click.

Clicking the left mouse button in the "add state" mode will add a new state at the position that was clicked. A dialog where you can specify the properties of the new state will be opend beforehand. See Section 4, “Adding and modifying states” for details.

Dragging the mouse pointer in the "add transition" mode will add a new transition from the state where you pressed the left mouse button to the state where you relesed it. A dialog where you can specify the properties of the new transition will be opend beforehand. See Section 5, “Adding and modifying transitions” for details.

In the simulate mode you can test the behaviour of your state machine with respect to external input. When entering this state the simulator dialog will appear and all interaction with the state diagram is disabled until you close the dialog. See Section 8, “Simulating a FSM” for details.

This is the most simple form of condition. It contains one ASCII character, e.g. 'a' or 'z'.

Note that for special characters, e.g. '-' (minus sign) or the space character you need to use an escape sequence (see Section 6.3, “Escape sequences”).

If you want the condition to contain multiple characters, i.e. 'a' or 'f' or '+' you just enter the string: 'af+'. Clearly, the order is not important.

Note that it is not possible to use a concatenation of characters as input condition, for example 'print' in order to recognize the word "print". To do this, you have to create a transition and a state for each character and build a chain with the respective characters.

Special characters like the newline character need to be escaped, i.e. backslash + some character. The following table shows the recognized escape sequences.

Note that the last escape sequence '\d' actually represents 10 characters.

Characters that are neither printable nor in the above table can be specified by '\0' (backslash zero) followed by their hexadecimal code. For example, '\0CF' would represent the ASCII character 207 (decimal).

You can further specify ranges by using the minus sign. Thus, 'a-z' means one of the characters between 'a' and 'z' (including). Any character, even escaped ones, can be used as start or end point of a range.

Finally, you can combine several conditions, each of them in one of the above mentioned notations, into one long condition by just concatenating them. Note that you must not separate them by any character, like white space or comma.

Here are some examples:

State tables can be exported in the formats: ASCII (plain text), Latex or HTML. State tables show for each possible state and input (here called event) the respective resulting states.

A dialog will allow you to change some options concerning the layout of the state table.

For this type of output there is only one type, namely the ragel file format, and only ASCII FSMs can be exported. The resulting file serves as an input for the ragel state machine compiler. The ragel state machine compiler is a compiler that generates code from a high-level state machine description language. In this way, you can create parsers, for example. For details refer to the ragel homepage.

A dialog allows you to create a so-called action file. That means, the ragel state machine specification is divided into two files. One that contains the state machine logic (which I will call FSM file here) and an action file that contains the action definitions and a framework calling the state machine. Thus, the action file actually includes the FSM file. The name of the action file is determined automatically by appending '_action' at the end of the file name.

Example: suppose you have created an ASCII FSM and you export it under the name myFSM.rl. If you check the option 'Create action file' the action file will be created under the name myFSM_actions.rl.

Using ragel you can compile the action file: ragel -C -o myFSM.c myFSM_actions.rl

This will create a file, called myFSM.c with the C code of the FSM. It will contain a function: int parse(char* string) that parses an input string and returns 1 if the FSM accepts it, i.e. finishes in a final state, and 0 otherwise.