diff options
Diffstat (limited to 'unix/man/quote.3')
-rw-r--r-- | unix/man/quote.3 | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/unix/man/quote.3 b/unix/man/quote.3 new file mode 100644 index 00000000..dfeb2597 --- /dev/null +++ b/unix/man/quote.3 @@ -0,0 +1,151 @@ +.TH QUOTE 3 +.SH NAME +quotestrdup, quoterunestrdup, unquotestrdup, unquoterunestrdup, quotestrfmt, quoterunestrfmt, quotefmtinstall, fmtdoquote \- quoted character strings +.SH SYNOPSIS +.B #include <utf.h> +.br +.B #include <fmt.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 (*fmtdoquote)(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 fmtdoquote +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 *fmtdoquote , +blanks, control characters, and quotes are always quoted. +.I Needsrcquote +is provided as a +.I fmtdoquote +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. +.SH SOURCE +.B http://swtch.com/plan9port/unix +.SH "SEE ALSO +.IR rc (1), +.IR malloc (3), +.IR print (3), +.IR strcat (3) |