.\" 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.