NAME

Data::Hopen::G::Runnable - parent class for runnable things in a hopen graph

SYNOPSIS

Anything with "run" inherits from this. TODO should this be a role?

ATTRIBUTES

need

(Not currently used) Inputs this Runnable requires. A Data::Hopen::Util::NameSet, with the restriction that need may not contain regexes. ("Sorry, I can't run unless you give me every variable in the world that starts with Q." I don't think so!) Or maybe later an arrayref? TODO.

scope

If defined, a Data::Hopen::Scope that will have the final say on the data used by "run". This is the basis of the fine-grained override mechanism in hopen.

want

(Not currently used) Inputs this Runnable accepts but does not require. A Data::Hopen::Util::NameSet, which may include regexes. Or maybe later an arrayref? TODO.

FUNCTIONS

run

Run the operation, whatever that means. Returns a new hashref. Usage:

    my $hrOutputs = $op->run([options])

Options are:

-context

A Data::Hopen::Scope or subclass including the inputs the caller wants to pass to the Runnable. The "scope" of the Runnable itself may override values in the context.

-phase

If given, the phase that is currently under way in a build-system run.

-visitor

If given, an instance that supports visit_goal() and visit_node() calls. A Data::Hopen::G::DAG instance invokes those calls after processing each goal or other node, respectively. They are invoked after the goal or node has run. They are, however, given access to the Data::Hopen::Scope that the node used for its inputs, in the $node_inputs parameter. Example:

    $visitor->visit_goal($goal, $node_inputs);

The return value from visit_goal() or visit_node() is ignored.

-nocontext

If -nocontext=>1 is specified, don't link a context scope into this one. May not be specified together with -context.

See the source for this function, which contains as an example of setting the scope.

_run

The internal method that implements "run". Must be implemented by subclasses. When _run is called, $self->scope has been hooked to the context scope, if any.

Parameters are -phase and -visitor, and are always passed by name (-phase=>$p, -visitor=>$v). _run is always called in scalar context, and must return a new hashref.

I recommend starting your _run function with:

    my ($self, %args) = getparameters('self', [qw(; phase visitor)], @_);

and working from there.

passthrough

Returns a new hashref of this Runnable's local values, as defined by "local" in Data::Hopen::Scope. Usage:

    my $hashref = $runnable->passthrough([-context => $outer_scope]);
        # To use $outer_scope as the context
    my $hashref = $runnable->passthrough(-nocontext => 1);
        # To ignore the context

Other valid options include -levels.