quotearg.h

   1 /* quotearg.h - quote arguments for output.
   2
   3    Copyright (C) 1998-2002, 2004, 2006, 2008-2022 Free Software Foundation,
   4    Inc.
   5
   6    This program is free software: you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation, either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  18
  19 /* Written by Paul Eggert <eggert@twinsun.com> */
  20 /* Standalone version made by
  21    Sergey Sushilin <sergeysushilin@protonmail.com> */
  22
  23 #ifndef LIBQUOTE_QUOTEARG_H
  24 #define LIBQUOTE_QUOTEARG_H 1
  25
  26 #include <stdlib.h>
  27
  28 #include "quoting-slots.h"
  29
  30 /* Basic quoting styles.  For each style, an example is given on the
  31    input strings "simple", "\0 \t\n'\"\033?""?/\\", and "a:b", using
  32    quotearg_buffer, quotearg_memory, and quotearg_colon_memory with that
  33    style and the default flags and quoted characters.  Note that the
  34    examples are shown here as valid C strings rather than what
  35    displays on a terminal (with "??/" as a trigraph for "\\").  */
  36 enum quoting_style
  37   {
  38     /* Output names as-is (ls --quoting-style=literal).  Can result in
  39        embedded null bytes if QA_ELIDE_NULL_BYTES is not in
  40        effect.
  41
  42        quotearg_buffer:
  43        "simple", "\0 \t\n'\"\033??/\\", "a:b"
  44        quotearg:
  45        "simple", " \t\n'\"\033??/\\", "a:b"
  46        quotearg_colon:
  47        "simple", " \t\n'\"\033??/\\", "a:b"
  48     */
  49     quoting_style_literal,
  50
  51     /* Quote names for the shell if they contain shell metacharacters
  52        or would cause ambiguous output (ls --quoting-style=shell).
  53        Can result in embedded null bytes if QA_ELIDE_NULL_BYTES is not
  54        in effect.
  55
  56        quotearg_buffer:
  57        "simple", "'\0 \t\n'\\''\"\033??/\\'", "a:b"
  58        quotearg:
  59        "simple", "' \t\n'\\''\"\033??/\\'", "a:b"
  60        quotearg_colon:
  61        "simple", "' \t\n'\\''\"\033??/\\'", "'a:b'"
  62     */
  63     quoting_style_shell,
  64
  65     /* Quote names for the shell, even if they would normally not
  66        require quoting (ls --quoting-style=shell-always).  Can result
  67        in embedded null bytes if QA_ELIDE_NULL_BYTES is not in effect.
  68        Behaves like quoting_style_shell if QA_ELIDE_OUTER_QUOTES is in
  69        effect.
  70
  71        quotearg_buffer:
  72        "'simple'", "'\0 \t\n'\\''\"\033??/\\'", "'a:b'"
  73        quotearg:
  74        "'simple'", "' \t\n'\\''\"\033??/\\'", "'a:b'"
  75        quotearg_colon:
  76        "'simple'", "' \t\n'\\''\"\033??/\\'", "'a:b'"
  77     */
  78     quoting_style_shell_always,
  79
  80     /* Quote names for the shell if they contain shell metacharacters
  81        or other problematic characters (ls --quoting-style=shell-escape).
  82        Non printable characters are quoted using the $'...' syntax,
  83        which originated in ksh93 and is widely supported by most shells,
  84        and proposed for inclusion in POSIX.
  85
  86        quotearg_buffer:
  87        "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\\'", "a:b"
  88        quotearg:
  89        "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\\'", "a:b"
  90        quotearg_colon:
  91        "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\\'", "'a:b'"
  92     */
  93     quoting_style_shell_escape,
  94
  95     /* Quote names for the shell even if they would normally not
  96        require quoting (ls --quoting-style=shell-escape).
  97        Non printable characters are quoted using the $'...' syntax,
  98        which originated in ksh93 and is widely supported by most shells,
  99        and proposed for inclusion in POSIX.  Behaves like
 100        quoting_style_shell_escape if QA_ELIDE_OUTER_QUOTES is in effect.
 101
 102        quotearg_buffer:
 103        "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\'", "a:b"
 104        quotearg:
 105        "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\'", "a:b"
 106        quotearg_colon:
 107        "simple", "''$'\\0'' '$'\\t\\n'\\''\"'$'\\033''??/\'", "'a:b'"
 108     */
 109     quoting_style_shell_escape_always,
 110
 111     /* Quote names as for a C language string (ls --quoting-style=c).
 112        Behaves like quoting_style_c_maybe if QA_ELIDE_OUTER_QUOTES is
 113        in effect.  Split into consecutive strings if
 114        QA_SPLIT_TRIGRAPHS.
 115
 116        quotearg_buffer:
 117        "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\""
 118        quotearg:
 119        "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\""
 120        quotearg_colon:
 121        "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a\\:b\""
 122     */
 123     quoting_style_c,
 124
 125     /* Like quoting_style_c except omit the surrounding double-quote
 126        characters if no quoted characters are encountered.
 127
 128        quotearg_buffer:
 129        "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "a:b"
 130        quotearg:
 131        "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "a:b"
 132        quotearg_colon:
 133        "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\""
 134     */
 135     quoting_style_c_maybe,
 136
 137     /* Like quoting_style_c except always omit the surrounding
 138        double-quote characters and ignore QA_SPLIT_TRIGRAPHS
 139        (ls --quoting-style=escape).
 140
 141        quotearg_buffer:
 142        "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a:b"
 143        quotearg:
 144        "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a:b"
 145        quotearg_colon:
 146        "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a\\:b"
 147     */
 148     quoting_style_escape,
 149
 150     /* Like quoting_style_clocale, but use single quotes in the
 151        default C locale or if the program does not use gettext
 152        (ls --quoting-style=locale).  For UTF-8 locales, quote
 153        characters will use Unicode.
 154
 155        LC_MESSAGES=C
 156        quotearg_buffer:
 157        "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a:b'"
 158        quotearg:
 159        "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a:b'"
 160        quotearg_colon:
 161        "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a\\:b'"
 162
 163        LC_MESSAGES=pt_PT.utf8
 164        quotearg_buffer:
 165        "\302\253simple\302\273",
 166        "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273"
 167        quotearg:
 168        "\302\253simple\302\273",
 169        "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273"
 170        quotearg_colon:
 171        "\302\253simple\302\273",
 172        "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a\\:b\302\273"
 173     */
 174     quoting_style_locale,
 175
 176     /* Like quoting_style_c except use quotation marks appropriate for
 177        the locale and ignore QA_SPLIT_TRIGRAPHS
 178        (ls --quoting-style=clocale).
 179
 180        LC_MESSAGES=C
 181        quotearg_buffer:
 182        "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\""
 183        quotearg:
 184        "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\""
 185        quotearg_colon:
 186        "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a\\:b\""
 187
 188        LC_MESSAGES=pt_PT.utf8
 189        quotearg_buffer:
 190        "\302\253simple\302\273",
 191        "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273"
 192        quotearg:
 193        "\302\253simple\302\273",
 194        "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273"
 195        quotearg_colon:
 196        "\302\253simple\302\273",
 197        "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a\\:b\302\273"
 198     */
 199     quoting_style_clocale,
 200
 201     /* Like quoting_style_clocale except use the custom quotation marks
 202        set by quote_set_custom_quoting.  If custom quotation marks are not
 203        set, the behavior is undefined.
 204
 205        left_quote = right_quote = "'"
 206        quotearg_buffer:
 207        "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a:b'"
 208        quotearg:
 209        "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a:b'"
 210        quotearg_colon:
 211        "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a\\:b'"
 212
 213        left_quote = "(" and right_quote = ")"
 214        quotearg_buffer:
 215        "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a:b)"
 216        quotearg:
 217        "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a:b)"
 218        quotearg_colon:
 219        "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a\\:b)"
 220
 221        left_quote = ":" and right_quote = " "
 222        quotearg_buffer:
 223        ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a:b "
 224        quotearg:
 225        ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a:b "
 226        quotearg_colon:
 227        ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a\\:b "
 228
 229        left_quote = "\"'" and right_quote = "'\""
 230        Notice that this is treated as a single level of quotes or two
 231        levels where the outer quote need not be escaped within the inner
 232        quotes.  For two levels where the outer quote must be escaped
 233        within the inner quotes, you must use separate quotearg
 234        invocations.
 235        quotearg_buffer:
 236        "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a:b'\""
 237        quotearg:
 238        "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a:b'\""
 239        quotearg_colon:
 240        "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a\\:b'\""
 241     */
 242     quoting_style_custom
 243   };
 244
 245 /* Flags for use in quote_set_quoting_flags.  */
 246 enum quoting_flags
 247   {
 248     /* Always elide null bytes from styles that do not quote them,
 249        even when the length of the result is available to the
 250        caller.  */
 251     QUOTING_FLAGS_ELIDE_NULL_BYTES = 0x01,
 252
 253     /* Omit the surrounding quote characters if no escaped characters
 254        are encountered.  Note that if no other character needs
 255        escaping, then neither does the escape character.  */
 256     QUOTING_FLAGS_ELIDE_OUTER_QUOTES = 0x02,
 257
 258     /* In the quoting_style_c and quoting_style_c_maybe, split ANSI
 259        trigraph sequences into concatenated strings (for example,
 260        "?""?/" rather than "??/", which could be confused with
 261        "\\").  */
 262     QUOTING_FLAGS_SPLIT_TRIGRAPHS = 0x04
 263   };
 264
 265 struct quoting_options
 266 {
 267   /* Basic quoting style.  */
 268   enum quoting_style style;
 269
 270   /* Additional flags.  Bitwise combination of enum quoting_flags.  */
 271   enum quoting_flags flags;
 272
 273   /* Quote the characters indicated by this bit vector even if the
 274      quoting style would not normally require them to be quoted.  */
 275   unsigned int quote_these_too[256 / (8 * sizeof (int))];
 276
 277   /* The left quote for quoting_style_custom.  */
 278   const char *left_quote;
 279
 280   /* The right quote for quoting_style_custom.  */
 281   const char *right_quote;
 282 };
 283
 284 /* For now, --quoting-style=literal is the default, but this may change.  */
 285 #ifndef QUOTING_STYLE_DEFAULT
 286 # define QUOTING_STYLE_DEFAULT quoting_style_literal
 287 #endif
 288
 289 /* Names of quoting styles and their corresponding values.  */
 290 extern const char *const quoting_style_names[];
 291 extern const enum quoting_style quoting_style_values[];
 292 extern const size_t quoting_styles_count;
 293
 294 /* The functions listed below set and use a hidden variable
 295    that contains the default quoting style options.  */
 296
 297 extern void quoting_options_initialize (struct quoting_options *o);
 298
 299 extern const struct quoting_options *quote_get_default_quote_quoting_options (void);
 300 extern const struct quoting_options *quote_get_default_quotearg_quoting_options (void);
 301
 302 /* Allocate a new set of quoting options, with contents initially identical
 303    to O.  It is the caller's responsibility to free the result.  */
 304 extern struct quoting_options *quote_clone_quoting_options (const struct quoting_options *o);
 305
 306 /* Get the value of O's quoting style.  */
 307 extern enum quoting_style quote_get_quoting_style (const struct quoting_options *o);
 308
 309 /* In O set the value of the quoting style to S.  */
 310 extern void quote_set_quoting_style (struct quoting_options *o, enum quoting_style s);
 311
 312 /* In O set the value of the quoting options for character C to I.
 313    Return the old value.  Currently, the only values defined for I are
 314    0 (the default) and 1 (which means to quote the character even if
 315    it would not otherwise be quoted).  C must never be a digit or a
 316    letter that has special meaning after a backslash (for example, "\t"
 317    for tab).  */
 318 extern unsigned int quote_set_character_quoting (struct quoting_options *o,
 319                                                  char c, unsigned int i);
 320
 321 /* In O set the value of the quoting options flag to I, which can be a
 322    bitwise combination of enum quoting_flags, or 0 for default
 323    behavior.  Return the old value.  */
 324 extern enum quoting_flags quote_set_quoting_flags (struct quoting_options *o,
 325                                                    enum quoting_flags i);
 326
 327 /* In O set the value of the quoting style to quoting_style_custom,
 328    set the left quote to LEFT_QUOTE, and set the right quote to
 329    RIGHT_QUOTE.  Each of LEFT_QUOTE and RIGHT_QUOTE must be
 330    null-terminated and can be the empty string.  Because backslashes are
 331    used for escaping, it does not make sense for RIGHT_QUOTE to contain
 332    a backslash.  RIGHT_QUOTE must not begin with a digit or a letter
 333    that has special meaning after a backslash (for example, "\t" for
 334    tab).  */
 335 extern void quote_set_custom_quoting (struct quoting_options *o,
 336                                       const char *left_quote,
 337                                       const char *right_quote);
 338
 339 /* Place into buffer BUFFER (of size BUFFERSIZE) a quoted version of
 340    argument ARG (of size ARGSIZE), using O to control quoting.
 341    Terminate the output with a null character, and return the written
 342    size of the output, not counting the terminating null.
 343    If BUFFERSIZE is too small to store the output string, return the
 344    value that would have been returned had BUFFERSIZE been large enough.
 345    If ARGSIZE is -1, use the string length of the argument for ARGSIZE.
 346    On output, BUFFER might contain embedded null bytes if ARGSIZE was
 347    not -1, the style of O does not use backslash escapes, and the
 348    flags of O do not request elision of null bytes.*/
 349 extern size_t quotearg_buffer (char *buffer, size_t buffersize,
 350                                const char *arg, size_t argsize,
 351                                const struct quoting_options *o);
 352
 353 /* Like quotearg_buffer, except return the result in a newly allocated
 354    buffer.  It is the caller's responsibility to free the result.  The
 355    result will not contain embedded null bytes.  */
 356 extern char *quotearg_allocate (const char *arg, size_t argsize,
 357                                 const struct quoting_options *o);
 358
 359 /* Like quotearg_allocate, except that the length of the result,
 360    excluding the terminating null byte, is stored into SIZE if it is
 361    non-NULL.  The result might contain embedded null bytes if ARGSIZE
 362    was not -1, SIZE was not NULL, the style of O does not use
 363    backslash escapes, and the flags of O do not request elision of
 364    null bytes.*/
 365 extern char *quotearg_allocate_memory (const char *arg, size_t argsize,
 366                                        size_t *size,
 367                                        const struct quoting_options *o);
 368
 369 /* Use storage slot N to return a quoted version of the string ARG.
 370    Use the default quoting options.
 371    The returned value points to static storage that can be
 372    reused by the next call to this function with the same value of N.
 373    N must be nonnegative.  The output of all functions in the
 374    quotearg_n family are guaranteed to not contain embedded null
 375    bytes.  */
 376 extern char *quotearg_n (struct quoting_slots *q, unsigned int n, const char *arg);
 377
 378 /* Equivalent to quotearg_n (Q, 0, ARG).  */
 379 extern char *quotearg (struct quoting_slots *q, const char *arg);
 380
 381 /* Use storage slot N to return a quoted version of the argument ARG
 382    of size ARGSIZE.  This is like quotearg_n (Q, N, ARG), except it can
 383    quote null bytes.  */
 384 extern char *quotearg_n_memory (struct quoting_slots *q, unsigned int n,
 385                                 const char *arg, size_t argsize);
 386
 387 /* Equivalent to quotearg_n_memory (Q, 0, ARG, ARGSIZE).  */
 388 extern char *quotearg_memory (struct quoting_slots *q, const char *arg, size_t argsize);
 389
 390 /* Use style S and storage slot N to return a quoted version of the string ARG.
 391    This is like quotearg_n (Q, N, ARG), except that it uses S with no other
 392    options to specify the quoting method.  */
 393 extern char *quotearg_n_style (struct quoting_slots *q, unsigned int n,
 394                                enum quoting_style s, const char *arg);
 395
 396 /* Use style S and storage slot N to return a quoted version of the
 397    argument ARG of size ARGSIZE.  This is like
 398    quotearg_n_style (Q, N, S, ARG), except it can quote null bytes.  */
 399 extern char *quotearg_n_style_memory (struct quoting_slots *q,
 400                                       unsigned int n, enum quoting_style s,
 401                                       const char *arg, size_t argsize);
 402
 403 /* Equivalent to quotearg_n_style (Q, 0, S, ARG).  */
 404 extern char *quotearg_style (struct quoting_slots *q, enum quoting_style s, const char *arg);
 405
 406 /* Equivalent to quotearg_n_style_memory (Q, 0, S, ARG, ARGSIZE).  */
 407 extern char *quotearg_style_memory (struct quoting_slots *q, enum quoting_style s,
 408                                     const char *arg, size_t argsize);
 409
 410 /* Like quotearg (Q, ARG), except also quote any instances of CH.
 411    See quote_set_character_quoting for a description
 412    of acceptable CH values.  */
 413 extern char *quotearg_character (struct quoting_slots *q, const char *arg, char ch);
 414
 415 /* Like quotearg_character (Q, ARG, CH), except it can quote null bytes.  */
 416 extern char *quotearg_character_memory (struct quoting_slots *q, const char *arg, size_t argsize, char ch);
 417
 418 /* Equivalent to quotearg_character (Q, ARG, ':').  */
 419 extern char *quotearg_colon (struct quoting_slots *q, const char *arg);
 420
 421 /* Like quotearg_colon (Q, ARG), except it can quote null bytes.  */
 422 extern char *quotearg_colon_memory (struct quoting_slots *q,
 423                                     const char *arg, size_t argsize);
 424
 425 /* Like quotearg_n_style, except with ':' quoting enabled.  */
 426 extern char *quotearg_n_style_colon (struct quoting_slots *q, unsigned int n,
 427                                      enum quoting_style s, const char *arg);
 428
 429 /* Like quotearg_n_style (Q, N, S, ARG) but with S as quoting_style_custom
 430    with left quote as LEFT_QUOTE and right quote as RIGHT_QUOTE.  See
 431    quote_set_custom_quoting for a description of acceptable LEFT_QUOTE and
 432    RIGHT_QUOTE values.  */
 433 extern char *quotearg_n_custom (struct quoting_slots *q,
 434                                 unsigned int n,
 435                                 const char *left_quote,
 436                                 const char *right_quote,
 437                                 const char *arg);
 438
 439 /* Like quotearg_n_custom (Q, N, LEFT_QUOTE, RIGHT_QUOTE, ARG) except it
 440    can quote null bytes.  */
 441 extern char *quotearg_n_custom_memory (struct quoting_slots *q,
 442                                        unsigned int n,
 443                                        const char *left_quote,
 444                                        const char *right_quote,
 445                                        const char *arg,
 446                                        size_t argsize);
 447
 448 /* Equivalent to quotearg_n_custom (Q, 0, LEFT_QUOTE, RIGHT_QUOTE, ARG).  */
 449 extern char *quotearg_custom (struct quoting_slots *q,
 450                               const char *left_quote,
 451                               const char *right_quote,
 452                               const char *arg);
 453
 454 /* Equivalent to quotearg_n_custom_memory (Q, 0, LEFT_QUOTE, RIGHT_QUOTE, ARG,
 455                                            ARGSIZE).  */
 456 extern char *quotearg_custom_memory (struct quoting_slots *q,
 457                                      const char *left_quote,
 458                                      const char *right_quote,
 459                                      const char *arg,
 460                                      size_t argsize);
 461
 462 #endif /* LIBQUOTE_QUOTEARG_H */