1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
.TH QUOTE 3
.SH NAME
quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, doquote, needsrcquote \- quoted character strings
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
char *quotestrdup(char *s)
.PP
.B
Rune *quoterunestrdup(Rune *s)
.PP
.B
char *unquotestrdup(char *s)
.PP
.B
Rune *unquoterunestrdup(Rune *s)
.PP
.B
int quotestrfmt(Fmt*)
.PP
.B
int quoterunestrfmt(Fmt*)
.PP
.B
void quotefmtinstall(void)
.PP
.B
int (*doquote)(int c)
.PP
.B
int needsrcquote(int c)
.PP
.SH DESCRIPTION
These routines manipulate character strings, either adding or removing
quotes as necessary.
In the quoted form, the strings are in the style of
.IR rc (1) ,
with single quotes surrounding the string.
Embedded single quotes are indicated by a doubled single quote.
For instance,
.IP
.EX
Don't worry!
.EE
.PP
when quoted becomes
.IP
.EX
\&'Don''t worry!'
.EE
.PP
The empty string is represented by two quotes,
.BR '' .
.PP
The first four functions act as variants of
.B strdup
(see
.IR strcat (3)).
Each returns a
freshly allocated copy of the string, created using
.IR malloc (3).
.I Quotestrdup
returns a quoted copy of
.IR s ,
while
.I unquotestrdup
returns a copy of
.IR s
with the quotes evaluated.
The
.I rune
versions of these functions do the same for
.CW Rune
strings (see
.IR runestrcat (3)).
.PP
The string returned by
.I quotestrdup
or
.I quoterunestrdup
has the following properties:
.TP
1.
If the original string
.IR s
is empty, the returned string is
.BR '' .
.TP
2.
If
.I s
contains no quotes, blanks, or control characters,
the returned string is identical to
.IR s .
.TP
3.
If
.I s
needs quotes to be added, the first character of the returned
string will be a quote.
For example,
.B hello\ world
becomes
.B \&'hello\ world'
not
.BR hello'\ 'world .
.PP
The function pointer
.I doquote
is
.B nil
by default.
If it is non-nil, characters are passed to that function to see if they should
be quoted.
This mechanism allows programs to specify that
characters other than blanks, control characters, or quotes be quoted.
Regardless of the return value of
.IR *doquote ,
blanks, control characters, and quotes are always quoted.
.I Needsrcquote
is provided as a
.I doquote
function that flags any character special to
.IR rc (1).
.PP
.I Quotestrfmt
and
.I quoterunestrfmt
are
.IR print (3)
formatting routines that produce quoted strings as output.
They may be installed by hand, but
.I quotefmtinstall
installs them under the standard format characters
.B q
and
.BR Q .
(They are not installed automatically.)
If the format string includes the alternate format character
.BR # ,
for example
.BR %#q ,
the printed string will always be quoted; otherwise quotes will only be provided if necessary
to avoid ambiguity.
In
.B <libc.h>
there are
.B #pragma
statements so the compiler can type-check uses of
.B %q
and
.B %Q
in
.IR print (3)
format strings.
.SH SOURCE
.B /usr/local/plan9/src/lib9/quote.c
.br
.B /usr/local/plan9/src/lib9/fmt/fmtquote.c
.SH "SEE ALSO
.IR rc (1),
.IR malloc (3),
.IR print (3),
.IR strcat (3)
|