struct symbol encapsulates a preprocessor symbol's state More...

#include <symbol.h>

Classes
struct	locator
	`struct symbol::locator` encapsulates a symbol table entry. More...

Public Types
enum	provenance { provenance::unconfigured, provenance::global, provenance::transient }
	Symbolic constants denoting the provenance of a symbol. More...

using	symbol_table = std::map< std::string, symbol >
	Type of map implementing the symbol tbale.

using	table_entry = symbol_table::value_type
	Type of entry in the symbol table.

Public Member Functions
bool	operator== (symbol const &other) const
	Equality.

bool	operator!= (symbol const &other) const
	Inequality.

std::string const &	id () const
	Get the name of the symbol.

provenance	origin () const
	Get the provenance of the symbol.

void	originate (provenance origin)
	Set the symbol's provenance.

unsigned	line () const
	Get the source line-number at which this symbol was last defined or undefined.

std::shared_ptr< std::string const >	defn () const
	Get a pointer to the symbol's definition; null if undefined.

std::shared_ptr < parameter_substitution::format const >	format () const
	Get a pointer to the symbol's substitution format; null if none. More...

bool	defined () const
	Is the symbol defined.

void	set_definition (std::string const &defn)
	Set the definition of the symbol.

void	set_parameters (formal_parameter_list const &params)
	Set a macro parameter list for the symbol.

void	set_parameters (size_t n)
	Impute `n` parameters of the symbol.

void	define (std::string const &defn, formal_parameter_list const &params)
	Define symbol. More...

void	clear_parameters ()
	Remove any macro parameter list.

void	undef ()
	Undefine thesymbol.

void	report () const
	Report a reference to this symbol.

bool	configured () const
	Say whether the symbol is configured.

bool	deselected () const
	Say whether the symbol is deselected per the `--select` option.

bool	invoked () const
	Say whether the symbol has been invoked. More...

bool	self_referential () const
	Say whether the symbol's definition is infinitely regressive.

bool	dirty () const
	Say whether cached references of this symbol are out of date, due to configuration changes of this symbol or contributing symbols.

bool	clean () const
	Say whether the symbol's state has been determined.

bool	in_progress () const
	Say whether a determination the symbol's state is in progress.

std::string	signature () const
	Get the symbol's reference signature as string. More...

formal_parameter_list const &	parameters () const
	Get the symbol's formal parameter list.

size_t	which_parameter (std::string const &str) const
	Say whether a string is a parameter of the symbol.

bool	variadic () const
	Say whether this symbol is a variadic macro.

void	digest_global_define (chewer< std::string > &chew)
	Analyse and handle a `-D` option for this symbol. More...

line_type	digest_transient_define (formal_parameter_list const &params, std::string const &definition)
	Analyse and handle an in-source `define` directive for this symbol. More...

void	digest_global_undef (chewer< std::string > &chew)
	Analyse and handle a `-U` option for this symbol. More...

line_type	digest_transient_undef ()
	Analyse and handle an in-source `undef` directive for this symbol. More...

Static Public Member Functions
static size_t	count (provenance source)
	Get the number of symbols with a given provenance.

static size_t	count ()
	Get the number of symbols in the symbol table.

static locator	lookup (std::string const &id)
	Lookup an identifier in the symbol table. More...

template<class CharSeq >
static locator	find_any_in (chewer< CharSeq > &chew, size_t &off)
	Search a terminal portion of a `CharSeq` for any known symbol name. More...

static void	set_selection (char const *optarg)

static void	per_file_init ()
	Delete all transient symbols from the symbol table.

static void	report_global_config ()
	Report the global configuration, according to options.

Public Attributes
friend	reference
	Friendship to `struct reference`

Private Types
enum	pseudo_snapshot { pseudo_snapshot::pristine = -1, pseudo_snapshot::define_in_progress = -2, pseudo_snapshot::undef_in_progress = -3, pseudo_snapshot::infinite = -4 }
	Pseudo snapshot numbers for symbols in indeterminate states. More...

Private Member Functions
void	set_pseudo_snapshot (pseudo_snapshot n=pseudo_snapshot::pristine)
	Prime the symbol with a pseudo snapshot.

void	report_premiere ()
	Report a symbol as resolved from the global configuration. The method invokes itself recursively on all the symbol's contributors and then reports the symbol itself.

void	set_invoked (bool value=true)
	Mark the symbol as invoked, or not.

void	subscribe_to (locator other)
	Record the symbol's definition as referring to another another symbol, and recursively as referring to those referred to by the other.

bool	subscribes_to (locator other) const
	Say whether the symbol's definition refers to another another symbol, directly or indirectly.

void	subscribe ()
	Acquire all the symbol's contributors. More...

void	unsubscribe ()
	Forget all the symbol's contributors.

void	make_clean ()
	Assign the symbol state the current sequential snapshot number, signifying that it is up-to-date, and increment the current snapshot number.

void	make_dirty (pseudo_snapshot n=pseudo_snapshot::pristine)
	Assign the symbol state a pseudo snapshot number, signifying that it is out of date, and recursively to all its subscribers.

void	make_self_referential ()
	Assign the symbol state a pseudo snapshot number, signifying that its definition involves an infinite regress, and recursively to all its subscribers.

void	diagnose_retrospective_redefinition () const
	Diagnose the case in which defining or undefining the symbol retrospectively changes the expansion of a previously defined symbol.

int	snapshot_max () const
	Get the maximum sequential snapshot number in the the recursive closure of this symbol its contributors.

	symbol (provenance source)
	Explicitly construct given a `provenance`. More...

Static Private Member Functions
static bool	selected (std::string const &id)
	Say whether a symbol name matches a selection pattern for reporting.

static bool	deselected (std::string const &id)
	Say whether a symbol name is excluded from reporting by the `--select` option.

static bool	add_pattern (std::string const &pattern)
	Add a symbol name pattern for reporting. More...

static bool	wildcard_match (std::string const &wildcard, std::string const &name)
	Say whether a symbol name matches a *-terminated wildcard prefix.

static symbol_table &	table ()
	Get a reference to the symbol table.

static symbol_table::iterator	insert (std::string const &id, provenance source, symbol_table::iterator hint=table().end())
	Insert the symbol into the symbol table with a specified provenance. More...

Private Attributes
locator	_loc
	Locator of this symbol in the symbol table.

std::shared_ptr< std::string >	_defn
	Pointer to the symbol's definition, if any.

formal_parameter_list	_params
	List of the symbol's macro arguments, if any.

provenance	_provenance
	The provenance of the symbol.

unsigned	_line
	Source line-number where symbol last defined or undefined, or 0.

bool	_deselected
	Is the symbol deselected?

bool	_invoked
	Has the symbol been invoked?

std::shared_ptr < parameter_substitution::format >	_format

int	_snapshot

std::vector< symbol::locator >	_contributors

std::vector< symbol::locator >	_subscribers
	List of locators of the symbols to which this one contributes.

std::vector< bool >	_no_expand_pararms

Static Private Attributes
static int	_current_snapshot_
	The current sequential snapshot number.

static int	_last_global_snapshot_
	The last snapshot number consumed by the global configuration.

static std::set< std::string >	_selected_symbols_set_
	The set of symbols selected for reporting, if any.

static symbol_table	_sym_tab_
	The symbol table.

static table_entry	_null_
	The table entry of the null symbol.

Detailed Description

struct symbol encapsulates a preprocessor symbol's state

Definition at line 58 of file symbol.h.

Member Enumeration Documentation

enum symbol::provenance

strong

Symbolic constants denoting the provenance of a symbol.

Enumerator
unconfigured	The symbol is not configured.
global	The symbol is globally configured by a commandline option.
transient	The symbol is transiently configured by an in-source directive.

Definition at line 64 of file symbol.h.

enum symbol::pseudo_snapshot

strongprivate

Pseudo snapshot numbers for symbols in indeterminate states.

Enumerator
pristine	Symbol has merely be constructed.
define_in_progress	Symbol is in the process of being defined.
undef_in_progress	Symbol is in the process of being undefined.
infinite	References of the symbol are by definition insoluble.

Definition at line 438 of file symbol.h.

Constructor & Destructor Documentation

symbol::symbol ( provenance source )

inlineexplicitprivate

Explicitly construct given a provenance.

Parameters

source The provenance of the symbol to construct.

Definition at line 579 of file symbol.h.

Member Function Documentation

static bool symbol::add_pattern ( std::string const & pattern )

inlinestaticprivate

Add a symbol name pattern for reporting.

Parameters

pattern A symbol name pattern to select symbols for reporting

If pattern terminates with '*' then any symbol that initially matches the preceding portion of pattern will be reported.

Returns: True if the pattern was added, false if it was already present.

Definition at line 542 of file symbol.h.

void symbol::define	(	std::string const &	defn,
		formal_parameter_list const &	params
	)

Define symbol.

Parameters

defn	The definition of the symbol
params	The parameter list of the symbol

The symbol is assigned the new definition and parameter list, the resulting expansion and evaluation are resolved and cached and the symbol is left dirty, i.e. other cached references of this symbol become invalid.

void symbol::digest_global_define ( chewer< std::string > & chew )

Analyse and handle a -D option for this symbol.

Parameters

chew On entry, a chewer<std::string> positioned at the offset in the associated string from which to scan for a commandline definition. On return chew is positioned at the first offset not consumed. The commandline option is of the form -DSYM[(PARMS)[=VAL] or --define SYM[(PARMS)][=VAL] and chew shall finish just past SYM.

The commandline option is analysed for well-formedness, consistency and non-redundancy in the current configuration. Errors are diagnosed. If there are none the global configuration is updated if required.

void symbol::digest_global_undef ( chewer< std::string > & chew )

Analyse and handle a -U option for this symbol.

Parameters

chew	On entry, a `chewer<std::string>` positioned at the text offset from which to scan for a commabndline un-define. On return `chew` is positioned at the the first offset not consumed. The commandline option is of the form `-USYM` and `chew` shall finish just past `SYM`.

The option is analysed for well-formedness, consistency and non-redundancy in the current configuration. Errors are diagnosed. If there are none the global configuration is updated if required.

line_type symbol::digest_transient_define	(	formal_parameter_list const &	params,
		std::string const &	definition
	)

Analyse and handle an in-source define directive for this symbol.

Parameters

params	The macro parameter list of the symbol.
definition	The proposed definition of the symbol.

Returns: A line_type determined by the analysis, denoting the action to be taken on the directive.

The proposed defintion is analysed for consistency and non-redundancy in the current configuration. Errors are diagnosed. If there are none the transient configuration is updated if required.

line_type symbol::digest_transient_undef ( )

Analyse and handle an in-source undef directive for this symbol.

Returns: A line_type denoting the action to be taken with the directive.

The directive is analysed for well-formedness and for consistency non-redundancy in the current configuration. Errors that are diagnosed. If there are none the transient configuration is updated if required.

template<class CharSeq >

static locator symbol::find_any_in	(	chewer< CharSeq > &	chew,
		size_t &	off
	)

static

Search a terminal portion of a CharSeq for any known symbol name.

Search a terminal portion of a parse_buffer to find the first syntactic occurrence of the name of any symbol in the symbol table.

Template Parameters

CharSeq A charcter-sequence type.

Parameters

chew	On entry, a `chewer<CharSeq>` positioned at the offset in the associated `CharSeq` from which to scan. On return `chew` is positioned just passed the first occurrence found of he name of any known symbol, or at the end of the `CharSeq` if none.
off	On return, receives the offset in the `CharSeq` of the first known symbol name detected, if any, else is unchanged.

Returns: The locator of the known symbol detected, if any, else the null locator.

std::shared_ptr<parameter_substitution::format const> symbol::format ( ) const

inline

Get a pointer to the symbol's substitution format; null if none.

Returns

A pointer to the substitution format of this symbol, if any, else null.

The substitution format is coan's internal representation of the
manner in which macro arguments are to be interpolated into the
symbol's definition, if any.

Definition at line 208 of file symbol.h.

static symbol_table::iterator symbol::insert	(	std::string const &	id,
		provenance	source,
		symbol_table::iterator	hint = `table().end()`
	)

inlinestaticprivate

Insert the symbol into the symbol table with a specified provenance.

Parameters

id	The name of the symbol to insert.
source	The `provenance` of the symbol.
hint	An iterator that is an upper bound hint to the insertion position.

Returns: An iterator to the inserted symbol.

Definition at line 564 of file symbol.h.

bool symbol::invoked ( ) const

inline

Say whether the symbol has been invoked.

Returns: True iff the symbol has been invoked.

I.e. has a reference to the symbol been encountered.

Definition at line 274 of file symbol.h.

static locator symbol::lookup ( std::string const & id )

inlinestatic

Lookup an identifier in the symbol table.

Parameters

id	The identfier to be sought.

Returns: A locator. If no symbol named id is found then the mull locator is returned.

Definition at line 396 of file symbol.h.

static void symbol::set_selection ( char const * optarg )

static

brief Set the list of symbol masks for symbol reporting, as specified by the --select option.

Parameters

optarg The argument of the --select option

std::string symbol::signature ( ) const

inline

Get the symbol's reference signature as string.

Returns: The symbol name suffixed with its formal parameter list, if any.

Definition at line 306 of file symbol.h.

void symbol::subscribe ( )

private

Acquire all the symbol's contributors.

The symbol discovers all other symbols that contribute to its definition.

Member Data Documentation

std::vector<symbol::locator> symbol::_contributors

private

List of locators of the symbols that appear in the definition of this symbol

Definition at line 612 of file symbol.h.

std::shared_ptr<parameter_substitution::format> symbol::_format

private

Pointer to the parameter substitution format of the symbol, null if none.

Definition at line 603 of file symbol.h.

std::vector<bool> symbol::_no_expand_pararms

private

Boolean vector flagging the parameters whose arguments shall not be macro expanded because theya are subject to token ops.

Definition at line 618 of file symbol.h.

int symbol::_snapshot

mutableprivate

Sequential snapshot number of this symbol. Is set = the global sequential snapshot counter each time a reference of the symbol is resolved.

Definition at line 608 of file symbol.h.

The documentation for this struct was generated from the following file:

symbol.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation