1 /* 2 * Copyright (C) 2010 Google Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.streamhtmlparser; 18 19 /** 20 * Defines essential functionality that every parser we implement 21 * will support. This is then extended for HTML and Javascript parsing. 22 * 23 * <p>The typical caller is a Template System and will usually ask 24 * us to parse either a character at a time or a fragment of a template 25 * at a time, stopping only when it needs to determine the state of the 26 * parser for escaping purposes. 27 * 28 * <p>We will later add methods to save and restore the full state 29 * of the parser to better support conditional processing. 30 */ 31 public interface Parser { 32 33 // Consider using a Constants class instead 34 public final static ExternalState STATE_ERROR = 35 new ExternalState("STATE_ERROR"); 36 37 /** 38 * Tell the parser to process the provided {@code char}. Throws exception 39 * on an unrecoverable parsing error. 40 * 41 * @param input the character read 42 * @throws ParseException if an unrecoverable error occurred during parsing 43 */ 44 void parse(char input) throws ParseException; 45 46 /** 47 * Tell the parser to process the provided {@code String}. Throws exception 48 * on an unrecoverable parsing error. 49 * 50 * @param input the {@code String} to parse 51 * @throws ParseException if an unrecoverable error occurred during parsing 52 */ 53 void parse(String input) throws ParseException; 54 55 /** 56 * Reset the parser back to its initial default state. 57 */ 58 void reset(); 59 60 /** 61 * Returns the current state of the parser. May be {@link #STATE_ERROR} 62 * if the parser encountered an error. Such an error may be recoverable 63 * and the caller may want to continue parsing until {@link #parse(String)} 64 * returns {@code false}. 65 * 66 * @return current state of the parser 67 */ 68 ExternalState getState(); 69 70 /** 71 * Sets the current line number which is returned during error messages. 72 * @param lineNumber the line number to set in the parser 73 */ 74 void setLineNumber(int lineNumber); 75 76 /** 77 * Returns the current line number. 78 */ 79 int getLineNumber(); 80 81 /** 82 * Sets the current column number which is returned during error messages. 83 * @param columnNumber the column number to set in the parser 84 */ 85 void setColumnNumber(int columnNumber); 86 87 /** 88 * Returns the current column number. 89 */ 90 int getColumnNumber(); 91 } 92
