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	wakaba	1.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>