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