tquote.3 - plan9port - [fork] Plan 9 from user space
 (HTM) git clone git://src.adamsgaard.dk/plan9port
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       tquote.3 (2884B)
       ---
            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)