/ 
mpp-9
/ ActionParser

NAME

ActionParser - Makepp action parser base class

SYNOPSIS

perl_begin
 { package ActionParser::MyParser;
	our @ISA = qw/ActionParser/;
 }
 sub parser_myscan{
 	return new ActionParser::MyParser;
 };
perl_end

target: dependency : scanner myscan
	action

DESCRIPTION

ActionParser is a base class for makepp(1) action parsers. It is responsible for dealing with generic shell command parsing.

Ideally, rule options should indicate whether back-quotes should be expanded and/or parsed. Currently, they are neither.

THE SCANNER INTERFACE

When a scanner $parser is specified for a rule, first a subroutine named "parser_$parser" is sought. If it is found, then the parser object returned by that subroutine is used for the rule. Second, a subroutine named "scanner_$parser" is sought. If it is found, then a action parser that always uses that routine as the command parser is used. The second subroutine search is for legacy compatibility, and it is deprecated.

Note that this is implemented in the Makefile package, but we explain it here because you only need to know about it when you're messing with custom scanners.

METHODS

new

my $parser=new ActionParser;

Returns a new ActionParser object.

parse_rule

$parser->parse_rule($actions, $rule);

For each action in $actions, first deal with shell stuff, for example:

  1. Break the actions into commands (split on ;, &, &&, | and ||)

  2. Deal with I/O redirectors

  3. Determine which environment variables are set by each action [partially done]

  4. Expand and/or parse back-quoted expressions if $rule's options so indicate [TBD]

  5. For "cd" commands, determine the directory into which it changes [TBD]

For each remaining command, call parse_command().

$actions represents $rule's newline-separated actions, which are not derived from the rule itself so as to avoid duplicated expansion work.

Return value is TRUE on success.

parse_command

$parser->parse_command($command, $rule, $dir, $setenv_hash);

Parse $command as if it is executed in directory $dir (relative to $rule->build_cwd), and update $rule accordingly. $setenv_hash is the environmental settings that are set by the rule itself, with shell variables not expanded.

In this base class, calls find_command_parser to determine which command parser to use. If the result is FALSE, then do nothing more. (This can't happen for an object of the base class, since we always use a plain CommandParser.) Otherwise, the resulting object's parse_command method is called, and we return that method's return value.

Return value is TRUE on success, zero if no meaningful command parsing was performed, and undefined if a metadependency failed to build or if scanning failed.

find_command_parser

my $command_parser=$parser->find_command_parser(
  $command, $rule, $dir, \$found
);

The first word of $command is looked up in %scanners from the Makeppfile's namespace. If it isn't found, then undef is returned (after issuing a warning if it looks like the rule really ought to have a scanner). Otherwise, the resulting coderef is called with the command, rule and directory. If the return value is a reference to an object of type CommandParser, then it is returned. Otherwise, 0 is returned. Returning 0 is for backwards compatibility, and it might turn into an error in the future. There is no way to indicate a scanning failure if 0 is returned, for backward compatibility.

add_dependency

add_optional_dependency

add_simple_dependency

Like the corresponding methods in CommandParser, except that it's an ordinary function, and the parameter list is prepended with the command's directory name, directory FileInfo object, and Rule object.

add_target

Like the corresponding methods in CommandParser, except that it's an ordinary function, and the parameter list is prepended with the command's directory name and Rule object.

add_env_dependency

Like the corresponding methods in CommandParser, except that it's an ordinary function, and the parameter list is prepended with the Rule object.