1 /* Copyright (c) 2008 Google Inc. 2 * 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 package org.yaml.snakeyaml.external.com.google.gdata.util.common.base; 17 18 /** 19 * An object that converts literal text into a format safe for inclusion in a 20 * particular context (such as an XML document). Typically (but not always), the 21 * inverse process of "unescaping" the text is performed automatically by the 22 * relevant parser. 23 * 24 * <p> 25 * For example, an XML escaper would convert the literal string 26 * {@code "Foo<Bar>"} into {@code "Foo<Bar>"} to prevent {@code "<Bar>"} 27 * from being confused with an XML tag. When the resulting XML document is 28 * parsed, the parser API will return this text as the original literal string 29 * {@code "Foo<Bar>"}. 30 * 31 * <p> 32 * An {@code Escaper} instance is required to be stateless, and safe when used 33 * concurrently by multiple threads. 34 * 35 * <p> 36 * Several popular escapers are defined as constants in the class 37 * {@link CharEscapers}. To create your own escapers, use 38 * {@link CharEscaperBuilder}, or extend {@link CharEscaper} or 39 * {@code UnicodeEscaper}. 40 * 41 * 42 */ 43 public interface Escaper { 44 /** 45 * Returns the escaped form of a given literal string. 46 * 47 * <p> 48 * Note that this method may treat input characters differently depending on 49 * the specific escaper implementation. 50 * <ul> 51 * <li>{@link UnicodeEscaper} handles <a 52 * href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> correctly, 53 * including surrogate character pairs. If the input is badly formed the 54 * escaper should throw {@link IllegalArgumentException}. 55 * <li>{@link CharEscaper} handles Java characters independently and does 56 * not verify the input for well formed characters. A CharEscaper should not 57 * be used in situations where input is not guaranteed to be restricted to 58 * the Basic Multilingual Plane (BMP). 59 * </ul> 60 * 61 * @param string 62 * the literal string to be escaped 63 * @return the escaped form of {@code string} 64 * @throws NullPointerException 65 * if {@code string} is null 66 * @throws IllegalArgumentException 67 * if {@code string} contains badly formed UTF-16 or cannot be 68 * escaped for any other reason 69 */ 70 public String escape(String string); 71 72 /** 73 * Returns an {@code Appendable} instance which automatically escapes all 74 * text appended to it before passing the resulting text to an underlying 75 * {@code Appendable}. 76 * 77 * <p> 78 * Note that this method may treat input characters differently depending on 79 * the specific escaper implementation. 80 * <ul> 81 * <li>{@link UnicodeEscaper} handles <a 82 * href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> correctly, 83 * including surrogate character pairs. If the input is badly formed the 84 * escaper should throw {@link IllegalArgumentException}. 85 * <li>{@link CharEscaper} handles Java characters independently and does 86 * not verify the input for well formed characters. A CharEscaper should not 87 * be used in situations where input is not guaranteed to be restricted to 88 * the Basic Multilingual Plane (BMP). 89 * </ul> 90 * 91 * @param out 92 * the underlying {@code Appendable} to append escaped output to 93 * @return an {@code Appendable} which passes text to {@code out} after 94 * escaping it. 95 */ 96 public Appendable escape(Appendable out); 97 }