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