src/explain.c

   1 /*
   2  *  Render C declarations as English.
   3  *  Copyright © 2011, 2021, 2023 Nick Bowler
   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 3 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 #include <config.h>
  20 #include <stdio.h>
  21 #include <inttypes.h>
  22 #include <assert.h>
  23
  24 #include "cdecl.h"
  25 #include "cdecl-internal.h"
  26
  27 #define PRE_SPECS (CDECL_SPEC_FUNC|CDECL_SPEC_STOR)
  28 #define POST_SPECS (CDECL_SPEC_QUAL|CDECL_SPEC_TYPE)
  29
  30 static size_t explain_specs(struct output_state *dst, struct cdecl_declspec *s, unsigned mask)
  31 {
  32         size_t ret;
  33
  34         ret = cdecl__emit_specs(dst, s, mask);
  35         return ret + cdecl__emit(dst, " " + !ret);
  36 }
  37
  38 static size_t
  39 explain_specs_post(struct output_state *dst, struct cdecl_declspec *s)
  40 {
  41         return cdecl__emit_specs(dst, s, POST_SPECS);
  42 }
  43
  44 /*
  45  * If declarator declares an identifier foo, then emit "foo as "; otherwise
  46  * emit nothing.
  47  */
  48 static size_t
  49 explain_name(struct output_state *dst, struct cdecl_declarator *d)
  50 {
  51         size_t ret;
  52
  53         while (d->child)
  54                 d = d->child;
  55
  56         if (d->type != CDECL_DECL_IDENT)
  57                 return 0;
  58
  59         ret = cdecl__emit(dst, d->u.ident);
  60         return ret + cdecl__emit(dst, " as ");
  61 }
  62
  63 /*
  64  * For a pointer declarator, emit "[QUAL ]pointer to ", where
  65  * QUAL is the (possibly empty) list of qualifiers.
  66  */
  67 static size_t
  68 explain_pointer(struct output_state *dst, struct cdecl_pointer *p)
  69 {
  70         size_t ret;
  71
  72         ret = explain_specs(dst, p->qualifiers, -1);
  73         return ret + cdecl__emit(dst, "pointer to ");
  74 }
  75
  76 /*
  77  * For an array declarator, emit "[variable-length ]array [X ]of ", where
  78  * for a variable-length array X is the (possibly omitted) identifier name,
  79  * and for normal arrays X is the (possibly omitted) length.
  80  */
  81 static size_t
  82 explain_array(struct output_state *dst, struct cdecl_array *a)
  83 {
  84         size_t ret = 0, rc = 0;
  85
  86         if (a->vla)
  87                 ret += cdecl__emit(dst, "variable-length ");
  88         ret += cdecl__emit(dst, "array ");
  89
  90         if (a->vla) {
  91                 rc = cdecl__emit(dst, a->vla);
  92                 ret += rc;
  93         } else {
  94                 rc = snprintf(dst->dst, dst->dstlen, "%.0" PRIuMAX, a->length);
  95                 ret += cdecl__advance(dst, rc);
  96         }
  97
  98         return ret + cdecl__emit(dst, " of " + !rc);
  99 }
 100
 101 static size_t
 102 explain_declarators(struct output_state *dst, struct cdecl_declarator *decl);
 103
 104 static size_t explain_decl(struct output_state *dst, struct cdecl *decl)
 105 {
 106         size_t ret;
 107
 108         ret  = explain_name(dst, decl->declarators);
 109         ret += explain_specs(dst, decl->specifiers, PRE_SPECS);
 110         ret += explain_declarators(dst, decl->declarators);
 111         ret += explain_specs_post(dst, decl->specifiers);
 112
 113         return ret;
 114 }
 115
 116 /*
 117  * For a function declarator, emit "function [PARAM ]returning ", where
 118  * PARAM is the (omitted in the case of an empty non-prototype identifier
 119  * list) parameter or identifier lists enclosed in parentheses.
 120  */
 121 static size_t
 122 explain_function(struct output_state *dst, struct cdecl_function *f)
 123 {
 124         size_t ret = 0;
 125
 126         ret += cdecl__emit(dst, "function ");
 127
 128         if (f->parameters) {
 129                 struct cdecl *p;
 130
 131                 ret += cdecl__emit(dst, "(");
 132
 133                 for (p = f->parameters; p; p = p->next) {
 134                         ret += explain_decl(dst, p);
 135                         if (p->next)
 136                                 ret += cdecl__emit(dst, ", ");
 137                 }
 138
 139                 if (f->variadic)
 140                         ret += cdecl__emit(dst, ", ...) ");
 141                 else
 142                         ret += cdecl__emit(dst, ") ");
 143         }
 144
 145         return ret + cdecl__emit(dst, "returning ");
 146 }
 147
 148 static size_t
 149 explain_declarators(struct output_state *dst, struct cdecl_declarator *d)
 150 {
 151         size_t ret;
 152
 153         if (d->type == CDECL_DECL_IDENT || d->type == CDECL_DECL_NULL)
 154                 return 0;
 155
 156         ret = explain_declarators(dst, d->child);
 157
 158         switch (d->type) {
 159         case CDECL_DECL_POINTER:
 160                 return ret + explain_pointer(dst, &d->u.pointer);
 161         case CDECL_DECL_ARRAY:
 162                 return ret + explain_array(dst, &d->u.array);
 163         case CDECL_DECL_FUNCTION:
 164                 return ret + explain_function(dst, &d->u.function);
 165         default:
 166                 assert(0);
 167         }
 168 }
 169
 170 size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl)
 171 {
 172         struct output_state dst = { buf, n };
 173         size_t ret;
 174
 175         if (cdecl_is_abstract(decl->declarators))
 176                 ret = cdecl__emit(&dst, "type ");
 177         else
 178                 ret = cdecl__emit(&dst, "declare ");
 179
 180         return ret + explain_decl(&dst, decl);
 181 }