Regexp/Parser/Perl58.html

<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Regexp::Parser::Perl58 - A Regexp::Parser Subclass for Perl 5.8
Regular Expressions</title>
<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:wakaba@suika.fam.cx" />
</head>

<body>


<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>

<ul>

        <li><a href="#name">NAME</a></li>
        <li><a href="#synopsis">SYNOPSIS</a></li>
        <li><a href="#description">DESCRIPTION</a></li>
        <li><a href="#methods">METHODS</a></li>
        <li><a href="#dependency">DEPENDENCY</a></li>
        <li><a href="#see_also">SEE ALSO</a></li>
        <li><a href="#development">DEVELOPMENT</a></li>
        <li><a href="#author">AUTHOR</a></li>
        <li><a href="#license">LICENSE</a></li>
</ul>

<hr name="index" />
</div>
<!-- INDEX END -->

<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Regexp::Parser::Perl58 - A Regexp::Parser Subclass for Perl 5.8
Regular Expressions</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
  use Regexp::Parser::Perl58;
  
  my $parser = Regexp::Parser::Perl58-&gt;new;
  
  my @error;
  
  ## Prepare a callback function invoked whenever an error or warning
  ## is raised by the parser.
  $parser-&gt;onerror (sub {
    my %args = @_;
    
    my $error_message = '';
    if ($args{level} eq 'w') {
      $error_message .= 'Warning: ';
    } else {
      $error_message .= 'Error: ';
    }
    
    $error_message .= sprintf $args{type}, @{$args{args}};
    
    $error_message .= ' (';
    $error_message .= substr ${$args{valueref}},
        $args{pos_start}, $args{pos_end} - $args{pos_start};
    $error_message .= ')';
    
    $error_message .= &quot;\n&quot;;
    
    push @error, $error_message;
  });
  
  ## Parse the regular expression given as a string.
  ## Use |eval| to catch an exception that would be thrown if the
  ## regular expression contains a fatal error.
  eval {
    $parser-&gt;parse ($regexp_as_string);
  };
  
  if ($parser-&gt;errnum) {
    ## @error contains at least one fatal error.
    warn @error;
  } else {
    ## @error contains no fatal error.
    warn @error;
    
    ## Now, $parser-&gt;root contains the root node of the parsed regular
    ## expression tree.  See |perldoc Regexp::Parser| for more information.
  }</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The <code>Regexp::Parser::Perl58</code> modules provides a subclass of the
<code>Regexp::Parser</code>, a regular expression parser module.  The
<code>Regexp::Parser::Perl58</code> module provides an implementation of the
parser for the regular expression language as supported by Perl 5.8
(with some minor restrictions).</p>
<p>Although the <code>Regexp::Parser</code> itself provides the facility to parse
Perl 5.8 regular expression, this module in addition enables the
caller to specify a callback function that is invoked whenever the
parser detects an error or wants to issue a warning message.</p>
<p>Apart from this additional function, this module provides the same
interface as the one applied by the <code>Regexp::Parser</code> module.  For
more information, see <a href="../../Regexp/Parser.html">the Regexp::Parser manpage</a>.</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<p>The <code>Regexp::Parser::Perl58</code> module provides same methods as
<code>Regexp::Parser</code>.  In addition, the following method is defined:</p>
<dl>
<dt><strong><a name="onerror" class="item">[<em>$onerror</em> =] <em>$parser</em>-&gt;onerror ([<em>$onerror</em>]);</a></strong>

<dd>
<p>Gets or sets the callback function that is invoked when an error or
warning is issued by the parser.</p>
</dd>
<dd>
<p>On setting, i.e. an argument is specified to the method, the argument
is set as the error handler function.  The argument must be a <code>CODE</code>
reference or <code>undef</code>, which represents no-op.</p>
</dd>
<dd>
<p>On getting, i.e, no argument is specified to the method, the method
returns the current error handler function, if it has been set, or
returns <code>undef</code>.</p>
</dd>
<dd>
<p>The callback function, if specified, is invoked whenever the parser
wants to report an error or warning to the application.  When invoked,
the callback function is given a set of key-value pairs describing the
error or warning.</p>
</dd>
<dl>
<dt><strong><a name="level_m_w" class="item">level =&gt; &quot;m&quot; / &quot;w&quot;</a></strong>

<dd>
<p>The level of the error.  String <code>m</code> represents that it is a fatal
error which prevents the regular expression from being effective.
String <code>w</code> represents that it is a warning.</p>
</dd>
</li>
<dt><strong><a name="code_integer" class="item">code =&gt; <em>integer</em></a></strong>

<dd>
<p>The code that identifies the type of the error.  See <a href="../../Regexp/Parser.html">the Regexp::Parser manpage</a>
for the list of error codes.</p>
</dd>
</li>
<dt><strong><a name="type_string" class="item">type =&gt; <em>string</em></a></strong>

<dd>
<p>The error type.  The error type is a string that describes the type of
the error as a simple English text.  It can be used as the first
argument of an <code>sprintf</code> call to obtain an error message, with the
<code>args</code> argument, like:</p>
</dd>
<dd>
<pre>
  sprintf $args{type}, @{$args{args}}</pre>
</dd>
</li>
<dt><strong><a name="args_array_ref" class="item">args =&gt; <em>ARRAY-ref</em></a></strong>

<dd>
<p>The optional values that describes the error or warning.  The number
and contents of the values depends on the type of the error.</p>
</dd>
</li>
<dt><strong><a name="valueref_scalar_ref_to_string" class="item">valueref =&gt; <em>SCALAR-ref-to-string</em></a></strong>

<dd>
<p>A reference to the string being parsed.</p>
</dd>
</li>
<dt><strong><a name="pos_start_integer" class="item">pos_start =&gt; <em>integer</em></a></strong>

<dd>
<p>The index in the string referenced by <code>valueref</code>, from which the
substring that causes the error or warning starts.</p>
</dd>
</li>
<dt><strong><a name="pos_end_integer" class="item">pos_end =&gt; <em>integer</em></a></strong>

<dd>
<p>The index in the string referenced by <code>valueref</code>, at which the
substring that causes the error or warning ends.</p>
</dd>
</li>
</dl>
</dl>
<p>
</p>
<hr />
<h1><a name="dependency">DEPENDENCY</a></h1>
<p>This module requires Perl 5.10.0 or later.</p>
<p>This module depends on the <code>Regexp::Parser</code> module.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>The latest version of this module is available at
<a href="http://suika.fam.cx/regexp/">http://suika.fam.cx/regexp/</a>.</p>
<p>Regular expression visualizer
<a href="http://suika.fam.cx/regexp/visualizer/input">http://suika.fam.cx/regexp/visualizer/input</a>.  It uses this module
to parse Perl 5.8 regular expressions.</p>
<p><a href="../../Regexp/Parser.html">the Regexp::Parser manpage</a> - The superclass, available from CPAN.</p>
<p><a href="../../Regexp/Parser/JavaScript.html">the Regexp::Parser::JavaScript manpage</a> - A parser for JavaScript regular
expresssions.</p>
<p>
</p>
<hr />
<h1><a name="development">DEVELOPMENT</a></h1>
<p>CVS log:
<a href="http://suika.fam.cx/regexp/lib/Regexp/Parser/Perl58.pm,cvslog">http://suika.fam.cx/regexp/lib/Regexp/Parser/Perl58.pm,cvslog</a>.</p>
<p>Bug tracking system: <a href="http://manakai.g.hatena.ne.jp/task/7/">http://manakai.g.hatena.ne.jp/task/7/</a>.</p>
<p>Note that this module does not support Perl 5.10 regular expression
extensions, as the module name suggests.  They are expected to be
supported by another module.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;.</p>
<p>
</p>
<hr />
<h1><a name="license">LICENSE</a></h1>
<p>Copyright 2008-2009 Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;.</p>
<p>This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.</p>

</body>

</html>
1	<?xml version="1.0" ?>
2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3	<html xmlns="http://www.w3.org/1999/xhtml">
4	<head>
5	<title>Regexp::Parser::Perl58 - A Regexp::Parser Subclass for Perl 5.8
6	Regular Expressions</title>
7	<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" />
8	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
9	<link rev="made" href="mailto:wakaba@suika.fam.cx" />
10	</head>
11
12	<body>
13
14
15	<!-- INDEX BEGIN -->
16	<div name="index">
17	<p><a name="__index__"></a></p>
18
19	<ul>
20
21	<li><a href="#name">NAME</a></li>
22	<li><a href="#synopsis">SYNOPSIS</a></li>
23	<li><a href="#description">DESCRIPTION</a></li>
24	<li><a href="#methods">METHODS</a></li>
25	<li><a href="#dependency">DEPENDENCY</a></li>
26	<li><a href="#see_also">SEE ALSO</a></li>
27	<li><a href="#development">DEVELOPMENT</a></li>
28	<li><a href="#author">AUTHOR</a></li>
29	<li><a href="#license">LICENSE</a></li>
30	</ul>
31
32	<hr name="index" />
33	</div>
34	<!-- INDEX END -->
35
36	<p>
37	</p>
38	<h1><a name="name">NAME</a></h1>
39	<p>Regexp::Parser::Perl58 - A Regexp::Parser Subclass for Perl 5.8
40	Regular Expressions</p>
41	<p>
42	</p>
43	<hr />
44	<h1><a name="synopsis">SYNOPSIS</a></h1>
45	<pre>
46	use Regexp::Parser::Perl58;
47
48	my $parser = Regexp::Parser::Perl58->new;
49
50	my @error;
51
52	## Prepare a callback function invoked whenever an error or warning
53	## is raised by the parser.
54	$parser->onerror (sub {
55	my %args = @_;
56
57	my $error_message = '';
58	if ($args{level} eq 'w') {
59	$error_message .= 'Warning: ';
60	} else {
61	$error_message .= 'Error: ';
62	}
63
64	$error_message .= sprintf $args{type}, @{$args{args}};
65
66	$error_message .= ' (';
67	$error_message .= substr ${$args{valueref}},
68	$args{pos_start}, $args{pos_end} - $args{pos_start};
69	$error_message .= ')';
70
71	$error_message .= "\n";
72
73	push @error, $error_message;
74	});
75
76	## Parse the regular expression given as a string.
77	## Use \|eval\| to catch an exception that would be thrown if the
78	## regular expression contains a fatal error.
79	eval {
80	$parser->parse ($regexp_as_string);
81	};
82
83	if ($parser->errnum) {
84	## @error contains at least one fatal error.
85	warn @error;
86	} else {
87	## @error contains no fatal error.
88	warn @error;
89
90	## Now, $parser->root contains the root node of the parsed regular
91	## expression tree. See \|perldoc Regexp::Parser\| for more information.
92	}</pre>
93	<p>
94	</p>
95	<hr />
96	<h1><a name="description">DESCRIPTION</a></h1>
97	<p>The <code>Regexp::Parser::Perl58</code> modules provides a subclass of the
98	<code>Regexp::Parser</code>, a regular expression parser module. The
99	<code>Regexp::Parser::Perl58</code> module provides an implementation of the
100	parser for the regular expression language as supported by Perl 5.8
101	(with some minor restrictions).</p>
102	<p>Although the <code>Regexp::Parser</code> itself provides the facility to parse
103	Perl 5.8 regular expression, this module in addition enables the
104	caller to specify a callback function that is invoked whenever the
105	parser detects an error or wants to issue a warning message.</p>
106	<p>Apart from this additional function, this module provides the same
107	interface as the one applied by the <code>Regexp::Parser</code> module. For
108	more information, see <a href="../../Regexp/Parser.html">the Regexp::Parser manpage</a>.</p>
109	<p>
110	</p>
111	<hr />
112	<h1><a name="methods">METHODS</a></h1>
113	<p>The <code>Regexp::Parser::Perl58</code> module provides same methods as
114	<code>Regexp::Parser</code>. In addition, the following method is defined:</p>
115	<dl>
116	<dt><strong><a name="onerror" class="item">[<em>$onerror</em> =] <em>$parser</em>->onerror ([<em>$onerror</em>]);</a></strong>
117
118	<dd>
119	<p>Gets or sets the callback function that is invoked when an error or
120	warning is issued by the parser.</p>
121	</dd>
122	<dd>
123	<p>On setting, i.e. an argument is specified to the method, the argument
124	is set as the error handler function. The argument must be a <code>CODE</code>
125	reference or <code>undef</code>, which represents no-op.</p>
126	</dd>
127	<dd>
128	<p>On getting, i.e, no argument is specified to the method, the method
129	returns the current error handler function, if it has been set, or
130	returns <code>undef</code>.</p>
131	</dd>
132	<dd>
133	<p>The callback function, if specified, is invoked whenever the parser
134	wants to report an error or warning to the application. When invoked,
135	the callback function is given a set of key-value pairs describing the
136	error or warning.</p>
137	</dd>
138	<dl>
139	<dt><strong><a name="level_m_w" class="item">level => "m" / "w"</a></strong>
140
141	<dd>
142	<p>The level of the error. String <code>m</code> represents that it is a fatal
143	error which prevents the regular expression from being effective.
144	String <code>w</code> represents that it is a warning.</p>
145	</dd>
146	</li>
147	<dt><strong><a name="code_integer" class="item">code => <em>integer</em></a></strong>
148
149	<dd>
150	<p>The code that identifies the type of the error. See <a href="../../Regexp/Parser.html">the Regexp::Parser manpage</a>
151	for the list of error codes.</p>
152	</dd>
153	</li>
154	<dt><strong><a name="type_string" class="item">type => <em>string</em></a></strong>
155
156	<dd>
157	<p>The error type. The error type is a string that describes the type of
158	the error as a simple English text. It can be used as the first
159	argument of an <code>sprintf</code> call to obtain an error message, with the
160	<code>args</code> argument, like:</p>
161	</dd>
162	<dd>
163	<pre>
164	sprintf $args{type}, @{$args{args}}</pre>
165	</dd>
166	</li>
167	<dt><strong><a name="args_array_ref" class="item">args => <em>ARRAY-ref</em></a></strong>
168
169	<dd>
170	<p>The optional values that describes the error or warning. The number
171	and contents of the values depends on the type of the error.</p>
172	</dd>
173	</li>
174	<dt><strong><a name="valueref_scalar_ref_to_string" class="item">valueref => <em>SCALAR-ref-to-string</em></a></strong>
175
176	<dd>
177	<p>A reference to the string being parsed.</p>
178	</dd>
179	</li>
180	<dt><strong><a name="pos_start_integer" class="item">pos_start => <em>integer</em></a></strong>
181
182	<dd>
183	<p>The index in the string referenced by <code>valueref</code>, from which the
184	substring that causes the error or warning starts.</p>
185	</dd>
186	</li>
187	<dt><strong><a name="pos_end_integer" class="item">pos_end => <em>integer</em></a></strong>
188
189	<dd>
190	<p>The index in the string referenced by <code>valueref</code>, at which the
191	substring that causes the error or warning ends.</p>
192	</dd>
193	</li>
194	</dl>
195	</dl>
196	<p>
197	</p>
198	<hr />
199	<h1><a name="dependency">DEPENDENCY</a></h1>
200	<p>This module requires Perl 5.10.0 or later.</p>
201	<p>This module depends on the <code>Regexp::Parser</code> module.</p>
202	<p>
203	</p>
204	<hr />
205	<h1><a name="see_also">SEE ALSO</a></h1>
206	<p>The latest version of this module is available at
207	<a href="http://suika.fam.cx/regexp/">http://suika.fam.cx/regexp/</a>.</p>
208	<p>Regular expression visualizer
209	<a href="http://suika.fam.cx/regexp/visualizer/input">http://suika.fam.cx/regexp/visualizer/input</a>. It uses this module
210	to parse Perl 5.8 regular expressions.</p>
211	<p><a href="../../Regexp/Parser.html">the Regexp::Parser manpage</a> - The superclass, available from CPAN.</p>
212	<p><a href="../../Regexp/Parser/JavaScript.html">the Regexp::Parser::JavaScript manpage</a> - A parser for JavaScript regular
213	expresssions.</p>
214	<p>
215	</p>
216	<hr />
217	<h1><a name="development">DEVELOPMENT</a></h1>
218	<p>CVS log:
219	<a href="http://suika.fam.cx/regexp/lib/Regexp/Parser/Perl58.pm,cvslog">http://suika.fam.cx/regexp/lib/Regexp/Parser/Perl58.pm,cvslog</a>.</p>
220	<p>Bug tracking system: <a href="http://manakai.g.hatena.ne.jp/task/7/">http://manakai.g.hatena.ne.jp/task/7/</a>.</p>
221	<p>Note that this module does not support Perl 5.10 regular expression
222	extensions, as the module name suggests. They are expected to be
223	supported by another module.</p>
224	<p>
225	</p>
226	<hr />
227	<h1><a name="author">AUTHOR</a></h1>
228	<p>Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>>.</p>
229	<p>
230	</p>
231	<hr />
232	<h1><a name="license">LICENSE</a></h1>
233	<p>Copyright 2008-2009 Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>>.</p>
234	<p>This library is free software; you can redistribute it and/or modify
235	it under the same terms as Perl itself.</p>
236
237	</body>
238
239	</html>