Crystal Space: csVerbosityParser Class Reference (Crystal Space Public API Reference)

| ## Public API Reference

- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# 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