NAME

String::RexxParse - Perl implementation of REXX parse command

Download:

http://www.danofsteel.com/Parser/String-RexxParse-1.10.tar.gz

ftp://www.danofsteel.com/pub/RexxParse/String-RexxParse-1.10.tar.gz

AUTHOR

Dan Campbell

Copyright: Copyright (c) 1999, 2000 Dan Campbell. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DESCRIPTION

Some long-time REXX programmers switching to Perl find it difficult to give up REXX's template-based parsing abilities. This module is my attempt to provide such parsing in Perl. The documentation assumes a familiarity with REXX parse statements.

CHANGES

Version 1.10

Put eval around processing of numeric patterns in order to set $@ in calling module when there is an error.

Added protection against errors for numeric patterns when string to be parsed is shorter than the pattern calls for.

Version 1.09

General cleanup. No functional changes.

Version 1.08

Fixed bug introduced in 1.07 and added j.t to test suite.

Version 1.07

Additional internal optimizations for the following templates special cases:

  Template only contains variables (or . )
  Template only contains variables (or . ) or patterns (literal or variable)

Version 1.06

Removed email address that only gets spam.

Added String::RexxParse->email which returns me email address.

Internal optimizations for the following templates special cases:

  Template is only a single lvalue
  Template only contains variables (or . )
  Template only contains variables (or . ) or patterns (literal or variable)

Version 1.05

Minor doc changes (README, mostly).

Version 1.04

Changed name String::Parser to String::RexxParse.

Version 1.03

Fixed incorrect handling of template when two or more patterns are next to each other, or when last template item is a pattern.

Version 1.02

Fixed incorrect handling of variable pattern in template when variable's value contains regex meta characters.

Version 1.01

Fixed incorrect template parsing when a pattern is the first template item.

Version 1.00

Consider this the starting point. Any previous version should be replaced.

SYNOPSIS

use String::RexxParse qw(parse);
parse $source, q! $var1 $var2 '(' $var3 ')' $var4 ($var5) $var6 !;
use String::PexxParse;
$parse = String::RexxParse->new(q! $var1 $var2 '(' $var3 ')' $var4 ($var5) $var6 !);
$parse->parse($source);

SYNTAX

parse EXPR, EXPR

The first EXPR is the source string to be parsed and must resolve to a scalar value.

The second EXPR is the template specification. The first time parse is called with a particular template, the template is compiled, then used to parse the source expression. Subsequent parse calls with the same template will use the previously compiled version of the template rather than compile the template again.

The template is specified as a single expression, usually using some single-quotish type of quoting, like q!...! for instance. The variable specifications, (or lvalue specifications) must not contain spaces. If you want data assigned to $qq{$one}, do not specify it as $qq{ $one } but as $qq{$one}. Although both are valid in Perl, only the latter is valid in a String::RexxParse template. Likewise, substr( $b , pos( $source ) , length( $match ) ) is NOT valid, but substr($b,pos($source),length($match)) is. Also, there must be white space following any lvalue specification (unless it's the last item in the template). q/$b $c/ is OK, but q/$b$c/ is not.

If a variable's value is to be used as a pattern, it is enclosed in parentheses.

Literal patterns are enclosed in either single or double quotes. Patterns can contain spaces within the quotes or parentheses.

A period (.) is used as a placeholder to skip part of the source string.

Numeric patterns (absolute or relative position) are supported. 3, =7, +5, -12, =($n), +($x), -($somenumber) are all numeric patterns (if you use variables inside parentheses preceeded by =, +, or -, make sure they contain numeric values). Remember that Perl starts counting position at zero, so absolute numeric patterns should be one less than in REXX to identify the same character position.

All Perl variables used must either be in the package that called parse, or they must be explicitly referenced with their package name (i.e., if parse is called from package Pack, $a implies $Pack::a -- if you want $a in package Sack, you must specify $Sack::a ). Lexical variables can not be used in the template. To assign values to lexical variables do somthing like this:

 my ($b, $c, $d, $e) = parse $a, q! $x . $x '(' $x ')' $x !;

If you're concerned about the compiled templates taking up memory after you're done with them, you can add 'drop' to the import list when you 'use String::RexxParse'. Then pass the template to 'drop' when you're done with it. Or just call String::RexxParse::drop($template). Or use the object oriented flavor discussed below.

Consult your favorite REXX manual for more details on templates.

$parse = String::RexxParse->new(EXPR);

$parse->parse(EXPR);

If you like, you can use String::RexxParse->new(EXPR) to create a String::RexxParse object. The EXPR passed to new is a template specification as described above. When you want to parse an EXPR, you just pass the string to the String::RexxParse object like so: $parse->parse(EXPR);

EXAMPLES

 REXX:
 parse var a b c '.' d '([' e '])' f qq.one

 Perl:
 parse $a, q! $b $c '.' $d '([' $e '])' $f $qq{one} !;
 # or
 $p = String::RexxParse->new(q! $b $c '.' $d '([' $e '])' $f $qq{one} !);
 $p->parse($a);

 ~~~~~~~~~~~~~~~

 REXX:
 parse var a b . '.' d '([' e '])' f qq.one

 Perl:
 parse $a, q!$b . '.' $d '([' $e '])' $f $qq{one}!;

 ~~~~~~~~~~~~~~~

 REXX:
 parse linein b c '.' d '([' e '])' f qq.one

 Perl:
 parse <>, q! $b $c '.' $d '([' $e '])' $f $qq{one} !;

 ~~~~~~~~~~~~~~~

 REXX:
 parse linein('filename') b c '.' d '([' e '])' f qq.one

 Perl:
 open FILE,"filename";
 parse <FILE>, q! $b $c '.' $d '([' $e '])' $f $qq{one}!;

 ~~~~~~~~~~~~~~~

 REXX:
 parse value(func(a)) with b c '.' d '([' e '])' f qq.one

 Perl:
 parse func($a), q! $b $c '.' $d '([' $e '])' $f $qq{one}!;

 ~~~~~~~~~~~~~~~

 REXX:
 variable = '.'
 parse a b c (variable) d 

 Perl:
 $variable = '.';
 parse $a, q/$b $c ($variable) $d/;

 ~~~~~~~~~~~~~~~

 REXX:
 variable = "abc"
 parse a b c (' 'variable' ') d 

 Perl:
 parse $a, q/$b $c (" $variable ") $d/;

 ~~~~~~~~~~~~~~~

 REXX:
 parse a b 12 c +8 d 

 Perl:
 parse $a, q! $b 11 $c +8 $d !;
 # position 12 in REXX is position 11 in Perl!


 ~~~~~~~~~~~~~~~
 
 REXX:
 parse var a b . d '([' e '])' f -13 g +(eight) qq.one

 Perl:
 @list = parse $a,  q!$b '.' $d '([' $e '])' $f -13 $g +($eight) $qq{one}!;
 # In addition to assiging values to the variables identified in the template,
 # @list will contain a list of corresponding values.

BUGS, QUESTIONS, COMMENTS

Please report any suspected bugs to Dan Campbell (String::RexxParse->email). Include the template and sample text that produces the incorrect results, along with a description of the problem. Questions and comments are also welcome.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 745:: Can't have a 0 in =over 0