1 files changed, 119 insertions, 0 deletions
diff --git a/cppawk-quote.1 b/cppawk-quote.1
new file mode 100644
index 0000000..29af8e6
--- /dev/null
+++ b/cppawk-quote.1
@@ -0,0 +1,119 @@
+.\" 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.
+.de bk
+.IP " "
+.PP
+..
+.TH CPPAWK-QUOTE 1 "26 June 2023" "cppawk Libraries" "Shell Quoting"
+
+.SH NAME
+q \- Function for shell quoting.
+
+.SH SYNOPSIS
+
+.ft B
+  #include <quote.h>
+
+  q(str)        \fI// return str, shell-escaped\fP
+.ft R
+
+.SH DESCRIPTION
+.bk
+The
+.B q
+function shell-escapes its argument
+.IR str .
+This means that if the argument contains
+special characters, it is transformed such that the resulting string
+can safely be inserted into a shell command as an argument. That argument,
+when interpreted by the shell, will be interpreted as the original text
+which was input to
+.BR q .
+
+If
+.I str
+contains any of the following special characters, it will be single-quoted
+(turned into a string which begins and ends with the single quote,
+also known as the ASCII apostrophe character).
+
+.ft B
+  \e * ? $ ` ~
+.ft R
+
+Otherwise, if it contains single quotes
+it will be double-quoted (surrounded in double quotes).
+
+Otherwise, if it contains double quotes, it will be
+single-quoted.
+
+Otherwise, if it contains spaces, tabs or newlines, it will
+be double-quoted.
+
+If none of the above cases apply,
+.I str
+is returned unmodified.
+
+If single quoting is applied to a string which contains single quote
+characters, those characters are replaced by the sequence
+.BR '\e'' .
+
+If double quoting is applied to a string which contains double quotes,
+those characters are replaced by
+.BR \e" .
+
+.B Examples:
+
+.ft B
+  // safely execute mv 
+
+  function mv(from, to)
+  {
+    system("mv -- " q(from) " " q(to))
+  }
+
+  // code           // output
+  print q("abc")    abc
+  print q("ab cd")  "ab cd"
+  print q("ab\enc")  "ab
+                    c"
+  print q("ab'cd")  "ab'cd"
+  print q("ab\e"cd") 'ab"cd'
+  print q("abc*")   'abc*'
+.ft R
+
+
+.SH "SEE ALSO"
+
+cppawk(1)
+
+.SH BUGS
+
+.SH AUTHOR
+Kaz Kylheku <kaz@kylheku.com>
+
+.SH COPYRIGHT
+Copyright 2023, BSD2 License.