Zonemaster::CLI::TestCaseSet(3pm)

NAME
    Zonemaster::CLI::TestCaseSet - Manage and modify Zonemaster test case selections

SYNOPSIS
    use Zonemaster::CLI::TestCaseSet;

    # Define the names of the available test modules and their test cases
    my $schema = {
        alpha => [qw( alpha01 alpha02 alpha03 )],
        beta  => [qw( beta01 beta02 )],
    };

    # Construct an initial selection of test cases
    my $selection = Zonemaster::CLI::TestCaseSet->new(
        [qw( alpha01 alpha02 alpha03 beta01 )],
        $schema,
    );

    # Parse and apply a modifier expression
    my @modifiers = Zonemaster::CLI::TestCaseSet->parse_modifier_expr( '-alpha+alpha02' );
    while ( @modifiers ) {
        my ( $op, $term ) = splice @modifiers, 0, 2;
        $selection->apply_modifier( $op, $term )
          or die "Error: Unrecognized term '$term'.\n";
    }

    # Output final test case selection
    print join( ' ', $selection->to_list );    # alpha02 beta01

DESCRIPTION
Zonemaster::CLI::TestCaseSet represents a mutable selection of test cases, together with an immutable schema defining available test modules and their associated test cases.

The schema is defined as a mapping of test module names to their associated test case names.

The selection can be adjusted using modifier expressions.

  MODIFIER EXPRESSIONS
A modifier expression describes a change to the current selection. Expressions combine terms using operators, e.g., '-alpha+alpha02'.

These operators are supported:

'+' (union)
    Add test cases to the current selection. The set of test cases to add is the expansion of $term.

'-' (difference)
    Remove test cases from the current selection. The set of test cases to remove is the expansion of $term.

'' (replace)
    Replace the current selection. The new selection is the set of test cases expanded from $term.

Terms expand into sets of test cases in one of three ways:

"all"
    Expands to all available test cases defined by the schema.

Test module name
    Expands to all test cases associated with the test module.

Test case name
    Expands directly to the specified test case itself. Test cases may be specified plainly (e.g., "Case10") or fully qualified (module/testcase, e.g., "Case/Case10").

Term matching is case-insensitive.

CONSTRUCTORS

  new( $selection, $schema )
Construct a new TestCaseSet object.

$selection (arrayref)
    Initial selection of test case names.

$schema (hashref)
    A hash mapping test module names to arrays of their associated test case names.

Dies if: - Any test case name in $schema is repeated. - $selection contains names not found in $schema.

CLASS METHODS
parse_modifier_expr( $modifier_expr )

Parse a string containing a modifier expression and returns a list of alternating operators and terms.

The returned list always starts with an operator.

For example, parsing '-alpha+beta02' returns:

    ('-', 'alpha', '+', 'beta02')

INSTANCE METHODS

  apply_modifier( $operator, $term )
Update the selection using the given operator and term.

Returns true if successful, or false if the term could not be expanded based on the schema.

Dies if the operator is invalid.

Example:

    $selection->apply_modifier('+', 'beta')
        or die "Unrecognized term";

  to_list
Return a lowercase list of the currently selected test case names.