Zonema...aseSet(3pm)

✨ Zonemaster::CLI::TestCaseSet ✨

okay bestie, welcome to the Zonemaster::CLI::TestCaseSet page — it's a 3pm number from the User Contributed Perl Documentation crew, and it's literally all about managing and modifying your Zonemaster test case selections. yes, we're doing set math today. no, it's not that deep. let's go 🦋

---

🎀 NAME 🎀

Zonemaster::CLI::TestCaseSet — manage and modify Zonemaster test case selections. that's the whole job description, she's booked and busy 💅

---

🌸 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

like, look at her go. that last line spits out alpha02 beta01 and honestly? ate. 🔥

---

💜 DESCRIPTION 💜

Zonemaster::CLI::TestCaseSet is giving mutable selection of test cases energy — she can be changed, she can be shaped — paired up with an immutable schema that defines which test modules exist and which test cases belong to each one. the schema stays put. the selection does the moving. it's a whole dynamic, iykyk.

the schema is defined as a mapping of test module names to their associated test case names. that's it, that's the structure.

and the selection can be adjusted using modifier expressions, which is the fun part, so let's get into it 👑

---

🌈 MODIFIER EXPRESSIONS 🌈

a modifier expression is just, like, a description of a change you want to make to the current selection. you combine terms using operators — for example, -alpha+alpha02. cute, right? little string, big power.

these operators are supported:

• '+' (union) — add test cases to the current selection. the set of test cases to add is the expansion of $term. so, like, more stuff please ✨
• '-' (difference) — remove test cases from the current selection. the set of test cases to remove is the expansion of $term. bye girl, not you anymore 💀
• '' (replace) — replace the current selection. the new selection is the set of test cases expanded from $term. full glow-up, old selection who? never met her.

and here's the thing — terms expand into sets of test cases in one of three ways:

• "all" — expands to all available test cases defined by the schema. the entire roster, no crumbs left 🫶
• Test module name — expands to all test cases associated with that test module. one module, all her children.
• 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"). yes, both formats are valid, she's flexible like that 💁

term matching is case-insensitive. so don't stress about your shift key, bestie, she's not judging.

---

🧚 CONSTRUCTORS 🧚

new( $selection, $schema )

construct a brand new TestCaseSet object. fresh out the box, main character energy from day one 👑

• $selection (arrayref) — initial selection of test case names. your starting lineup ⭐
• $schema (hashref) — a hash mapping test module names to arrays of their associated test case names. the rulebook, the blueprint, the canon.

dies if: — any test case name in $schema is repeated. — $selection contains names not found in $schema.

ok so like, do not be sloppy with your schema. duplicate test case names? gone. a selection name that doesn't exist in the schema? also gone. she will literally end the program over it and honestly, fair. boundaries 💅

---

⭐ 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. no exceptions, no edge cases, that's just the format bestie.

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

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

see how it alternates? operator, term, operator, term. so satisfying. so tidy. we love a predictable data structure 🌸

---

👑 INSTANCE METHODS 👑

apply_modifier( $operator, $term )

update the selection using the given operator and term. this is the one doing the actual work, the girl behind the scenes.

• returns true if successful ✅
• returns 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";

see that or die? that's you catching the false. do not skip the or die, bestie, that's how you end up confused at 2am 😭

---

to_list

return a lowercase list of the currently selected test case names. lowercase. all of it. every time. she doesn't do caps, that's just her aesthetic 🎀

---

and that's the page!! every option, every operator, every "dies if", every return value — all of it, no crumbs left behind, periodt 🫶

this lil rewrite is based on the Perl v5.40.1 docs, dated 2025-12-23 — shoutout to the original Zonemaster::CLI::TestCaseSet(3pm) page from User Contributed Perl Documentation for the facts, and to you for reading all the way to the bottom. mwah 💖