tidy-html5/src/config.h

434 lines
15 KiB
C
Raw Normal View History

2011-11-17 02:44:16 +00:00
#ifndef __CONFIG_H__
#define __CONFIG_H__
/**************************************************************************//**
* @file
* Read configuration files and manage configuration properties.
*
* Config files associate a property name with a value.
*
* // comments can start at the beginning of a line
* # comments can start at the beginning of a line
* name: short values fit onto one line
* name: a really long value that
* continues on the next line
*
* Property names are case insensitive and should be less than 60 characters
2021-07-21 19:50:53 +00:00
* in length, and must start at the beginning of the line, as whitespace at
* the start of a line signifies a line continuation.
*
* @author HTACG, et al (consult git log)
*
* @copyright
* Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts
* Institute of Technology, European Research Consortium for Informatics
* and Mathematics, Keio University) and HTACG.
* @par
* All Rights Reserved.
* @par
* See `tidy.h` for the complete license.
*
* @date Additional updates: consult git log
*
******************************************************************************/
2011-11-17 02:44:16 +00:00
#include "forward.h"
#include "tidy.h"
#include "streamio.h"
2017-10-07 16:14:51 +00:00
/** @addtogroup internal_api */
/** @{ */
/***************************************************************************//**
** @defgroup configuration_options Configuration Options
**
** This module organizes all of Tidy's configuration options, including
** picklist management, option setting and retrieval, option file utilities,
** and so on.
**
** @{
******************************************************************************/
/** Determines the maximum number of items in an option's picklist. PickLists
** may have up to 16 items. For some reason, this limit has been hard-coded
** into Tidy for some time. Feel free to increase this as needed.
*/
#define TIDY_PL_SIZE 16
2017-10-07 16:14:51 +00:00
/** Structs of this type contain information needed in order to present
** picklists, relate picklist entries to public enum values, and parse
** strings that are accepted in order to assign the value.
*/
typedef struct PickListItem {
ctmbstr label; /**< PickList label for this item. */
const int value; /**< The option value represented by this label. */
ctmbstr inputs[10]; /**< String values that can select this value. */
} PickListItem;
/** An array of PickListItems, fixed in size for in-code declarations.
** Arrays must be populated in 0 to 10 order, as the option value is assigned
** based on this index and *not* on the structures' value field. It remains
** a best practice, however, to assign a public enum value with the proper
** index value.
*/
typedef const PickListItem PickListItems[TIDY_PL_SIZE];
2017-10-07 16:14:51 +00:00
struct _tidy_option; /* forward */
/** The TidyOptionImpl type implements the `_tidy_option` structure.
*/
2011-11-17 02:44:16 +00:00
typedef struct _tidy_option TidyOptionImpl;
2017-10-07 16:14:51 +00:00
/** This typedef describes a function that is used for parsing the input
** given for a particular Tidy option.
*/
2011-11-17 02:44:16 +00:00
typedef Bool (ParseProperty)( TidyDocImpl* doc, const TidyOptionImpl* opt );
2017-10-07 16:14:51 +00:00
/** This structure defines the internal representation of a Tidy option.
*/
2011-11-17 02:44:16 +00:00
struct _tidy_option
{
TidyOptionId id; /**< The unique identifier for this option. */
2017-10-07 16:14:51 +00:00
TidyConfigCategory category; /**< The category of the option. */
ctmbstr name; /**< The name of the option. */
TidyOptionType type; /**< The date type for the option. */
ulong dflt; /**< Default value for TidyInteger and TidyBoolean */
2017-10-07 16:14:51 +00:00
ParseProperty* parser; /**< Function to parse input; read-only if NULL. */
PickListItems* pickList; /**< The picklist of possible values for this option. */
ctmbstr pdflt; /**< Default value for TidyString. */
2011-11-17 02:44:16 +00:00
};
2017-10-07 16:14:51 +00:00
/** Stored option values can be one of two internal types.
*/
2011-11-17 02:44:16 +00:00
typedef union
{
ulong v; /**< Value for TidyInteger and TidyBoolean */
char *p; /**< Value for TidyString */
2011-11-17 02:44:16 +00:00
} TidyOptionValue;
2017-10-07 16:14:51 +00:00
/** This type is used to define a structure for keeping track of the values
** for each option.
*/
2011-11-17 02:44:16 +00:00
typedef struct _tidy_config
{
2017-10-07 16:14:51 +00:00
TidyOptionValue value[ N_TIDY_OPTIONS + 1 ]; /**< Current config values. */
TidyOptionValue snapshot[ N_TIDY_OPTIONS + 1 ]; /**< Snapshot of values to be restored later. */
uint defined_tags; /**< Tracks user-defined tags. */
uint c; /**< Current char in input stream for reading options. */
StreamIn* cfgIn; /**< Current input source for reading options.*/
2011-11-17 02:44:16 +00:00
} TidyConfigImpl;
2017-10-07 16:14:51 +00:00
/** Used to build a table of documentation cross-references.
*/
2011-11-17 02:44:16 +00:00
typedef struct {
TidyOptionId opt; /**< Identifier. */
TidyOptionId const *links; /**< Cross references. Last element must be 'TidyUnknownOption'. */
2011-11-17 02:44:16 +00:00
} TidyOptionDoc;
2017-10-07 16:14:51 +00:00
/** Given an option name, return an instance of an option.
** @param optnam The option name to retrieve.
** @returns The instance of the requested option.
2017-10-07 16:14:51 +00:00
*/
TY_PRIVATE const TidyOptionImpl* TY_(lookupOption)( ctmbstr optnam );
2017-10-07 16:14:51 +00:00
/** Given an option ID, return an instance of an option.
** @param optId The option ID to retrieve.
** @returns The instance of the requested option.
2017-10-07 16:14:51 +00:00
*/
TY_PRIVATE const TidyOptionImpl* TY_(getOption)( TidyOptionId optId );
2011-11-17 02:44:16 +00:00
/** Given an option ID, indicates whether or not the option is a list.
** @param optId The option ID to check.
** @returns Returns yes if the option value is a list.
*/
TY_PRIVATE const Bool TY_(getOptionIsList)( TidyOptionId optId );
2017-10-07 16:14:51 +00:00
/** Initiates an iterator to cycle through all of the available options.
** @param doc The Tidy document to get options.
** @returns An iterator token to be used with TY_(getNextOption)().
2017-10-07 16:14:51 +00:00
*/
TY_PRIVATE TidyIterator TY_(getOptionList)( TidyDocImpl* doc );
2017-10-07 16:14:51 +00:00
/** Gets the next option provided by the iterator.
** @param doc The Tidy document to get options.
** @param iter The iterator token initialized by TY_(getOptionList)().
** @returns The instance of the next option.
2017-10-07 16:14:51 +00:00
*/
TY_PRIVATE const TidyOptionImpl* TY_(getNextOption)( TidyDocImpl* doc, TidyIterator* iter );
2011-11-17 02:44:16 +00:00
2017-10-07 16:14:51 +00:00
/** Initiates an iterator to cycle through all of the available picklist
** possibilities.
** @param option An instance of an option for which to iterate a picklist.
2021-07-21 19:50:53 +00:00
** @returns An iterator token to be used with TY_(getNextOptionPick)().
2017-10-07 16:14:51 +00:00
*/
TY_PRIVATE TidyIterator TY_(getOptionPickList)( const TidyOptionImpl* option );
2017-10-07 16:14:51 +00:00
/** Gets the next picklist possibility provided by the iterator.
** @param option The instance of the option for which to iterate a picklist.
** @param iter The iterator token initialized by TY_(getOptionPickList)().
** @returns The next picklist entry.
2017-10-07 16:14:51 +00:00
*/
TY_PRIVATE ctmbstr TY_(getNextOptionPick)( const TidyOptionImpl* option, TidyIterator* iter );
2011-11-17 02:44:16 +00:00
Several foundational changes preparing for release of 5.4 and future 5.5: - Consolidated all output string definitions enums into `tidyenum.h`, which is where they belong, and where they have proper visibility. - Re-arranged `messages.c/h` with several comments useful to developers. - Properly added the key lookup functions and the language localization functions into tidy.h/tidylib.c with proper name-spacing. - Previous point restored a *lot* of sanity to the #include pollution that's been introduced in light of these. - Note that opaque types have been (properly) introduced. Look at the updated headers for `language.h`. In particular only an opaque structure is passed outside of LibTidy, and so use TidyLangWindowsName and TidyLangPosixName to poll these objects. - Console application updated as a result of this. - Removed dead code: - void TY_(UnknownOption)( TidyDocImpl* doc, char c ); - void TY_(UnknownFile)( TidyDocImpl* doc, ctmbstr program, ctmbstr file ); - Redundant strings were removed with the removal of this dead code. - Several enums were given fixed starting values. YOUR PROGRAMS SHOULD NEVER depend on enum values. `TidyReportLevel` is an example of such. - Some enums were removed as a result of this. `TidyReportLevel` now has matching strings, so the redundant `TidyReportLevelStrings` was removed. - All of the PO's and language header files were regenerated as a result of the string cleanup and header cleanup. - Made the interface to the library version and release date consistent. - CMakeLists.txt now supports SUPPORT_CONSOLE_APP. The intention is to be able to remove console-only code from LibTidy (for LibTidy users). - Updated README/MESSAGES.md, which is *vastly* more simple now.
2017-02-13 19:29:47 +00:00
#if SUPPORT_CONSOLE_APP
/** Returns the cross-reference information structure for optID, which is
** used for generating documentation.
** @param optId The option ID to get cross-reference information for.
** @returns Cross reference information.
*/
TY_PRIVATE const TidyOptionDoc* TY_(OptGetDocDesc)( TidyOptionId optId );
Several foundational changes preparing for release of 5.4 and future 5.5: - Consolidated all output string definitions enums into `tidyenum.h`, which is where they belong, and where they have proper visibility. - Re-arranged `messages.c/h` with several comments useful to developers. - Properly added the key lookup functions and the language localization functions into tidy.h/tidylib.c with proper name-spacing. - Previous point restored a *lot* of sanity to the #include pollution that's been introduced in light of these. - Note that opaque types have been (properly) introduced. Look at the updated headers for `language.h`. In particular only an opaque structure is passed outside of LibTidy, and so use TidyLangWindowsName and TidyLangPosixName to poll these objects. - Console application updated as a result of this. - Removed dead code: - void TY_(UnknownOption)( TidyDocImpl* doc, char c ); - void TY_(UnknownFile)( TidyDocImpl* doc, ctmbstr program, ctmbstr file ); - Redundant strings were removed with the removal of this dead code. - Several enums were given fixed starting values. YOUR PROGRAMS SHOULD NEVER depend on enum values. `TidyReportLevel` is an example of such. - Some enums were removed as a result of this. `TidyReportLevel` now has matching strings, so the redundant `TidyReportLevelStrings` was removed. - All of the PO's and language header files were regenerated as a result of the string cleanup and header cleanup. - Made the interface to the library version and release date consistent. - CMakeLists.txt now supports SUPPORT_CONSOLE_APP. The intention is to be able to remove console-only code from LibTidy (for LibTidy users). - Updated README/MESSAGES.md, which is *vastly* more simple now.
2017-02-13 19:29:47 +00:00
#endif /* SUPPORT_CONSOLE_APP */
2011-11-17 02:44:16 +00:00
/** Initialize the configuration for the given Tidy document.
** @param doc The Tidy document.
*/
TY_PRIVATE void TY_(InitConfig)( TidyDocImpl* doc );
/** Frees the configuration memory for the given Tidy document.
** @param doc The Tidy document.
*/
TY_PRIVATE void TY_(FreeConfig)( TidyDocImpl* doc );
2011-11-17 02:44:16 +00:00
/** Gets the picklist label for a given value.
** @param optId the option id having a picklist to check.
** @param pick the picklist item to retrieve.
** @returns The label for the pick.
*/
TY_PRIVATE ctmbstr TY_(GetPickListLabelForPick)( TidyOptionId optId, uint pick );
/** Sets the integer value for the given option Id.
** @param doc The Tidy document.
** @param optId The option ID to set.
** @param val The value to set.
** @returns Success or failure.
*/
TY_PRIVATE Bool TY_(SetOptionInt)( TidyDocImpl* doc, TidyOptionId optId, ulong val );
/** Sets the bool value for the given option Id.
** @param doc The Tidy document.
** @param optId The option ID to set.
** @param val The value to set.
** @returns Success or failure.
*/
TY_PRIVATE Bool TY_(SetOptionBool)( TidyDocImpl* doc, TidyOptionId optId, Bool val );
2011-11-17 02:44:16 +00:00
/** Resets the given option to its default value.
** @param doc The Tidy document.
** @param optId The option ID to set.
** @returns Success or failure.
*/
TY_PRIVATE Bool TY_(ResetOptionToDefault)( TidyDocImpl* doc, TidyOptionId optId );
/** Resets all options in the document to their default values.
** @param doc The Tidy document.
*/
TY_PRIVATE void TY_(ResetConfigToDefault)( TidyDocImpl* doc );
/** Stores a snapshot of all of the configuration values that can be
** restored later.
** @param doc The Tidy document.
*/
TY_PRIVATE void TY_(TakeConfigSnapshot)( TidyDocImpl* doc );
/** Restores all of the configuration values to their snapshotted values.
** @param doc The Tidy document.
*/
TY_PRIVATE void TY_(ResetConfigToSnapshot)( TidyDocImpl* doc );
2011-11-17 02:44:16 +00:00
/** Copies the configuration from one document to another.
** @param docTo The destination Tidy document.
** @param docFrom The source Tidy document.
*/
TY_PRIVATE void TY_(CopyConfig)( TidyDocImpl* docTo, TidyDocImpl* docFrom );
2011-11-17 02:44:16 +00:00
/** Attempts to parse the given config file into the document.
** @param doc The Tidy document.
** @param cfgfil The file to load.
** @returns a file system error code.
*/
TY_PRIVATE int TY_(ParseConfigFile)( TidyDocImpl* doc, ctmbstr cfgfil );
/** Attempts to parse the given config file into the document, using
** the provided encoding.
** @param doc The Tidy document.
** @param cfgfil The file to load.
** @param charenc The name of the encoding to use for reading the file.
** @returns a file system error code.
*/
TY_PRIVATE int TY_(ParseConfigFileEnc)( TidyDocImpl* doc,
2011-11-17 02:44:16 +00:00
ctmbstr cfgfil, ctmbstr charenc );
/** Saves the current configuration for options not having default values
** into the specified file.
** @param doc The Tidy document.
** @param cfgfil The file to save.
** @returns a file system error code.
*/
TY_PRIVATE int TY_(SaveConfigFile)( TidyDocImpl* doc, ctmbstr cfgfil );
/** Writes the current configuration for options not having default values
** into the specified sink.
** @param doc The Tidy document.
** @param sink The sink to save into.
** @returns a file system error code.
*/
TY_PRIVATE int TY_(SaveConfigSink)( TidyDocImpl* doc, TidyOutputSink* sink );
2011-11-17 02:44:16 +00:00
/** Attempts to parse the provided value for the given option name. Returns
** false if unknown option, missing parameter, or the option doesn't
** use the parameter.
** @param doc The Tidy document.
** @param optnam The name of the option to be set.
** @param optVal The string value to attempt to parse.
** @returns Success or failure.
*/
TY_PRIVATE Bool TY_(ParseConfigOption)( TidyDocImpl* doc, ctmbstr optnam, ctmbstr optVal );
/** Attempts to parse the provided value for the given option id. Returns
** false if unknown option, missing parameter, or the option doesn't
** use the parameter.
** @param doc The Tidy document.
** @param optId The ID of the option to be set.
** @param optVal The string value to attempt to parse.
** @returns Success or failure.
*/
TY_PRIVATE Bool TY_(ParseConfigValue)( TidyDocImpl* doc, TidyOptionId optId, ctmbstr optVal );
2011-11-17 02:44:16 +00:00
/** Ensure that char encodings are self consistent.
** @param doc The Tidy document to adjust.
** @param encoding The encoding being applied.
** @returns A bool indicating success or failure.
*/
TY_PRIVATE Bool TY_(AdjustCharEncoding)( TidyDocImpl* doc, int encoding );
2011-11-17 02:44:16 +00:00
/** Ensure that the configuration options are self consistent.
** THIS PROCESS IS DESTRUCTIVE TO THE USER STATE. It examines
** certain user-specified options and changes other options
** as a result. This means that documented API functions such
** as tidyOptGetValue() won't return the user-set values after
** this is used. As a result, *don't* just use this function
** at every opportunity, but only where needed, which is ONLY
** prior to parsing a stream, and again prior to saving a
** stream (because we reset after parsing.)
** @param doc The Tidy document to adjust.
*/
TY_PRIVATE void TY_(AdjustConfig)( TidyDocImpl* doc );
/** Indicates whether or not the current configuration is completely default.
** @param doc The Tidy document.
** @returns The result.
*/
TY_PRIVATE Bool TY_(ConfigDiffThanDefault)( TidyDocImpl* doc );
/** Indicates whether or not the current configuration is different from the
** stored snapshot.
** @param doc The Tidy document.
** @returns The result.
*/
TY_PRIVATE Bool TY_(ConfigDiffThanSnapshot)( TidyDocImpl* doc );
2011-11-17 02:44:16 +00:00
/** Returns the character encoding ID for the given character encoding
** string.
** @param doc The Tidy document.
** @param charenc The name of the character encoding.
** @returns The Id of the character encoding.
*/
TY_PRIVATE int TY_(CharEncodingId)( TidyDocImpl* doc, ctmbstr charenc );
/** Returns the full name of the encoding for the given ID.
** @param encoding The Id of the encoding.
** @returns The name of the character encoding.
*/
TY_PRIVATE ctmbstr TY_(CharEncodingName)( int encoding );
/** Returns the Tidy command line option name of the encoding for the given ID.
** @param encoding The Id of the encoding.
** @returns The Tidy command line option representing the encoding.
*/
TY_PRIVATE ctmbstr TY_(CharEncodingOptName)( int encoding );
2011-11-17 02:44:16 +00:00
/** Coordinates Config update and list data.
** @param doc The Tidy document.
** @param opt The option the list item is intended for.
** @param name The name of the new list item.
*/
TY_PRIVATE void TY_(DeclareListItem)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name );
2011-11-17 02:44:16 +00:00
#ifdef _DEBUG
/* Debug lookup functions will be type-safe and assert option type match */
TY_PRIVATE ulong TY_(_cfgGet)( TidyDocImpl* doc, TidyOptionId optId );
TY_PRIVATE Bool TY_(_cfgGetBool)( TidyDocImpl* doc, TidyOptionId optId );
TY_PRIVATE TidyTriState TY_(_cfgGetAutoBool)( TidyDocImpl* doc, TidyOptionId optId );
TY_PRIVATE ctmbstr TY_(_cfgGetString)( TidyDocImpl* doc, TidyOptionId optId );
2011-11-17 02:44:16 +00:00
#define cfg(doc, id) TY_(_cfgGet)( (doc), (id) )
#define cfgBool(doc, id) TY_(_cfgGetBool)( (doc), (id) )
#define cfgAutoBool(doc, id) TY_(_cfgGetAutoBool)( (doc), (id) )
#define cfgStr(doc, id) TY_(_cfgGetString)( (doc), (id) )
#else
/* Release build macros for speed */
/** Access the raw, non-string uint value of the given option ID. */
2011-11-17 02:44:16 +00:00
#define cfg(doc, id) ((doc)->config.value[ (id) ].v)
/** Access the Bool value of the given option ID. */
2011-11-17 02:44:16 +00:00
#define cfgBool(doc, id) ((Bool) cfg(doc, id))
/** Access the TidyTriState value of the given option ID. */
2011-11-17 02:44:16 +00:00
#define cfgAutoBool(doc, id) ((TidyTriState) cfg(doc, id))
/** Access the string value of the given option ID. */
2011-11-17 02:44:16 +00:00
#define cfgStr(doc, id) ((ctmbstr) (doc)->config.value[ (id) ].p)
#endif /* _DEBUG */
2017-10-07 16:14:51 +00:00
/** @} configuration_options group */
/** @} internal_api addtogroup */
2011-11-17 02:44:16 +00:00
#endif /* __CONFIG_H__ */