/ 
Shell-Parser-0.04
River stage one • 1 direct dependent • 1 total dependent
/ Shell::Parser

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

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.