GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  SHELL::PARSER (3)

.ds Aq ’

NAME

Shell::Parser - Simple shell script parser

CONTENTS

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.

<B>OptionsB>
o handlers - sets the parsing events handlers. See handlers() for more information.
o syntax - selects the shell syntax. See syntax() for more information.

<B>ExamplesB>



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



parse() Parse the shell code given in argument.

<B>ExamplesB>



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

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

<B>ExamplesB>



    # 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:
o bourne - the standard Bourne shell
o csh - the C shell
o tcsh - the TENEX C shell
o korn88 - the Korn shell, 1988 version
o korn93 - the Korn shell 1993 version
o bash - GNU Bourne Again SHell
o 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:
o a reference to the current Shell::Parser object
o a hash with the following keys:
o token - the actual shell token
o 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 <B>(F)B> You gave a reference to parse(), which is not handled at this time.
No such handler: %s <B>(E)B> You gave an unknown handler name. Please check handlers() for the available handlers.
Unknown syntax ’%s’ <B>(E)B> You gave an unknown syntax. Please check syntax() for the available syntaxes.

CAVEATS

o Running Shell::Parser with the -W flag gives many warnings, but most come from Text::ParseWords.
o Comments curently contains the newline character that terminate them. This is not very intuituive and will be corrected in later versions.
o The command event is currently unimplemented.
o 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 Se\k:'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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 SHELL::PARSER (3) 2005-04-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.