Add --function= arg to doc_extract so we can use it on normal ccan C
[ccan] / tools / doc_extract.c
1 /* This merely extracts, doesn't do XML or anything. */
2 #include <err.h>
3 #include <stdio.h>
4 #include <stdlib.h>
5 #include <unistd.h>
6 #include <string.h>
7 #include <sys/types.h>
8 #include <sys/stat.h>
9 #include <fcntl.h>
10 #include <stdbool.h>
11 #include <ccan/talloc/talloc.h>
12 #include <ccan/str/str.h>
13 #include <ccan/str_talloc/str_talloc.h>
14 #include <ccan/grab_file/grab_file.h>
15 #include "tools.h"
16
17 static char **grab_doc(const char *fname)
18 {
19         char *file;
20         char **lines, **ret;
21         unsigned int i, num;
22         bool printing = false;
23
24         file = grab_file(NULL, fname, NULL);
25         if (!file)
26                 err(1, "Reading file %s", fname);
27         lines = strsplit(file, file, "\n", &num);
28         ret = talloc_array(NULL, char *, num+1);
29
30         num = 0;
31         for (i = 0; lines[i]; i++) {
32                 if (streq(lines[i], "/**")) {
33                         printing = true;
34                         if (num != 0)
35                                 talloc_append_string(ret[num-1], "\n");
36                 } else if (streq(lines[i], " */")) 
37                         printing = false;
38                 else if (printing) {
39                         if (strstarts(lines[i], " * "))
40                                 ret[num++] = talloc_strdup(ret, lines[i]+3);
41                         else if (strstarts(lines[i], " *"))
42                                 ret[num++] = talloc_strdup(ret, lines[i]+2);
43                         else
44                                 errx(1, "Malformed line %s:%u", fname, i);
45                 }
46         }
47         ret[num] = NULL;
48         talloc_free(file);
49         return ret;
50 }
51
52 static bool is_blank(const char *line)
53 {
54         return line && line[strspn(line, " \t\n")] == '\0';
55 }
56
57 static bool is_section(const char *line, bool maybe_one_liner)
58 {
59         unsigned int len;
60
61         len = strcspn(line, " \t\n:");
62         if (len == 0)
63                 return false;
64
65         if (line[len] != ':')
66                 return false;
67
68         /* If it can be a one-liner, a space is sufficient.*/
69         if (maybe_one_liner && (line[len+1] == ' ' || line[len+1] == '\t'))
70                 return true;
71
72         return line[len] == ':' && is_blank(line+len+1);
73 }
74
75 /* Summary line is form '<identifier> - ' */
76 static bool is_summary_line(const char *line)
77 {
78         unsigned int id_len;
79
80         id_len = strspn(line, IDENT_CHARS);
81         if (id_len == 0)
82                 return false;
83         if (!strstarts(line + id_len, " - "))
84                 return false;
85
86         return true;
87 }
88
89 static bool end_section(const char *line)
90 {
91         return !line || is_section(line, true) || is_summary_line(line);
92 }
93
94 static unsigned int find_section(char **lines, const char *name,
95                                  bool maybe_one_liner)
96 {
97         unsigned int i;
98
99         for (i = 0; lines[i]; i++) {
100                 if (!is_section(lines[i], maybe_one_liner))
101                         continue;
102                 if (strncasecmp(lines[i], name, strlen(name)) != 0)
103                         continue;
104                 if (lines[i][strlen(name)] == ':')
105                         break;
106         }
107         return i;
108 }
109
110 /* function is NULL if we don't care. */
111 static unsigned int find_summary(char **lines, const char *function)
112 {
113         unsigned int i;
114
115         for (i = 0; lines[i]; i++) {
116                 if (!is_summary_line(lines[i]))
117                         continue;
118                 if (function) {
119                         if (!strstarts(lines[i], function))
120                                 continue;
121                         if (!strstarts(lines[i] + strlen(function), " - "))
122                                 continue;
123                 }
124                 break;
125         }
126         return i;
127 }
128
129
130 int main(int argc, char *argv[])
131 {
132         unsigned int i;
133         const char *type;
134         const char *function = NULL;
135
136         if (argc < 3)
137                 errx(1, "Usage: doc_extract [--function=<funcname>] TYPE <file>...\n"
138                      "Where TYPE is functions|author|licence|maintainer|summary|description|example|all");
139
140         if (strstarts(argv[1], "--function=")) {
141                 function = argv[1] + strlen("--function=");
142                 argv++;
143                 argc--;
144         }
145
146         type = argv[1];
147         for (i = 2; i < argc; i++) {
148                 unsigned int line;
149                 char **lines = grab_doc(argv[i]);
150
151                 if (!lines[0])
152                         errx(1, "No documentation in file %s", argv[i]);
153
154                 if (function) {
155                         /* Allow us to trawl multiple files for a function */
156                         line = find_summary(lines, function);
157                         if (!lines[line])
158                                 continue;
159
160                         /* Trim to just this function then. */
161                         lines += line;
162                         lines[find_summary(lines+1, NULL)] = NULL;
163                 }
164                 /* Simple one-line fields. */
165                 if (streq(type, "author")
166                     || streq(type, "maintainer")
167                     || streq(type, "licence")) {
168                         line = find_section(lines, type, true);
169                         if (lines[line]) {
170                                 const char *p = strchr(lines[line], ':') + 1;
171                                 p += strspn(p, " \t\n");
172                                 if (p[0] == '\0') {
173                                         /* Must be on next line. */
174                                         if (end_section(lines[line+1]))
175                                                 errx(1, "Malformed %s", type);
176                                         puts(lines[line+1]);
177                                 } else
178                                         puts(p);
179                         }
180                 } else if (streq(type, "summary")) {
181                         /* Summary comes after - on first line. */
182                         char *dash;
183
184                         dash = strchr(lines[0], '-');
185                         if (!dash)
186                                 errx(1, "Malformed first line: no -");
187                         dash += strspn(dash, "- ");
188                         puts(dash);
189                 } else if (streq(type, "description")) {
190                         line = 1;
191                         while (is_blank(lines[line]))
192                                 line++;
193
194                         while (!end_section(lines[line]))
195                                 puts(lines[line++]);
196                 } else if (streq(type, "example")) {
197                         line = find_section(lines, type, false);
198                         if (lines[line]) {
199                                 unsigned int strip;
200                                 line++;
201
202                                 while (is_blank(lines[line]))
203                                         line++;
204
205                                 /* Examples can be indented.  Take cue
206                                  * from first non-blank line. */
207                                 if (lines[line])
208                                         strip = strspn(lines[line], " \t");
209
210                                 while (!end_section(lines[line])) {
211                                         if (strspn(lines[line], " \t") >= strip)
212                                                 puts(lines[line] + strip);
213                                         else
214                                                 puts(lines[line]);
215                                         line++;
216                                 }
217                         }
218                 } else if (streq(type, "functions")) {
219                         while (lines[line = find_summary(lines, NULL)]) {
220                                 const char *dash = strstr(lines[line], " - ");
221                                 printf("%.*s\n",
222                                        dash - lines[line], lines[line]);
223                                 lines += line+1;
224                         }
225                 } else if (streq(type, "all")) {
226                         for (line = 0; lines[line]; line++)
227                                 puts(lines[line]);
228                 } else
229                         errx(1, "Unknown type '%s'", type);
230         }
231         return 0;
232 }