NAME

Build::Hopen::G::DAG - A hopen build graph

SYNOPSIS

This class encapsulates the DAG for a particular set of one or more goals. It is itself a Build::Hopen::G::Op so that it can be composed into other DAGs.

VARIABLES

goals

Arrayref of the goals for this DAG.

default_goal

The default goal for this DAG.

_graph

The actual graph. Provided so you can use it if you want. However, if you find that you do have to use it, please open an issue so we can see about providing a documented API for your use case!

_final

The node to which all goals are connected.

FUNCTIONS

run

Traverses the graph. The DAG is similar to a subroutine in this respect. The outputs from all the goals of the DAG are aggregated and provided as the outputs of the DAG. The output is a hash keyed by the name of each goal, with each goal's outputs as the values under that name. Usage:

    my $hrOutputs = $dag->run($scope)

goal

Creates a goal of the DAG. Goals are names for sequences of operations, akin to top-level Makefile targets. Usage:

    my $goalOp = $dag->goal('name')

Returns a passthrough operation representing the goal. Any inputs passed into that operation are provided as outputs of the DAG under the corresponding name.

     TODO integrate
     A C<hopen> file with no C<main:goal()> calls will result in nothing
     happening when C<hopen> is run.

The first call to goal() also sets "default_goal".

connect

   - C<DAG:connect(<op1>, <out-edge>, <in-edge>, <op2>)>:
     connects output C<< out-edge >> of operation C<< op1 >> as input C<< in-edge >> of
     operation C<< op2 >>.  No processing is done between output and input.
     - C<< out-edge >> and C<< in-edge >> can be anything usable as a table index,
       provided that table index appears in the corresponding operation's
       descriptor.
   - C<DAG:connect(<op1>, <op2>)>: creates a dependency edge from C<< op1 >> to
     C<< op2 >>, indicating that C<< op1 >> must be run before C<< op2 >>.
     Does not transfer any data from C<< op1 >> to C<< op2 >>.
   - C<DAG:connect(<op1>, <Link>, <op2>)>: Connects C<< op1 >> to
     C<< op2 >> via L<Build::Hopen::G::Link> C<< Link >>.

Returns the name of the edge? The edge instance itself? Maybe a fluent interface to the DAG for chaining connect calls?

BUILD

Initialize the instance.

IMPLEMENTATION

Each DAG has a hidden "root" node. All outputs have edges from the root node. The traversal order is reverse topological from the root node, but is not constrained beyond that. Generators can ask for the nodes in root-first or root-last order.

The DAG is built backwards from the outputs toward the inputs, although calls to "output" and "connect" can appear in any order in the hopen file as long as everything is hooked in by the end of the file.

The following is in flux:

 - C<DAG>: A class representing a DAG.  An instance called C<main> represents
   what will be generated.

   - C<DAG:set_default(<goal>)>: make C<< goal >> the default goal of this DAG
     (default target).
   - C<DAG:inject(<op1>,<op2>[, after/before'])>: Returns an operation that
     lives on the edge between C<op1> and C<op2>.  If the third parameter is
     false, C<'before'>, or omitted, the new operation will be the first
     operation on that edge.  If the third parameter is true or C<'after'>,
     the new operation will be the last operation on that edge.  Any number
     of operations can be injected on any edge.

cpanm Build::Hopen

perl -MCPAN -e shell
install Build::Hopen