Add HTML string escape and unescape APIs

doc/developer-guide/api/functions/TSStringHtmlEscape.en.rst

@@ -0,0 +1,81 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: cpp
+
+TSStringHtmlEscape
+******************
+
+Escape and unescape strings for inclusion in HTML.
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. var:: constexpr bool TS_HTML_ESCAPE_USE_ATTRIBUTE_MODE = true
+
+.. function:: TSReturnCode TSStringHtmlEscape(const char * str, int str_len, char * dst, size_t dst_size, size_t * length, bool use_attribute_mode)
+.. function:: TSReturnCode TSStringHtmlUnescape(const char * str, int str_len, char * dst, size_t dst_size, size_t * length)
+
+Description
+===========
+
+:func:`TSStringHtmlEscape` escapes the UTF-8 string in :arg:`str` according to
+the `HTML fragment serialization escaping algorithm
+<https://html.spec.whatwg.org/#escapingString>`_. Ampersands, less-than signs,
+greater-than signs, and U+00A0 NO-BREAK SPACE characters are replaced by their
+HTML named character references. Pass :var:`TS_HTML_ESCAPE_USE_ATTRIBUTE_MODE` as
+:arg:`use_attribute_mode` to also replace double quotes with ``&quot;`` for use
+in double-quoted HTML attribute values. Pass
+:literal:`!TS_HTML_ESCAPE_USE_ATTRIBUTE_MODE` to leave double quotes unchanged.
+
+:func:`TSStringHtmlUnescape` is the inverse operation. It replaces ``&amp;``,
+``&nbsp;``, ``&lt;``, ``&gt;``, and ``&quot;`` with the corresponding UTF-8
+characters. Other named or numeric character references are left unchanged.
+References are matched case-sensitively and must include the terminating
+semicolon. Unescaping is performed once from left to right, so ``&amp;lt;``
+becomes ``&lt;``, not ``<``.
+
+:arg:`str_len` is the number of bytes to read from :arg:`str`. A value of
+:literal:`-1` treats :arg:`str` as NUL-terminated. The caller must provide a
+non-overlapping :arg:`dst` buffer whose :arg:`dst_size` includes room for the
+terminating NUL. On success, :arg:`length` is set to the number of output bytes,
+excluding that NUL. On failure, :arg:`length` is set to :literal:`0` if it is
+not :literal:`nullptr`.
+
+The worst-case destination size for :func:`TSStringHtmlEscape` is six times the
+input length plus one byte for the terminating NUL. An input-length-plus-one
+buffer is always sufficient for :func:`TSStringHtmlUnescape`.
+
+Return Values
+=============
+
+:func:`TSStringHtmlEscape` returns :enumerator:`TS_SUCCESS` on success and
+:enumerator:`TS_ERROR` if :arg:`str_len` is invalid, the escaped length
+overflows, or :arg:`dst` is too small. :func:`TSStringHtmlUnescape` returns
+:enumerator:`TS_ERROR` if :arg:`str_len` is invalid or :arg:`dst` is too small.
+
+See Also
+========
+
+:manpage:`TSAPI(3ts)`,
+:manpage:`TSUrlPercentEncode(3ts)`

include/ts/ts.h

@@ -738,6 +738,60 @@ TSReturnCode TSUrlHttpFragmentSet(TSMBuffer bufp, TSMLoc offset, const char *val
 TSReturnCode TSStringPercentEncode(const char *str, int str_len, char *dst, size_t dst_size, size_t *length,
                                    const unsigned char *map);
 
+/// Request double-quoted attribute escaping in TSStringHtmlEscape().
+constexpr bool TS_HTML_ESCAPE_USE_ATTRIBUTE_MODE = true;
+
+/**
+   Escape a UTF-8 string for inclusion in HTML, storing the escaped string in
+   the destination buffer. The output is NUL-terminated. The length parameter
+   is set to the escaped string length, excluding the terminating NUL, or zero
+   if escaping fails.
+
+   This follows the HTML fragment serialization escaping algorithm. Ampersand,
+   less-than, greater-than, and U+00A0 NO-BREAK SPACE characters are always
+   escaped. Double quotes are also escaped when @a use_attribute_mode is @c true.
+
+   @param[in] str string buffer to escape.
+   @param[in] str_len length of the string buffer, or -1 if @a str is
+     NUL-terminated.
+   @param[out] dst destination buffer. This must not overlap @a str.
+   @param[in] dst_size size of the destination buffer, including space for the
+     terminating NUL.
+   @param[out] length amount of data written to the destination buffer,
+     excluding the terminating NUL. This may be @c nullptr.
+   @param[in] use_attribute_mode whether to escape for a double-quoted HTML
+     attribute value.
+
+   @return @c TS_SUCCESS on success, @c TS_ERROR if @a str_len is less than
+     -1, the output length overflows, or @a dst is too small.
+ */
+TSReturnCode TSStringHtmlEscape(const char *str, int str_len, char *dst, size_t dst_size, size_t *length, bool use_attribute_mode);
+
+/**
+   Unescape the HTML character references emitted by TSStringHtmlEscape(),
+   storing the resulting UTF-8 string in the destination buffer. The output is
+   NUL-terminated. The length parameter is set to the unescaped string length,
+   excluding the terminating NUL, or zero if unescaping fails.
+
+   The character references @c &, @c  , @c <, @c >, and
+   @c " are replaced by their corresponding characters. Other character
+   references are preserved. Unescaping is performed once, so an unescaped
+   character reference is not unescaped again.
+
+   @param[in] str string buffer to unescape.
+   @param[in] str_len length of the string buffer, or -1 if @a str is
+     NUL-terminated.
+   @param[out] dst destination buffer. This must not overlap @a str.
+   @param[in] dst_size size of the destination buffer, including space for the
+     terminating NUL.
+   @param[out] length amount of data written to the destination buffer,
+     excluding the terminating NUL. This may be @c nullptr.
+
+   @return @c TS_SUCCESS on success, @c TS_ERROR if @a str_len is less than
+     -1 or @a dst is too small.
+ */
+TSReturnCode TSStringHtmlUnescape(const char *str, int str_len, char *dst, size_t dst_size, size_t *length);
+
 /**
    Similar to TSStringPercentEncode(), but works on a URL object.
 

include/tscore/Encoding.h

@@ -19,6 +19,9 @@
   limitations under the License.
  */
 
+#include <cstddef>
+#include <string_view>
+
 class Arena;
 
 /*-------------------------------------------------------------------------
@@ -40,4 +43,41 @@ char *escapify_url(Arena *arena, char *url, size_t len_in, int *len_out, char *d
                    const unsigned char *map = nullptr);
 char *pure_escapify_url(Arena *arena, char *url, size_t len_in, int *len_out, char *dst = nullptr, size_t dst_size = 0,
                         const unsigned char *map = nullptr);
+
+/** Escape a UTF-8 string for inclusion in HTML.
+
+    This implements the HTML fragment serialization escaping algorithm. The
+    characters @c &, @c <, @c >, and U+00A0 NO-BREAK SPACE are always escaped.
+    The @c " character is additionally escaped when @a use_attribute_mode is
+    @c true.
+
+    @param[in] input string to escape.
+    @param[out] dst destination buffer, which must not overlap @a input.
+    @param[in] dst_size size of @a dst, including space for the terminating NUL.
+    @param[out] length amount of data written, excluding the terminating NUL.
+      This is set to zero if escaping fails. This may be @c nullptr.
+    @param[in] use_attribute_mode whether to escape for a double-quoted HTML
+      attribute value.
+
+    @return @c true on success, @c false if @a dst is null, the output length
+      overflows, or @a dst is too small.
+ */
+bool html_escape(std::string_view input, char *dst, size_t dst_size, size_t *length, bool use_attribute_mode);
+
+/** Unescape the HTML character references emitted by html_escape().
+
+    The character references @c &amp;, @c &nbsp;, @c &lt;, @c &gt;, and
+    @c &quot; are replaced by their corresponding UTF-8 characters. Other
+    character references are preserved. Unescaping is performed once, so an
+    unescaped character reference is not unescaped again.
+
+    @param[in] input string to unescape.
+    @param[out] dst destination buffer, which must not overlap @a input.
+    @param[in] dst_size size of @a dst, including space for the terminating NUL.
+    @param[out] length amount of data written, excluding the terminating NUL.
+      This is set to zero if unescaping fails. This may be @c nullptr.
+
+    @return @c true on success, @c false if @a dst is null or too small.
+ */
+bool html_unescape(std::string_view input, char *dst, size_t dst_size, size_t *length);
 }; // namespace Encoding

src/api/InkAPI.cc

@@ -1347,6 +1347,46 @@ TSStringPercentEncode(const char *str, int str_len, char *dst, size_t dst_size,
   return TS_SUCCESS;
 }
 
+TSReturnCode
+TSStringHtmlEscape(const char *str, int str_len, char *dst, size_t dst_size, size_t *length, bool use_attribute_mode)
+{
+  sdk_assert(sdk_sanity_check_null_ptr((void *)str) == TS_SUCCESS);
+  sdk_assert(sdk_sanity_check_null_ptr((void *)dst) == TS_SUCCESS);
+
+  if (str_len < -1) {
+    if (length) {
+      *length = 0;
+    }
+    return TS_ERROR;
+  }
+  size_t input_length = str_len == -1 ? strlen(str) : static_cast<size_t>(str_len);
+
+  if (!Encoding::html_escape(std::string_view{str, input_length}, dst, dst_size, length, use_attribute_mode)) {
+    return TS_ERROR;
+  }
+  return TS_SUCCESS;
+}
+
+TSReturnCode
+TSStringHtmlUnescape(const char *str, int str_len, char *dst, size_t dst_size, size_t *length)
+{
+  sdk_assert(sdk_sanity_check_null_ptr((void *)str) == TS_SUCCESS);
+  sdk_assert(sdk_sanity_check_null_ptr((void *)dst) == TS_SUCCESS);
+
+  if (str_len < -1) {
+    if (length) {
+      *length = 0;
+    }
+    return TS_ERROR;
+  }
+  size_t input_length = str_len == -1 ? strlen(str) : static_cast<size_t>(str_len);
+
+  if (!Encoding::html_unescape(std::string_view{str, input_length}, dst, dst_size, length)) {
+    return TS_ERROR;
+  }
+  return TS_SUCCESS;
+}
+
 TSReturnCode
 TSStringPercentDecode(const char *str, size_t str_len, char *dst, size_t dst_size, size_t *length)
 {