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