001: /*
002: * $Id: PatternCompiler.java,v 1.7 2003/11/07 20:16:25 dfs Exp $
003: *
004: * ====================================================================
005: * The Apache Software License, Version 1.1
006: *
007: * Copyright (c) 2000 The Apache Software Foundation. All rights
008: * reserved.
009: *
010: * Redistribution and use in source and binary forms, with or without
011: * modification, are permitted provided that the following conditions
012: * are met:
013: *
014: * 1. Redistributions of source code must retain the above copyright
015: * notice, this list of conditions and the following disclaimer.
016: *
017: * 2. Redistributions in binary form must reproduce the above copyright
018: * notice, this list of conditions and the following disclaimer in
019: * the documentation and/or other materials provided with the
020: * distribution.
021: *
022: * 3. The end-user documentation included with the redistribution,
023: * if any, must include the following acknowledgment:
024: * "This product includes software developed by the
025: * Apache Software Foundation (http://www.apache.org/)."
026: * Alternately, this acknowledgment may appear in the software itself,
027: * if and wherever such third-party acknowledgments normally appear.
028: *
029: * 4. The names "Apache" and "Apache Software Foundation", "Jakarta-Oro"
030: * must not be used to endorse or promote products derived from this
031: * software without prior written permission. For written
032: * permission, please contact apache@apache.org.
033: *
034: * 5. Products derived from this software may not be called "Apache"
035: * or "Jakarta-Oro", nor may "Apache" or "Jakarta-Oro" appear in their
036: * name, without prior written permission of the Apache Software Foundation.
037: *
038: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
039: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
040: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
041: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
042: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
043: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
044: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
045: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
046: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
047: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
048: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
049: * SUCH DAMAGE.
050: * ====================================================================
051: *
052: * This software consists of voluntary contributions made by many
053: * individuals on behalf of the Apache Software Foundation. For more
054: * information on the Apache Software Foundation, please see
055: * <http://www.apache.org/>.
056: */
057:
058: package org.apache.oro.text.regex;
059:
060: /**
061: * The PatternCompiler interface defines the operations a regular
062: * expression compiler must implement. However, the types of
063: * regular expressions recognized by a compiler and the Pattern
064: * implementations produced as a result of compilation are not
065: * restricted.
066: * <p>
067: * A PatternCompiler instance is used to compile the string representation
068: * (either as a String or char[]) of a regular expression into a Pattern
069: * instance. The Pattern can then be used in conjunction with the appropriate
070: * PatternMatcher instance to perform pattern searches. A form
071: * of use might be:
072: * <p>
073: * <blockquote><pre>
074: * PatternCompiler compiler;
075: * PatternMatcher matcher;
076: * Pattern pattern;
077: * String input;
078: *
079: * // Initialization of compiler, matcher, and input omitted;
080: *
081: * try {
082: * pattern = compiler.compile("\\d+");
083: * } catch(MalformedPatternException e) {
084: * System.out.println("Bad pattern.");
085: * System.out.println(e.getMessage());
086: * System.exit(1);
087: * }
088: *
089: *
090: * if(matcher.matches(input, pattern))
091: * System.out.println(input + " is a number");
092: * else
093: * System.out.println(input + " is not a number");
094: *
095: * </pre></blockquote>
096: * <p>
097: * Specific PatternCompiler implementations such as Perl5Compiler may have
098: * variations of the compile() methods that take extra options affecting
099: * the compilation of a pattern. However, the PatternCompiler method
100: * implementations should provide the default behavior of the class.
101: *
102: * @version @version@
103: * @since 1.0
104: * @see Pattern
105: * @see PatternMatcher
106: * @see MalformedPatternException
107: */
108: public interface PatternCompiler {
109: /**
110: * Compiles a regular expression into a data structure that can be used
111: * by a PatternMatcher implementation to perform pattern matching.
112: * <p>
113: * @param pattern A regular expression to compile.
114: * @return A Pattern instance constituting the compiled regular expression.
115: * @exception MalformedPatternException If the compiled expression
116: * does not conform to the grammar understood by the PatternCompiler or
117: * if some other error in the expression is encountered.
118: */
119: public Pattern compile(String pattern)
120: throws MalformedPatternException;
121:
122: /**
123: * Compiles a regular expression into a data structure that can be
124: * used by a PatternMatcher implementation to perform pattern matching.
125: * Additional regular expression syntax specific options can be passed
126: * as a bitmask of options.
127: * <p>
128: * @param pattern A regular expression to compile.
129: * @param options A set of flags giving the compiler instructions on
130: * how to treat the regular expression. The flags
131: * are a logical OR of any number of the allowable
132: * constants permitted by the PatternCompiler
133: * implementation.
134: * @return A Pattern instance constituting the compiled regular expression.
135: * @exception MalformedPatternException If the compiled expression
136: * does not conform to the grammar understood by the PatternCompiler or
137: * if some other error in the expression is encountered.
138: */
139: public Pattern compile(String pattern, int options)
140: throws MalformedPatternException;
141:
142: /**
143: * Compiles a regular expression into a data structure that can be used
144: * by a PatternMatcher implementation to perform pattern matching.
145: * <p>
146: * @param pattern A regular expression to compile.
147: * @return A Pattern instance constituting the compiled regular expression.
148: * @exception MalformedPatternException If the compiled expression
149: * does not conform to the grammar understood by the PatternCompiler or
150: * if some other error in the expression is encountered.
151: */
152: public Pattern compile(char[] pattern)
153: throws MalformedPatternException;
154:
155: /**
156: * Compiles a regular expression into a data structure that can be
157: * used by a PatternMatcher implementation to perform pattern matching.
158: * Additional regular expression syntax specific options can be passed
159: * as a bitmask of options.
160: * <p>
161: * @param pattern A regular expression to compile.
162: * @param options A set of flags giving the compiler instructions on
163: * how to treat the regular expression. The flags
164: * are a logical OR of any number of the allowable
165: * constants permitted by the PatternCompiler
166: * implementation.
167: * @return A Pattern instance constituting the compiled regular expression.
168: * @exception MalformedPatternException If the compiled expression
169: * does not conform to the grammar understood by the PatternCompiler or
170: * if some other error in the expression is encountered.
171: */
172: public Pattern compile(char[] pattern, int options)
173: throws MalformedPatternException;
174:
175: }
|