src/explain.c

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