From ea10fe7ab0df085b51189adabdb079fc4442c6be Mon Sep 17 00:00:00 2001
From: Rebecca Turner <rbt@sent.as>
Date: Thu, 28 Mar 2024 16:26:42 -0700
Subject: Add `EscapeStringOptions` and `escapeString` tests

Change-Id: I86ead2f969c9e03c9edfa51bbc92ee06393fd7d6
---
 src/libutil/escape-string.hh | 60 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 52 insertions(+), 8 deletions(-)

(limited to 'src/libutil/escape-string.hh')

diff --git a/src/libutil/escape-string.hh b/src/libutil/escape-string.hh
index 28c6c8d64..7f0a9e701 100644
--- a/src/libutil/escape-string.hh
+++ b/src/libutil/escape-string.hh
@@ -5,6 +5,41 @@
 
 namespace nix {
 
+/**
+ * Options for escaping strings in `escapeString`.
+ *
+ * With default optional parameters, the output string will round-trip through
+ * the Nix evaluator (i.e. you can copy/paste this function's output into the
+ * REPL and have it evaluate as the string that got passed in).
+ *
+ * With non-default optional parameters, the output string will be
+ * human-readable.
+ */
+struct EscapeStringOptions
+{
+    /**
+     * If `maxLength` is decreased, some trailing portion of the string may be
+     * omitted with a message like `«123 bytes elided»`.
+     */
+    size_t maxLength = std::numeric_limits<size_t>::max();
+
+    /**
+     * If `outputAnsiColors` is set, the string will be colored the color of literals, using
+     * ANSI escape codes.
+     */
+    bool outputAnsiColors = false;
+
+    /**
+     * If `escapeNonPrinting` is set, non-printing ASCII characters (i.e. with
+     * byte values less than 0x20) will be printed in `\xhh` format, like
+     * `\x1d` (other than those that Nix supports, like `\n`, `\r`, `\t`).
+     * Note that this format is not yet supported by the Lix parser/evaluator!
+     *
+     * See: https://git.lix.systems/lix-project/lix/issues/149
+     */
+    bool escapeNonPrinting = false;
+};
+
 /**
  * Escape a string for output.
  *
@@ -14,21 +49,30 @@ namespace nix {
  *
  * With non-default optional parameters, the output string will be
  * human-readable.
+ *
+ * See `EscapeStringOptions` for more details on customizing the output.
  */
+std::ostream &
+escapeString(std::ostream & output, std::string_view s, EscapeStringOptions options = {});
+
+inline std::ostream & escapeString(std::ostream & output, const char * s)
+{
+    return escapeString(output, std::string_view(s));
+}
 
-std::ostream & escapeString(
-    std::ostream & output,
-    const std::string_view string,
-    size_t maxLength = std::numeric_limits<size_t>::max(),
-    bool ansiColors = false
-);
+inline std::ostream & escapeString(std::ostream & output, const std::string & s)
+{
+    return escapeString(output, std::string_view(s));
+}
 
 /**
  * Escape a string for output, writing the escaped result to a new string.
  */
-inline std::ostream & escapeString(std::ostream & output, const char * string)
+std::string escapeString(std::string_view s, EscapeStringOptions options = {});
+
+inline std::string escapeString(const char * s, EscapeStringOptions options = {})
 {
-    return escapeString(output, std::string_view(string));
+    return escapeString(std::string_view(s), options);
 }
 
 } // namespace nix
-- 
cgit v1.2.3