lib/string-desc-quotearg.h

   1 /* Quote string descriptors for output.
   2    Copyright (C) 2023-2024 Free Software Foundation, Inc.
   3
   4    This file is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published
   6    by the Free Software Foundation, either version 3 of the License,
   7    or (at your option) any later version.
   8
   9    This file is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 /* Written by Bruno Haible <bruno@clisp.org>, 2023.  */
  18
  19 #ifndef _STRING_DESC_QUOTEARG_H
  20 #define _STRING_DESC_QUOTEARG_H 1
  21
  22 /* This file uses _GL_INLINE_HEADER_BEGIN, _GL_INLINE, _GL_ATTRIBUTE_MALLOC,
  23    _GL_ATTRIBUTE_NONNULL, _GL_ATTRIBUTE_RETURNS_NONNULL.  */
  24 #if !_GL_CONFIG_H_INCLUDED
  25  #error "Please include config.h first."
  26 #endif
  27
  28 #include "string-desc.h"
  29 #include "quotearg.h"
  30
  31
  32 _GL_INLINE_HEADER_BEGIN
  33 #ifndef GL_STRING_DESC_QUOTEARG_INLINE
  34 # define GL_STRING_DESC_QUOTEARG_INLINE _GL_INLINE
  35 #endif
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41
  42 /* Place into buffer BUFFER (of size BUFFERSIZE) a quoted version of
  43    argument ARG, using O to control quoting.
  44    If O is null, use the default.
  45    Terminate the output with a null character, and return the written
  46    size of the output, not counting the terminating null.
  47    If BUFFERSIZE is too small to store the output string, return the
  48    value that would have been returned had BUFFERSIZE been large enough.
  49    On output, BUFFER might contain embedded null bytes if the style of O
  50    does not use backslash escapes and the flags of O do not request
  51    elision of null bytes.  */
  52 #if 0
  53 extern size_t string_desc_quotearg_buffer (char *restrict buffer,
  54                                            size_t buffersize,
  55                                            string_desc_t arg,
  56                                            struct quoting_options const *o);
  57 #endif
  58
  59 /* Like string_desc_quotearg_buffer, except return the result in a newly
  60    allocated buffer and store its length, excluding the terminating null
  61    byte, in *SIZE.  It is the caller's responsibility to free the result.
  62    The result might contain embedded null bytes if the style of O does
  63    not use backslash escapes and the flags of O do not request elision
  64    of null bytes.  */
  65 #if 0
  66 extern char *string_desc_quotearg_alloc (string_desc_t arg,
  67                                          size_t *size,
  68                                          struct quoting_options const *o)
  69   _GL_ATTRIBUTE_NONNULL ((2))
  70   _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
  71   _GL_ATTRIBUTE_RETURNS_NONNULL;
  72 #endif
  73
  74 /* Use storage slot N to return a quoted version of the string ARG.
  75    Use the default quoting options.
  76    The returned value points to static storage that can be
  77    reused by the next call to this function with the same value of N.
  78    N must be nonnegative.  */
  79 #if 0
  80 extern char *string_desc_quotearg_n (int n, string_desc_t arg);
  81 #endif
  82
  83 /* Equivalent to string_desc_quotearg_n (0, ARG).  */
  84 #if 0
  85 extern char *string_desc_quotearg (string_desc_t arg);
  86 #endif
  87
  88 /* Use style S and storage slot N to return a quoted version of the string ARG.
  89    This is like string_desc_quotearg_n (N, ARG), except that it uses S
  90    with no other options to specify the quoting method.  */
  91 #if 0
  92 extern char *string_desc_quotearg_n_style (int n, enum quoting_style s,
  93                                            string_desc_t arg);
  94 #endif
  95
  96 /* Equivalent to string_desc_quotearg_n_style (0, S, ARG).  */
  97 #if 0
  98 extern char *string_desc_quotearg_style (enum quoting_style s,
  99                                          string_desc_t arg);
 100 #endif
 101
 102 /* Like string_desc_quotearg (ARG), except also quote any instances of CH.
 103    See set_char_quoting for a description of acceptable CH values.  */
 104 #if 0
 105 extern char *string_desc_quotearg_char (string_desc_t arg, char ch);
 106 #endif
 107
 108 /* Equivalent to string_desc_quotearg_char (ARG, ':').  */
 109 #if 0
 110 extern char *string_desc_quotearg_colon (string_desc_t arg);
 111 #endif
 112
 113 /* Like string_desc_quotearg_n_style (N, S, ARG) but with S as
 114    custom_quoting_style with left quote as LEFT_QUOTE and right quote
 115    as RIGHT_QUOTE.  See set_custom_quoting for a description of acceptable
 116    LEFT_QUOTE and RIGHT_QUOTE values.  */
 117 #if 0
 118 extern char *string_desc_quotearg_n_custom (int n,
 119                                             char const *left_quote,
 120                                             char const *right_quote,
 121                                             string_desc_t arg);
 122 #endif
 123
 124 /* Equivalent to
 125    string_desc_quotearg_n_custom (0, LEFT_QUOTE, RIGHT_QUOTE, ARG).  */
 126 #if 0
 127 extern char *string_desc_quotearg_custom (char const *left_quote,
 128                                           char const *right_quote,
 129                                           string_desc_t arg);
 130 #endif
 131
 132
 133 /* ==== Inline function definitions ==== */
 134
 135 GL_STRING_DESC_QUOTEARG_INLINE size_t
 136 string_desc_quotearg_buffer (char *restrict buffer, size_t buffersize,
 137                              string_desc_t arg,
 138                              struct quoting_options const *o)
 139 {
 140   return quotearg_buffer (buffer, buffersize,
 141                           string_desc_data (arg), string_desc_length (arg),
 142                           o);
 143 }
 144
 145 GL_STRING_DESC_QUOTEARG_INLINE
 146 _GL_ATTRIBUTE_NONNULL ((2))
 147 _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
 148 _GL_ATTRIBUTE_RETURNS_NONNULL
 149 char *
 150 string_desc_quotearg_alloc (string_desc_t arg,
 151                             size_t *size,
 152                             struct quoting_options const *o)
 153 {
 154   return quotearg_alloc_mem (string_desc_data (arg), string_desc_length (arg),
 155                              size,
 156                              o);
 157 }
 158
 159 GL_STRING_DESC_QUOTEARG_INLINE char *
 160 string_desc_quotearg_n (int n, string_desc_t arg)
 161 {
 162   return quotearg_n_mem (n, string_desc_data (arg), string_desc_length (arg));
 163 }
 164
 165 GL_STRING_DESC_QUOTEARG_INLINE char *
 166 string_desc_quotearg (string_desc_t arg)
 167 {
 168   return quotearg_mem (string_desc_data (arg), string_desc_length (arg));
 169 }
 170
 171 GL_STRING_DESC_QUOTEARG_INLINE char *
 172 string_desc_quotearg_n_style (int n, enum quoting_style s, string_desc_t arg)
 173 {
 174   return quotearg_n_style_mem (n, s,
 175                                string_desc_data (arg), string_desc_length (arg));
 176 }
 177
 178 GL_STRING_DESC_QUOTEARG_INLINE char *
 179 string_desc_quotearg_style (enum quoting_style s, string_desc_t arg)
 180 {
 181   return quotearg_style_mem (s,
 182                              string_desc_data (arg), string_desc_length (arg));
 183 }
 184
 185 GL_STRING_DESC_QUOTEARG_INLINE char *
 186 string_desc_quotearg_char (string_desc_t arg, char ch)
 187 {
 188   return quotearg_char_mem (string_desc_data (arg), string_desc_length (arg),
 189                             ch);
 190 }
 191
 192 GL_STRING_DESC_QUOTEARG_INLINE char *
 193 string_desc_quotearg_colon (string_desc_t arg)
 194 {
 195   return quotearg_colon_mem (string_desc_data (arg), string_desc_length (arg));
 196 }
 197
 198 GL_STRING_DESC_QUOTEARG_INLINE char *
 199 string_desc_quotearg_n_custom (int n,
 200                                char const *left_quote, char const *right_quote,
 201                                string_desc_t arg)
 202 {
 203   return quotearg_n_custom_mem (n, left_quote, right_quote,
 204                                 string_desc_data (arg), string_desc_length (arg));
 205 }
 206
 207 GL_STRING_DESC_QUOTEARG_INLINE char *
 208 string_desc_quotearg_custom (char const *left_quote, char const *right_quote,
 209                              string_desc_t arg)
 210 {
 211   return quotearg_custom_mem (left_quote, right_quote,
 212                               string_desc_data (arg), string_desc_length (arg));
 213 }
 214
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 _GL_INLINE_HEADER_END
 221
 222
 223 #endif /* _STRING_DESC_QUOTEARG_H */