KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > oro > text > regex > PatternCompiler


1 package org.apache.oro.text.regex;
2
3 /* ====================================================================
4  * The Apache Software License, Version 1.1
5  *
6  * Copyright (c) 2000 The Apache Software Foundation. All rights
7  * reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  *
16  * 2. Redistributions in binary form must reproduce the above copyright
17  * notice, this list of conditions and the following disclaimer in
18  * the documentation and/or other materials provided with the
19  * distribution.
20  *
21  * 3. The end-user documentation included with the redistribution,
22  * if any, must include the following acknowledgment:
23  * "This product includes software developed by the
24  * Apache Software Foundation (http://www.apache.org/)."
25  * Alternately, this acknowledgment may appear in the software itself,
26  * if and wherever such third-party acknowledgments normally appear.
27  *
28  * 4. The names "Apache" and "Apache Software Foundation", "Jakarta-Oro"
29  * must not be used to endorse or promote products derived from this
30  * software without prior written permission. For written
31  * permission, please contact apache@apache.org.
32  *
33  * 5. Products derived from this software may not be called "Apache"
34  * or "Jakarta-Oro", nor may "Apache" or "Jakarta-Oro" appear in their
35  * name, without prior written permission of the Apache Software Foundation.
36  *
37  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48  * SUCH DAMAGE.
49  * ====================================================================
50  *
51  * This software consists of voluntary contributions made by many
52  * individuals on behalf of the Apache Software Foundation. For more
53  * information on the Apache Software Foundation, please see
54  * <http://www.apache.org/>.
55  *
56  * Portions of this software are based upon software originally written
57  * by Daniel F. Savarese. We appreciate his contributions.
58  */
59
60 /**
61  * The PatternCompiler interface defines the operations a regular
62  * expression compiler must implement. However, the types of
63  * regular expressions recognized by a compiler and the Pattern
64  * implementations produced as a result of compilation are not
65  * restricted.
66  * <p>
67  * A PatternCompiler instance is used to compile the string representation
68  * (either as a String or char[]) of a regular expression into a Pattern
69  * instance. The Pattern can then be used in conjunction with the appropriate
70  * PatternMatcher instance to perform pattern searches. A form
71  * of use might be:
72  * <p>
73  * <blockquote><pre>
74  * PatternCompiler compiler;
75  * PatternMatcher matcher;
76  * Pattern pattern;
77  * String input;
78  *
79  * // Initialization of compiler, matcher, and input omitted;
80  *
81  * try {
82  * pattern = compiler.compile("\\d+");
83  * } catch(MalformedPatternException e) {
84  * System.out.println("Bad pattern.");
85  * System.out.println(e.getMessage());
86  * System.exit(1);
87  * }
88  *
89  *
90  * if(matcher.matches(input, pattern))
91  * System.out.println(input + " is a number");
92  * else
93  * System.out.println(input + " is not a number");
94  *
95  * </pre></blockquote>
96  * <p>
97  * Specific PatternCompiler implementations such as Perl5Compiler may have
98  * variations of the compile() methods that take extra options affecting
99  * the compilation of a pattern. However, the PatternCompiler method
100  * implementations should provide the default behavior of the class.
101
102  @author <a HREF="dfs@savarese.org">Daniel F. Savarese</a>
103  @version $Id: PatternCompiler.java,v 1.1.1.1 2000/07/23 23:08:51 jon Exp $
104
105  * @see Pattern
106  * @see PatternMatcher
107  * @see MalformedPatternException
108  */
109 public interface PatternCompiler {
110   /**
111    * Compiles a regular expression into a data structure that can be used
112    * by a PatternMatcher implementation to perform pattern matching.
113    * <p>
114    * @param pattern A regular expression to compile.
115    * @return A Pattern instance constituting the compiled regular expression.
116    * @exception MalformedPatternException If the compiled expression
117    * does not conform to the grammar understood by the PatternCompiler or
118    * if some other error in the expression is encountered.
119    */
120   public Pattern compile(String JavaDoc pattern) throws MalformedPatternException;
121
122
123   /**
124    * Compiles a regular expression into a data structure that can be
125    * used by a PatternMatcher implementation to perform pattern matching.
126    * Additional regular expression syntax specific options can be passed
127    * as a bitmask of options.
128    * <p>
129    * @param pattern A regular expression to compile.
130    * @param options A set of flags giving the compiler instructions on
131    * how to treat the regular expression. The flags
132    * are a logical OR of any number of the allowable
133    * constants permitted by the PatternCompiler
134    * implementation.
135    * @return A Pattern instance constituting the compiled regular expression.
136    * @exception MalformedPatternException If the compiled expression
137    * does not conform to the grammar understood by the PatternCompiler or
138    * if some other error in the expression is encountered.
139    */
140   public Pattern compile(String JavaDoc pattern, int options)
141        throws MalformedPatternException;
142
143
144   /**
145    * Compiles a regular expression into a data structure that can be used
146    * by a PatternMatcher implementation to perform pattern matching.
147    * <p>
148    * @param pattern A regular expression to compile.
149    * @return A Pattern instance constituting the compiled regular expression.
150    * @exception MalformedPatternException If the compiled expression
151    * does not conform to the grammar understood by the PatternCompiler or
152    * if some other error in the expression is encountered.
153    */
154   public Pattern compile(char[] pattern) throws MalformedPatternException;
155
156
157   /**
158    * Compiles a regular expression into a data structure that can be
159    * used by a PatternMatcher implementation to perform pattern matching.
160    * Additional regular expression syntax specific options can be passed
161    * as a bitmask of options.
162    * <p>
163    * @param pattern A regular expression to compile.
164    * @param options A set of flags giving the compiler instructions on
165    * how to treat the regular expression. The flags
166    * are a logical OR of any number of the allowable
167    * constants permitted by the PatternCompiler
168    * implementation.
169    * @return A Pattern instance constituting the compiled regular expression.
170    * @exception MalformedPatternException If the compiled expression
171    * does not conform to the grammar understood by the PatternCompiler or
172    * if some other error in the expression is encountered.
173    */
174   public Pattern compile(char[] pattern, int options)
175        throws MalformedPatternException;
176
177 }
178
Popular Tags