YAPE::Regex::Element(3pm)

1Regex::Element(3)     User Contributed Perl Documentation    Regex::Element(3)
2
3
4

NAME

6       YAPE::Regex::Element - sub-classes for YAPE::Regex elements
7

VERSION

9       This document refers to YAPE::Regex::Element version 4.00.
10

SYNOPSIS

12         use YAPE::Regex 'MyExt::Mod';
13         # this sets up inheritence in MyExt::Mod
14         # see YAPE::Regex documentation
15

"YAPE" MODULES

17       The "YAPE" hierarchy of modules is an attempt at a unified means of
18       parsing and extracting content.  It attempts to maintain a generic
19       interface, to promote simplicity and reusability.  The API is powerful,
20       yet simple.  The modules do tokenization (which can be intercepted) and
21       build trees, so that extraction of specific nodes is doable.
22

DESCRIPTION

24       This module provides the classes for the "YAPE::Regex" objects.  The
25       base class for these objects is "YAPE::Regex::Element".  The objects
26       classes are numerous.
27
28   Methods for "YAPE::Regex::Element"
29       This class contains fallback methods for the other classes.
30
31       •   "my $str = $obj->text;"
32
33           Returns a string representation of the content of the regex node
34           itself, not any nodes contained in it.  This is "undef" for non-
35           text nodes.
36
37       •   "my $str = $obj->string;"
38
39           Returns a string representation of the regex node itself, not any
40           nodes contained in it.
41
42       •   "my $str = $obj->fullstring;"
43
44           Returns a string representation of the regex node, including any
45           nodes contained in it.
46
47       •   "my $quant = $obj->quant;"
48
49           Returns a string with the quantity, and a "?" if the node is non-
50           greedy.  The quantity is one of "*", "+", "?", "{M,N}", or an empty
51           string.
52
53       •   "my $ng = $obj->ngreed;"
54
55           Returns a "?" if the node is non-greedy, and an empty string
56           otherwise.
57
58   Methods for "YAPE::Regex::anchor"
59       This class represents anchors.  Objects have the following methods:
60
61       •   "my $anchor = YAPE::Regex::anchor->new($type,$q,$ng);"
62
63           Creates a "YAPE::Regex::anchor" object.  Takes three arguments:
64           the anchor ("^", "\A", "$", "\Z", "\z", "\B", "\b", or "\G"), the
65           quantity, and the non-greedy flag.  The quantity should be an empty
66           string.
67
68             my $anc = YAPE::Regex::anchor->new('\A', '', '?');
69             # /\A?/
70
71       •   "my $type = $anchor->type;"
72
73           Returns the string "anchor".
74
75   Methods for "YAPE::Regex::macro"
76       This class represents character-class macros.  Objects have the
77       following methods:
78
79       •   "my $macro = YAPE::Regex::macro->new($type,$q,$ng);"
80
81           Creates a "YAPE::Regex::macro" object.  Takes three arguments:  the
82           macro ("w", "W", "d", "D", "s", or "S"), the quantity, and the non-
83           greedy flag.
84
85             my $macro = YAPE::Regex::macro->new('s', '{3,5}');
86             # /\s{3,5}/
87
88       •   "my $text = $macro->text;"
89
90           Returns the macro.
91
92             print $macro->text;  # '\s'
93
94       •   "my $type = $macro->type;"
95
96           Returns the string "macro".
97
98   Methods for "YAPE::Regex::oct"
99       This class represents octal escapes.  Objects have the following
100       methods:
101
102       •   "my $oct = YAPE::Regex::oct->new($type,$q,$ng);"
103
104           Creates a "YAPE::Regex::oct" object.  Takes three arguments:  the
105           octal number (as a string), the quantity, and the non-greedy flag.
106
107             my $oct = YAPE::Regex::oct->new('040');
108             # /\040/
109
110       •   "my $text = $oct->text;"
111
112           Returns the octal escape.
113
114             print $oct->text;  # '\040'
115
116       •   "my $type = $oct->type;"
117
118           Returns the string "oct".
119
120   Methods for "YAPE::Regex::hex"
121       This class represents hexadecimal escapes.  Objects have the following
122       methods:
123
124       •   "my $hex = YAPE::Regex::hex->new($type,$q,$ng);"
125
126           Creates a "YAPE::Regex::hex" object.  Takes three arguments:  the
127           hexadecimal number (as a string), the quantity, and the non-greedy
128           flag.
129
130             my $hex = YAPE::Regex::hex->new('20','{2,}');
131             # /\x20{2,}/
132
133       •   "my $text = $hex->text;"
134
135           Returns the hexadecimal escape.
136
137             print $hex->text;  # '\x20'
138
139       •   "my $type = $hex->type;"
140
141           Returns the string "hex".
142
143   Methods for "YAPE::Regex::utf8hex"
144       This class represents UTF hexadecimal escapes.  Objects have the
145       following methods:
146
147       •   "my $hex = YAPE::Regex::utf8hex->new($type,$q,$ng);"
148
149           Creates a "YAPE::Regex::utf8hex" object.  Takes three arguments:
150           the hexadecimal number (as a string), the quantity, and the non-
151           greedy flag.
152
153             my $utf8hex = YAPE::Regex::utf8hex->new('beef','{0,4}');
154             # /\x{beef}{2,}/
155
156       •   "my $text = $utf8hex->text;"
157
158           Returns the hexadecimal escape.
159
160             print $utf8hex->text;  # '\x{beef}'
161
162       •   "my $type = $utf8hex->type;"
163
164           Returns the string "utf8hex".
165
166   Methods for "YAPE::Regex::backref"
167       This class represents back-references.  Objects have the following
168       methods:
169
170       •   "my $bref = YAPE::Regex::bref->new($type,$q,$ng);"
171
172           Creates a "YAPE::Regex::bref" object.  Takes three arguments:  the
173           number of the back-reference, the quantity, and the non-greedy
174           flag.
175
176             my $bref = YAPE::Regex::bref->new(2,'','?');
177             # /\2?/
178
179       •   "my $text = $bref->text;"
180
181           Returns the backescape.
182
183             print $bref->text;  # '\2'
184
185       •   "my $type = $bref->type;"
186
187           Returns the string "backref".
188
189   Methods for "YAPE::Regex::ctrl"
190       This class represents control character escapes.  Objects have the
191       following methods:
192
193       •   "my $ctrl = YAPE::Regex::ctrl->new($type,$q,$ng);"
194
195           Creates a "YAPE::Regex::ctrl" object.  Takes three arguments:  the
196           control character, the quantity, and the non-greedy flag.
197
198             my $ctrl = YAPE::Regex::ctrl->new('M');
199             # /\cM/
200
201       •   "my $text = $ctrl->text;"
202
203           Returns the control character escape.
204
205             print $ctrl->text;  # '\cM'
206
207       •   "my $type = $ctrl->type;"
208
209           Returns the string "ctrl".
210
211   Methods for "YAPE::Regex::named"
212       This class represents named characters.  Objects have the following
213       methods:
214
215       •   "my $ctrl = YAPE::Regex::named->new($type,$q,$ng);"
216
217           Creates a "YAPE::Regex::named" object.  Takes three arguments:  the
218           name of the character, the quantity, and the non-greedy flag.
219
220             my $named = YAPE::Regex::named->new('GREEK SMALL LETTER BETA');
221             # /\N{GREEK SMALL LETTER BETA}/
222
223       •   "my $text = $named->text;"
224
225           Returns the character escape text.
226
227             print $named->text;  # '\N{GREEK SMALL LETTER BETA}'
228
229       •   "my $type = $named->type;"
230
231           Returns the string "named".
232
233   Methods for "YAPE::Regex::Cchar"
234       This class represents C characters.  Objects have the following
235       methods:
236
237       •   "my $ctrl = YAPE::Regex::Cchar->new($q,$ng);"
238
239           Creates a "YAPE::Regex::Cchar" object.  Takes two arguments:  the
240           quantity and the non-greedy flag.
241
242             my $named = YAPE::Regex::Char->new(2);
243             # /\C{2}/
244
245       •   "my $text = $Cchar->text;"
246
247           Returns the escape sequence.
248
249             print $Cchar->text;  # '\C'
250
251       •   "my $type = $Cchar->type;"
252
253           Returns the string "Cchar".
254
255   Methods for "YAPE::Regex::slash"
256       This class represents any other escaped characters.  Objects have the
257       following methods:
258
259       •   "my $slash = YAPE::Regex::slash->new($type,$q,$ng);"
260
261           Creates a "YAPE::Regex::slash" object.  Takes three arguments:  the
262           backslashed character, the quantity, and the non-greedy flag.
263
264             my $slash = YAPE::Regex::slash->new('t','','?');
265             # /\t?/
266
267       •   "my $text = $slash->text;"
268
269           Returns the escaped character.
270
271             print $slash->text;  # '\t'
272
273       •   "my $type = $slash->type;"
274
275           Returns the string "slash".
276
277   Methods for "YAPE::Regex::any"
278       This class represents the dot metacharacter.  Objects have the
279       following methods:
280
281       •   "my $any = YAPE::Regex::any->new($q,$ng);"
282
283           Creates a "YAPE::Regex::any" object.  Takes two arguments:  the
284           quantity, and the non-greedy flag.
285
286             my $any = YAPE::Regex::any->new('{1,3}');
287             # /.{1,3}/
288
289       •   "my $type = $any->type;"
290
291           Returns the string "any".
292
293   Methods for "YAPE::Regex::class"
294       This class represents character classes.  Objects have the following
295       methods:
296
297       •   "my $class = YAPE::Regex::class->new($chars,$neg,$q,$ng);"
298
299           Creates a "YAPE::Regex::class" object.  Takes four arguments:  the
300           characters in the class, a "^" if the class is negated (an empty
301           string otherwise), the quantity, and the non-greedy flag.
302
303             my $class = YAPE::Regex::class->new('aeiouy','^');
304             # /[^aeiouy]/
305
306       •   "my $text = $class->text;"
307
308           Returns the character class.
309
310             print $class->text;  # [^aeiouy]
311
312       •   "my $type = $class->type;"
313
314           Returns the string "class".
315
316   Methods for "YAPE::Regex::hex"
317       This class represents hexadecimal escapes.  Objects have the following
318       methods:
319
320       •   "my $text = YAPE::Regex::text->new($text,$q,$ng);"
321
322           Creates a "YAPE::Regex::text" object.  Takes three arguments:  the
323           text, the quantity, and the non-greedy flag.  The quantity and non-
324           greedy modifier should only be present for single-character text,
325           because of the way the parser renders the quantity and non-greedy
326           modifier.
327
328             my $text = YAPE::Regex::text->new('alphabet','');
329             # /alphabet/
330
331             my $text = YAPE::Regex::text->new('x','?','?');
332             # /x??/
333
334       •   "my $type = $text->type;"
335
336           Returns the string "text".
337
338   Methods for "YAPE::Regex::alt"
339       This class represents alternation.  Objects have the following methods:
340
341       •   "my $alt = YAPE::Regex::alt->new;"
342
343           Creates a "YAPE::Regex::alt" object.
344
345             my $alt = YAPE::Regex::alt->new;
346             # /|/
347
348       •   "my $type = $oct->type;"
349
350           Returns the string "alt".
351
352   Methods for "YAPE::Regex::comment"
353       This class represents in-line comments.  Objects have the following
354       methods:
355
356       •   "my $comment = YAPE::Regex::comment->new($comment,$x);"
357
358           Creates a "YAPE::Regex::comment" object.  Takes two arguments:  the
359           text of the comment, and whether or not the "/x" regex modifier is
360           in effect for this comment.  Note that Perl's regex engine will
361           stop a "(?#...)" comment at the first ")", regardless of what you
362           do.
363
364             my $comment = YAPE::Regex::comment->new(
365               "match an optional string of digits"
366             );
367             # /(?#match an optional string of digits)/
368
369             my $comment = YAPE::Regex::comment->new(
370               "match an optional string of digits",
371               1
372             );
373             # /# match an optional string of digits/
374
375       •   "my $type = $comment->type;"
376
377           Returns the string "comment".
378
379       •   "my $x_on = $comment->xcomm;"
380
381           Returns true or false, depending on whether the comment is under
382           the "/x" regex modifier.
383
384   Methods for "YAPE::Regex::whitespace"
385       This class represents whitespace under the "/x" regex modifier.
386       Objects have the following methods:
387
388       •   "my $ws = YAPE::Regex::whitespace->new($text);"
389
390           Creates a "YAPE::Regex::whitespace" object.  Takes one argument:
391           the text of the whitespace.
392
393             my $ws = YAPE::Regex::whitespace->new('  ');
394             # /  /x
395
396       •   "my $text = $ws->text;"
397
398           Returns the whitespace.
399
400             print $ws->text;  # '  '
401
402       •   "my $type = $ws->type;"
403
404           Returns the string "whitespace".
405
406   Methods for "YAPE::Regex::flags"
407       This class represents "(?ismx)" flags.  Objects have the following
408       methods:
409
410       •   "my $flags = YAPE::Regex::flags->new($add,$sub);"
411
412           Creates a "YAPE::Regex::flags" object.  Takes two arguments:  a
413           string of the modes to have on, and a string of the modes to
414           explicitly turn off.  The flags are displayed in alphabetical
415           order.
416
417             my $flags = YAPE::Regex::flags->new('is','m');
418             # /(?is-m)/
419
420       •   "my $type = $flags->type;"
421
422           Returns the string "flags".
423
424   Methods for "YAPE::Regex::cut"
425       This class represents the cut assertion.  Objects have the following
426       methods:
427
428       •   "my $look = YAPE::Regex::cut->new(\@nodes);"
429
430           Creates a "YAPE::Regex::cut" object.  Takes one arguments:  a
431           reference to an array of objects to be contained in the cut.
432
433             my $REx = YAPE::Regex::class->new('aeiouy','','+');
434             my $look = YAPE::Regex::cut->new(0,[$REx]);
435             # /(?>[aeiouy]+)/
436
437       •   "my $type = $cut->type;"
438
439           Returns the string "cut".
440
441   Methods for "YAPE::Regex::lookahead"
442       This class represents lookaheads.  Objects have the following methods:
443
444       •   "my $look = YAPE::Regex::lookahead->new($pos,\@nodes);"
445
446           Creates a "YAPE::Regex::lookahead" object.  Takes two arguments:  a
447           boolean value indicating whether or not the lookahead is positive,
448           and a reference to an array of objects to be contained in the
449           lookahead.
450
451             my $REx = YAPE::Regex::class->new('aeiouy');
452             my $look = YAPE::Regex::lookahead->new(0,[$REx]);
453             # /(?![aeiouy])/
454
455       •   "my $pos = $look->pos;"
456
457           Returns true if the lookahead is positive.
458
459             print $look->pos ? 'pos' : 'neg';  # 'neg'
460
461       •   "my $type = $look->type;"
462
463           Returns the string lookahead(pos) or lookahead(neg).
464
465   Methods for "YAPE::Regex::lookbehind"
466       This class represents lookbehinds.  Objects have the following methods:
467
468       •   "my $look = YAPE::Regex::lookbehind->new($pos,\@nodes);"
469
470           Creates a "YAPE::Regex::lookbehind" object.  Takes two arguments:
471           a boolean value indicating whether or not the lookbehind is
472           positive, and a reference to an array of objects to be contained in
473           the lookbehind.
474
475             my $REx = YAPE::Regex::class->new('aeiouy','^');
476             my $look = YAPE::Regex::lookbehind->new(1,[$REx]);
477             # /(?<=[^aeiouy])/
478
479       •   "my $pos = $look->pos;"
480
481           Returns true if the lookbehind is positive.
482
483             print $look->pos ? 'pos' : 'neg';  # 'pos'
484
485       •   "my $type = $look->type;"
486
487           Returns the string lookbehind(pos) or lookbehind(neg).
488
489   Methods for "YAPE::Regex::conditional"
490       This class represents conditionals.  Objects have the following
491       methods:
492
493       •   "my $cond = YAPE::Regex::conditional->new($br,$t,$f,$q,$ng);"
494
495           Creates a "YAPE::Regex::hex" object.  Takes five arguments:  the
496           number of the back-reference (that's all that's supported in the
497           current version), an array reference to the "true" pattern, an
498           array reference to the "false" pattern, and the quantity and non-
499           greedy flag.
500
501             my $cond = YAPE::Regex::conditional->new(
502               2,
503               [],
504               [ YAPE::Regex::text->new('foo') ],
505               '?',
506             );
507             # /(?(2)|foo)?/
508
509       •   "my $br = $cond->backref;"
510
511           Returns the number of the back-reference the conditional depends
512           on.
513
514             print $br->backref;  # 2
515
516       •   "my $type = $cond->type;"
517
518           Returns the string conditional(N), where N is the number of the
519           back-reference.
520
521   Methods for "YAPE::Regex::group"
522       This class represents non-capturing groups.  Objects have the following
523       methods:
524
525       •   "my $group = YAPE::Regex::group->new($on,$off,\@nodes,$q,$ng);"
526
527           Creates a "YAPE::Regex::group" object.  Takes five arguments:  the
528           modes turned on, the modes explicitly turned off, a reference to an
529           array of objects in the group, the quantity, and the non-greedy
530           flag.  The modes are displayed in alphabetical order.
531
532             my $group = YAPE::Regex::group->new(
533               'i',
534               's',
535               [
536                 YAPE::Regex::macro->new('d', '{2}'),
537                 YAPE::Regex::macro->new('s'),
538                 YAPE::Regex::macro->new('d', '{2}'),
539               ],
540               '?',
541             );
542             # /(?i-s:\d{2}\s\d{2})?/
543
544       •   "my $type = $group->type;"
545
546           Returns the string "group".
547
548   Methods for "YAPE::Regex::capture"
549       This class represents capturing groups.  Objects have the following
550       methods:
551
552       •   "my $capture = YAPE::Regex::capture->new(\@nodes,$q,$ng);"
553
554           Creates a "YAPE::Regex::capture" object.  Takes three arguments:  a
555           reference to an array of objects in the group, the quantity, and
556           the non-greedy flag.
557
558             my $capture = YAPE::Regex::capture->new(
559               [
560                 YAPE::Regex::macro->new('d', '{2}'),
561                 YAPE::Regex::macro->new('s'),
562                 YAPE::Regex::macro->new('d', '{2}'),
563               ],
564             );
565             # /(\d{2}\s\d{2})/
566
567       •   "my $type = $capture->type;"
568
569           Returns the string "capture".
570
571   Methods for "YAPE::Regex::code"
572       This class represents code blocks.  Objects have the following methods:
573
574       •   "my $code = YAPE::Regex::code->new($block);"
575
576           Creates a "YAPE::Regex::code" object.  Takes one arguments:  a
577           string holding a block of code.
578
579             my $code = YAPE::Regex::code->new(q({ push @poss, $1 }));
580             # /(?{ push @poss, $1 })/
581
582       •   "my $type = $code->type;"
583
584           Returns the string "code".
585
586   Methods for "YAPE::Regex::later"
587       This class represents closed parentheses.  Objects have the following
588       methods:
589
590       •   "my $later = YAPE::Regex::later->new($block);"
591
592           Creates a "YAPE::Regex::later" object.  Takes one arguments:  a
593           string holding a block of code.
594
595             my $later = YAPE::Regex::later->new(q({ push @poss, $1 }));
596             # /(?{{ push @poss, $1 }})/
597
598       •   "my $type = $later->type;"
599
600           Returns the string "later".
601
602   Methods for "YAPE::Regex::close"
603       This class represents closed parentheses.  Objects have the following
604       methods:
605
606       •   "my $close = YAPE::Regex::close->new($q,$ng);"
607
608           Creates a "YAPE::Regex::close" object.  Takes two arguments:  the
609           quantity, and the non-greedy flag.  This object is never needed in
610           the tree; however, they are returned in the parsing stage, so that
611           you know when they've been reached.
612
613             my $close = YAPE::Regex::close->new('?','?');
614             # /)??/
615
616       •   "my $type = $close->type;"
617
618           Returns the string "close".
619

TO DO

621       This is a listing of things to add to future versions of this module.
622
623       •   None!
624

BUGS

626       Following is a list of known or reported bugs.
627
628       •   This documentation might be incomplete.
629

SUPPORT

631       Visit "YAPE"'s web site at http://www.pobox.com/~japhy/YAPE/.
632

AUTHOR

637       The original author is Jeff "japhy" Pinyan (CPAN ID: PINYAN).
638
639       Gene Sullivan (gsullivan@cpan.org) is a co-maintainer.
640

LICENSE

642       This module is free software; you can redistribute it and/or modify it
643       under the same terms as Perl itself.  See perlartistic.
644
645
646
647perl v5.38.0                      2023-07-21                 Regex::Element(3)