basic/extract_word: try to explain what the various options do

A test for stripping of escaped backslashes without any flags was explicitly
added back in 4034a06ddb82ec9868cd52496fef2f5faa25575f. So it seems to be on
purpose, though I would say that this is at least surprising and hence deserves
a comment.

In test-extract-word, add tests for standalone EXTRACT_UNESCAPE_SEPARATORS.
Only behaviour combined with EXTRACT_CUNESCAPE was tested.

diff --git a/src/basic/extract-word.h b/src/basic/extract-word.h
index d1de32e5806d316f3e7cf50564a990089d951e8f..3c1e7d98b646d3bcd01c48f59c251c04ca0c6960 100644 (file)
--- a/src/basic/extract-word.h
+++ b/src/basic/extract-word.h
@@ -4,13 +4,15 @@
 #include "macro.h"
 
 typedef enum ExtractFlags {
-        EXTRACT_RELAX                    = 1 << 0,
-        EXTRACT_CUNESCAPE                = 1 << 1,
-        EXTRACT_CUNESCAPE_RELAX          = 1 << 2,
-        EXTRACT_UNESCAPE_SEPARATORS      = 1 << 3,
-        EXTRACT_UNQUOTE                  = 1 << 4,
-        EXTRACT_DONT_COALESCE_SEPARATORS = 1 << 5,
-        EXTRACT_RETAIN_ESCAPE            = 1 << 6,
+        EXTRACT_RELAX                    = 1 << 0, /* Allow unbalanced quote and eat up trailing backslash. */
+        EXTRACT_CUNESCAPE                = 1 << 1, /* Unescape known escape sequences. */
+        EXTRACT_CUNESCAPE_RELAX          = 1 << 2, /* Allow and keep unknown escape sequences, allow and keep trailing backslash. */
+        EXTRACT_UNESCAPE_SEPARATORS      = 1 << 3, /* Unescape separators (those specified, or whitespace by default). */
+        EXTRACT_UNQUOTE                  = 1 << 4, /* Remove quoting with "" and ''. */
+        EXTRACT_DONT_COALESCE_SEPARATORS = 1 << 5, /* Don't treat multiple adjacent separators as one */
+        EXTRACT_RETAIN_ESCAPE            = 1 << 6, /* Treat escape character '\' as any other character without special meaning */
+
+        /* Note that if no flags are specified, escaped escape characters will be silently stripped. */
 } ExtractFlags;
 
 int extract_first_word(const char **p, char **ret, const char *separators, ExtractFlags flags);

diff --git a/src/test/test-extract-word.c b/src/test/test-extract-word.c
index 56b516fe40af2ada77fec8f3302e4b09240fd94a..f718556d39961c253be9a6c39727f4890c5c668e 100644 (file)
--- a/src/test/test-extract-word.c
+++ b/src/test/test-extract-word.c
@@ -344,6 +344,27 @@ static void test_extract_first_word(void) {
         free(t);
         assert_se(p == NULL);
 
+        p = "\\:";
+        assert_se(extract_first_word(&p, &t, ":", EXTRACT_UNESCAPE_SEPARATORS) == 1);
+        assert_se(streq(t, ":"));
+        free(t);
+        assert_se(p == NULL);
+
+        p = "a\\:b";
+        assert_se(extract_first_word(&p, &t, ":", EXTRACT_UNESCAPE_SEPARATORS) == 1);
+        assert_se(streq(t, "a:b"));
+        free(t);
+        assert_se(p == NULL);
+
+        p = "a\\ b:c";
+        assert_se(extract_first_word(&p, &t, WHITESPACE ":", EXTRACT_UNESCAPE_SEPARATORS) == 1);
+        assert_se(streq(t, "a b"));
+        free(t);
+        assert_se(extract_first_word(&p, &t, WHITESPACE ":", EXTRACT_UNESCAPE_SEPARATORS) == 1);
+        assert_se(streq(t, "c"));
+        free(t);
+        assert_se(p == NULL);
+
         p = "\\:";
         assert_se(extract_first_word(&p, &t, ":", EXTRACT_CUNESCAPE|EXTRACT_UNESCAPE_SEPARATORS) == 1);
         assert_se(streq(t, ":"));