src/explain.c

   1 /*
   2  *  Render C declarations as English.
   3  *  Copyright © 2011 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 #include <stdio.h>
  19 #include <stdlib.h>
  20 #include <stdarg.h>
  21 #include <stdbool.h>
  22 #include <assert.h>
  23
  24 #include "cdecl.h"
  25 #include "typemap.h"
  26
  27 /* declare [ident] as [storage] [function specs] [other crap] [qualifiers] [type specs] */
  28
  29 static size_t
  30 voutput(char *buf, size_t n, size_t off, const char *fmt, va_list ap)
  31 {
  32         if (off >= n)
  33                 return vsnprintf(NULL, 0, fmt, ap);
  34         return vsnprintf(buf+off, n-off, fmt, ap);
  35 }
  36
  37 static size_t output(char *buf, size_t n, size_t off, const char *fmt, ...)
  38 {
  39         va_list ap;
  40         size_t ret;
  41
  42         va_start(ap, fmt);
  43         ret = voutput(buf, n, off, fmt, ap);
  44         va_end(ap);
  45
  46         return ret;
  47 }
  48
  49 static size_t advance_(char **buf, size_t *n, size_t amount)
  50 {
  51         if (amount >= *n) {
  52                 *n   = 0;
  53                 *buf = 0;
  54         } else {
  55                 *buf += amount;
  56                 *n   -= amount;
  57         }
  58
  59         return amount;
  60 }
  61
  62 static size_t advance(char **buf, size_t *n, size_t amount)
  63 {
  64         size_t ret, rc;
  65
  66         if (!amount)
  67                 return 0;
  68
  69         ret = advance_(buf, n, amount);
  70         rc = snprintf(*buf, *n, " ");
  71         return ret + advance_(buf, n, rc);
  72 }
  73
  74 static size_t
  75 explain_qualifiers(char *buf, size_t n, struct cdecl_declspec *s)
  76 {
  77         unsigned long qualmap = 0;
  78         size_t ret = 0, rc = 0;
  79
  80         for (struct cdecl_declspec *c = s; c; c = c->next) {
  81                 if (cdecl_spec_kind(c) != CDECL_SPEC_QUAL)
  82                         continue;
  83                 qualmap |= 1ul << (c->type & 0xff);
  84         }
  85
  86         if (qualmap & (1ul << (CDECL_QUAL_RESTRICT & 0xff))) {
  87                 ret += advance(&buf, &n, rc);
  88                 rc = snprintf(buf, n, "restrict");
  89         }
  90         if (qualmap & (1ul << (CDECL_QUAL_VOLATILE & 0xff))) {
  91                 ret += advance(&buf, &n, rc);
  92                 rc = snprintf(buf, n, "volatile");
  93         }
  94         if (qualmap & (1ul << (CDECL_QUAL_CONST & 0xff))) {
  95                 ret += advance(&buf, &n, rc);
  96                 rc = snprintf(buf, n, "const");
  97         }
  98
  99         return ret + rc;
 100 }
 101
 102 /* Renders the type qualifiers and type specifiers in canonical form. */
 103 static size_t
 104 explain_post_specs(char *buf, size_t n, struct cdecl_declspec *s)
 105 {
 106         const char *tag = NULL;
 107         unsigned long typemap;
 108         size_t ret = 0, rc;
 109
 110         typemap = cdecl__build_typemap(s);
 111         if (typemap == -1)
 112                 return 0;
 113
 114         for (struct cdecl_declspec *c = s; c; c = c->next) {
 115                 if (cdecl_spec_kind(c) != CDECL_SPEC_TYPE)
 116                         continue;
 117
 118                 /* Valid C types have at most one identifier. */
 119                 if (c->ident)
 120                         tag = c->ident;
 121         }
 122
 123         rc = explain_qualifiers(buf, n, s);
 124         ret += advance(&buf, &n, rc);
 125
 126         rc = snprintf(buf, n, "%s", cdecl__explain_typemap(typemap));
 127         if (tag) {
 128                 ret += advance(&buf, &n, rc);
 129                 rc = snprintf(buf, n, "%s", tag);
 130         }
 131
 132         return ret + rc;
 133 }
 134
 135 static const char *explain_storage(unsigned spec)
 136 {
 137         switch (spec) {
 138         case CDECL_STOR_TYPEDEF:
 139                 return "typedef";
 140         case CDECL_STOR_EXTERN:
 141                 return "extern";
 142         case CDECL_STOR_STATIC:
 143                 return "static";
 144         case CDECL_STOR_AUTO:
 145                 return "auto";
 146         case CDECL_STOR_REGISTER:
 147                 return "register";
 148         default:
 149                 assert(0);
 150         }
 151 }
 152
 153 /* Renders the storage-class and function specifiers in canonical form. */
 154 static size_t explain_pre_specs(char *buf, size_t n, struct cdecl_declspec *s)
 155 {
 156         unsigned long funcmap = 0;
 157         const char *storage = NULL;
 158         size_t ret = 0;
 159
 160         for (struct cdecl_declspec *c = s; c; c = c->next) {
 161                 switch (cdecl_spec_kind(c)) {
 162                 case CDECL_SPEC_FUNC:
 163                         funcmap |= 1ul << (c->type & 0xff);
 164                         break;
 165                 case CDECL_SPEC_STOR:
 166                         /* Valid C declarations have at most one
 167                          * storage-class specifier. */
 168                         storage = explain_storage(c->type);
 169                         break;
 170                 }
 171         }
 172
 173         if (storage)
 174                 ret += output(buf, n, ret, "%s", storage);
 175         if (funcmap & (1ul << (CDECL_FUNC_INLINE & 0xff)))
 176                 ret += output(buf, n, ret, "%.*s%s", !!ret, "", "inline");
 177         return ret;
 178 }
 179
 180 /*
 181  * Renders the start of the thing being declared.  If top is true, print
 182  * the "declare" or "type" keywords at the front, as appropriate.
 183  */
 184 static size_t
 185 explain_prologue(char *buf, size_t n, struct cdecl_declarator *d, bool top)
 186 {
 187         size_t ret = 0, rc = 0;
 188
 189         while (d) {
 190                 switch (d->type) {
 191                 case CDECL_DECL_NULL:
 192                         if (top)
 193                                 return snprintf(buf, n, "type");
 194                         return 0;
 195                 case CDECL_DECL_IDENT:
 196                         if (top)
 197                                 rc = snprintf(buf, n, "declare");
 198                         ret += advance(&buf, &n, rc);
 199                         return ret + snprintf(buf, n, "%s as", d->u.ident);
 200                 }
 201
 202                 d = d->child;
 203         }
 204 }
 205
 206 static size_t
 207 explain_pointer(char *buf, size_t n, struct cdecl_pointer *p)
 208 {
 209         size_t ret = 0, rc;
 210
 211         rc = explain_qualifiers(buf, n, p->qualifiers);
 212         ret += advance(&buf, &n, rc);
 213
 214         return ret + snprintf(buf, n, "pointer to");
 215 }
 216
 217 static size_t
 218 explain_array(char *buf, size_t n, struct cdecl_array *a)
 219 {
 220         size_t ret = 0, rc = 0;
 221
 222         if (a->vla)
 223                 rc = snprintf(buf, n, "variable-length array");
 224         else
 225                 rc = snprintf(buf, n, "array");
 226         ret += advance(&buf, &n, rc);
 227
 228         if (a->vla) {
 229                 rc = snprintf(buf, n, "%s", a->vla);
 230                 ret += advance(&buf, &n, rc);
 231         } else if (a->length) {
 232                 rc = snprintf(buf, n, "%ju", a->length);
 233                 ret += advance(&buf, &n, rc);
 234         }
 235
 236         return ret + snprintf(buf, n, "of");
 237 }
 238
 239 static size_t
 240 explain_declarators(char *buf, size_t n, struct cdecl_declarator *decl);
 241
 242 static size_t explain_decl(char *buf, size_t n, struct cdecl *decl, bool top)
 243 {
 244         size_t ret = 0, rc;
 245
 246         rc = explain_prologue(buf, n, decl->declarators, top);
 247         ret += advance(&buf, &n, rc);
 248
 249         rc = explain_pre_specs(buf, n, decl->specifiers);
 250         ret += advance(&buf, &n, rc);
 251
 252         rc = explain_declarators(buf, n, decl->declarators);
 253         ret += advance(&buf, &n, rc);
 254
 255         return ret + explain_post_specs(buf, n, decl->specifiers);
 256 }
 257
 258 static size_t explain_function(char *buf, size_t n, struct cdecl_function *f)
 259 {
 260         size_t ret = 0, rc = 0;
 261
 262         rc = snprintf(buf, n, "function");
 263         ret += advance(&buf, &n, rc);
 264
 265         if (f->parameters) {
 266                 rc = snprintf(buf, n, "(");
 267                 ret += advance_(&buf, &n, rc);
 268
 269                 for (struct cdecl *p = f->parameters; p; p = p->next) {
 270                         rc = explain_decl(buf, n, p, false);
 271                         ret += advance_(&buf, &n, rc);
 272
 273                         if (p->next)
 274                                 rc = snprintf(buf, n, ",");
 275                         else if (f->variadic)
 276                                 rc = snprintf(buf, n, ", ...)");
 277                         else
 278                                 rc = snprintf(buf, n, ")");
 279                         ret += advance(&buf, &n, rc);
 280                 }
 281         }
 282
 283         return ret + snprintf(buf, n, "returning");
 284 }
 285
 286 static size_t
 287 explain_declarators(char *buf, size_t n, struct cdecl_declarator *d)
 288 {
 289         size_t ret = 0, rc;
 290
 291         if (d->type == CDECL_DECL_IDENT || d->type == CDECL_DECL_NULL)
 292                 return 0;
 293
 294         rc = explain_declarators(buf, n, d->child);
 295         ret += advance(&buf, &n, rc);
 296
 297         switch (d->type) {
 298         case CDECL_DECL_POINTER:
 299                 return ret + explain_pointer(buf, n, &d->u.pointer);
 300         case CDECL_DECL_ARRAY:
 301                 return ret + explain_array(buf, n, &d->u.array);
 302         case CDECL_DECL_FUNCTION:
 303                 return ret + explain_function(buf, n, &d->u.function);
 304         default:
 305                 assert(0);
 306         }
 307 }
 308
 309 size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl)
 310 {
 311         return explain_decl(buf, n, decl, true);
 312 }