Subversion Repositories planix.SVN

Rev

Rev 22 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 - 1 
.TH QUOTE 2
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 
.IR strcat (2)).
62 
Each returns a
63 
freshly allocated copy of the string, created using
64 
.IR malloc (2).
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 
.IR runestrcat (2)).
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 
.IR rc (1).
128 
.PP
129 
.I Quotestrfmt
130 
and
131 
.I quoterunestrfmt
132 
are
133 
.IR print (2)
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 
.IR print (2)
158 
format strings.
159 
.SH SOURCE
160 
.B /sys/src/libc/port/quote.c
161 
.br
162 
.B /sys/src/libc/fmt/fmtquote.c
163 
.SH "SEE ALSO
164 
.IR rc (1),
165 
.IR malloc (2),
166 
.IR print (2),
167 
.IR strcat (2)