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 metomi.rose.apps.ana_builtin.grepper analysis class.

Config skip-if-all-files-missing

Causes the metomi.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.

The following options can be specified in:

• rose.conf[rose-ana]

• rose_ana[ana:config]

Options

grepper-report-limit:

A numerical value giving the maximum number of informational output lines to print for each comparison. This is intended for cases where for example a pattern-matching comparison is expected to match many thousands of occurrences in the given files; it may not be desirable to print the results of every comparison. After the given number of lines are printed a special message indicating that the rest of the output is truncated will be produced.

skip-if-all-files-missing:

Can be set to .true. or .false.; if active, any comparison done on files by grepper will be skipped if all of those files are non-existent. In this case the task will return as “skipped” rather than passed/failed.

class metomi.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.

run_analysis()

Main analysis routine called from rose_ana.

search_for_matches()

Run the command on each file then search its output for the pattern; returning a dictionary whose keys are the file-names and whose values are lists of the groupings (one for each occurrence).

class metomi.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).

process_opt_tolerance()

Process the tolerance option; a value given either an absolute or relative tolerance which a numeric value must lie within.

run_analysis()

Main analysis routine called from rose_ana.

search_for_matches()

Search the contents of the files for the patterns; returning a dictionary whose keys are the file-names and whose values are lists of the groupings (one for each occurrence)

class metomi.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.

process_opt_pattern()

Process the pattern option; a regular expression which will be checked against the command output.

run_analysis()

Main analysis routine called from rose_ana.

run_command_and_check()

Run the command and check for the presence of the pattern in its standard output.

class metomi.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).

check_for_skip()

If the user’s config options specified that the task should be ignored if all of its files were missing, set skipped attribute here.

get_config_opts()

Process any configuration options.

process_opt_command()

Process the command option; this is the (shell) command that will be run for this task.

process_opt_files()

Process the files option; a list of one or more filenames.

process_opt_kgo()

Process the KGO option; an index indicating which file (if any) is the KGO (Known Good Output) - this may be needed later to assist in updating of test results.

read_file(filename)

Return the content of a given file as a list of lines.

run_analysis()

Main analysis routine called from rose_ana.

run_command(command)

Simple command runner; returns output error and return code.

run_command_and_check()

Run the command and return based on the output.

update_kgo()

Update the KGO database with the status of any files marked by the kgo_file option (i.e. whether they have passed/failed the test.