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 import com.google.common.base.Preconditions;
20 
21 /**
22  * A representation of the parser state suitable for use by the caller
23  * of the Parser. The meaning of each state and therefore which action
24  * the caller should perform on that state is not self-evident. In particular,
25  * it depends on which parser is used (currently {@link HtmlParser} and
26  * {@link JavascriptParser}). For examples, you will have to look
27  * at the <code>Google Template System</code> and <code>ClearSilver</code>
28  * both of which support Auto-Escaping by interfacing with our parser
29  * (using the parser written in C++).
30  *
31  * <p>The caller of the Parser will query for the current parser state at
32  * points of interest during parsing of templates. Based on the parser's
33  * current state as represented by this class, the caller can determine
34  * the appropriate escaping to apply.
35  *
36  * <p>Note: Given this class is external-facing, I considered creating
37  * an interface but it is not likely we'll ever need to add more flexibility
38  * and the class is so simple, I figured it was not warranted.
39  *
40  *
41  * @see HtmlParser
42  * @see JavascriptParser
43  */
44 public class ExternalState {
45 
46   private final String name;
47 
48   /**
49    * Creates an {@code ExternalState} object.
50    *
51    * @param name the name to assign to that state
52    * @see HtmlParser
53    * @see JavascriptParser
54    */
ExternalState(String name)55   public ExternalState(String name) {
56     Preconditions.checkNotNull(name);   // Developer error if it happens.
57     this.name = name;
58   }
59 
60   /**
61    * Returns the name of the object. The name is only needed
62    * to provide human-readable information when debugging.
63    *
64    * @return the name of that object
65    */
getName()66   public String getName() {
67     return name;
68   }
69 
70   /**
71    * Returns the string representation of this external state.
72    * The details of this representation are subject to change.
73    */
74   @Override
toString()75   public String toString() {
76     return String.format("ExternalState: %s", name);
77   }
78 }
79