NAME

Shell::Parser - Simple shell script parser

VERSION

Version 0.04

SYNOPSIS

    use Shell::Parser;

    my $parser = new Shell::Parser syntax => 'bash', handlers => {
        
    };
    $parser->parse(...);
    $parser->eof;

DESCRIPTION

This module implements a rudimentary shell script parser in Perl. It was primarily written as a backend for "Syntax::Highlight::Shell", in order to simplify the creation of the later.

METHODS

new(): Creates and returns a new "Shell::Parser" object. Options can be provided as key/value pairs.
Options

"handlers" - sets the parsing events handlers. See "handlers()" for more information.
"syntax" - selects the shell syntax. See "syntax()" for more information.

Examples

    my $parser = new Shell::Parser syntax => 'bash', 
        handlers => { default => \&default_handler };

parse()

Parse the shell code given in argument.

Examples

    $parser->parse(qq{echo "hello world"\n});
    $parser->parse(<<'SHELL');
        for pat; do 
            echo "greping for $pat"
            ps aux | grep $pat
        done
    SHELL

eof()

Tells the parser that there is no more data.

Note that this method is a no-op for now, but this may change in the future.

handlers()

Assign handlers to parsing events using a hash or a hashref. Available events:

"assign" - handler for assignments: "VARIABLE=VALUE"
"builtin" - handler for shell builtin commands: "alias", "jobs", "read"...
"command" - handler for external commands (not implemented)
"comment" - handler for comments: "# an impressive comment"
"keyword" - handler for shell reserved words: "for", "if", "case"...
"metachar" - handler for shell metacharacters: ";", "&", "|"...
"variable" - handler for variable expansion: $VARIABLE
"text" - handler for anything else

There is also a "default" handler, which will be used for any handler which has not been explicitely defined.

Examples

    # set the default event handler
    $parser->handlers(default => \&default_handler);
    
    # set the 'builtin' and 'keywords' events handlers
    $parser->handlers({ builtin => \&handle_internals, keywords => \&handle_internals });

See also "Handlers" for more information on how event handlers receive their data in argument.

syntax(): Selects the shell syntax. Use one of:

"bourne" - the standard Bourne shell
"csh" - the C shell
"tcsh" - the TENEX C shell
"korn88" - the Korn shell, 1988 version
"korn93" - the Korn shell 1993 version
"bash" - GNU Bourne Again SHell
"zsh" - the Z shell

Returns the current syntax when called with no argument, or the previous syntax when affecting a new one.

HANDLERS

During parsing, the functions defined as handlers for the corresponding events will be called with the following arguments:

a reference to the current "Shell::Parser" object
a hash with the following keys:

"token" - the actual shell token
"type" - the type of the token

Therefore, a typical handler function will begin with something like this:

    sub my_handler {
        my $self = shift;
        my %args = @_;
        
        # do stuff
        # ...
    }

EXAMPLE

Here is an example that shows how the tokens are given to the events handlers. It uses the script eg/parsedump.pl:

    #!/usr/bin/perl
    use strict;
    use Shell::Parser;
    
    my $parser = new Shell::Parser handlers => { default => \&dumpnode };
    $parser->parse(join '', <>);
    
    sub dumpnode {
        my $self = shift;
        my %args = @_;
        print "$args{type}: <$args{token}>\n"
    }

Running this Perl script with the following shell script in argument:

    #!/bin/sh
    if [ "$text" != "" ]; then grep "$text" file.txt; fi

will produce the following trace:

    comment: <#!/bin/sh>
    text: <
    >
    keyword: <if>
    text: < >
    text: <[>
    text: < >
    text: <"$text">
    text: < >
    assign: <!=>
    text: < >
    text: <"">
    text: < >
    text: <]>
    metachar: <;>
    text: < >
    keyword: <then>
    text: < >
    text: <grep>
    text: < >
    text: <"$text">
    text: < >
    text: <file.txt>
    metachar: <;>
    text: < >
    keyword: <fi>
    text: <
    >

DIAGNOSTICS

Can't deal with ref of any kind for now: (F) You gave a reference to "parse()", which is not handled at this time.
No such handler: %s: (E) You gave an unknown handler name. Please check "handlers()" for the available handlers.
Unknown syntax '%s': (E) You gave an unknown syntax. Please check "syntax()" for the available syntaxes.

CAVEATS

Running "Shell::Parser" with the "-W" flag gives many warnings, but most come from "Text::ParseWords".
Comments curently contains the newline character that terminate them. This is not very intuituive and will be corrected in later versions.
The "command" event is currently unimplemented.
Here-documents are currently not parsed.

AUTHOR

SEeacute>bastien Aperghis-Tramoni, <sebastien@aperghis.net>

BUGS

Please report any bugs or feature requests to "bug-shell-parser@rt.cpan.org", or through the web interface at <https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Shell-Parser>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

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