expand.h

   1 /* Yash: yet another shell */
   2 /* expand.h: word expansion */
   3 /* (C) 2007-2020 magicant */
   4
   5 /* This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation, either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  17
  18
  19 #ifndef YASH_EXPAND_H
  20 #define YASH_EXPAND_H
  21
  22 #include <stddef.h>
  23
  24
  25 #define DEFAULT_IFS L" \t\n"
  26
  27 /* characters that can be escaped with a backslash inside double-quotes. */
  28 #define CHARS_ESCAPABLE L"$`\"\\"
  29
  30 /* type of tilde expansion */
  31 typedef enum { TT_NONE, TT_SINGLE, TT_MULTI, } tildetype_T;
  32
  33 /* treatment of quotation marks during expansion */
  34 typedef enum {
  35     Q_WORD,     /* Single quotations, double quotations, and backslashes are
  36                    recognized as in the normal word. */
  37     Q_DQPARAM,  /* The string is treated as the substitution word of a parameter
  38                    expansion inside a pair of double quotations: Double
  39                    quotations are recognized, but single quotations are not.
  40                    Backslashes are recognized only before $, `, ", \ or }. */
  41     Q_INDQ,     /* The string is treated as if it is inside a pair of double
  42                    quotations: Single and double quotations are not recognized.
  43                    Backslashes are recognized only before a $, `, or \. */
  44     Q_LITERAL,  /* No quotations are recognized. */
  45 } quoting_T;
  46
  47 /* Category of characters resulting from expansion.
  48  * A charcategory_T value is bitwise or of one of the origin categories
  49  * (CC_LITERAL, CC_HARD_EXPANSION, and CC_SOFT_EXPANSION) and optionally any
  50  * combinations of modifier flags (CC_QUOTED and CC_QUOTATION).
  51  * The category determines if a character is subject to brace expansion, field
  52  * splitting, and globbing (pathname expansion). */
  53 typedef enum {
  54     CC_LITERAL,         /* from the original word */
  55     CC_HARD_EXPANSION,  /* from tilde expansion or numeric brace expansion */
  56     CC_SOFT_EXPANSION,  /* from parameter expansion, command substitution or
  57                            arithmetic expansion */
  58     CC_ORIGIN_MASK = (1 << 2) - 1,
  59     CC_QUOTED      = 1 << 2, /* The character is quoted by backslash, single- or
  60                                 double-quotes. */
  61     CC_QUOTATION   = 1 << 3, /* The character is a quotation mark */
  62 } charcategory_T;
  63 /* A character can be both CC_QUOTED and CC_QUOTATION at a time. This may happen
  64  * in a nested quotation like "\"". */
  65
  66 /* type of characters to be backslash-escaped in the expansion results */
  67 typedef enum {
  68     ES_NONE,         /* No characters are escaped. */
  69     ES_QUOTED,       /* Quoted characters remain escaped. */
  70     ES_QUOTED_HARD,  /* Ditto, and characters marked CC_HARD_EXPANSION and
  71                         backslashes are also escaped. */
  72 } escaping_T;
  73 /* ES_QUOTED_HARD is for pathname expansion patterns while ES_QUOTED is for
  74  * other patterns. With ES_QUOTED_HARD, backslashes that are not quotation
  75  * marks are escaped to prevent them from being regarded as escaping
  76  * characters. This does not apply to ES_QUOTED because the pattern is
  77  * supposed to be matched without quote removal. */
  78
  79 /* result of word expansion */
  80 typedef struct cc_word_T {
  81     wchar_t *value;  /* word value */
  82     char *cc;        /* corresponding charcategory_T string */
  83 } cc_word_T;
  84
  85 struct wordunit_T;
  86 struct plist_T;
  87 extern _Bool expand_line(
  88         void *const *restrict args,
  89         int *restrict argcp,
  90         void ***restrict argvp)
  91     __attribute__((nonnull));
  92 extern _Bool expand_multiple(
  93         const struct wordunit_T *restrict w, struct plist_T *restrict list)
  94     __attribute__((nonnull(2)));
  95 extern struct cc_word_T expand_single_cc(
  96         const struct wordunit_T *w, tildetype_T tilde, quoting_T quoting)
  97     __attribute__((warn_unused_result));
  98 extern wchar_t *expand_single(
  99         const struct wordunit_T *w,
 100         tildetype_T tilde, quoting_T quoting, escaping_T escaping)
 101     __attribute__((malloc,warn_unused_result));
 102 extern char *expand_single_with_glob(const struct wordunit_T *arg)
 103     __attribute__((malloc,warn_unused_result));
 104
 105 extern wchar_t *extract_fields(
 106         const wchar_t *restrict s, const char *restrict cc,
 107         const wchar_t *restrict ifs, struct plist_T *restrict dest)
 108     __attribute__((nonnull));
 109
 110 struct xwcsbuf_T;
 111 extern wchar_t *escape(const wchar_t *restrict s, const wchar_t *restrict t)
 112     __attribute__((nonnull(1),malloc,warn_unused_result));
 113 extern wchar_t *escapefree(
 114         wchar_t *restrict s, const wchar_t *restrict t)
 115     __attribute__((nonnull(1),malloc,warn_unused_result));
 116 extern wchar_t *unescape(const wchar_t *s)
 117     __attribute__((nonnull,malloc,warn_unused_result));
 118 extern wchar_t *unescapefree(wchar_t *s)
 119     __attribute__((nonnull,malloc,warn_unused_result));
 120 extern wchar_t *quote_as_word(const wchar_t *s)
 121     __attribute__((nonnull,malloc,warn_unused_result));
 122 extern struct xwcsbuf_T *wb_quote_as_word(
 123         struct xwcsbuf_T *restrict buf, const wchar_t *restrict s)
 124     __attribute__((nonnull));
 125 extern wchar_t *unquote(const wchar_t *s)
 126     __attribute__((nonnull,malloc,warn_unused_result));
 127 extern wchar_t *quote_removal(
 128         const wchar_t *restrict s, const char *restrict cc, escaping_T escaping)
 129     __attribute__((nonnull,malloc,warn_unused_result));
 130
 131 extern wchar_t *parse_and_expand_string(
 132         const wchar_t *s, const char *name, _Bool esc)
 133     __attribute__((nonnull(1),malloc,warn_unused_result));
 134
 135
 136 #endif /* YASH_EXPAND_H */
 137
 138
 139 /* vim: set ts=8 sts=4 sw=4 et tw=80: */