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