From 19896b3034813663f790ed85d3e253fd9ff00738 Mon Sep 17 00:00:00 2001 From: Julie Heard <55280278+julieheard@users.noreply.github.com> Date: Thu, 9 Feb 2023 10:35:55 +0000 Subject: [PATCH] Updating the descriptions for the escape/encode functions (#7606) * Updating the descriptions for the escape/encode functions Adding explanations and examples to the encode and escape functions * Updated description for encode I have edited some of the descriptions to bring them in line with the documentation over on husdon.Util * Changed leading and trailing spaces on encode I left one space at the end and added a note to say how a blank space is rendered * Removed trailing whitespace to satisfy checkstyle * Preserve formatting and escape HTML tags * Update core/src/main/java/hudson/Functions.java Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> * Changed escaping on examples so they rendered properly in the javadoc I was tempted to use {@literal &} notation but this added blank spaces, making the examples look strange. Instead I have used the &amp; notation. * Update core/src/main/java/hudson/Functions.java Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> * Update core/src/main/java/hudson/Functions.java Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> * Update core/src/main/java/hudson/Functions.java Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> * Update core/src/main/java/hudson/Functions.java Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> * Update core/src/main/java/hudson/Functions.java Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> * Update core/src/main/java/hudson/Functions.java Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> --------- Co-authored-by: Alexander Brandes Co-authored-by: Daniel Beck <1831569+daniel-beck@users.noreply.github.com> --- core/src/main/java/hudson/Functions.java | 60 ++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/core/src/main/java/hudson/Functions.java b/core/src/main/java/hudson/Functions.java index b7f05208e8..9352944e3d 100644 --- a/core/src/main/java/hudson/Functions.java +++ b/core/src/main/java/hudson/Functions.java @@ -758,6 +758,19 @@ public class Functions { return s.indexOf('\r') >= 0 || s.indexOf('\n') >= 0; } + /** + * Percent-encodes space and non-ASCII UTF-8 characters for use in URLs. + * 
+     * Input example  1: !"£$%^&*()_+}{:@~?><|¬`,./;'#[]- =
+     * Output example 1: !"%C2%A3$%^&*()_+}{:@~?><|%C2%AC`,./;'#[]-%20=
+     *
+ * Notes: + * + */ public static String encode(String s) { return Util.encode(s); } @@ -766,6 +779,13 @@ public class Functions { * Shortcut function for calling {@link URLEncoder#encode(String,String)} (with UTF-8 encoding).
* Useful for encoding URL query parameters in jelly code (as in {@code "...?param=${h.urlEncode(something)}"}).
* For convenience in jelly code, it also accepts null parameter, and then returns an empty string. + * 
+     * Input example  1: & " ' < >
+     * Output example 1: %26+%22+%27+%3C+%3E
+     * Input example  2: !"£$%^&*()_+}{:@~?><|¬`,./;'#[]-=
+     * Output example 2: %21%22%C2%A3%24%25%5E%26*%28%29_%2B%7D%7B%3A%40%7E%3F%3E%3C%7C%C2%AC%60%2C.%2F%3B%27%23%5B%5D-%3D
+     *
+ * Note: A blank space will render as + (You can see this in above examples) * * @since 2.200 */ @@ -776,10 +796,31 @@ public class Functions { return URLEncoder.encode(s, StandardCharsets.UTF_8); } + /** + * Transforms the input string so it renders as written in HTML output: newlines are converted to HTML line breaks, consecutive spaces are retained as {@code &nbsp;}, and HTML metacharacters are escaped. + * 
+     * Input example  1: & " ' < >
+     * Output example 1: &amp; &quot; &#039; &lt; &gt;
+     * Input example  2: !"£$%^&*()_+}{:@~?><|¬`,./;'#[]-=
+     * Output example 2: !&quot;£$%^&amp;*()_+}{:@~?&gt;&lt;|¬`,./;&#039;#[]-=
+     *
+ * @see #xmlEscape + * @see hudson.Util#escape + */ public static String escape(String s) { return Util.escape(s); } + /** + * Escapes XML unsafe characters + * 
+     * Input example  1: < > &
+     * Output example 1: &lt; &gt; &amp;
+     * Input example  2: !"£$%^&*()_+}{:@~?><|¬`,./;'#[]-=
+     * Output example 2: !"£$%^&amp;*()_+}{:@~?&gt;&lt;|¬`,./;'#[]-=
+     *
+ * @see hudson.Util#xmlEscape + */ public static String xmlEscape(String s) { return Util.xmlEscape(s); } @@ -788,6 +829,16 @@ public class Functions { return s.replace("<", "<").replace(">", ">").replace("&", "&"); } + /** + * Escapes a string so it can be used in an HTML attribute value. + * 
+     * Input example  1: & " ' < >
+     * Output example 1: &amp; &quot; &#39; &lt; &gt;
+     * Input example  2: !"£$%^&*()_+}{:@~?><|¬`,./;'#[]-=
+     * Output example 2: !&quot;£$%^&amp;*()_+}{:@~?&gt;&lt;|¬`,./;&#39;#[]-=
+     *
+ * Note: 2 consecutive blank spaces will not render any special chars. + */ public static String htmlAttributeEscape(String text) { StringBuilder buf = new StringBuilder(text.length() + 64); for (int i = 0; i < text.length(); i++) { @@ -1569,6 +1620,15 @@ public class Functions { return Collections.emptyList(); } + /** + * Escape a string so variable values can be used in inline JavaScript in views. + * Note that inline JavaScript and especially passing variables is discouraged, see the documentation for alternatives. + * 
+     * Input example : \ \\ ' "
+     * Output example: \\ \\\\ \' \"
+     *
+ * @see Passing values to JavaScript + */ public static String jsStringEscape(String s) { if (s == null) return null; StringBuilder buf = new StringBuilder(); -- GitLab