Sébastien Aperghis-Tramoni > Shell-Parser-0.04 > Shell::Parser

Download:
Shell-Parser-0.04.tar.gz

Dependencies

Annotate this POD

Related Modules

Text::ParseWords
Text::Balanced
more...
By perlmonks.org

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.04   Source  

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:

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 ^

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.

syntax highlighting: