Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  SHELL::PARSER (3)

.ds Aq ’


Shell::Parser - Simple shell script parser



Version 0.04


    use Shell::Parser;

    my $parser = new Shell::Parser syntax => bash, handlers => {


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.


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

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


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

parse() Parse the shell code given in argument.


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

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.


    # 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.


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
        # ...


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

    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:

    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: <


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.


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.


SEeacute>bastien Aperghis-Tramoni, <>


Please report any bugs or feature requests to, or through the web interface at <>. I will be notified, and then you’ll automatically be notified of progress on your bug as I make changes.


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.