156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson/* 256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Copyright (C) 2010 Google Inc. 356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Licensed under the Apache License, Version 2.0 (the "License"); 556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * you may not use this file except in compliance with the License. 656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * You may obtain a copy of the License at 756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * http://www.apache.org/licenses/LICENSE-2.0 956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 1056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Unless required by applicable law or agreed to in writing, software 1156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * distributed under the License is distributed on an "AS IS" BASIS, 1256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * See the License for the specific language governing permissions and 1456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * limitations under the License. 1556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 1656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 1756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonpackage com.google.streamhtmlparser; 1856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 1956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson/** 2056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Defines essential functionality that every parser we implement 2156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * will support. This is then extended for HTML and Javascript parsing. 2256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 2356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * <p>The typical caller is a Template System and will usually ask 2456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * us to parse either a character at a time or a fragment of a template 2556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * at a time, stopping only when it needs to determine the state of the 2656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * parser for escaping purposes. 2756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 2856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * <p>We will later add methods to save and restore the full state 2956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * of the parser to better support conditional processing. 3056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 3156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodsonpublic interface Parser { 3256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 3356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson // Consider using a Constants class instead 3456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson public final static ExternalState STATE_ERROR = 3556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson new ExternalState("STATE_ERROR"); 3656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 3756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 3856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Tell the parser to process the provided {@code char}. Throws exception 3956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * on an unrecoverable parsing error. 4056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 4156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @param input the character read 4256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @throws ParseException if an unrecoverable error occurred during parsing 4356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 4456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void parse(char input) throws ParseException; 4556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 4656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 4756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Tell the parser to process the provided {@code String}. Throws exception 4856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * on an unrecoverable parsing error. 4956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 5056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @param input the {@code String} to parse 5156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @throws ParseException if an unrecoverable error occurred during parsing 5256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 5356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void parse(String input) throws ParseException; 5456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 5556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 5656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Reset the parser back to its initial default state. 5756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 5856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void reset(); 5956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 6056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 6156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Returns the current state of the parser. May be {@link #STATE_ERROR} 6256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * if the parser encountered an error. Such an error may be recoverable 6356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * and the caller may want to continue parsing until {@link #parse(String)} 6456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * returns {@code false}. 6556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * 6656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @return current state of the parser 6756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 6856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson ExternalState getState(); 6956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 7056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 7156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Sets the current line number which is returned during error messages. 7256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @param lineNumber the line number to set in the parser 7356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 7456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void setLineNumber(int lineNumber); 7556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 7656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 7756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Returns the current line number. 7856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 7956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson int getLineNumber(); 8056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 8156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 8256ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Sets the current column number which is returned during error messages. 8356ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * @param columnNumber the column number to set in the parser 8456ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 8556ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson void setColumnNumber(int columnNumber); 8656ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson 8756ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson /** 8856ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson * Returns the current column number. 8956ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson */ 9056ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson int getColumnNumber(); 9156ed4167b942ec265f9cee70ac4d71d10b3835ceBen Dodson} 92