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.

Constructor & Destructor Documentation

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.

Member Function Documentation

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.