| 1 | /* |
| 2 | * html.h: HTML output format for agedu. |
| 3 | */ |
| 4 | |
| 5 | struct html_config { |
| 6 | /* |
| 7 | * Configure the format of the URI pathname fragment corresponding |
| 8 | * to a given tree entry. |
| 9 | * |
| 10 | * 'uriformat' is expected to have the following format: |
| 11 | * - it consists of one or more _options_, each indicating a |
| 12 | * particular way to format a URI, separated by '%|' |
| 13 | * - each option contains _at most one_ formatting directive; |
| 14 | * without any, it is assumed to only be able to encode the |
| 15 | * root tree entry |
| 16 | * - the formatting directive may be followed before and/or |
| 17 | * afterwards with literal text; percent signs in that literal |
| 18 | * text are specified as %% (which doesn't count as a |
| 19 | * formatting directive for the 'at most one' rule) |
| 20 | * - formatting directives are as follows: |
| 21 | * + '%n' outputs the numeric index (in decimal) of the tree |
| 22 | * entry |
| 23 | * + '%p' outputs the pathname of the tree entry, not counting |
| 24 | * any common prefix of the whole tree or a subdirectory |
| 25 | * separator following that (so that the root directory of |
| 26 | * the tree will always be rendered as the empty string). |
| 27 | * The subdirectory separator is translated into '/'; any |
| 28 | * remotely worrying character is escaped as = followed by |
| 29 | * two hex digits (including, in particular, = itself). The |
| 30 | * only characters not escaped are the ASCII alphabets and |
| 31 | * numbers, the subdirectory separator as mentioned above, |
| 32 | * and the four punctuation characters -.@_ (with the |
| 33 | * exception that at the very start of a pathname, even '.' |
| 34 | * is escaped). |
| 35 | * - '%/p' outputs the pathname of the tree entry, but this time |
| 36 | * the subdirectory separator is also considered to be a |
| 37 | * worrying character and is escaped. |
| 38 | * - '%-p' and '%-/p' are like '%p' and '%/p' respectively, |
| 39 | * except that they use the full pathname stored in the tree |
| 40 | * without stripping a common prefix. |
| 41 | * |
| 42 | * These formats are used both for generating and parsing URI |
| 43 | * fragments. When generating, the first valid option is used |
| 44 | * (which is always the very first one if we're generating the |
| 45 | * root URI, or else it's the first option with any formatting |
| 46 | * directive); when parsing, the first option that matches will be |
| 47 | * accepted. (Thus, you can have '.../subdir' and '.../subdir/' |
| 48 | * both accepted, but make the latter canonical; clients of this |
| 49 | * mechanism will typically regenerate a URI string after parsing |
| 50 | * an index out of it, and return an HTTP redirect if it isn't in |
| 51 | * canonical form.) |
| 52 | * |
| 53 | * All hyperlinks should be correctly generated as relative (i.e. |
| 54 | * with the right number of ../ and ./ considering both the |
| 55 | * pathname for the page currently being generated, and the one |
| 56 | * for the link target). |
| 57 | * |
| 58 | * If 'uriformat' is NULL, the HTML is generated without hyperlinks. |
| 59 | */ |
| 60 | const char *uriformat; |
| 61 | |
| 62 | /* |
| 63 | * Configure the filenames output by html_dump(). These can be |
| 64 | * configured separately from the URI formats, so that the root |
| 65 | * file can be called index.html on disk but have a notional URI |
| 66 | * of just / or similar. |
| 67 | * |
| 68 | * Formatting directives are the same as the uriformat above. |
| 69 | */ |
| 70 | const char *fileformat; |
| 71 | |
| 72 | /* |
| 73 | * Time stamps to assign to the extreme ends of the colour |
| 74 | * scale. If "autoage" is true, they are ignored and the time |
| 75 | * stamps are derived from the limits of the age data stored |
| 76 | * in the index. |
| 77 | */ |
| 78 | int autoage; |
| 79 | time_t oldest, newest; |
| 80 | |
| 81 | /* |
| 82 | * Specify whether to show individual files as well as |
| 83 | * directories in the report. |
| 84 | */ |
| 85 | int showfiles; |
| 86 | /* |
| 87 | * The string appearing in the <title> part of HTML pages, before |
| 88 | * a colon followed by the path being served. Default is "agedu". |
| 89 | */ |
| 90 | const char *html_title; |
| 91 | }; |
| 92 | |
| 93 | /* |
| 94 | * Parse a URI pathname segment against the URI formats specified in |
| 95 | * 'cfg', and return a numeric index in '*index'. Return value is true |
| 96 | * on success, or false if the pathname makes no sense, or the index |
| 97 | * is out of range, or the index does not correspond to a directory in |
| 98 | * the trie. |
| 99 | */ |
| 100 | int html_parse_path(const void *t, const char *path, |
| 101 | const struct html_config *cfg, unsigned long *index); |
| 102 | |
| 103 | /* |
| 104 | * Generate a URI pathname segment from an index. |
| 105 | */ |
| 106 | char *html_format_path(const void *t, const struct html_config *cfg, |
| 107 | unsigned long index); |
| 108 | |
| 109 | /* |
| 110 | * Generate an HTML document containing the results of a query |
| 111 | * against the pathname at a given index. Returns a dynamically |
| 112 | * allocated piece of memory containing the entire HTML document, |
| 113 | * as an ordinary C zero-terminated string. |
| 114 | * |
| 115 | * 'downlink' is TRUE if hyperlinks should be generated for |
| 116 | * subdirectories. (This can also be disabled by setting cfg->format |
| 117 | * to NULL, but that also disables the upward hyperlinks to parent |
| 118 | * directories. Setting cfg->format to non-NULL but downlink to NULL |
| 119 | * will generate uplinks but no downlinks.) |
| 120 | */ |
| 121 | char *html_query(const void *t, unsigned long index, |
| 122 | const struct html_config *cfg, int downlink); |
| 123 | |
| 124 | /* |
| 125 | * Recursively output a dump of lots of HTML files which crosslink |
| 126 | * to each other. cfg->format and cfg->rootpath will be used to |
| 127 | * generate the filenames for both the hyperlinks and the output |
| 128 | * file names; the file names will have "pathprefix" prepended to |
| 129 | * them before being opened. |
| 130 | * |
| 131 | * "index" and "endindex" point to the region of index file that |
| 132 | * should be generated by the dump, which must be a subdirectory. |
| 133 | * |
| 134 | * "maxdepth" limits the depth of recursion. Setting it to zero |
| 135 | * outputs only one page, 1 outputs the current directory and its |
| 136 | * immediate children but no further, and so on. Making it negative |
| 137 | * gives unlimited depth. |
| 138 | * |
| 139 | * Return value is 0 on success, or 1 if an error occurs during |
| 140 | * output. |
| 141 | */ |
| 142 | int html_dump(const void *t, unsigned long index, unsigned long endindex, |
| 143 | int maxdepth, const struct html_config *cfg, |
| 144 | const char *pathprefix); |