autodata: add example, clean up description a little.

Also add #include to AUTODATA_TYPE example, so ccanlint doesn't try to
put it inside a function (which works, for this, but gives a warning
about unused variables).

diff --git a/ccan/autodata/_info b/ccan/autodata/_info
index b804bcdd329c2eba9a49a7b6a95837124b6e9f62..11b6e16dcc183c0d093c6bed66ff71adc7b01f23 100644 (file)
--- a/ccan/autodata/_info
+++ b/ccan/autodata/_info
@@ -6,10 +6,90 @@
  *
  * This code allows declarations in your source which you can gather
  * together at runtime to form tables.  This is often used in place of
- * having to patch a registration function call out, or a central
- * table.
+ * having a central registration function or table.
  *
  * License: BSD-MIT
+ *
+ * Example:
+ * // Distributed commandline option registration (note: ccan/opt is better!)
+ * #include <ccan/autodata/autodata.h>
+ * #include <stdio.h>
+ * #include <unistd.h>
+ * #include <stdbool.h>
+ * #include <err.h>
+ *
+ * static bool verbose = false;
+ *
+ * // This would normally be in a header, so any C file can use it.
+ * struct option {
+ *     char c;
+ *     bool takes_arg;
+ *     bool (*cb)(char *optarg);
+ * };
+ * AUTODATA_TYPE(options, struct option);
+ * #define REGISTER_OPTION(optstruct) \
+ *             AUTODATA(options, (optstruct))
+ *
+ * // Now a few examples (could be anywhere in source)
+ * static bool verbose_cb(char *unused)
+ * {
+ *     verbose = true;
+ *      return true;
+ * }
+ * static struct option dash_v = { 'v', false, verbose_cb };
+ * REGISTER_OPTION(&dash_v);
+ *
+ * static bool chdir_cb(char *dir)
+ * {
+ *     if (verbose)
+ *             printf("chdir to %s. ", dir);
+ *     if (chdir(dir) != 0)
+ *             return false;
+ *      return true;
+ * }
+ * static struct option dash_C = { 'C', true, chdir_cb };
+ * REGISTER_OPTION(&dash_C);
+ *
+ * int main(int argc, char *argv[])
+ * {
+ *     struct option **opts;
+ *     size_t i, num;
+ *     int o;
+ *     char *optstring, *p;
+ *
+ *     // Gather together all the registered options.
+ *     opts = autodata_get(options, &num);
+ *
+ *     // Make pretty string for getopt().
+ *     p = optstring = malloc(num * 2 + 1);
+ *     for (i = 0; i < num; i++) {
+ *             *(p++) = opts[i]->c;
+ *             if (opts[i]->takes_arg)
+ *                     *(p++) = ':';
+ *     }
+ *     *p = '\0';
+ *
+ *     while ((o = getopt(argc, argv, optstring)) != -1) {
+ *             if (o == '?')
+ *                     exit(1);
+ *             // Call callback in matching option.
+ *             for (i = 0; i < num; i++) {
+ *                     if (opts[i]->c == o) {
+ *                             if (!opts[i]->cb(optarg))
+ *                                     err(1, "parsing -%c", o);
+ *                             break;
+ *                     }
+ *             }
+ *     }
+ *     // free up gathered option table.
+ *     autodata_free(opts);
+ *
+ *     if (verbose)
+ *             printf("verbose mode on\n");
+ *     return 0;
+ * }
+ * // Given -v outputs 'verbose mode on'
+ * // Given -v -C / outputs 'chdir to /. verbose mode on'
  */
 int main(int argc, char *argv[])
 {

diff --git a/ccan/autodata/autodata.h b/ccan/autodata/autodata.h
index d16c6a5c465311a05d3810378892a768549ca357..c9d774b982ee74256eb898917ed365ba1c7ac62d 100644 (file)
--- a/ccan/autodata/autodata.h
+++ b/ccan/autodata/autodata.h
@@ -16,6 +16,8 @@
  * autodata functions in the file.
  *
  * Example:
+ *     #include <ccan/autodata/autodata.h>
+ *
  *     // My set of char pointers.
  *     AUTODATA_TYPE(names, char);
  */