1
0

quote 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  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)