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