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    */
parse(char input)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    */
parse(String input)53   void parse(String input) throws ParseException;
54 
55   /**
56    * Reset the parser back to its initial default state.
57    */
reset()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    */
getState()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    */
setLineNumber(int lineNumber)74   void setLineNumber(int lineNumber);
75 
76   /**
77    * Returns the current line number.
78    */
getLineNumber()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    */
setColumnNumber(int columnNumber)85   void setColumnNumber(int columnNumber);
86 
87   /**
88    * Returns the current column number.
89    */
getColumnNumber()90   int getColumnNumber();
91 }
92