HTML Tidy 5.8.0
The HTACG Tidy HTML Project
 
Loading...
Searching...
No Matches
config.h
Go to the documentation of this file.
1#ifndef __CONFIG_H__
2#define __CONFIG_H__
3
4/**************************************************************************//**
5 * @file
6 * Read configuration files and manage configuration properties.
7 *
8 * Config files associate a property name with a value.
9 *
10 * // comments can start at the beginning of a line
11 * # comments can start at the beginning of a line
12 * name: short values fit onto one line
13 * name: a really long value that
14 * continues on the next line
15 *
16 * Property names are case insensitive and should be less than 60 characters
17 * in length, and must start at the begining of the line, as whitespace at
18 * the start of a line signifies a line continuation.
19 *
20 * @author HTACG, et al (consult git log)
21 *
22 * @copyright
23 * Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts
24 * Institute of Technology, European Research Consortium for Informatics
25 * and Mathematics, Keio University) and HTACG.
26 * @par
27 * All Rights Reserved.
28 * @par
29 * See `tidy.h` for the complete license.
30 *
31 * @date Additional updates: consult git log
32 *
33 ******************************************************************************/
34
35#include "forward.h"
36#include "tidy.h"
37#include "streamio.h"
38
39/** @addtogroup internal_api */
40/** @{ */
41
42
43/***************************************************************************//**
44 ** @defgroup configuration_options Configuration Options
45 **
46 ** This module organizes all of Tidy's configuration options, including
47 ** picklist management, option setting and retrieval, option file utilities,
48 ** and so on.
49 **
50 ** @{
51 ******************************************************************************/
52
53
54/** Determines the maximum number of items in an option's picklist. PickLists
55 ** may have up to 16 items. For some reason, this limit has been hard-coded
56 ** into Tidy for some time. Feel free to increase this as needed.
57 */
58#define TIDY_PL_SIZE 16
59
60
61/** Structs of this type contain information needed in order to present
62 ** picklists, relate picklist entries to public enum values, and parse
63 ** strings that are accepted in order to assign the value.
64 */
65typedef struct PickListItem {
66 ctmbstr label; /**< PickList label for this item. */
67 const int value; /**< The option value represented by this label. */
68 ctmbstr inputs[10]; /**< String values that can select this value. */
70
71
72/** An array of PickListItems, fixed in size for in-code declarations.
73 ** Arrays must be populated in 0 to 10 order, as the option value is assigned
74 ** based on this index and *not* on the structures' value field. It remains
75 ** a best practice, however, to assign a public enum value with the proper
76 ** index value.
77 */
79
80
81struct _tidy_option; /* forward */
82
83/** The TidyOptionImpl type implements the `_tidy_option` structure.
84 */
85typedef struct _tidy_option TidyOptionImpl;
86
87
88/** This typedef describes a function that is used for parsing the input
89 ** given for a particular Tidy option.
90 */
91typedef Bool (ParseProperty)( TidyDocImpl* doc, const TidyOptionImpl* opt );
92
93
94/** This structure defines the internal representation of a Tidy option.
95 */
97{
98 TidyOptionId id; /**< The unique identifier for this option. */
99 TidyConfigCategory category; /**< The category of the option. */
100 ctmbstr name; /**< The name of the option. */
101 TidyOptionType type; /**< The date type for the option. */
102 ulong dflt; /**< Default value for TidyInteger and TidyBoolean */
103 ParseProperty* parser; /**< Function to parse input; read-only if NULL. */
104 PickListItems* pickList; /**< The picklist of possible values for this option. */
105 ctmbstr pdflt; /**< Default value for TidyString. */
106};
107
108
109/** Stored option values can be one of two internal types.
110 */
111typedef union
112{
113 ulong v; /**< Value for TidyInteger and TidyBoolean */
114 char *p; /**< Value for TidyString */
116
117
118/** This type is used to define a structure for keeping track of the values
119 ** for each option.
120 */
121typedef struct _tidy_config
122{
123 TidyOptionValue value[ N_TIDY_OPTIONS + 1 ]; /**< Current config values. */
124 TidyOptionValue snapshot[ N_TIDY_OPTIONS + 1 ]; /**< Snapshot of values to be restored later. */
125 uint defined_tags; /**< Tracks user-defined tags. */
126 uint c; /**< Current char in input stream for reading options. */
127 StreamIn* cfgIn; /**< Current input source for reading options.*/
129
130
131/** Used to build a table of documentation cross-references.
132 */
133typedef struct {
134 TidyOptionId opt; /**< Identifier. */
135 TidyOptionId const *links; /**< Cross references. Last element must be 'TidyUnknownOption'. */
137
138
139/** Given an option name, return an instance of an option.
140 ** @param optnam The option name to retrieve.
141 ** @returns The instance of the requested option.
142 */
143TY_PRIVATE const TidyOptionImpl* TY_(lookupOption)( ctmbstr optnam );
144
145
146/** Given an option ID, return an instance of an option.
147 ** @param optId The option ID to retrieve.
148 ** @returns The instance of the requested option.
149 */
150TY_PRIVATE const TidyOptionImpl* TY_(getOption)( TidyOptionId optId );
151
152/** Given an option ID, indicates whether or not the option is a list.
153 ** @param optId The option ID to check.
154 ** @returns Returns yes if the option value is a list.
155 */
156TY_PRIVATE const Bool TY_(getOptionIsList)( TidyOptionId optId );
157
158/** Initiates an iterator to cycle through all of the available options.
159 ** @param doc The Tidy document to get options.
160 ** @returns An iterator token to be used with TY_(getNextOption)().
161 */
162TY_PRIVATE TidyIterator TY_(getOptionList)( TidyDocImpl* doc );
163
164
165/** Gets the next option provided by the iterator.
166 ** @param doc The Tidy document to get options.
167 ** @param iter The iterator token initialized by TY_(getOptionList)().
168 ** @returns The instance of the next option.
169 */
170TY_PRIVATE const TidyOptionImpl* TY_(getNextOption)( TidyDocImpl* doc, TidyIterator* iter );
171
172
173/** Initiates an iterator to cycle through all of the available picklist
174 ** possibilities.
175 ** @param option An instance of an option for which to iterate a picklist.
176 ** @returns An interator token to be used with TY_(getNextOptionPick)().
177 */
178TY_PRIVATE TidyIterator TY_(getOptionPickList)( const TidyOptionImpl* option );
179
180
181/** Gets the next picklist possibility provided by the iterator.
182 ** @param option The instance of the option for which to iterate a picklist.
183 ** @param iter The iterator token initialized by TY_(getOptionPickList)().
184 ** @returns The next picklist entry.
185 */
186TY_PRIVATE ctmbstr TY_(getNextOptionPick)( const TidyOptionImpl* option, TidyIterator* iter );
187
188
189#if SUPPORT_CONSOLE_APP
190/** Returns the cross-reference information structure for optID, which is
191 ** used for generating documentation.
192 ** @param optId The option ID to get cross-reference information for.
193 ** @returns Cross reference information.
194 */
195TY_PRIVATE const TidyOptionDoc* TY_(OptGetDocDesc)( TidyOptionId optId );
196#endif /* SUPPORT_CONSOLE_APP */
197
198
199/** Initialize the configuration for the given Tidy document.
200 ** @param doc The Tidy document.
201 */
202TY_PRIVATE void TY_(InitConfig)( TidyDocImpl* doc );
203
204
205/** Frees the configuration memory for the given Tidy document.
206 ** @param doc The Tidy document.
207 */
208TY_PRIVATE void TY_(FreeConfig)( TidyDocImpl* doc );
209
210
211/** Gets the picklist label for a given value.
212 ** @param optId the option id having a picklist to check.
213 ** @param pick the picklist item to retrieve.
214 ** @returns The label for the pick.
215 */
216TY_PRIVATE ctmbstr TY_(GetPickListLabelForPick)( TidyOptionId optId, uint pick );
217
218
219/** Sets the integer value for the given option Id.
220 ** @param doc The Tidy document.
221 ** @param optId The option ID to set.
222 ** @param val The value to set.
223 ** @returns Success or failure.
224 */
225TY_PRIVATE Bool TY_(SetOptionInt)( TidyDocImpl* doc, TidyOptionId optId, ulong val );
226
227
228/** Sets the bool value for the given option Id.
229 ** @param doc The Tidy document.
230 ** @param optId The option ID to set.
231 ** @param val The value to set.
232 ** @returns Success or failure.
233 */
234TY_PRIVATE Bool TY_(SetOptionBool)( TidyDocImpl* doc, TidyOptionId optId, Bool val );
235
236
237/** Resets the given option to its default value.
238 ** @param doc The Tidy document.
239 ** @param optId The option ID to set.
240 ** @returns Success or failure.
241 */
242TY_PRIVATE Bool TY_(ResetOptionToDefault)( TidyDocImpl* doc, TidyOptionId optId );
243
244
245/** Resets all options in the document to their default values.
246 ** @param doc The Tidy document.
247 */
248TY_PRIVATE void TY_(ResetConfigToDefault)( TidyDocImpl* doc );
249
250
251/** Stores a snapshot of all of the configuration values that can be
252 ** restored later.
253 ** @param doc The Tidy document.
254 */
255TY_PRIVATE void TY_(TakeConfigSnapshot)( TidyDocImpl* doc );
256
257
258/** Restores all of the configuration values to their snapshotted values.
259 ** @param doc The Tidy document.
260 */
261TY_PRIVATE void TY_(ResetConfigToSnapshot)( TidyDocImpl* doc );
262
263
264/** Copies the configuration from one document to another.
265 ** @param docTo The destination Tidy document.
266 ** @param docFrom The source Tidy document.
267 */
268TY_PRIVATE void TY_(CopyConfig)( TidyDocImpl* docTo, TidyDocImpl* docFrom );
269
270
271/** Attempts to parse the given config file into the document.
272 ** @param doc The Tidy document.
273 ** @param cfgfil The file to load.
274 ** @returns a file system error code.
275 */
276TY_PRIVATE int TY_(ParseConfigFile)( TidyDocImpl* doc, ctmbstr cfgfil );
277
278
279/** Attempts to parse the given config file into the document, using
280 ** the provided encoding.
281 ** @param doc The Tidy document.
282 ** @param cfgfil The file to load.
283 ** @param charenc The name of the encoding to use for reading the file.
284 ** @returns a file system error code.
285 */
286TY_PRIVATE int TY_(ParseConfigFileEnc)( TidyDocImpl* doc,
287 ctmbstr cfgfil, ctmbstr charenc );
288
289
290/** Saves the current configuration for options not having default values
291 ** into the specified file.
292 ** @param doc The Tidy document.
293 ** @param cfgfil The file to save.
294 ** @returns a file system error code.
295 */
296TY_PRIVATE int TY_(SaveConfigFile)( TidyDocImpl* doc, ctmbstr cfgfil );
297
298
299/** Writes the current configuration for options not having default values
300 ** into the specified sink.
301 ** @param doc The Tidy document.
302 ** @param sink The sink to save into.
303 ** @returns a file system error code.
304 */
305TY_PRIVATE int TY_(SaveConfigSink)( TidyDocImpl* doc, TidyOutputSink* sink );
306
307
308/** Attempts to parse the provided value for the given option name. Returns
309 ** false if unknown option, missing parameter, or the option doesn't
310 ** use the parameter.
311 ** @param doc The Tidy document.
312 ** @param optnam The name of the option to be set.
313 ** @param optVal The string value to attempt to parse.
314 ** @returns Success or failure.
315 */
316TY_PRIVATE Bool TY_(ParseConfigOption)( TidyDocImpl* doc, ctmbstr optnam, ctmbstr optVal );
317
318
319/** Attempts to parse the provided value for the given option id. Returns
320 ** false if unknown option, missing parameter, or the option doesn't
321 ** use the parameter.
322 ** @param doc The Tidy document.
323 ** @param optId The ID of the option to be set.
324 ** @param optVal The string value to attempt to parse.
325 ** @returns Success or failure.
326 */
327TY_PRIVATE Bool TY_(ParseConfigValue)( TidyDocImpl* doc, TidyOptionId optId, ctmbstr optVal );
328
329
330/** Ensure that char encodings are self consistent.
331 ** @param doc The Tidy document to adjust.
332 ** @param encoding The encoding being applied.
333 ** @returns A bool indicating success or failure.
334 */
335TY_PRIVATE Bool TY_(AdjustCharEncoding)( TidyDocImpl* doc, int encoding );
336
337
338/** Ensure that the configuration options are self consistent.
339 ** THIS PROCESS IS DESTRUCTIVE TO THE USER STATE. It examines
340 ** certain user-specified options and changes other options
341 ** as a result. This means that documented API functions such
342 ** as tidyOptGetValue() won't return the user-set values after
343 ** this is used. As a result, *don't* just use this function
344 ** at every opportunity, but only where needed, which is ONLY
345 ** prior to parsing a stream, and again prior to saving a
346 ** stream (because we reset after parsing.)
347 ** @param doc The Tidy document to adjust.
348 */
349void TY_(AdjustConfig)( TidyDocImpl* doc );
350
351
352/** Indicates whether or not the current configuration is completely default.
353 ** @param doc The Tidy document.
354 ** @returns The result.
355 */
356TY_PRIVATE Bool TY_(ConfigDiffThanDefault)( TidyDocImpl* doc );
357
358
359/** Indicates whether or not the current configuration is different from the
360 ** stored snapshot.
361 ** @param doc The Tidy document.
362 ** @returns The result.
363 */
364TY_PRIVATE Bool TY_(ConfigDiffThanSnapshot)( TidyDocImpl* doc );
365
366
367/** Returns the character encoding ID for the given character encoding
368 ** string.
369 ** @param doc The Tidy document.
370 ** @param charenc The name of the character encoding.
371 ** @returns The Id of the character encoding.
372 */
373TY_PRIVATE int TY_(CharEncodingId)( TidyDocImpl* doc, ctmbstr charenc );
374
375
376/** Returns the full name of the encoding for the given ID.
377 ** @param encoding The Id of the encoding.
378 ** @returns The name of the character encoding.
379 */
380TY_PRIVATE ctmbstr TY_(CharEncodingName)( int encoding );
381
382
383/** Returns the Tidy command line option name of the encoding for the given ID.
384 ** @param encoding The Id of the encoding.
385 ** @returns The Tidy command line option representing the encoding.
386 */
387TY_PRIVATE ctmbstr TY_(CharEncodingOptName)( int encoding );
388
389
390/** Coordinates Config update and list data.
391 ** @param doc The Tidy document.
392 ** @param opt The option the list item is intended for.
393 ** @param name The name of the new list item.
394 */
395TY_PRIVATE void TY_(DeclareListItem)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name );
396
397#ifdef _DEBUG
398
399/* Debug lookup functions will be type-safe and assert option type match */
400TY_PRIVATE ulong TY_(_cfgGet)( TidyDocImpl* doc, TidyOptionId optId );
401TY_PRIVATE Bool TY_(_cfgGetBool)( TidyDocImpl* doc, TidyOptionId optId );
402TY_PRIVATE TidyTriState TY_(_cfgGetAutoBool)( TidyDocImpl* doc, TidyOptionId optId );
403TY_PRIVATE ctmbstr TY_(_cfgGetString)( TidyDocImpl* doc, TidyOptionId optId );
404
405#define cfg(doc, id) TY_(_cfgGet)( (doc), (id) )
406#define cfgBool(doc, id) TY_(_cfgGetBool)( (doc), (id) )
407#define cfgAutoBool(doc, id) TY_(_cfgGetAutoBool)( (doc), (id) )
408#define cfgStr(doc, id) TY_(_cfgGetString)( (doc), (id) )
409
410#else
411
412/* Release build macros for speed */
413
414/** Access the raw, non-string uint value of the given option ID. */
415#define cfg(doc, id) ((doc)->config.value[ (id) ].v)
416
417/** Access the Bool value of the given option ID. */
418#define cfgBool(doc, id) ((Bool) cfg(doc, id))
419
420/** Access the TidyTriState value of the given option ID. */
421#define cfgAutoBool(doc, id) ((TidyTriState) cfg(doc, id))
422
423/** Access the string value of the given option ID. */
424#define cfgStr(doc, id) ((ctmbstr) (doc)->config.value[ (id) ].p)
425
426#endif /* _DEBUG */
427
428
429/** @} configuration_options group */
430/** @} internal_api addtogroup */
431
432
433#endif /* __CONFIG_H__ */
#define TY_PRIVATE
Definition forward.h:29
#define TY_(str)
Definition forward.h:23
This type defines an output destination capable of accepting raw bytes of output.
Definition tidy.h:1129
TidyOptionId id
The unique identifier for this option.
Definition config.h:98
uint c
Current char in input stream for reading options.
Definition config.h:126
ctmbstr inputs[10]
String values that can select this value.
Definition config.h:68
TidyOptionValue value[N_TIDY_OPTIONS+1]
Current config values.
Definition config.h:123
const int value
The option value represented by this label.
Definition config.h:67
ulong dflt
Default value for TidyInteger and TidyBoolean.
Definition config.h:102
ctmbstr label
PickList label for this item.
Definition config.h:66
ctmbstr name
The name of the option.
Definition config.h:100
TidyOptionValue snapshot[N_TIDY_OPTIONS+1]
Snapshot of values to be restored later.
Definition config.h:124
ulong v
Value for TidyInteger and TidyBoolean.
Definition config.h:113
TidyOptionId opt
Identifier.
Definition config.h:134
char * p
Value for TidyString.
Definition config.h:114
StreamIn * cfgIn
Current input source for reading options.
Definition config.h:127
TidyConfigCategory category
The category of the option.
Definition config.h:99
ParseProperty * parser
Function to parse input; read-only if NULL.
Definition config.h:103
ctmbstr pdflt
Default value for TidyString.
Definition config.h:105
PickListItems * pickList
The picklist of possible values for this option.
Definition config.h:104
TidyOptionType type
The date type for the option.
Definition config.h:101
uint defined_tags
Tracks user-defined tags.
Definition config.h:125
TidyOptionId const * links
Cross references.
Definition config.h:135
Bool ParseProperty(TidyDocImpl *doc, const TidyOptionImpl *opt)
This typedef describes a function that is used for parsing the input given for a particular Tidy opti...
Definition config.h:91
#define TIDY_PL_SIZE
Determines the maximum number of items in an option's picklist.
Definition config.h:58
const PickListItem PickListItems[TIDY_PL_SIZE]
An array of PickListItems, fixed in size for in-code declarations.
Definition config.h:78
Structs of this type contain information needed in order to present picklists, relate picklist entrie...
Definition config.h:65
This type is used to define a structure for keeping track of the values for each option.
Definition config.h:122
Used to build a table of documentation cross-references.
Definition config.h:133
This structure defines the internal representation of a Tidy option.
Definition config.h:97
Stored option values can be one of two internal types.
Definition config.h:112
TidyConfigCategory
Categories of Tidy configuration options, which are used mostly by user interfaces to sort Tidy optio...
Definition tidyenum.h:686
TidyOptionId
Option IDs are used used to get and/or set configuration option values and retrieve their description...
Definition tidyenum.h:560
TidyTriState
AutoBool values used by ParseBool, ParseTriState, ParseIndent, ParseBOM.
Definition tidyenum.h:713
TidyOptionType
A Tidy configuration option can have one of these data types.
Definition tidyenum.h:694
@ N_TIDY_OPTIONS
Must be last.
Definition tidyenum.h:672
Defines HTML Tidy public API implemented by LibTidy.
Bool
Definition tidyplatform.h:647
unsigned int uint
Definition tidyplatform.h:569
const tmbchar * ctmbstr
Definition tidyplatform.h:609