Public API Reference

csVerbosityParser Class Reference

Utility for parsing verbosity flags such as those provided by the --verbose=flags command-line option. More...

#include <csutil/verbosity.h>

List of all members.

Public Member Functions
bool	CheckFlag (char const *major, char const *minor) const
	Given major and minor components, check if the verbosity class "major.minor" is enabled.
	csVerbosityParser (csVerbosityParser const &v)
	Copy constructor.
	csVerbosityParser (char const *flags=0)
	Construct the verbosity flag parser.
bool	Enabled (char const *flag=0, bool fuzzy=true) const
	Check if verbosity should be enabled for a particular flag.
csVerbosityParser &	operator= (csVerbosityParser const &v)
	Assignment operator.
void	Parse (char const *flags)
	Parse additional verbosity flags.
	~csVerbosityParser ()
	Destructor.

---

Detailed Description

Utility for parsing verbosity flags such as those provided by the --verbose=flags command-line option.

The general format of a verbosity flag is an optional + or - followed by a period-delimited name, such as foo.bar.baz. Multiple flags can be specified, separated by commas. The + and - tokens indicate whether the verbosity class should be enabled or disabled. If neither is specified, then + is assumed. The flags argument given to the csVerbosityManager constructor and the Parse() method is the text following the equal sign in the command-line --verbose=flags option; it should not include the literal "<tt>--verbose=</tt>".

Period-delimited verbosity names form a sort of parent/child relationship hierarchy which makes it possible to specify both coarse- and fine-grained verbosity settings easily. When the Enabled() method tests if a verbosity class is enabled, it first checks the most specific child flag. If no such flag is found, it tries a less specific option by backing up to the child's parent. If that fails, it attempts the grandparent, and so on. For example, given the command-line verbosity setting `-foo,+foo.bar', if client code invokes Enabled("foo.bar.baz"), it will first look for foo.bar.baz. When that fails to produce a result, it will look for foo.bar, which will succeed, reporting that verbosity is enabled for foo.bar.baz on account of the explicit +foo.bar from the command-line. Thus, though not specified explicitly, foo.bar.baz implicitly inherits the setting of its parent foo.bar. Likewise, Enabled("foo.beep.bop") will attempt, in order, foo.beep.bop, then foo.beep, and ultimately foo, which finally succeeds, reporting that verbosity is disabled for foo.beep.bop on account of the -foo from the command-line.

If an invocation of Enabled() is unable to find any matching verbosity class, even after traveling up the inheritance hierarchy, it instead reports the global verbosity setting. The global verbosity setting is derived inversely from the very first verbosity specification seen by the constructor or by Parse(). If the first verbosity flag is `true' (via the optional +), then the global verbosity setting is `false'. Conversely, if the first verbosity flag is `false' (via -), then the global setting is `true'. The upshot of this heuristic is that command-line verbosity settings work in an intuitive fashion. For instance, --verbose=scf (or +scf) enables verbosity for only the `scf' module and disables it for all other modules. Likewise, --verbose=-scf enables verbosity for all modules except `scf'.

If only the empty-string "" is passed to the constructor or Parse(), then Enabled() returns `true' for all queries. This gives the intuitive interpretation to a bare --verbose without any flags, which means to enable verbosity for all modules. If only a null is passed to the constructor or Parse(), then Enabled() returns `false' for all queries. This is interpreted intuitively as meaning that no modules should be verbose in the absence of --verbose on the command-line.

Examples:

• --verbose Enables verbosity for all modules.
• --verbose=scf,vfs Enables verbosity for only `scf' and `vfs'.
• --verbose=-scf,-vfs Enables verbosity for all modules except `scf' and `vfs'.
• --verbose=+scf.register.class Enables verbosity for only `scf.register.class'.
• --verbose=+scf,-scf.register,+scf.register.class Enables verbosity for only `scf' and its children except `scf.register' or any of its children other than `scf.register.class which is explicitly enabled.

See also:

csVerbosityManager

csCheckVerbosity

csParseVerbosity;

iVerbosityManager

Definition at line 103 of file verbosity.h.

---

Constructor & Destructor Documentation

csVerbosityParser::csVerbosityParser

(

char const *

flags = 0

)

Construct the verbosity flag parser.

Parameters:

flags

The verbosity flags; usually the text following the equal sign in the command-line `--verbose=flags option.

Remarks:

If flags is the empty (zero-length) string "", then all Enabled() queries return true. This is the intuitive interpretation of a bare --verbose option without any explicit flags specification. If flags is a null pointer, then all Enabled() queries return false. This is the intuitive interpretation of the absence of --verbose on the command-line.

See the class description for detailed information regarding the interpretation of flags.

csVerbosityParser::csVerbosityParser

(

csVerbosityParser const &

v

)

[inline]

Copy constructor.

Definition at line 139 of file verbosity.h.

csVerbosityParser::~csVerbosityParser

(

)

[inline]

Destructor.

Definition at line 144 of file verbosity.h.

---

Member Function Documentation

bool csVerbosityParser::CheckFlag	(	char const *	major,
		char const *	minor
	)			const [inline]

Given major and minor components, check if the verbosity class "major.minor" is enabled.

Deprecated:

Use instead the more generic Enabled() method, which accepts any granularity of class breakdown; not just major and minor components.

Definition at line 193 of file verbosity.h.

bool csVerbosityParser::Enabled	(	char const *	flag = 0,
		bool	fuzzy = true
	)			const

Check if verbosity should be enabled for a particular flag.

Parameters:

	flag	The flag for which verboseness should be queried. If flag is a null pointer, then the global verbosity setting is queried. Such coarse-grained checking is not typically desired, though it may be useful in the unlikely event of a module needing to know if verbosity is enabled for any other (unspecified) modules.
	fuzzy	When true, if there is no exact match for flag, then also travel up the inheritance chain, checking the parent, grandparent, etc. This is the normal, desired behavior, and is the default setting. There may be special cases, however, when traversing the inheritance chain should be avoided, and an explicit match of flag is warranted. For example, a module may want to provide a way to emit low-level debugging messages when requested explicitly, but not normally emit them when a general --verbose is in effect. In such cases, setting fuzzy to false would be appropriate.

Remarks:

See the class description for detailed information regarding the interpretation of flag.

csVerbosityParser& csVerbosityParser::operator=

(

csVerbosityParser const &

v

)

[inline]

Assignment operator.

Definition at line 149 of file verbosity.h.

void csVerbosityParser::Parse

(

char const *

flags

)

Parse additional verbosity flags.

Parameters:

flags

The verbosity flags; usually the text following the equal sign in the command-line `--verbose=flags option.

Remarks:

This method is useful if additional flags need to be parsed after construction time.

See the class description for detailed information regarding the interpretation of flags.

---

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

• csutil/verbosity.h

---