.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "PPIx::Regexp::Token::Modifier 3pm"
.TH PPIx::Regexp::Token::Modifier 3pm "2019-04-03" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PPIx::Regexp::Token::Modifier \- Represent modifiers.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use PPIx::Regexp::Dumper;
\& PPIx::Regexp::Dumper\->new( \*(Aqqr{foo}smx\*(Aq )
\&     \->print();
.Ve
.PP
The trailing \f(CW\*(C`smx\*(C'\fR will be represented by this class.
.PP
This class also represents the whole of things like \f(CW\*(C`(?ismx)\*(C'\fR. But the
modifiers in something like \f(CW\*(C`(?i:foo)\*(C'\fR are represented by a
PPIx::Regexp::Token::GroupType::Modifier.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
\&\f(CW\*(C`PPIx::Regexp::Token::Modifier\*(C'\fR is a
PPIx::Regexp::Token.
.PP
\&\f(CW\*(C`PPIx::Regexp::Token::Modifier\*(C'\fR is the parent of
PPIx::Regexp::Token::GroupType::Modifier.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class represents modifier characters at the end of the regular
expression.  For example, in \f(CW\*(C`qr{foo}smx\*(C'\fR this class would represent
the terminal \f(CW\*(C`smx\*(C'\fR.
.ie n .SS "The ""a"", ""aa"", ""d"", ""l"", and ""u"" modifiers"
.el .SS "The \f(CWa\fP, \f(CWaa\fP, \f(CWd\fP, \f(CWl\fP, and \f(CWu\fP modifiers"
.IX Subsection "The a, aa, d, l, and u modifiers"
The \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`aa\*(C'\fR, \f(CW\*(C`d\*(C'\fR, \f(CW\*(C`l\*(C'\fR, and \f(CW\*(C`u\*(C'\fR modifiers, introduced starting in
Perl 5.13.6, are used to force either Unicode pattern semantics (\f(CW\*(C`u\*(C'\fR),
locale semantics (\f(CW\*(C`l\*(C'\fR) default semantics (\f(CW\*(C`d\*(C'\fR the traditional Perl
semantics, which can also mean 'dual' since it means Unicode if the
string's \s-1UTF\-8\s0 bit is on, and locale if the \s-1UTF\-8\s0 bit is off), or
restricted default semantics (\f(CW\*(C`a\*(C'\fR). These are mutually exclusive, and
only one can be asserted at a time. Asserting any of these overrides
the inherited value of any of the others. The \f(CW\*(C`asserted()\*(C'\fR method
reports as asserted the last one it sees, or none of them if it has seen
none.
.PP
For example, given \f(CW\*(C`PPIx::Regexp::Token::Modifier\*(C'\fR \f(CW$elem\fR
representing the invalid regular expression fragment \f(CW\*(C`(?dul)\*(C'\fR,
\&\f(CW\*(C`$elem\->asserted( \*(Aql\*(Aq )\*(C'\fR would return true, but
\&\f(CW\*(C`$elem\->asserted( \*(Aqu\*(Aq )\*(C'\fR would return false. Note that
\&\f(CW\*(C`$elem\->negated( \*(Aqu\*(Aq )\*(C'\fR would also return false, since \f(CW\*(C`u\*(C'\fR is not
explicitly negated.
.PP
If \f(CW$elem\fR represented regular expression fragment \f(CW\*(C`(?i)\*(C'\fR,
\&\f(CW\*(C`$elem\->asserted( \*(Aqd\*(Aq )\*(C'\fR would return false, since even though \f(CW\*(C`d\*(C'\fR
represents the default behavior it is not explicitly asserted.
.ie n .SS "The caret (""^"") modifier"
.el .SS "The caret (\f(CW^\fP) modifier"
.IX Subsection "The caret (^) modifier"
Calling \f(CW\*(C`^\*(C'\fR a modifier is a bit of a misnomer. The \f(CW\*(C`(?^...)\*(C'\fR
construction was introduced in Perl 5.13.6, to prevent the inheritance
of modifiers. The documentation calls the caret a shorthand equivalent
for \f(CW\*(C`d\-imsx\*(C'\fR, and that it the way this class handles it.
.PP
For example, given \f(CW\*(C`PPIx::Regexp::Token::Modifier\*(C'\fR \f(CW$elem\fR
representing regular expression fragment \f(CW\*(C`(?^i)\*(C'\fR,
\&\f(CW\*(C`$elem\->asserts( \*(Aqd\*(Aq )\*(C'\fR would return true, since in the absence of
an explicit \f(CW\*(C`l\*(C'\fR or \f(CW\*(C`u\*(C'\fR this class considers the \f(CW\*(C`^\*(C'\fR to explicitly
assert \f(CW\*(C`d\*(C'\fR.
.PP
The caret handling is complicated by the fact that the \f(CW\*(Aqn\*(Aq\fR modifier
was introduced in 5.21.8, at which point the caret became equivalent to
\&\f(CW\*(C`d\-imnsx\*(C'\fR. I did not feel I could unconditionally add the \f(CW\*(C`\-n\*(C'\fR to the
expansion of the caret, because that would produce confusing output from
methods like \fBexplain()\fR. Nor could I
make it conditional on the minimum perl version, because that
information is not available early enough in the parse. What I did was
to expand the caret into \f(CW\*(C`d\-imnsx\*(C'\fR if and only if \f(CW\*(Aqn\*(Aq\fR was in effect
at some point in the scope in which the modifier was parsed.
.PP
Continuing the above example, \f(CW\*(C`$elem\->asserts( \*(Aqn\*(Aq )\*(C'\fR and
\&\f(CW\*(C`$elem\->modifier_asserted( \*(Aqn\*(Aq )\*(C'\fR would both return false, but
\&\f(CW\*(C`$elem\->negates( \*(Aqn\*(Aq )\*(C'\fR would return true if and only if the \f(CW\*(C`/m\*(C'\fR
modifier has been asserted somewhere before and in-scope from this
token. The
modifier_asserted( 'n' )
method is inherited from PPIx::Regexp::Element.
.SH "METHODS"
.IX Header "METHODS"
This class provides the following public methods. Methods not documented
here are private, and unsupported in the sense that the author reserves
the right to change or remove them without notice.
.SS "asserts"
.IX Subsection "asserts"
.Vb 2
\& $token\->asserts( \*(Aqi\*(Aq ) and print "token asserts i";
\& foreach ( $token\->asserts() ) { print "token asserts $_\en" }
.Ve
.PP
This method returns true if the token explicitly asserts the given
modifier. The example would return true for the modifier in
\&\f(CW\*(C`(?i:foo)\*(C'\fR, but false for \f(CW\*(C`(?\-i:foo)\*(C'\fR.
.PP
Starting with version 0.036_01, if the argument is a
single-character modifier followed by an asterisk (intended as a wild
card character), the return is the number of times that modifier
appears. In this case an exception will be thrown if you specify a
multi-character modifier (e.g.  \f(CW\*(Aqee*\*(Aq\fR).
.PP
If called without an argument, or with an undef argument, all modifiers
explicitly asserted by this token are returned.
.SS "match_semantics"
.IX Subsection "match_semantics"
.Vb 3
\& my $sem = $token\->match_semantics();
\& defined $sem or $sem = \*(Aqundefined\*(Aq;
\& print "This token has $sem match semantics\en";
.Ve
.PP
This method returns the match semantics asserted by the token, as one of
the strings \f(CW\*(Aqa\*(Aq\fR, \f(CW\*(Aqaa\*(Aq\fR, \f(CW\*(Aqd\*(Aq\fR, \f(CW\*(Aql\*(Aq\fR, or \f(CW\*(Aqu\*(Aq\fR. If no explicit
match semantics are asserted, this method returns \f(CW\*(C`undef\*(C'\fR.
.SS "modifiers"
.IX Subsection "modifiers"
.Vb 1
\& my %mods = $token\->modifiers();
.Ve
.PP
Returns all modifiers asserted or negated by this token, and the values
set (true for asserted, false for negated). If called in scalar context,
returns a reference to a hash containing the values.
.SS "negates"
.IX Subsection "negates"
.Vb 2
\& $token\->negates( \*(Aqi\*(Aq ) and print "token negates i\en";
\& foreach ( $token\->negates() ) { print "token negates $_\en" }
.Ve
.PP
This method returns true if the token explicitly negates the given
modifier. The example would return true for the modifier in
\&\f(CW\*(C`(?\-i:foo)\*(C'\fR, but false for \f(CW\*(C`(?i:foo)\*(C'\fR.
.PP
If called without an argument, or with an undef argument, all modifiers
explicitly negated by this token are returned.
.SH "SUPPORT"
.IX Header "SUPPORT"
Support is by the author. Please file bug reports at
<http://rt.cpan.org>, or in electronic mail to the author.
.SH "AUTHOR"
.IX Header "AUTHOR"
Thomas R. Wyant, \s-1III\s0 \fIwyant at cpan dot org\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2009\-2019 by Thomas R. Wyant, \s-1III\s0
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl 5.10.0. For more details, see the full text
of the licenses in the directory \s-1LICENSES.\s0
.PP
This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.