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
17package 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 */
31public 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