git.ozlabs.org Git - ccan/blob - tools/ccanlint/tests/has_examples.c

   1 #include <tools/ccanlint/ccanlint.h>
   2 #include <tools/tools.h>
   3 #include <ccan/talloc/talloc.h>
   4 #include <ccan/str/str.h>
   5 #include <sys/types.h>
   6 #include <sys/stat.h>
   7 #include <fcntl.h>
   8 #include <unistd.h>
   9 #include <limits.h>
  10 #include <errno.h>
  11 #include <stdlib.h>
  12 #include <stdio.h>
  13 #include <err.h>
  14 #include <string.h>
  15 #include <ctype.h>
  16
  17 /* Creates and adds an example file. */
  18 static char *add_example(struct manifest *m, struct ccan_file *source,
  19                          bool keep,
  20                          struct doc_section *example)
  21 {
  22         char *name;
  23         unsigned int i;
  24         int fd;
  25         struct ccan_file *f;
  26
  27         name = maybe_temp_file(m, ".c", keep,
  28                                talloc_asprintf(m, "%s/example-%s-%s.c",
  29                                                talloc_dirname(m,
  30                                                               source->fullname),
  31                                                source->name,
  32                                                example->function));
  33         f = new_ccan_file(m, talloc_dirname(m, name), talloc_basename(m, name));
  34         talloc_steal(f, name);
  35         list_add_tail(&m->examples, &f->list);
  36
  37         fd = open(f->fullname, O_WRONLY | O_CREAT | O_EXCL, 0600);
  38         if (fd < 0)
  39                 return talloc_asprintf(m, "Creating temporary file %s: %s",
  40                                        f->fullname, strerror(errno));
  41
  42         for (i = 0; i < example->num_lines; i++) {
  43                 if (write(fd, example->lines[i], strlen(example->lines[i]))
  44                     != strlen(example->lines[i])
  45                     || write(fd, "\n", 1) != 1) {
  46                         close(fd);
  47                         return "Failure writing to temporary file";
  48                 }
  49         }
  50         close(fd);
  51         return NULL;
  52 }
  53
  54 /* FIXME: We should have one example per function in header. */
  55 struct score {
  56         bool info_example, header_example;
  57         char *error;
  58 };
  59
  60 static void *extract_examples(struct manifest *m,
  61                               bool keep,
  62                               unsigned int *timeleft)
  63 {
  64         struct ccan_file *f;
  65         struct doc_section *d;
  66         struct score *score = talloc(m, struct score);
  67
  68         score->info_example = score->header_example = false;
  69         score->error = NULL;
  70
  71         list_for_each(get_ccan_file_docs(m->info_file), d, list) {
  72                 if (streq(d->type, "example")) {
  73                         score->error = add_example(m, m->info_file, keep, d);
  74                         if (score->error)
  75                                 return score;
  76                         score->info_example = true;
  77                 }
  78         }
  79
  80         /* Check main header. */
  81         list_for_each(&m->h_files, f, list) {
  82                 if (!strstarts(f->name, m->basename)
  83                     || strlen(f->name) != strlen(m->basename) + 2)
  84                         continue;
  85
  86                 list_for_each(get_ccan_file_docs(f), d, list) {
  87                         if (streq(d->type, "example")) {
  88                                 score->error = add_example(m, f, keep, d);
  89                                 if (score->error)
  90                                         return score;
  91                                 score->header_example = true;
  92                         }
  93                 }
  94         }
  95         return score;
  96 }
  97
  98 static unsigned int score_examples(struct manifest *m, void *check_result)
  99 {
 100         struct score *score = check_result;
 101         int total = 0;
 102
 103         if (score->error)
 104                 return 0;
 105         total += score->info_example;
 106         total += score->header_example;
 107         return total;
 108 }
 109
 110 static const char *describe_examples(struct manifest *m,
 111                                      void *check_result)
 112 {
 113         struct score *score = check_result;
 114         char *descrip = NULL;
 115
 116         if (score->error)
 117                 return score->error;
 118
 119         if (!score->info_example)
 120                 descrip = talloc_asprintf(score,
 121                 "Your _info file has no module example.\n\n"
 122                 "There should be an Example: section of the _info documentation\n"
 123                 "which provides a concise toy program which uses your module\n");
 124
 125         if (!score->header_example)
 126                 descrip = talloc_asprintf(score,
 127                  "%sMain header file file has no examples\n\n"
 128                  "There should be an Example: section for each public function\n"
 129                   "demonstrating its use\n", descrip ? descrip : "");
 130
 131         return descrip;
 132 }
 133
 134 struct ccanlint has_examples = {
 135         .key = "has-examples",
 136         .name = "_info and header files have examples",
 137         .score = score_examples,
 138         .check = extract_examples,
 139         .describe = describe_examples,
 140         .total_score = 2,
 141 };
 142
 143 REGISTER_TEST(has_examples, &has_info, NULL);