HTML Tidy  5.8.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 TY_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  */
150 TY_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  */
156 TY_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  */
162 TY_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  */
170 TY_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  */
178 TY_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  */
186 TY_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  */
195 TY_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  */
202 TY_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  */
208 TY_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  */
216 TY_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  */
225 TY_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  */
234 TY_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  */
242 TY_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  */
248 TY_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  */
255 TY_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  */
261 TY_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  */
268 TY_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  */
276 TY_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  */
286 TY_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  */
296 TY_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  */
305 TY_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  */
316 TY_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  */
327 TY_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  */
335 TY_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  */
349 void 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  */
356 TY_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  */
364 TY_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  */
373 TY_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  */
380 TY_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  */
387 TY_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  */
395 TY_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 */
400 TY_PRIVATE ulong TY_(_cfgGet)( TidyDocImpl* doc, TidyOptionId optId );
401 TY_PRIVATE Bool TY_(_cfgGetBool)( TidyDocImpl* doc, TidyOptionId optId );
402 TY_PRIVATE TidyTriState TY_(_cfgGetAutoBool)( TidyDocImpl* doc, TidyOptionId optId );
403 TY_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
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
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
#define TIDY_PL_SIZE
Determines the maximum number of items in an option's picklist.
Definition: config.h:58
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
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:699
TidyOptionId
Option IDs are used used to get and/or set configuration option values and retrieve their description...
Definition: tidyenum.h:573
TidyTriState
AutoBool values used by ParseBool, ParseTriState, ParseIndent, ParseBOM.
Definition: tidyenum.h:725
TidyOptionType
A Tidy configuration option can have one of these data types.
Definition: tidyenum.h:706
@ N_TIDY_OPTIONS
Must be last.
Definition: tidyenum.h:685
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