1 78e51a8c 2005-01-14 devnull .TH QUOTE 3
3 78e51a8c 2005-01-14 devnull quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, fmtdoquote \- quoted character strings
4 78e51a8c 2005-01-14 devnull .SH SYNOPSIS
5 78e51a8c 2005-01-14 devnull .B #include <utf.h>
7 78e51a8c 2005-01-14 devnull .B #include <fmt.h>
10 78e51a8c 2005-01-14 devnull char *quotestrdup(char *s)
13 78e51a8c 2005-01-14 devnull Rune *quoterunestrdup(Rune *s)
16 78e51a8c 2005-01-14 devnull char *unquotestrdup(char *s)
19 78e51a8c 2005-01-14 devnull Rune *unquoterunestrdup(Rune *s)
22 78e51a8c 2005-01-14 devnull int quotestrfmt(Fmt*)
25 78e51a8c 2005-01-14 devnull int quoterunestrfmt(Fmt*)
28 78e51a8c 2005-01-14 devnull void quotefmtinstall(void)
31 78e51a8c 2005-01-14 devnull int (*fmtdoquote)(int c)
33 78e51a8c 2005-01-14 devnull .SH DESCRIPTION
34 78e51a8c 2005-01-14 devnull These routines manipulate character strings, either adding or removing
35 78e51a8c 2005-01-14 devnull quotes as necessary.
36 78e51a8c 2005-01-14 devnull In the quoted form, the strings are in the style of
37 78e51a8c 2005-01-14 devnull .IR rc (1) ,
38 78e51a8c 2005-01-14 devnull with single quotes surrounding the string.
39 78e51a8c 2005-01-14 devnull Embedded single quotes are indicated by a doubled single quote.
40 78e51a8c 2005-01-14 devnull For instance,
43 78e51a8c 2005-01-14 devnull Don't worry!
46 78e51a8c 2005-01-14 devnull when quoted becomes
49 78e51a8c 2005-01-14 devnull \&'Don''t worry!'
52 78e51a8c 2005-01-14 devnull The empty string is represented by two quotes,
55 78e51a8c 2005-01-14 devnull The first four functions act as variants of
56 78e51a8c 2005-01-14 devnull .B strdup
58 78e51a8c 2005-01-14 devnull .IR strcat (3)).
59 78e51a8c 2005-01-14 devnull Each returns a
60 78e51a8c 2005-01-14 devnull freshly allocated copy of the string, created using
61 78e51a8c 2005-01-14 devnull .IR malloc (3).
62 78e51a8c 2005-01-14 devnull .I Quotestrdup
63 78e51a8c 2005-01-14 devnull returns a quoted copy of
66 78e51a8c 2005-01-14 devnull .I unquotestrdup
67 78e51a8c 2005-01-14 devnull returns a copy of
69 78e51a8c 2005-01-14 devnull with the quotes evaluated.
72 78e51a8c 2005-01-14 devnull versions of these functions do the same for
74 78e51a8c 2005-01-14 devnull strings (see
75 78e51a8c 2005-01-14 devnull .IR runestrcat (3)).
77 78e51a8c 2005-01-14 devnull The string returned by
78 78e51a8c 2005-01-14 devnull .I quotestrdup
80 78e51a8c 2005-01-14 devnull .I quoterunestrdup
81 78e51a8c 2005-01-14 devnull has the following properties:
84 78e51a8c 2005-01-14 devnull If the original string
86 78e51a8c 2005-01-14 devnull is empty, the returned string is
92 78e51a8c 2005-01-14 devnull contains no quotes, blanks, or control characters,
93 78e51a8c 2005-01-14 devnull the returned string is identical to
99 78e51a8c 2005-01-14 devnull needs quotes to be added, the first character of the returned
100 78e51a8c 2005-01-14 devnull string will be a quote.
101 78e51a8c 2005-01-14 devnull For example,
102 78e51a8c 2005-01-14 devnull .B hello\ world
104 78e51a8c 2005-01-14 devnull .B \&'hello\ world'
106 78e51a8c 2005-01-14 devnull .BR hello'\ 'world .
108 78e51a8c 2005-01-14 devnull The function pointer
109 78e51a8c 2005-01-14 devnull .I fmtdoquote
112 78e51a8c 2005-01-14 devnull by default.
113 78e51a8c 2005-01-14 devnull If it is non-nil, characters are passed to that function to see if they should
114 78e51a8c 2005-01-14 devnull be quoted.
115 78e51a8c 2005-01-14 devnull This mechanism allows programs to specify that
116 78e51a8c 2005-01-14 devnull characters other than blanks, control characters, or quotes be quoted.
117 78e51a8c 2005-01-14 devnull Regardless of the return value of
118 78e51a8c 2005-01-14 devnull .IR *fmtdoquote ,
119 78e51a8c 2005-01-14 devnull blanks, control characters, and quotes are always quoted.
120 78e51a8c 2005-01-14 devnull .I Needsrcquote
121 78e51a8c 2005-01-14 devnull is provided as a
122 78e51a8c 2005-01-14 devnull .I fmtdoquote
123 78e51a8c 2005-01-14 devnull function that flags any character special to
124 78e51a8c 2005-01-14 devnull .IR rc (1).
126 78e51a8c 2005-01-14 devnull .I Quotestrfmt
128 78e51a8c 2005-01-14 devnull .I quoterunestrfmt
130 78e51a8c 2005-01-14 devnull .IR print (3)
131 78e51a8c 2005-01-14 devnull formatting routines that produce quoted strings as output.
132 78e51a8c 2005-01-14 devnull They may be installed by hand, but
133 78e51a8c 2005-01-14 devnull .I quotefmtinstall
134 78e51a8c 2005-01-14 devnull installs them under the standard format characters
138 78e51a8c 2005-01-14 devnull (They are not installed automatically.)
139 78e51a8c 2005-01-14 devnull If the format string includes the alternate format character
141 78e51a8c 2005-01-14 devnull for example
142 78e51a8c 2005-01-14 devnull .BR %#q ,
143 78e51a8c 2005-01-14 devnull the printed string will always be quoted; otherwise quotes will only be provided if necessary
144 78e51a8c 2005-01-14 devnull to avoid ambiguity.
145 78e51a8c 2005-01-14 devnull .SH SOURCE
146 a3993885 2017-09-01 rsc .B https://9fans.github.io/plan9port/unix
147 78e51a8c 2005-01-14 devnull .SH "SEE ALSO
148 78e51a8c 2005-01-14 devnull .IR rc (1),
149 78e51a8c 2005-01-14 devnull .IR malloc (3),
150 78e51a8c 2005-01-14 devnull .IR print (3),
151 78e51a8c 2005-01-14 devnull .IR strcat (3)
