2005-07-08 14:58:32 +08:00
|
|
|
#ifndef QUOTE_H
|
|
|
|
|
#define QUOTE_H
|
|
|
|
|
|
2011-01-05 08:36:34 +08:00
|
|
|
struct strbuf;
|
2005-07-08 14:58:32 +08:00
|
|
|
|
|
|
|
|
/* Help to copy the thing properly quoted for the shell safety.
|
2005-10-11 05:46:10 +08:00
|
|
|
* any single quote is replaced with '\'', any exclamation point
|
|
|
|
|
* is replaced with '\!', and the whole thing is enclosed in a
|
|
|
|
|
* single quote pair.
|
2005-07-08 14:58:32 +08:00
|
|
|
*
|
|
|
|
|
* For example, if you are passing the result to system() as an
|
|
|
|
|
* argument:
|
|
|
|
|
*
|
|
|
|
|
* sprintf(cmd, "foobar %s %s", sq_quote(arg0), sq_quote(arg1))
|
|
|
|
|
*
|
|
|
|
|
* would be appropriate. If the system() is going to call ssh to
|
|
|
|
|
* run the command on the other side:
|
|
|
|
|
*
|
|
|
|
|
* sprintf(cmd, "git-diff-tree %s %s", sq_quote(arg0), sq_quote(arg1));
|
|
|
|
|
* sprintf(rcmd, "ssh %s %s", sq_quote(host), sq_quote(cmd));
|
|
|
|
|
*
|
|
|
|
|
* Note that the above examples leak memory! Remember to free result from
|
|
|
|
|
* sq_quote() in a real application.
|
2005-10-11 05:46:10 +08:00
|
|
|
*
|
|
|
|
|
* sq_quote_buf() writes to an existing buffer of specified size; it
|
|
|
|
|
* will return the number of characters that would have been written
|
|
|
|
|
* excluding the final null regardless of the buffer size.
|
2016-03-01 06:58:34 +08:00
|
|
|
*
|
|
|
|
|
* sq_quotef() quotes the entire formatted string as a single result.
|
2005-07-08 14:58:32 +08:00
|
|
|
*/
|
|
|
|
|
|
2019-04-29 16:28:14 +08:00
|
|
|
void sq_quote_buf(struct strbuf *, const char *src);
|
|
|
|
|
void sq_quote_argv(struct strbuf *, const char **argv);
|
2019-04-29 16:28:20 +08:00
|
|
|
void sq_quotef(struct strbuf *, const char *fmt, ...);
|
2006-09-11 12:59:22 +08:00
|
|
|
|
2018-01-15 18:59:44 +08:00
|
|
|
/*
|
|
|
|
|
* These match their non-pretty variants, except that they avoid
|
|
|
|
|
* quoting when there are no exotic characters. These should only be used for
|
|
|
|
|
* human-readable output, as sq_dequote() is not smart enough to dequote it.
|
|
|
|
|
*/
|
|
|
|
|
void sq_quote_buf_pretty(struct strbuf *, const char *src);
|
|
|
|
|
void sq_quote_argv_pretty(struct strbuf *, const char **argv);
|
2019-08-09 23:00:55 +08:00
|
|
|
void sq_append_quote_argv_pretty(struct strbuf *dst, const char **argv);
|
2018-01-15 18:59:44 +08:00
|
|
|
|
2021-01-12 20:26:49 +08:00
|
|
|
/*
|
|
|
|
|
* This unwraps what sq_quote() produces in place, but returns
|
2005-10-24 05:30:45 +08:00
|
|
|
* NULL if the input does not look like what sq_quote would have
|
2021-01-12 20:26:49 +08:00
|
|
|
* produced (the full string must be a single quoted item).
|
2005-10-24 05:30:45 +08:00
|
|
|
*/
|
2019-04-29 16:28:14 +08:00
|
|
|
char *sq_dequote(char *);
|
2005-10-24 05:30:45 +08:00
|
|
|
|
2021-01-12 20:26:49 +08:00
|
|
|
/*
|
|
|
|
|
* Like sq_dequote(), but dequote a single item, and leave "next" pointing to
|
|
|
|
|
* the next character. E.g., in the string:
|
|
|
|
|
*
|
|
|
|
|
* 'one' 'two' 'three'
|
|
|
|
|
*
|
|
|
|
|
* after the first call, the return value would be the unquoted string "one",
|
|
|
|
|
* with "next" pointing to the space between "one" and "two"). The caller is
|
|
|
|
|
* responsible for advancing the pointer to the start of the next item before
|
|
|
|
|
* calling sq_dequote_step() again.
|
|
|
|
|
*/
|
|
|
|
|
char *sq_dequote_step(char *src, char **next);
|
|
|
|
|
|
2009-03-29 17:44:44 +08:00
|
|
|
/*
|
|
|
|
|
* Same as the above, but can be used to unwrap many arguments in the
|
2011-09-14 05:57:47 +08:00
|
|
|
* same string separated by space. Like sq_quote, it works in place,
|
|
|
|
|
* modifying arg and appending pointers into it to argv.
|
2009-03-29 17:44:44 +08:00
|
|
|
*/
|
2019-04-29 16:28:14 +08:00
|
|
|
int sq_dequote_to_argv(char *arg, const char ***argv, int *nr, int *alloc);
|
2009-03-29 17:44:44 +08:00
|
|
|
|
2011-09-14 05:58:08 +08:00
|
|
|
/*
|
2020-07-29 04:24:02 +08:00
|
|
|
* Same as above, but store the unquoted strings in a strvec. We will
|
|
|
|
|
* still modify arg in place, but unlike sq_dequote_to_argv, the strvec
|
2011-09-14 05:58:08 +08:00
|
|
|
* will duplicate and take ownership of the strings.
|
|
|
|
|
*/
|
argv-array: rename to strvec
The name "argv-array" isn't very good, because it describes what the
data type can be used for (program argument arrays), not what it
actually is (a dynamically-growing string array that maintains a
NULL-terminator invariant). This leads to people being hesitant to use
it for other cases where it would actually be a good fit. The existing
name is also clunky to use. It's overly long, and the name often leads
to saying things like "argv.argv" (i.e., the field names overlap with
variable names, since they're describing the use, not the type). Let's
give it a more neutral name.
I settled on "strvec" because "vector" is the name for a dynamic array
type in many programming languages. "strarray" would work, too, but it's
longer and a bit more awkward to say (and don't we all say these things
in our mind as we type them?).
A more extreme direction would be a generic data structure which stores
a NULL-terminated of _any_ type. That would be easy to do with void
pointers, but we'd lose some type safety for the existing cases. Plus it
raises questions about memory allocation and ownership. So I limited
myself here to changing names only, and not semantics. If we do find a
use for that more generic data type, we could perhaps implement it at a
lower level and then provide type-safe wrappers around it for strings.
But that can come later.
This patch does the minimum to convert the struct and function names in
the header and implementation, leaving a few things for follow-on
patches:
- files retain their original names for now
- struct field names are retained for now
- there's a preprocessor compat layer that lets most users remain the
same for now. The exception is headers which made a manual forward
declaration of the struct. I've converted them (and their dependent
function declarations) here.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-07-29 04:23:25 +08:00
|
|
|
struct strvec;
|
2020-07-29 04:24:02 +08:00
|
|
|
int sq_dequote_to_strvec(char *arg, struct strvec *);
|
2011-09-14 05:58:08 +08:00
|
|
|
|
2019-04-29 16:28:14 +08:00
|
|
|
int unquote_c_style(struct strbuf *, const char *quoted, const char **endp);
|
2020-09-11 01:01:59 +08:00
|
|
|
|
|
|
|
|
/* Bits in the flags parameter to quote_c_style() */
|
|
|
|
|
#define CQUOTE_NODQ 01
|
|
|
|
|
size_t quote_c_style(const char *name, struct strbuf *, FILE *, unsigned);
|
|
|
|
|
void quote_two_c_style(struct strbuf *, const char *, const char *, unsigned);
|
2005-10-15 12:54:47 +08:00
|
|
|
|
2019-04-29 16:28:14 +08:00
|
|
|
void write_name_quoted(const char *name, FILE *, int terminator);
|
|
|
|
|
void write_name_quoted_relative(const char *name, const char *prefix,
|
2019-04-29 16:28:23 +08:00
|
|
|
FILE *fp, int terminator);
|
2005-07-08 14:58:32 +08:00
|
|
|
|
2008-03-07 10:30:58 +08:00
|
|
|
/* quote path as relative to the given prefix */
|
2020-09-11 01:01:54 +08:00
|
|
|
char *quote_path(const char *in, const char *prefix, struct strbuf *out, unsigned flags);
|
2020-09-11 01:01:55 +08:00
|
|
|
#define QUOTE_PATH_QUOTE_SP 01
|
2008-03-07 10:30:58 +08:00
|
|
|
|
2006-09-16 04:30:02 +08:00
|
|
|
/* quoting as a string literal for other languages */
|
2019-04-29 16:28:14 +08:00
|
|
|
void perl_quote_buf(struct strbuf *sb, const char *src);
|
|
|
|
|
void python_quote_buf(struct strbuf *sb, const char *src);
|
|
|
|
|
void tcl_quote_buf(struct strbuf *sb, const char *src);
|
|
|
|
|
void basic_regex_quote_buf(struct strbuf *sb, const char *src);
|
2006-09-16 04:30:02 +08:00
|
|
|
|
2005-07-08 14:58:32 +08:00
|
|
|
#endif
|
