rose_ana§

This built-in application runs the rose-ana analysis engine.

rose-ana performs various configurable analysis steps. For example a common usage is to compare two files and report whether they differ or not. It can write the details of any comparisons it runs to a database in the suite’s log directory to assist with any automated updating of control data.

Invocation§

In automatic selection mode, this built-in application will be invoked automatically if a task has a name that starts with rose_ana*.

Analysis Modules§

The built-in application will search for suitable analysis modules to load firstly in the ana subdirectory of the rose-ana app, then in the ana subdirectory of the top-most suite directory. Any additional directories to search (for example a site-wide central directory) may be specified by setting the rose.conf[rose-ana]method-path variable. Finally the ana_builtins subdirectory of the Rose installation itself contains any built-in comparisons.

Configuration§

The application configuration should contain configuration sections which describe an analysis step. These sections must follow a particular format:

• the name must begin with ana:. This is required for rose-ana to recognise it as a valid section.
• the next part gives the name of the class within one of the analysis modules, including namespace information; for example to use the built-in FilePattern class from the grepper module you would provide the name grepper.FilePattern.
• finally an expression within parentheses which may contain any string; this should be used to make comparisons using the same class unique, but can otherwise simply act as a description or note.

The content within each of these sections consists of a series of key-value option pairs, just like other standard Rose apps. However the availability of options for a given section is specified and controlled by the class rather than the meta-data. This makes it easy to provide your own analysis modules without requiring changes to Rose itself.

Therefore you should consult the documentation or source code of the analysis module you wish to use for details of which options it supports. Additionally, some special treatment is applied to all options depending on what they contain:

Environment Variables

If the option contains any words prefixed by $ they will be substituted for the equivalent environment variable, if one is available.

Lists

If the option contains newlines it will be returned as a list of strings automatically.

Argument substitution

If the option contains one or more pairs of braces ({}) the option will be returned multiple times with the parentheses substituted once for each argument passed to rose task-run

The app may also define a configuration section, [ana:config], whose key-value pairs define app-wide settings that are passed through to the analysis classes. In the same way that the task options are dependent on the class definition, interpretation of the config options is done by the class(es), so their documentation or source code should be consulted for details.

Rose App rose_ana

Config [ana:config]

Config grepper-report-limit

Limits the number of lines printed when using the rose.apps.ana_builtin.grepper analysis class.

Config skip-if-all-files-missing

Causes the rose.apps.ana_builtin.grepper class to pass if all files to be compared are missing.

Config kgo-database

Turns on the Rose Ana Comparison Database.

Config [ana:ANALYSIS_CLASS]

Define a new analysis step. ANALYSIS_CLASS is the name of the analysis class e.g. grepper.FilePattern.

Config KEY= VALUE

Define an argument to ANALYSIS_CLASS.

Analysis Classes§

There is one built-in module of analysis classes called grepper.

class rose.apps.ana_builtin.grepper.FileCommandPattern(parent_app, task_options)

Check for occurrences of a particular expression or value in the standard output from a command applied to two or more files.

Options:

files (optional):

Same as previous tasks.

kgo_file:

Same as previous tasks.

pattern:

Same as previous tasks.

tolerance (optional):

Same as previous tasks.

command:

The command to run; it should contain a Python style format specifier to be expanded using the list of files above.

class rose.apps.ana_builtin.grepper.FilePattern(parent_app, task_options)

Check for occurrences of a particular expression or value within the contents of two or more files.

Options:

files (optional):

Same as previous tasks.

kgo_file:

Same as previous tasks.

pattern:

The regular expression to search for in the files. The expression should include one or more capture groups; each of these will be compared between the files any time the pattern occurs.

tolerance (optional):

By default the above comparisons will be compared exactly, but if this argument is specified they will be converted to float values and compared according to the given tolerance. If this tolerance ends in % it will be interpreted as a relative tolerance (otherwise absolute).

class rose.apps.ana_builtin.grepper.SingleCommandPattern(parent_app, task_options)

Run a single command and then pass/fail depending on the presence of a particular expression in that command’s standard output.

Options:

files (optional):

Same as previous task. command - same as previous task.

kgo_file:

Same as previous task.

pattern:

The regular expression to search for in the stdout from the command.

class rose.apps.ana_builtin.grepper.SingleCommandStatus(parent_app, task_options)

Run a shell command, passing or failing depending on the exit status of that command.

Options:

files (optional):

A newline-separated list of filenames which may appear in the command.

command:

The command to run; if it contains Python style format specifiers these will be expanded using the list of files above (if provided).

kgo_file:

If the list of files above was provided gives the (0-based) index of the file holding the “kgo” or “control” output for use with the comparisons database (if active).