70322ae3 |
1 | /* |
2 | * html.h: HTML output format for agedu. |
3 | */ |
4 | |
f2e52893 |
5 | struct html_config { |
6 | /* |
c47f39de |
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, |
1d3a7ff6 |
32 | * and the four punctuation characters -.@_ (with the |
33 | * exception that at the very start of a pathname, even '.' |
34 | * is escaped). |
c47f39de |
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. |
f2e52893 |
59 | */ |
c47f39de |
60 | const char *uriformat; |
f2e52893 |
61 | |
62 | /* |
c47f39de |
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. |
00c5e40c |
69 | */ |
c47f39de |
70 | const char *fileformat; |
00c5e40c |
71 | |
72 | /* |
f2e52893 |
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; |
16139d21 |
80 | |
81 | /* |
82 | * Specify whether to show individual files as well as |
83 | * directories in the report. |
84 | */ |
85 | int showfiles; |
494ef23b |
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; |
f2e52893 |
91 | }; |
92 | |
70322ae3 |
93 | /* |
c47f39de |
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 | /* |
70322ae3 |
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. |
00c5e40c |
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.) |
70322ae3 |
120 | */ |
f2e52893 |
121 | char *html_query(const void *t, unsigned long index, |
00c5e40c |
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); |