Add `EscapeStringOptions` and `escapeString` tests

Change-Id: I86ead2f969c9e03c9edfa51bbc92ee06393fd7d6

5 files changed, 132 insertions, 29 deletions

diff --git a/src/libexpr/print.cc b/src/libexpr/print.cc
index e5e6b9b21..8d7e2ab34 100644
--- a/src/libexpr/print.cc
+++ b/src/libexpr/print.cc
@@ -198,12 +198,14 @@ private:
 
     void printString(Value & v)
     {
-        // NB: Non-printing characters won't be escaped.
         escapeString(
             output,
             v.string.s,
-            options.maxStringLength,
-            options.ansiColors
+            {
+                .maxLength = options.maxStringLength,
+                .outputAnsiColors = options.ansiColors,
+                // NB: Non-printing characters won't be escaped.
+            }
         );
     }
 
diff --git a/src/libutil/escape-string.cc b/src/libutil/escape-string.cc
index 8160403cd..c3cea96d2 100644
--- a/src/libutil/escape-string.cc
+++ b/src/libutil/escape-string.cc
@@ -11,30 +11,51 @@
 namespace nix {
 
 std::ostream &
-escapeString(std::ostream & str, const std::string_view string, size_t maxLength, bool ansiColors)
+escapeString(std::ostream & output, std::string_view string, EscapeStringOptions options)
 {
     size_t charsPrinted = 0;
-    if (ansiColors)
-        str << ANSI_MAGENTA;
-    str << "\"";
+    if (options.outputAnsiColors) {
+        output << ANSI_MAGENTA;
+    }
+    output << "\"";
     for (auto i = string.begin(); i != string.end(); ++i) {
-        if (charsPrinted >= maxLength) {
-            str << "\" ";
-            printElided(str, string.length() - charsPrinted, "byte", "bytes", ansiColors);
-            return str;
+        if (charsPrinted >= options.maxLength) {
+            output << "\" ";
+            printElided(
+                output, string.length() - charsPrinted, "byte", "bytes", options.outputAnsiColors
+            );
+            return output;
+        }
+
+        if (*i == '\"' || *i == '\\') {
+            output << "\\" << *i;
+        } else if (*i == '\n') {
+            output << "\\n";
+        } else if (*i == '\r') {
+            output << "\\r";
+        } else if (*i == '\t') {
+            output << "\\t";
+        } else if (*i == '$' && *(i + 1) == '{') {
+            output << "\\" << *i;
+        } else if (options.escapeNonPrinting && !isprint(*i)) {
+            output << MaybeHexEscapedChar{*i};
+        } else {
+            output << *i;
         }
-        if (*i == '\"' || *i == '\\') str << "\\" << *i;
-        else if (*i == '\n') str << "\\n";
-        else if (*i == '\r') str << "\\r";
-        else if (*i == '\t') str << "\\t";
-        else if (*i == '$' && *(i+1) == '{') str << "\\" << *i;
-        else str << *i;
         charsPrinted++;
     }
-    str << "\"";
-    if (ansiColors)
-        str << ANSI_NORMAL;
-    return str;
+    output << "\"";
+    if (options.outputAnsiColors) {
+        output << ANSI_NORMAL;
+    }
+    return output;
+}
+
+std::string escapeString(std::string_view s, EscapeStringOptions options)
+{
+    std::ostringstream output;
+    escapeString(output, s, options);
+    return output.str();
 }
 
 }; // namespace nix
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
@@ -6,6 +6,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.
  *
  * With default optional parameters, the output string will round-trip through
@@ -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
diff --git a/tests/unit/libutil/escape-string.cc b/tests/unit/libutil/escape-string.cc
new file mode 100644
index 000000000..5ce2b73d8
--- /dev/null
+++ b/tests/unit/libutil/escape-string.cc
@@ -0,0 +1,35 @@
+#include "escape-string.hh"
+#include "ansicolor.hh"
+#include <gtest/gtest.h>
+
+namespace nix {
+
+TEST(EscapeString, simple) {
+  auto escaped = escapeString("puppy");
+  ASSERT_EQ(escaped, "\"puppy\"");
+}
+
+TEST(EscapeString, escaping) {
+  auto escaped = escapeString("\n\r\t \" \\ ${ooga booga}");
+  ASSERT_EQ(escaped, R"RAW("\n\r\t \" \\ \${ooga booga}")RAW");
+}
+
+TEST(EscapeString, maxLength) {
+  auto escaped = escapeString("puppy", {.maxLength = 5});
+  ASSERT_EQ(escaped, "\"puppy\"");
+
+  escaped = escapeString("puppy doggy", {.maxLength = 5});
+  ASSERT_EQ(escaped, "\"puppy\" «6 bytes elided»");
+}
+
+TEST(EscapeString, ansiColors) {
+  auto escaped = escapeString("puppy doggy", {.maxLength = 5, .outputAnsiColors = true});
+  ASSERT_EQ(escaped, ANSI_MAGENTA "\"puppy\" " ANSI_FAINT "«6 bytes elided»" ANSI_NORMAL);
+}
+
+TEST(EscapeString, escapeNonPrinting) {
+  auto escaped = escapeString("puppy\u0005doggy", {.escapeNonPrinting = true});
+  ASSERT_EQ(escaped, "\"puppy\\x05doggy\"");
+}
+
+} // namespace nix
diff --git a/tests/unit/meson.build b/tests/unit/meson.build
index a5523a813..60bb2de89 100644
--- a/tests/unit/meson.build
+++ b/tests/unit/meson.build
@@ -39,6 +39,7 @@ libutil_tests_sources = files(
   'libutil/closure.cc',
   'libutil/compression.cc',
   'libutil/config.cc',
+  'libutil/escape-string.cc',
   'libutil/git.cc',
   'libutil/hash.cc',
   'libutil/hilite.cc',