HTML Tidy  5.7.0
The HTACG Tidy HTML Project
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  */
65 typedef 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. */
69 } PickListItem;
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 
81 struct _tidy_option; /* forward */
82 
83 /** The TidyOptionImpl type implements the `_tidy_option` structure.
84  */
85 typedef 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  */
91 typedef 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  */
111 typedef 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  */
121 typedef 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  */
133 typedef struct {
134  TidyOptionId opt; /**< Identifier. */
135  TidyOptionId const *links; /**< Cross references. Last element must be 'TidyUnknownOption'. */
136 } TidyOptionDoc;
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  */
143 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  */
150 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  */
156 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  */
162 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  */
170 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  */
178 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  */
186 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  */
195 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  */
202 void TY_(InitConfig)( TidyDocImpl* doc );
203 
204 
205 /** Frees the configuration memory for the given Tidy document.
206  ** @param doc The Tidy document.
207  */
208 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  */
216 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  */
225 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  */
234 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  */
242 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  */
248 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  */
255 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  */
261 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  */
268 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  */
276 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  */
286 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  */
296 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  */
305 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  */
316 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  */
327 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  */
335 Bool TY_(AdjustCharEncoding)( TidyDocImpl* doc, int encoding );
336 
337 
338 /** Ensure that the configuration options are self consistent.
339  ** @param doc The Tidy document to adjust.
340  */
341 void TY_(AdjustConfig)( TidyDocImpl* doc );
342 
343 
344 /** Indicates whether or not the current configuration is completely default.
345  ** @param doc The Tidy document.
346  ** @returns The result.
347  */
348 Bool TY_(ConfigDiffThanDefault)( TidyDocImpl* doc );
349 
350 
351 /** Indicates whether or not the current configuration is different from the
352  ** stored snapshot.
353  ** @param doc The Tidy document.
354  ** @returns The result.
355  */
356 Bool TY_(ConfigDiffThanSnapshot)( TidyDocImpl* doc );
357 
358 
359 /** Returns the character encoding ID for the given character encoding
360  ** string.
361  ** @param doc The Tidy document.
362  ** @param charenc The name of the character encoding.
363  ** @returns The Id of the character encoding.
364  */
365 int TY_(CharEncodingId)( TidyDocImpl* doc, ctmbstr charenc );
366 
367 
368 /** Returns the full name of the encoding for the given ID.
369  ** @param encoding The Id of the encoding.
370  ** @returns The name of the character encoding.
371  */
372 ctmbstr TY_(CharEncodingName)( int encoding );
373 
374 
375 /** Returns the Tidy command line option name of the encoding for the given ID.
376  ** @param encoding The Id of the encoding.
377  ** @returns The Tidy command line option representing the encoding.
378  */
379 ctmbstr TY_(CharEncodingOptName)( int encoding );
380 
381 
382 /** Coordinates Config update and list data.
383  ** @param doc The Tidy document.
384  ** @param opt The option the list item is intended for.
385  ** @param name The name of the new list item.
386  */
387 void TY_(DeclareListItem)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name );
388 
389 #ifdef _DEBUG
390 
391 /* Debug lookup functions will be type-safe and assert option type match */
392 ulong TY_(_cfgGet)( TidyDocImpl* doc, TidyOptionId optId );
393 Bool TY_(_cfgGetBool)( TidyDocImpl* doc, TidyOptionId optId );
394 TidyTriState TY_(_cfgGetAutoBool)( TidyDocImpl* doc, TidyOptionId optId );
395 ctmbstr TY_(_cfgGetString)( TidyDocImpl* doc, TidyOptionId optId );
396 
397 #define cfg(doc, id) TY_(_cfgGet)( (doc), (id) )
398 #define cfgBool(doc, id) TY_(_cfgGetBool)( (doc), (id) )
399 #define cfgAutoBool(doc, id) TY_(_cfgGetAutoBool)( (doc), (id) )
400 #define cfgStr(doc, id) TY_(_cfgGetString)( (doc), (id) )
401 
402 #else
403 
404 /* Release build macros for speed */
405 
406 /** Access the raw, non-string uint value of the given option ID. */
407 #define cfg(doc, id) ((doc)->config.value[ (id) ].v)
408 
409 /** Access the Bool value of the given option ID. */
410 #define cfgBool(doc, id) ((Bool) cfg(doc, id))
411 
412 /** Access the TidyTriState value of the given option ID. */
413 #define cfgAutoBool(doc, id) ((TidyTriState) cfg(doc, id))
414 
415 /** Access the string value of the given option ID. */
416 #define cfgStr(doc, id) ((ctmbstr) (doc)->config.value[ (id) ].p)
417 
418 #endif /* _DEBUG */
419 
420 
421 /** @} configuration_options group */
422 /** @} internal_api addtogroup */
423 
424 
425 #endif /* __CONFIG_H__ */
Structs of this type contain information needed in order to present picklists, relate picklist entrie...
Definition: config.h:65
TidyConfigCategory category
The category of the option.
Definition: config.h:99
Must be last.
Definition: tidyenum.h:681
ctmbstr label
PickList label for this item.
Definition: config.h:66
Used to build a table of documentation cross-references.
Definition: config.h:133
const tmbchar * ctmbstr
Definition: tidyplatform.h:594
PickListItems * pickList
The picklist of possible values for this option.
Definition: config.h:104
ctmbstr name
The name of the option.
Definition: config.h:100
TidyOptionId const * links
Cross references.
Definition: config.h:135
uint c
Current char in input stream for reading options.
Definition: config.h:126
TidyOptionId
Option IDs are used used to get and/or set configuration option values and retrieve their description...
Definition: tidyenum.h:569
#define TIDY_PL_SIZE
Determines the maximum number of items in an option&#39;s picklist.
Definition: config.h:58
ctmbstr inputs[10]
String values that can select this value.
Definition: config.h:68
Bool
Definition: tidyplatform.h:631
TidyOptionType type
The date type for the option.
Definition: config.h:101
Defines HTML Tidy public API implemented by LibTidy.
Stored option values can be one of two internal types.
Definition: config.h:111
ctmbstr pdflt
Default value for TidyString.
Definition: config.h:105
ParseProperty * parser
Function to parse input; read-only if NULL.
Definition: config.h:103
ulong dflt
Default value for TidyInteger and TidyBoolean.
Definition: config.h:102
TidyOptionId id
The unique identifier for this option.
Definition: config.h:98
This type is used to define a structure for keeping track of the values for each option.
Definition: config.h:121
unsigned int uint
Definition: tidyplatform.h:554
This type defines an output destination capable of accepting raw bytes of output. ...
Definition: tidy.h:1128
uint defined_tags
Tracks user-defined tags.
Definition: config.h:125
const int value
The option value represented by this label.
Definition: config.h:67
char * p
Value for TidyString.
Definition: config.h:114
TidyOptionId opt
Identifier.
Definition: config.h:134
This structure defines the internal representation of a Tidy option.
Definition: config.h:96
#define TY_(str)
Definition: forward.h:23
TidyConfigCategory
Categories of Tidy configuration options, which are used mostly by user interfaces to sort Tidy optio...
Definition: tidyenum.h:694
ulong v
Value for TidyInteger and TidyBoolean.
Definition: config.h:113
TidyOptionType
A Tidy configuration option can have one of these data types.
Definition: tidyenum.h:701
TidyTriState
AutoBool values used by ParseBool, ParseTriState, ParseIndent, ParseBOM.
Definition: tidyenum.h:720
StreamIn * cfgIn
Current input source for reading options.
Definition: config.h:127
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
const PickListItem PickListItems[TIDY_PL_SIZE]
An array of PickListItems, fixed in size for in-code declarations.
Definition: config.h:78