Getting started

To get started with pantr create a pantrfile.php at the top level of your application and add tasks to it.

A task in pantr is defined using PHP 5.3.0 syntax and and optional php doc comment. For example:

<?php
namespace pantr\file;

/**
 * Says hello to the user
 */
task('greet', function() {
	writeln('Hello my friend!');
});

To invoke your new task use the pantr command:

$ pantr greet
Hello my friend!

pantr can also handle task dependencies and tasks may have their own parameters and arguments. All of these options can be specified using annotations within the doc comment.
To improve the previous example:

<?php
namespace pantr\file;

use pantr\pantr;

/**
 * Says hello
 */
task('say-hello', function() {
	write('Hello ');
});

/**
 * Greets the user
 *
 * @usage greet [-i|--important] <name>
 * @option i:important If set the user name will be displayed in red.
 * @dependsOn say-hello
 */
task('greet', function($req) {
	if(isset($req['important'])) {
		writeln($req[0], pantr::WARNING);
	} else {
		writeln($req[0], pantr::COMMENT);
	}
});

Invoke it:

$ pantr greet Patrick
Hello Patrick

If your terminal supports it, “Patrick” will be displayed using a different color.
To invoke the version with argument:

$ pantr greet -i Patrick

pantr also includes a help system that can be invoked with the help command:

$ pantr help

The output of the help command on the sample project would be:

$ pantr help
pantr 0.8.1 (c) 2010 Patrick Gotthardt

Usage:
pantr [options] <task> [args]

Options:
-f --file                 The name of the pantrfile
-g --global               Execute a global command
   --ignore-failure       If specified, the task will be executed even if some or all of its dependencies fail

Available tasks:
               greet    Greets the user
                help    Display this help message
           say-hello    Says hello

Help
See pantr help <task>  for help with a specific task.

As you can see the content of your doc comment will be used to explain the tasks to the user. In case you’ve been wondering why the syntax for @option annotation looks so verbose and what the @usage annotation does, have a look at the more detailed output of the help task when a taskname has been specified:

$ pantr help greet
pantr DEV (c) 2010 Patrick Gotthardt

greet
Greets the user

Usage:
pantr greet [-i|--important] <name>

Options:
-i --important            If set the user name will be displayed in red.

Now it might be nice to prevent the user from seeing the “say-hello” task since that one does not work well when it is invoked directly. We can do this by adding the @hidden annotation:

/**
 * Says hello
 *
 * @hidden
 */
task('say-hello', function() {
	write('Hello ');
});

Now when we execute the help command, “say-hello” will not be displayed.

To get an overview of pantrs project creation tasks you can use help with the -g option:

$ pantr help -g