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.net;
016
017import com.google.common.annotations.GwtCompatible;
018import com.google.common.escape.Escaper;
019
020/**
021 * {@code Escaper} instances suitable for strings to be included in particular sections of URLs.
022 *
023 * <p>If the resulting URLs are inserted into an HTML or XML document, they will require additional
024 * escaping with {@link com.google.common.html.HtmlEscapers} or {@link
025 * com.google.common.xml.XmlEscapers}.
026 *
027 * @author David Beaumont
028 * @author Chris Povirk
029 * @since 15.0
030 */
031@GwtCompatible
032@ElementTypesAreNonnullByDefault
033public final class UrlEscapers {
034  private UrlEscapers() {}
035
036  // For each xxxEscaper() method, please add links to external reference pages
037  // that are considered authoritative for the behavior of that escaper.
038
039  static final String URL_FORM_PARAMETER_OTHER_SAFE_CHARS = "-_.*";
040
041  static final String URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS =
042      "-._~" // Unreserved characters.
043          + "!$'()*,;&=" // The subdelim characters (excluding '+').
044          + "@:"; // The gendelim characters permitted in paths.
045
046  /**
047   * Returns an {@link Escaper} instance that escapes strings so they can be safely included in <a
048   * href="https://url.spec.whatwg.org/#application-x-www-form-urlencoded-percent-encode-set">URL
049   * form parameter names and values</a>. Escaping is performed with the UTF-8 character encoding.
050   * The caller is responsible for <a
051   * href="https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#multipart-form-data">replacing
052   * any unpaired carriage return or line feed characters with a CR+LF pair</a> on any non-file
053   * inputs before escaping them with this escaper.
054   *
055   * <p>When escaping a String, the following rules apply:
056   *
057   * <ul>
058   *   <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain
059   *       the same.
060   *   <li>The special characters ".", "-", "*", and "_" remain the same.
061   *   <li>The space character " " is converted into a plus sign "+".
062   *   <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
063   *       byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
064   *       uppercase, hexadecimal representation of the byte value.
065   * </ul>
066   *
067   * <p>This escaper is suitable for escaping parameter names and values even when <a
068   * href="https://www.w3.org/TR/html401/appendix/notes.html#h-B.2.2">using the non-standard
069   * semicolon</a>, rather than the ampersand, as a parameter delimiter. Nevertheless, we recommend
070   * using the ampersand unless you must interoperate with systems that require semicolons.
071   *
072   * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
073   * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
074   *
075   */
076  public static Escaper urlFormParameterEscaper() {
077    return URL_FORM_PARAMETER_ESCAPER;
078  }
079
080  private static final Escaper URL_FORM_PARAMETER_ESCAPER =
081      new PercentEscaper(URL_FORM_PARAMETER_OTHER_SAFE_CHARS, true);
082
083  /**
084   * Returns an {@link Escaper} instance that escapes strings so they can be safely included in <a
085   * href="https://url.spec.whatwg.org/#syntax-url-path-segment">URL path segments</a>. The returned
086   * escaper escapes all non-ASCII characters, even though <a
087   * href="https://url.spec.whatwg.org/#url-code-points">many of these are accepted in modern
088   * URLs</a>. (<a href="https://url.spec.whatwg.org/#path-state">If the escaper were to leave these
089   * characters unescaped, they would be escaped by the consumer at parse time, anyway.</a>)
090   * Additionally, the escaper escapes the slash character ("/"). While slashes are acceptable in
091   * URL paths, they are considered by the specification to be separators between "path segments."
092   * This implies that, if you wish for your path to contain slashes, you must escape each segment
093   * separately and then join them.
094   *
095   * <p>When escaping a String, the following rules apply:
096   *
097   * <ul>
098   *   <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain
099   *       the same.
100   *   <li>The unreserved characters ".", "-", "~", and "_" remain the same.
101   *   <li>The general delimiters "@" and ":" remain the same.
102   *   <li>The subdelimiters "!", "$", "&amp;", "'", "(", ")", "*", "+", ",", ";", and "=" remain
103   *       the same.
104   *   <li>The space character " " is converted into %20.
105   *   <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
106   *       byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
107   *       uppercase, hexadecimal representation of the byte value.
108   * </ul>
109   *
110   * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
111   * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
112   */
113  public static Escaper urlPathSegmentEscaper() {
114    return URL_PATH_SEGMENT_ESCAPER;
115  }
116
117  private static final Escaper URL_PATH_SEGMENT_ESCAPER =
118      new PercentEscaper(URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS + "+", false);
119
120  /**
121   * Returns an {@link Escaper} instance that escapes strings so they can be safely included in a <a
122   * href="https://url.spec.whatwg.org/#concept-url-fragment">URL fragment</a>. The returned escaper
123   * escapes all non-ASCII characters.
124   *
125   * <p>When escaping a String, the following rules apply:
126   *
127   * <ul>
128   *   <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain
129   *       the same.
130   *   <li>The unreserved characters ".", "-", "~", and "_" remain the same.
131   *   <li>The general delimiters "@" and ":" remain the same.
132   *   <li>The subdelimiters "!", "$", "&amp;", "'", "(", ")", "*", "+", ",", ";", and "=" remain
133   *       the same.
134   *   <li>The space character " " is converted into %20.
135   *   <li>Fragments allow unescaped "/" and "?", so they remain the same.
136   *   <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
137   *       byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
138   *       uppercase, hexadecimal representation of the byte value.
139   * </ul>
140   *
141   * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
142   * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
143   */
144  public static Escaper urlFragmentEscaper() {
145    return URL_FRAGMENT_ESCAPER;
146  }
147
148  private static final Escaper URL_FRAGMENT_ESCAPER =
149      new PercentEscaper(URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS + "+/?", false);
150}