Add function for shell quoting.

* README.md: Mention <quote.h> and cppawk-quote man page.

* share/cppawk/include/quote.h,
* share/cppawk/include/quote-priv.h: New files.

* testcases-quote: New file.

* cppawk-quote.1: New file.

* runtests: Add testcases-quote.

2 files changed, 106 insertions, 0 deletions

diff --git a/share/cppawk/include/quote-priv.h b/share/cppawk/include/quote-priv.h
new file mode 100644
index 0000000..1dd635d
--- /dev/null
+++ b/share/cppawk/include/quote-priv.h
@@ -0,0 +1,69 @@
+// cppawk: C preprocessor wrapper around awk
+// Copyright 2023 Kaz Kylheku <kaz@kylheku.com>
+//
+// BSD-2 License
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice,
+//    this list of conditions and the following disclaimer.
+//
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+// POSSIBILITY OF SUCH DAMAGE.
+
+#ifndef __CPPAWK_QUOTE_PRIV_H
+#define __CPPAWK_QUOTE_PRIV_H
+
+function __squote(__str)
+{
+  gsub("'", "'\\''", __str)
+  return "'" __str "'"
+}
+
+function __dquote(__str)
+{
+  gsub("\"", "\\\"", __str)
+  return "\"" __str "\""
+}
+
+function __quote(__str,
+                 __dquot_present,
+                 __squot_present,
+                 __meta_present,
+                 __space_present)
+{
+    __dquot_present = __str ~ "\""
+    __squot_present = __str ~ "'"
+    __meta_present = __str ~ "[\\\\*?$`~]"
+    __space_present = __str ~ "[\\t\\n ]"
+
+    if (__meta_present)
+      return __squote(__str)
+
+    if (__squot_present)
+      return __dquote(__str)
+
+    if (__dquot_present)
+      return "'" __str "'"
+
+    if (__space_present)
+      return __dquote(__str)
+
+    return __str
+}
+
+#endif
diff --git a/share/cppawk/include/quote.h b/share/cppawk/include/quote.h
new file mode 100644
index 0000000..9b91568
--- /dev/null
+++ b/share/cppawk/include/quote.h
@@ -0,0 +1,37 @@
+// cppawk: C preprocessor wrapper around awk
+// Copyright 2023 Kaz Kylheku <kaz@kylheku.com>
+//
+// BSD-2 License
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice,
+//    this list of conditions and the following disclaimer.
+//
+// 2. Redistributions in binary form must reproduce the above copyright notice,
+//    this list of conditions and the following disclaimer in the documentation
+//    and/or other materials provided with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+// POSSIBILITY OF SUCH DAMAGE.
+
+#ifndef __CPPAWK_QUOTE_H
+#define __CPPAWK_QUOTE_H
+
+#ifndef __CPPAWK_QUOTE_PRIV_H
+#include "quote-priv.h"
+#endif
+
+#define q(str) __quote(str)
+
+#endif