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

    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:

    # 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 });

syntax()

Selects the shell syntax. Use one of:

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:

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

Copyright 2004 Sébastien Aperghis-Tramoni, All Rights Reserved.

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