New API aug_escape_name

Provide a way to escape the characters that are special in a path
expression

NEWS

@@ -1,4 +1,13 @@
 1.4.0 - 2015-XX-XX
+  - General changes/additions
+    * add a aug_escape_name call to sanitize strings for use in path
+      expressions. There are a few characters that are special in path
+      expressions. This function makes it possible to have them all escaped
+      so that the resulting string can be used in a path expression and is
+      guaranteed to only match a node with exactly that name
+    * paths generated by Augeas are now properly escaped so that, e.g., the
+      strings returned by aug_match can always be fed to aug_get, even if
+      they contain special characters
   - Lens changes/additions
     * Dnsmasq: Parse the structure of the 'address' and 'server' options
                (incompatible change) (Kaarle Ritvanen)

src/augeas.c

@@ -1985,6 +1985,20 @@ int aug_transform(struct augeas *aug, const char *lens,
     return result;
 }
 
+int aug_escape_name(augeas *aug, const char *in, char **out) {
+    int result;
+
+    api_entry(aug);
+    ARG_CHECK(in == NULL, aug, "aug_escape_name: IN must not be NULL");
+    ARG_CHECK(out == NULL, aug, "aug_escape_name: OUT must not be NULL");
+
+    result = pathx_escape_name(in, out);
+    ERR_NOMEM(result < 0, aug);
+ error:
+    api_exit(aug);
+    return result;
+}
+
 int aug_print(const struct augeas *aug, FILE *out, const char *pathin) {
     struct pathx *p;
     int result;

src/augeas.h

@@ -370,6 +370,23 @@ int aug_text_retrieve(struct augeas *aug, const char *lens,
                       const char *node_in, const char *path,
                       const char *node_out);
 
+/* Function: aug_escape_name
+ *
+ * Escape special characters in a string such that it can be used as part
+ * of a path expressions and only matches a node named exactly
+ * IN. Characters that have special meanings in path expressions, such as
+ * '[' and ']' are prefixed with a '\\'. Note that this function assumes
+ * that it is passed a name, not a path, and will therefore escape '/',
+ * too.
+ *
+ * On return, *OUT is NULL if IN does not need any escaping at all, and
+ * points to an escaped copy of IN otherwise.
+ *
+ * Returns:
+ * 0 on success, or a negative value on failure
+ */
+int aug_escape_name(augeas *aug, const char *in, char **out);
+
 /* Function: aug_print
  *
  * Print each node matching PATH and its descendants to OUT.

src/augeas_sym.version

@@ -65,3 +65,8 @@ AUGEAS_0.18.0 {
     global:
       aug_cp;
 } AUGEAS_0.16.0;
+
+AUGEAS_0.19.0 {
+    global:
+      aug_escape_name;
+} AUGEAS_0.18.0;

src/internal.c

@@ -359,6 +359,9 @@ char *path_expand(struct tree *tree, const char *ppath) {
         label = tree->label;
 
     r = pathx_escape_name(label, &escaped);
+    if (r < 0)
+        return NULL;
+
     if (escaped != NULL)
         label = escaped;
 

tests/test-api.c

@@ -625,6 +625,23 @@ static void testTextRetrieve(CuTest *tc) {
     CuAssertStrEquals(tc, hosts, hosts_out);
 }
 
+static void testAugEscape(CuTest *tc) {
+    static const char *const in  = "a/[]b|=c()!, \td";
+    static const char *const exp = "a\\/\\[\\]b\\|\\=c\\(\\)\\!\\,\\ \\\td";
+    char *out;
+    struct augeas *aug;
+    int r;
+
+    aug = aug_init(root, loadpath, AUG_NO_STDINC|AUG_NO_LOAD);
+    CuAssertPtrNotNull(tc, aug);
+
+    r = aug_escape_name(aug, in, &out);
+    CuAssertRetSuccess(tc, r);
+
+    CuAssertStrEquals(tc, out, exp);
+    free(out);
+}
+
 int main(void) {
     char *output = NULL;
     CuSuite* suite = CuSuiteNew();
@@ -643,6 +660,7 @@ int main(void) {
     SUITE_ADD_TEST(suite, testToXml);
     SUITE_ADD_TEST(suite, testTextStore);
     SUITE_ADD_TEST(suite, testTextRetrieve);
+    SUITE_ADD_TEST(suite, testAugEscape);
 
     abs_top_srcdir = getenv("abs_top_srcdir");
     if (abs_top_srcdir == NULL)