NAME

Data::Hopen::Phases - Definitions and routines for hopen phases

SYNOPSIS

Definition of hopen phases. Phase names are case-insensitive. The canonical form has only the first letter capitalized.

Phase names may only contain ASCII letters, digits, or underscore. The first character of a phase may not be a digit. This is so they can be used as identifiers if necessary.

This package also defines a special export tag, :hopenfile, for use when running hopen files. The wrapper code in Data::Hopen::App uses this tag. Hopen files themselves do not need to use this tag.

The names first, start, last, and end are reserved.

VARIABLES

@PHASES

The phases we know about, in order.

FUNCTIONS

is_phase

Return truthy if the given argument is the name of a phase we know about.

is_last_phase

Return truthy if the argument is the name of the last phase. If no argument is given, checks the current phase ("$Phase" in App::hopen::BuildSystemGlobals).

phase_idx

Get the index of the phase given as a parameter. Returns undef if none. Phases are case-insensitive.

curr_phase_idx

Get the index of the current phase.

next_phase

Get the phase after the given on. Returns undef if the argument is the last phase. Dies if the argument is not a phase.

ROUTINES FOR USE IN HOPEN FILES

These are exported if the tag :hopenfile is given on the use line.

on

Take a given action only in a specified phase. Usage examples:

    on check => { foo => 42 };  # Just return the given hashref
    on gen => 1337;             # Returns { Gen => 1337 }
    on check => sub { return { foo => 1337 } };
        # Call the given sub and return its return value.

This is designed for use within a hopen file. See "_run_phase" in Data::Hopen::App for the execution environment on() is designed to run in.

When run as part of a hopen file, on() will skip the rest of the file if it runs. For example:

    say "Hello, world!";                # This always runs
    on check => { answer => $answer };  # This runs during the Check phase
    on gen => { done => true };         # This runs during the Gen phase
    say "Phase was neither Check nor Gen";  # Doesn't run in Check or Gen

TODO support on '!last' => ... or similar to take action when not in the given phase.