git.ozlabs.org Git - ccan/blob - 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 }