NAME

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

VERSION

       version 0.017

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_extension($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.

       "load_module" is a depreciated alias for this function.

   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_extension("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.

   self()
       This returns the planner.

   outer()
       This returns the planner matching the outer scope of the current planner object.

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.

perl v5.40.1                                       2025-04-12                    ExtUtils::Builder::Planner(3pm)