Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Psh::Parser.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Psh::Parser 3"
.TH Psh::Parser 3 "2003-01-02" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
.Vb 1
\&  Psh::Parser - Perl Shell Parser
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Psh::Parser;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.IP "\(bu" 4
.Vb 3
\&  array decompose(regexp DELIMITER, string LINE, int PIECES,
\&                  bool KEEP, hashref QUOTINGPAIRS,
\&                  scalarref UNMATCHED_QUOTE)
.Ve
.Sp
decompose is a cross between \fIsplit()\fR and
Text::ParseWords::parse_line: it breaks \s-1LINE\s0 into at most \s-1PIECES\s0
pieces separated by \s-1DELIMITER\s0, except that the hash given by the
reference \s-1QUOTINGPAIRS\s0 specifies pairs of quotes (each key is an
open quote which matches the corresponding value) which prevent
splitting on internal instances of \s-1DELIMITER\s0, and negate the effect
of other quotes. The quoting characters are retained if \s-1KEEP\s0 is
true, discarded otherwise. Matches to the regexp \s-1METACHARACTERS\s0
(outside quotes) are their own words, regardless of being delimited.
Backslashes escape the meanings of characters that might match
delimiters, quotes, or metacharacters.  Initial unquoted empty
pieces are suppressed. 
.Sp
The regexp \s-1DELIMITER\s0 may contain a single back-reference parenthesis
construct, in which case the matches to the parenthesized
subexpression are also placed among the pieces, as with the
built-in split. \s-1METACHARACTERS\s0 may not contain any parenthesized
subexpression.
.Sp
decompose returns the array of pieces. If \s-1UNMATCHED_QUOTE\s0 is
specified, 1 will be placed in the scalar referred to if \s-1LINE\s0
contained an unmatched quote, 0 otherwise.
.Sp
If \s-1PIECES\s0 is undefined, as many pieces as
necessary are used. \s-1KEEP\s0 defaults to 1. If \s-1QUOTINGPAIRS\s0 is
undefined, {\*(L"'\*(R" => \*(L"'\*(R", \*(L"\e\*(R"\*(L" => \*(R"\e""} is used, i.e. single and
double quotes are recognized. Supply a reference to an empty hash to
have no quoting characters. \s-1METACHARACTERS\s0 defaults to a regexp that
never matches.
.Sp
\&\s-1EXAMPLE:\s0 if \f(CW$line\fR is exactly
.Sp
echo fred(joe, \*(L"Happy Days\*(R", ' steve\*(L"jan ', \*(R"\e\*(L"Oh, no!\e\*(R"")
.Sp
then decompose(' ', \f(CW$line\fR) should break it at the
following places marked by vertical bars: 
.Sp
echo|fred(joe,|\*(L"Happy Days\*(R",|' steve\*(L"jan',|\*(R"\e\*(L"Oh, no!\e\*(R"")
.IP "\(bu" 4
.Vb 1
\&  int incomplete_expr(string LINE)
.Ve
.Sp
Returns 2 if \s-1LINE\s0 has unmatched quotations. Returns \-1 if \s-1LINE\s0 has
mismatched parens. Otherwise, returns 1 if \s-1LINE\s0 has an unmatched
open brace, parenthesis, or square bracket and 0 in all other
cases. Summing up, negative is a mismatch, 0 is all \s-1OK\s0, and positive
is unfinished business. (Reasonably good, can be fooled with some
effort. I therefore have deliberately not taken comments into
account, which means you can use them to \*(L"unfool\*(R" this function, but
also that unmatched stuff in comments \s-1WILL\s0 fool this function.)
.IP "\(bu" 4
.Vb 1
\&  string unquote( string word)
.Ve
.Sp
Removes quotes from a word and backslash escapes
.IP "\(bu" 4
.Vb 1
\&  bool needs_double_quotes (string WORD)
.Ve
.Sp
Returns true if \s-1WORD\s0 needs double quotes around it to be interpreted
in a \*(L"shell\-like\*(R" manner when passed to eval. This covers barewords,
expressions that just have \e\-escapes and \f(CW$variables\fR in them, and
filenames.
.SH "AUTHOR"
.IX Header "AUTHOR"
Various