X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=lib%2Fquotearg.h;h=58ee3f60899cbe72200a02079ee420a17c172397;hb=8866a241ddbf4a459347b7147e325f539e4c07fe;hp=5d3ca4706a470a9635715b9bdf362f0f13b96931;hpb=74dd1966a5db708c66201bf952976ef27bd33e7e;p=gnulib.git diff --git a/lib/quotearg.h b/lib/quotearg.h index 5d3ca4706..58ee3f608 100644 --- a/lib/quotearg.h +++ b/lib/quotearg.h @@ -1,7 +1,7 @@ /* quotearg.h - quote arguments for output - Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004, 2006, 2008 Free - Software Foundation, Inc. + Copyright (C) 1998-2002, 2004, 2006, 2008-2013 Free Software Foundation, + Inc. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -23,47 +23,188 @@ # include -/* Basic quoting styles. */ +/* Basic quoting styles. For each style, an example is given on the + input strings "simple", "\0 \t\n'\"\033?""?/\\", and "a:b", using + quotearg_buffer, quotearg_mem, and quotearg_colon_mem with that + style and the default flags and quoted characters. Note that the + examples are shown here as valid C strings rather than what + displays on a terminal (with "??/" as a trigraph for "\\"). */ enum quoting_style { /* Output names as-is (ls --quoting-style=literal). Can result in embedded null bytes if QA_ELIDE_NULL_BYTES is not in - effect. */ + effect. + + quotearg_buffer: + "simple", "\0 \t\n'\"\033??/\\", "a:b" + quotearg: + "simple", " \t\n'\"\033??/\\", "a:b" + quotearg_colon: + "simple", " \t\n'\"\033??/\\", "a:b" + */ literal_quoting_style, /* Quote names for the shell if they contain shell metacharacters or would cause ambiguous output (ls --quoting-style=shell). Can result in embedded null bytes if QA_ELIDE_NULL_BYTES is not - in effect. */ + in effect. + + quotearg_buffer: + "simple", "'\0 \t\n'\\''\"\033??/\\'", "a:b" + quotearg: + "simple", "' \t\n'\\''\"\033??/\\'", "a:b" + quotearg_colon: + "simple", "' \t\n'\\''\"\033??/\\'", "'a:b'" + */ shell_quoting_style, /* Quote names for the shell, even if they would normally not require quoting (ls --quoting-style=shell-always). Can result in embedded null bytes if QA_ELIDE_NULL_BYTES is not in effect. Behaves like shell_quoting_style if QA_ELIDE_OUTER_QUOTES is in - effect. */ + effect. + + quotearg_buffer: + "'simple'", "'\0 \t\n'\\''\"\033??/\\'", "'a:b'" + quotearg: + "'simple'", "' \t\n'\\''\"\033??/\\'", "'a:b'" + quotearg_colon: + "'simple'", "' \t\n'\\''\"\033??/\\'", "'a:b'" + */ shell_always_quoting_style, /* Quote names as for a C language string (ls --quoting-style=c). Behaves like c_maybe_quoting_style if QA_ELIDE_OUTER_QUOTES is - in effect. */ + in effect. Split into consecutive strings if + QA_SPLIT_TRIGRAPHS. + + quotearg_buffer: + "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" + quotearg: + "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" + quotearg_colon: + "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a\\:b\"" + */ c_quoting_style, /* Like c_quoting_style except omit the surrounding double-quote - characters if no quoted characters are encountered. */ + characters if no quoted characters are encountered. + + quotearg_buffer: + "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "a:b" + quotearg: + "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "a:b" + quotearg_colon: + "simple", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" + */ c_maybe_quoting_style, /* Like c_quoting_style except always omit the surrounding - double-quote characters (ls --quoting-style=escape). */ + double-quote characters and ignore QA_SPLIT_TRIGRAPHS + (ls --quoting-style=escape). + + quotearg_buffer: + "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a:b" + quotearg: + "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a:b" + quotearg_colon: + "simple", "\\0 \\t\\n'\"\\033??/\\\\", "a\\:b" + */ escape_quoting_style, - /* Like clocale_quoting_style, but quote `like this' instead of - "like this" in the default C locale (ls --quoting-style=locale). */ + /* Like clocale_quoting_style, but use single quotes in the + default C locale or if the program does not use gettext + (ls --quoting-style=locale). For UTF-8 locales, quote + characters will use Unicode. + + LC_MESSAGES=C + quotearg_buffer: + "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a:b'" + quotearg: + "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a:b'" + quotearg_colon: + "`simple'", "`\\0 \\t\\n\\'\"\\033??/\\\\'", "`a\\:b'" + + LC_MESSAGES=pt_PT.utf8 + quotearg_buffer: + "\302\253simple\302\273", + "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" + quotearg: + "\302\253simple\302\273", + "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" + quotearg_colon: + "\302\253simple\302\273", + "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a\\:b\302\273" + */ locale_quoting_style, /* Like c_quoting_style except use quotation marks appropriate for - the locale (ls --quoting-style=clocale). */ - clocale_quoting_style + the locale and ignore QA_SPLIT_TRIGRAPHS + (ls --quoting-style=clocale). + + LC_MESSAGES=C + quotearg_buffer: + "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" + quotearg: + "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a:b\"" + quotearg_colon: + "\"simple\"", "\"\\0 \\t\\n'\\\"\\033??/\\\\\"", "\"a\\:b\"" + + LC_MESSAGES=pt_PT.utf8 + quotearg_buffer: + "\302\253simple\302\273", + "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" + quotearg: + "\302\253simple\302\273", + "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a:b\302\273" + quotearg_colon: + "\302\253simple\302\273", + "\302\253\\0 \\t\\n'\"\\033??/\\\\\302\253", "\302\253a\\:b\302\273" + */ + clocale_quoting_style, + + /* Like clocale_quoting_style except use the custom quotation marks + set by set_custom_quoting. If custom quotation marks are not + set, the behavior is undefined. + + left_quote = right_quote = "'" + quotearg_buffer: + "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a:b'" + quotearg: + "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a:b'" + quotearg_colon: + "'simple'", "'\\0 \\t\\n\\'\"\\033??/\\\\'", "'a\\:b'" + + left_quote = "(" and right_quote = ")" + quotearg_buffer: + "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a:b)" + quotearg: + "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a:b)" + quotearg_colon: + "(simple)", "(\\0 \\t\\n'\"\\033??/\\\\)", "(a\\:b)" + + left_quote = ":" and right_quote = " " + quotearg_buffer: + ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a:b " + quotearg: + ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a:b " + quotearg_colon: + ":simple ", ":\\0\\ \\t\\n'\"\\033??/\\\\ ", ":a\\:b " + + left_quote = "\"'" and right_quote = "'\"" + Notice that this is treated as a single level of quotes or two + levels where the outer quote need not be escaped within the inner + quotes. For two levels where the outer quote must be escaped + within the inner quotes, you must use separate quotearg + invocations. + quotearg_buffer: + "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a:b'\"" + quotearg: + "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a:b'\"" + quotearg_colon: + "\"'simple'\"", "\"'\\0 \\t\\n\\'\"\\033??/\\\\'\"", "\"'a\\:b'\"" + */ + custom_quoting_style }; /* Flags for use in set_quoting_flags. */ @@ -75,8 +216,15 @@ enum quoting_flags QA_ELIDE_NULL_BYTES = 0x01, /* Omit the surrounding quote characters if no escaped characters - are encountered. */ - QA_ELIDE_OUTER_QUOTES = 0x02 + are encountered. Note that if no other character needs + escaping, then neither does the escape character. */ + QA_ELIDE_OUTER_QUOTES = 0x02, + + /* In the c_quoting_style and c_maybe_quoting_style, split ANSI + trigraph sequences into concatenated strings (for example, + "?""?/" rather than "??/", which could be confused with + "\\"). */ + QA_SPLIT_TRIGRAPHS = 0x04 }; /* For now, --quoting-style=literal is the default, but this may change. */ @@ -109,7 +257,9 @@ void set_quoting_style (struct quoting_options *o, enum quoting_style s); set the value of the quoting options for character C to I. Return the old value. Currently, the only values defined for I are 0 (the default) and 1 (which means to quote the character even if - it would not otherwise be quoted). */ + it would not otherwise be quoted). C must never be a digit or a + letter that has special meaning after a backslash (for example, "\t" + for tab). */ int set_char_quoting (struct quoting_options *o, char c, int i); /* In O (or in the default if O is null), @@ -118,6 +268,19 @@ int set_char_quoting (struct quoting_options *o, char c, int i); behavior. Return the old value. */ int set_quoting_flags (struct quoting_options *o, int i); +/* In O (or in the default if O is null), + set the value of the quoting style to custom_quoting_style, + set the left quote to LEFT_QUOTE, and set the right quote to + RIGHT_QUOTE. Each of LEFT_QUOTE and RIGHT_QUOTE must be + null-terminated and can be the empty string. Because backslashes are + used for escaping, it does not make sense for RIGHT_QUOTE to contain + a backslash. RIGHT_QUOTE must not begin with a digit or a letter + that has special meaning after a backslash (for example, "\t" for + tab). */ +void set_custom_quoting (struct quoting_options *o, + char const *left_quote, + char const *right_quote); + /* Place into buffer BUFFER (of size BUFFERSIZE) a quoted version of argument ARG (of size ARGSIZE), using O to control quoting. If O is null, use the default. @@ -130,14 +293,14 @@ int set_quoting_flags (struct quoting_options *o, int i); not -1, the style of O does not use backslash escapes, and the flags of O do not request elision of null bytes.*/ size_t quotearg_buffer (char *buffer, size_t buffersize, - char const *arg, size_t argsize, - struct quoting_options const *o); + char const *arg, size_t argsize, + struct quoting_options const *o); /* Like quotearg_buffer, except return the result in a newly allocated buffer. It is the caller's responsibility to free the result. The result will not contain embedded null bytes. */ char *quotearg_alloc (char const *arg, size_t argsize, - struct quoting_options const *o); + struct quoting_options const *o); /* Like quotearg_alloc, except that the length of the result, excluding the terminating null byte, is stored into SIZE if it is @@ -146,7 +309,7 @@ char *quotearg_alloc (char const *arg, size_t argsize, backslash escapes, and the flags of O do not request elision of null bytes.*/ char *quotearg_alloc_mem (char const *arg, size_t argsize, - size_t *size, struct quoting_options const *o); + size_t *size, struct quoting_options const *o); /* Use storage slot N to return a quoted version of the string ARG. Use the default quoting options. @@ -177,16 +340,17 @@ char *quotearg_n_style (int n, enum quoting_style s, char const *arg); argument ARG of size ARGSIZE. This is like quotearg_n_style (N, S, ARG), except it can quote null bytes. */ char *quotearg_n_style_mem (int n, enum quoting_style s, - char const *arg, size_t argsize); + char const *arg, size_t argsize); /* Equivalent to quotearg_n_style (0, S, ARG). */ char *quotearg_style (enum quoting_style s, char const *arg); /* Equivalent to quotearg_n_style_mem (0, S, ARG, ARGSIZE). */ char *quotearg_style_mem (enum quoting_style s, - char const *arg, size_t argsize); + char const *arg, size_t argsize); -/* Like quotearg (ARG), except also quote any instances of CH. */ +/* Like quotearg (ARG), except also quote any instances of CH. + See set_char_quoting for a description of acceptable CH values. */ char *quotearg_char (char const *arg, char ch); /* Like quotearg_char (ARG, CH), except it can quote null bytes. */ @@ -198,6 +362,29 @@ char *quotearg_colon (char const *arg); /* Like quotearg_colon (ARG), except it can quote null bytes. */ char *quotearg_colon_mem (char const *arg, size_t argsize); +/* Like quotearg_n_style (N, S, ARG) but with S as custom_quoting_style + with left quote as LEFT_QUOTE and right quote as RIGHT_QUOTE. See + set_custom_quoting for a description of acceptable LEFT_QUOTE and + RIGHT_QUOTE values. */ +char *quotearg_n_custom (int n, char const *left_quote, + char const *right_quote, char const *arg); + +/* Like quotearg_n_custom (N, LEFT_QUOTE, RIGHT_QUOTE, ARG) except it + can quote null bytes. */ +char *quotearg_n_custom_mem (int n, char const *left_quote, + char const *right_quote, + char const *arg, size_t argsize); + +/* Equivalent to quotearg_n_custom (0, LEFT_QUOTE, RIGHT_QUOTE, ARG). */ +char *quotearg_custom (char const *left_quote, char const *right_quote, + char const *arg); + +/* Equivalent to quotearg_n_custom_mem (0, LEFT_QUOTE, RIGHT_QUOTE, ARG, + ARGSIZE). */ +char *quotearg_custom_mem (char const *left_quote, + char const *right_quote, + char const *arg, size_t argsize); + /* Free any dynamically allocated memory. */ void quotearg_free (void);