/ 
ExtUtils-Builder-0.015
River stage two • 2 direct dependents • 25 total dependents
/ ExtUtils::Builder::Planner

NAME

ExtUtils::Builder::Planner - An ExtUtils::Builder Plan builder

VERSION

version 0.015

SYNOPSIS

my $planner = ExtUtils::Builder::Planner->new;
$planner->create_node(
    target       => 'foo',
    dependencies => [ 'bar' ],
    actions      => \@actions,
);
my $plan = $planner->materialize;

DESCRIPTION

A Planner is an object that creates a Plan that can be executed.

The primary objective of this class is to gather a set of nodes (triplets of target, dependencies and actions), that represent building graph. To aid building this graph, this modules provides filesets to filter and transform filenames. Delegates can be mixed into the planner to aid in building these nodes and filesets. Extensions are a collection of such delegates.

METHODS

add_node($node)

This adds an ExtUtils::Builder::Node to the planner. It will also be added to the 'all-files' fileset if it's a file node.

create_node(%args)

This creates a new node and adds it to the planner using add_node. It takes the same named arguments as ExtUtils::Builder::Node.

  • target

    The target of the node. This is mandatory.

  • dependencies

    The list of dependencies for this node.

  • actions

    The actions to perform to create or update this node.

  • type

    This marks the type of the node: file or phony, defaulting to the former.

merge_plan($plan)

This merges all nodes of the plan to the planner.

add_delegate($name, $sub)

This adds $sub as a helper method to this planner, with the name $name.

create_phony($target, @dependencies)

This is a helper function that calls create_node for a action-free phony target.

create_filter(%options)

This will filter an existing fileset based on a condition, and return the name of the new fileset.

  • condition

    If this callback returns true the file will be included in the new filesets.

  • on

    this sets the input fileset, it defaults to c<'all-files'>.

  • name

    this sets the name of the new set, if none is given one will be generated.

create_pattern(%options)

This is a wrapper for add_filter for various common constructs. It takes several named options, at the moment at least one of file or dir is mandatory.

  • file

    A unix glob pattern that each filename is compared to, e.g. '*.pm'.

  • dir

    The directory under which files should be (e.g. 'lib').

  • negate

    This negates all the match.

  • on

    this sets the input fileset, it defaults to 'all-files'.

  • name

    this sets the name of the new set, if none is given one will be generated.

create_subst(%options)

This creates a new node based on the old one (source).

  • subst

    This callback is called for all entries in the input set. It should do two things:

    1. Return the name of the new target node.
    2. It should add a node to create the target from the source. The node should have source as its dependency.

  • on

    this sets the input fileset, it defaults to c<'all-files'>.

  • name

    this sets the name of the new set, if none is given one will be generated.

add_seen($filename)

This marks a file as existing on the filesystem by adding it to the 'all-files' fileset.

load_module($extension, $version, %options)

This adds the delegate from the given module. If $version is defined it will verify if the extension is at least that version.

new_scope()

This opens a new scope on the planner. It return a child planner that shared the build tree state with its parent, but any delegated added to it will not be added to the parent.

run_dsl($filename)

This runs $filename as a DSL file. This is a script file that includes Planner methods as functions. For example:

 use strict;
 use warnings;

 load_module("Foo");

 add_foo("a.foo", "a.bar");

 create_subst(
     on    => create_pattern(file => '*.src'),
     subst => sub {
	     my ($source) = @_;
		 my $target = $source =~ s/\.src$//r;
         return create_node(
             target       => $target,
             dependencies => [ $source ],
             actions      => [
                command('convert', $target, $source),
                function(module => 'Foo', function => 'bar'),
                code(code => 'print "Hello World"'),
             ],
         );
     },
 );

This will also add command, function and code helper functions that correspond to ExtUtils::Builder::Action::Command, ExtUtils::Builder::Action::Function and ExtUtils::Builder::Action::Code respectively.

materialize()

This returns a new ExtUtils::Builder::Plan object based on the planner.

AUTHOR

Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.