10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
175 lines
3.1 KiB
Groff
175 lines
3.1 KiB
Groff
.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
|
|
.MR strcat 3 ).
|
|
Each returns a
|
|
freshly allocated copy of the string, created using
|
|
.MR 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
|
|
.MR 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
|
|
.MR rc 1 .
|
|
.PP
|
|
.I Quotestrfmt
|
|
and
|
|
.I quoterunestrfmt
|
|
are
|
|
.MR 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
|
|
.MR print 3
|
|
format strings.
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/quote.c
|
|
.br
|
|
.B \*9/src/lib9/fmt/fmtquote.c
|
|
.SH "SEE ALSO
|
|
.MR rc 1 ,
|
|
.MR malloc 3 ,
|
|
.MR print 3 ,
|
|
.MR strcat 3
|
|
.SH BUGS
|
|
Because it is provided by the format library,
|
|
.I doquote
|
|
is a preprocessor macro defined as
|
|
.IR fmtdoquote ;
|
|
see
|
|
.MR intro 3 .
|