README.md
1# NAME
2
3Regexp::RegGrp - Groups a regular expressions collection
4
5<div>
6
7 <a href='https://travis-ci.org/leejo/regexp-reggrp-perl?branch=master'><img src='https://travis-ci.org/leejo/regexp-reggrp-perl.svg?branch=master' alt='Build Status' /></a>
8 <a href='https://coveralls.io/r/leejo/regexp-reggrp-perl'><img src='https://coveralls.io/repos/leejo/regexp-reggrp-perl/badge.png?branch=master' alt='Coverage Status' /></a>
9</div>
10
11# VERSION
12
13Version 2.00
14
15# DESCRIPTION
16
17Groups regular expressions to one regular expression
18
19# SYNOPSIS
20
21 use Regexp::RegGrp;
22
23 my $reggrp = Regexp::RegGrp->new(
24 {
25 reggrp => [
26 {
27 regexp => '%name%',
28 replacement => 'John Doe',
29 modifier => $modifier
30 },
31 {
32 regexp => '%company%',
33 replacement => 'ACME',
34 modifier => $modifier
35 }
36 ],
37 restore_pattern => $restore_pattern
38 }
39 );
40
41 $reggrp->exec( \$scalar );
42
43To return a scalar without changing the input simply use (e.g. example 2):
44
45 my $ret = $reggrp->exec( \$scalar );
46
47The first argument must be a hashref. The keys are:
48
49- reggrp (required)
50
51 Arrayref of hashrefs. The keys of each hashref are:
52
53 - regexp (required)
54
55 A regular expression
56
57 - replacement (optional)
58
59 Scalar or sub.
60
61 A replacement for the regular expression match. If not set, nothing will be replaced except "store" is set.
62 In this case the match is replaced by something like sprintf("\\x01%d\\x01", $idx) where $idx is the index
63 of the stored element in the store\_data arrayref. If "store" is set the default is:
64
65 sub {
66 return sprintf( "\x01%d\x01", $_[0]->{store_index} );
67 }
68
69 If a custom restore\_pattern is passed to to constructor you MUST also define a replacement. Otherwise
70 it is undefined.
71
72 If you define a subroutine as replacement an hashref is passed to this subroutine. This hashref has
73 four keys:
74
75 - match
76
77 Scalar. The match of the regular expression.
78
79 - submatches
80
81 Arrayref of submatches.
82
83 - store\_index
84
85 The next index. You need this if you want to create a placeholder and store the replacement in the
86 $self->{store\_data} arrayref.
87
88 - opts
89
90 Hashref of custom options.
91
92 - modifier (optional)
93
94 Scalar. The default is 'sm'.
95
96 - store (optional)
97
98 Scalar or sub. If you define a subroutine an hashref is passed to this subroutine. This hashref has
99 three keys:
100
101 - match
102
103 Scalar. The match of the regular expression.
104
105 - submatches
106
107 Arrayref of submatches.
108
109 - opts
110
111 Hashref of custom options.
112
113 A replacement for the regular expression match. It will not replace the match directly. The replacement
114 will be stored in the $self->{store\_data} arrayref. The placeholders in the text can easily be rereplaced
115 with the restore\_stored method later.
116
117- restore\_pattern (optional)
118
119 Scalar or Regexp object. The default restore pattern is
120
121 qr~\x01(\d+)\x01~
122
123 This means, if you use the restore\_stored method it is looking for \\x010\\x01, \\x011\\x01, ... and
124 replaces the matches with $self->{store\_data}->\[0\], $self->{store\_data}->\[1\], ...
125
126# EXAMPLES
127
128- Example 1
129
130 Common usage.
131
132 #!/usr/bin/perl
133
134 use strict;
135 use warnings;
136
137 use Regexp::RegGrp;
138
139 my $reggrp = Regexp::RegGrp->new(
140 {
141 reggrp => [
142 {
143 regexp => '%name%',
144 replacement => 'John Doe'
145 },
146 {
147 regexp => '%company%',
148 replacement => 'ACME'
149 }
150 ]
151 }
152 );
153
154 open( INFILE, 'unprocessed.txt' );
155 open( OUTFILE, '>processed.txt' );
156
157 my $txt = join( '', <INFILE> );
158
159 $reggrp->exec( \$txt );
160
161 print OUTFILE $txt;
162 close(INFILE);
163 close(OUTFILE);
164
165- Example 2
166
167 A scalar is requested by the context. The input will remain unchanged.
168
169 #!/usr/bin/perl
170
171 use strict;
172 use warnings;
173
174 use Regexp::RegGrp;
175
176 my $reggrp = Regexp::RegGrp->new(
177 {
178 reggrp => [
179 {
180 regexp => '%name%',
181 replacement => 'John Doe'
182 },
183 {
184 regexp => '%company%',
185 replacement => 'ACME'
186 }
187 ]
188 }
189 );
190
191 open( INFILE, 'unprocessed.txt' );
192 open( OUTFILE, '>processed.txt' );
193
194 my $unprocessed = join( '', <INFILE> );
195
196 my $processed = $reggrp->exec( \$unprocessed );
197
198 print OUTFILE $processed;
199 close(INFILE);
200 close(OUTFILE);
201
202# AUTHOR
203
204Merten Falk, `<nevesenin at cpan.org>`. Now maintained by LEEJO
205
206# BUGS
207
208Please report any bugs or feature requests through the web interface at
209[http://github.com/leejo/regexp-reggrp-perl/issues](http://github.com/leejo/regexp-reggrp-perl/issues).
210
211# SUPPORT
212
213You can find documentation for this module with the perldoc command.
214
215perldoc Regexp::RegGrp
216
217# COPYRIGHT & LICENSE
218
219Copyright 2010, 2011 Merten Falk, all rights reserved.
220
221This program is free software; you can redistribute it and/or modify it under
222the same terms as Perl itself.
223