001/* 002 * Copyright (C) 2009 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.escape; 016 017import static com.google.common.base.Preconditions.checkNotNull; 018 019import com.google.common.annotations.Beta; 020import com.google.common.annotations.GwtCompatible; 021import com.google.errorprone.annotations.CanIgnoreReturnValue; 022import java.util.HashMap; 023import java.util.Map; 024import org.checkerframework.checker.nullness.qual.Nullable; 025 026/** 027 * Static utility methods pertaining to {@link Escaper} instances. 028 * 029 * @author Sven Mawson 030 * @author David Beaumont 031 * @since 15.0 032 */ 033@Beta 034@GwtCompatible 035public final class Escapers { 036 private Escapers() {} 037 038 /** 039 * Returns an {@link Escaper} that does no escaping, passing all character data through unchanged. 040 */ 041 public static Escaper nullEscaper() { 042 return NULL_ESCAPER; 043 } 044 045 // An Escaper that efficiently performs no escaping. 046 // Extending CharEscaper (instead of Escaper) makes Escapers.compose() easier. 047 private static final Escaper NULL_ESCAPER = 048 new CharEscaper() { 049 @Override 050 public String escape(String string) { 051 return checkNotNull(string); 052 } 053 054 @Override 055 protected char[] escape(char c) { 056 // TODO: Fix tests not to call this directly and make it throw an error. 057 return null; 058 } 059 }; 060 061 /** 062 * Returns a builder for creating simple, fast escapers. A builder instance can be reused and each 063 * escaper that is created will be a snapshot of the current builder state. Builders are not 064 * thread safe. 065 * 066 * <p>The initial state of the builder is such that: 067 * 068 * <ul> 069 * <li>There are no replacement mappings 070 * <li>{@code safeMin == Character.MIN_VALUE} 071 * <li>{@code safeMax == Character.MAX_VALUE} 072 * <li>{@code unsafeReplacement == null} 073 * </ul> 074 * 075 * <p>For performance reasons escapers created by this builder are not Unicode aware and will not 076 * validate the well-formedness of their input. 077 */ 078 public static Builder builder() { 079 return new Builder(); 080 } 081 082 /** 083 * A builder for simple, fast escapers. 084 * 085 * <p>Typically an escaper needs to deal with the escaping of high valued characters or code 086 * points. In these cases it is necessary to extend either {@link ArrayBasedCharEscaper} or {@link 087 * ArrayBasedUnicodeEscaper} to provide the desired behavior. However this builder is suitable for 088 * creating escapers that replace a relative small set of characters. 089 * 090 * @author David Beaumont 091 * @since 15.0 092 */ 093 @Beta 094 public static final class Builder { 095 private final Map<Character, String> replacementMap = new HashMap<>(); 096 private char safeMin = Character.MIN_VALUE; 097 private char safeMax = Character.MAX_VALUE; 098 private String unsafeReplacement = null; 099 100 // The constructor is exposed via the builder() method above. 101 private Builder() {} 102 103 /** 104 * Sets the safe range of characters for the escaper. Characters in this range that have no 105 * explicit replacement are considered 'safe' and remain unescaped in the output. If {@code 106 * safeMax < safeMin} then the safe range is empty. 107 * 108 * @param safeMin the lowest 'safe' character 109 * @param safeMax the highest 'safe' character 110 * @return the builder instance 111 */ 112 @CanIgnoreReturnValue 113 public Builder setSafeRange(char safeMin, char safeMax) { 114 this.safeMin = safeMin; 115 this.safeMax = safeMax; 116 return this; 117 } 118 119 /** 120 * Sets the replacement string for any characters outside the 'safe' range that have no explicit 121 * replacement. If {@code unsafeReplacement} is {@code null} then no replacement will occur, if 122 * it is {@code ""} then the unsafe characters are removed from the output. 123 * 124 * @param unsafeReplacement the string to replace unsafe characters 125 * @return the builder instance 126 */ 127 @CanIgnoreReturnValue 128 public Builder setUnsafeReplacement(@Nullable String unsafeReplacement) { 129 this.unsafeReplacement = unsafeReplacement; 130 return this; 131 } 132 133 /** 134 * Adds a replacement string for the given input character. The specified character will be 135 * replaced by the given string whenever it occurs in the input, irrespective of whether it lies 136 * inside or outside the 'safe' range. 137 * 138 * @param c the character to be replaced 139 * @param replacement the string to replace the given character 140 * @return the builder instance 141 * @throws NullPointerException if {@code replacement} is null 142 */ 143 @CanIgnoreReturnValue 144 public Builder addEscape(char c, String replacement) { 145 checkNotNull(replacement); 146 // This can replace an existing character (the builder is re-usable). 147 replacementMap.put(c, replacement); 148 return this; 149 } 150 151 /** Returns a new escaper based on the current state of the builder. */ 152 public Escaper build() { 153 return new ArrayBasedCharEscaper(replacementMap, safeMin, safeMax) { 154 private final char[] replacementChars = 155 unsafeReplacement != null ? unsafeReplacement.toCharArray() : null; 156 157 @Override 158 protected char[] escapeUnsafe(char c) { 159 return replacementChars; 160 } 161 }; 162 } 163 } 164 165 /** 166 * Returns a {@link UnicodeEscaper} equivalent to the given escaper instance. If the escaper is 167 * already a UnicodeEscaper then it is simply returned, otherwise it is wrapped in a 168 * UnicodeEscaper. 169 * 170 * <p>When a {@link CharEscaper} escaper is wrapped by this method it acquires extra behavior with 171 * respect to the well-formedness of Unicode character sequences and will throw {@link 172 * IllegalArgumentException} when given bad input. 173 * 174 * @param escaper the instance to be wrapped 175 * @return a UnicodeEscaper with the same behavior as the given instance 176 * @throws NullPointerException if escaper is null 177 * @throws IllegalArgumentException if escaper is not a UnicodeEscaper or a CharEscaper 178 */ 179 static UnicodeEscaper asUnicodeEscaper(Escaper escaper) { 180 checkNotNull(escaper); 181 if (escaper instanceof UnicodeEscaper) { 182 return (UnicodeEscaper) escaper; 183 } else if (escaper instanceof CharEscaper) { 184 return wrap((CharEscaper) escaper); 185 } 186 // In practice this shouldn't happen because it would be very odd not to 187 // extend either CharEscaper or UnicodeEscaper for non trivial cases. 188 throw new IllegalArgumentException( 189 "Cannot create a UnicodeEscaper from: " + escaper.getClass().getName()); 190 } 191 192 /** 193 * Returns a string that would replace the given character in the specified escaper, or {@code 194 * null} if no replacement should be made. This method is intended for use in tests through the 195 * {@code EscaperAsserts} class; production users of {@link CharEscaper} should limit themselves 196 * to its public interface. 197 * 198 * @param c the character to escape if necessary 199 * @return the replacement string, or {@code null} if no escaping was needed 200 */ 201 public static String computeReplacement(CharEscaper escaper, char c) { 202 return stringOrNull(escaper.escape(c)); 203 } 204 205 /** 206 * Returns a string that would replace the given character in the specified escaper, or {@code 207 * null} if no replacement should be made. This method is intended for use in tests through the 208 * {@code EscaperAsserts} class; production users of {@link UnicodeEscaper} should limit 209 * themselves to its public interface. 210 * 211 * @param cp the Unicode code point to escape if necessary 212 * @return the replacement string, or {@code null} if no escaping was needed 213 */ 214 public static String computeReplacement(UnicodeEscaper escaper, int cp) { 215 return stringOrNull(escaper.escape(cp)); 216 } 217 218 private static String stringOrNull(char[] in) { 219 return (in == null) ? null : new String(in); 220 } 221 222 /** Private helper to wrap a CharEscaper as a UnicodeEscaper. */ 223 private static UnicodeEscaper wrap(final CharEscaper escaper) { 224 return new UnicodeEscaper() { 225 @Override 226 protected char[] escape(int cp) { 227 // If a code point maps to a single character, just escape that. 228 if (cp < Character.MIN_SUPPLEMENTARY_CODE_POINT) { 229 return escaper.escape((char) cp); 230 } 231 // Convert the code point to a surrogate pair and escape them both. 232 // Note: This code path is horribly slow and typically allocates 4 new 233 // char[] each time it is invoked. However this avoids any 234 // synchronization issues and makes the escaper thread safe. 235 char[] surrogateChars = new char[2]; 236 Character.toChars(cp, surrogateChars, 0); 237 char[] hiChars = escaper.escape(surrogateChars[0]); 238 char[] loChars = escaper.escape(surrogateChars[1]); 239 240 // If either hiChars or lowChars are non-null, the CharEscaper is trying 241 // to escape the characters of a surrogate pair separately. This is 242 // uncommon and applies only to escapers that assume UCS-2 rather than 243 // UTF-16. See: http://en.wikipedia.org/wiki/UTF-16/UCS-2 244 if (hiChars == null && loChars == null) { 245 // We expect this to be the common code path for most escapers. 246 return null; 247 } 248 // Combine the characters and/or escaped sequences into a single array. 249 int hiCount = hiChars != null ? hiChars.length : 1; 250 int loCount = loChars != null ? loChars.length : 1; 251 char[] output = new char[hiCount + loCount]; 252 if (hiChars != null) { 253 // TODO: Is this faster than System.arraycopy() for small arrays? 254 for (int n = 0; n < hiChars.length; ++n) { 255 output[n] = hiChars[n]; 256 } 257 } else { 258 output[0] = surrogateChars[0]; 259 } 260 if (loChars != null) { 261 for (int n = 0; n < loChars.length; ++n) { 262 output[hiCount + n] = loChars[n]; 263 } 264 } else { 265 output[hiCount] = surrogateChars[1]; 266 } 267 return output; 268 } 269 }; 270 } 271}