CBOLD Reference: auto

Coolquest, Inc.

C⁺⁺BOLD Reference Manual

<<< Previous

CBOLD Reference Home

Next >>>

11.2. auto_reg

11.2.1. Overview

The auto_reg Support Tool is not part of the CBOLD framework. It is an independent executable. Its use is optional. The auto_reg executable can be downloaded without charge, subject to licensing terms.

The auto_reg Support Tool automates coding of the Register() function. A designer typically must register each member of every TModule and TBundle in a CBOLD design. By automating this sometimes tedious task, auto_reg saves the designer time and also makes the design more readable and more maintainable.

The designer must provide an empy Register() declaration in each module to be auto registered:

class TMyModule : public TModule {
  ...
  virtual void Register {
  }  // the closing brace must be on a separate line
};

Although auto_reg is a console application, some IDE's allow the user to invoke auto_reg directly from the IDE. In this case, the IDE passes to auto_reg the name of the file currently appearing in the IDE's editor window, and auto_reg modifies this file's contents as necessary in order to register members of TModule and TBundle.

For convenience to the designer, auto_reg can operate in-place, i.e., its source file can also be its destination file. A designer may naturally see this as a risk to his source code, but auto_reg contains features intended to minimize this risk. For example, auto_reg operates line-by-line, only discarding lines that it identifies as having been inserted by auto_reg in a previous run. The discarded lines must:

a. be within the body of a class member function declared as virtual void Register(), and

b. end with the tag comment: // auto_reg

Likewise, auto_reg only inserts lines:

a. within the body of a class member function declared as virtual void Register(), and

b. ending with the tag comment: // auto_reg

The lines inserted by auto_reg will always follow any user lines within Register(). I.e., the designer may still place code within Register() as long as the lines do not end with the tag comment.

auto_reg is invoked at the console as follows:

autoreg srce_file [dest_file] [-wpur]
    -w = suppress warnings
    -p = prompt user to press a key if any error or warnings
    -u = unconditional write of destination file, even if it is unchanged
    -r = remove backup file, if any, upon successful completion

srce_file is the path to the source (user C++ design) file, including any extension (e.g., .h).

dest_file is the path to the destination (C++ design) file, including any extension (e.g., .h). If dest_file is omitted then the source file will also be the destination file.

If auto_reg detects any errors, the destination file will not be written.

A usage note is output to the console if auto_reg is invoked without any command-line arguments.

Flags:

Flag	Function
-w	Suppresses warning message output to the console.
-p	If there was an error or any warnings, prompts the user to press a key before exiting.
-u	Causes the destination file to be overwritten even if doing so does not change its contents. In other words, if -u is omitted, and the destination file already exists, its timestamp is changed only if its contents change.
-r	Causes the backup file to be removed after auto_reg has determined that it has successfully written the destination file. See backup file note below.

Backup File Note: A backup of the source file is created if:

a. dest_file is omitted or dest_file equals srce_file, and

b. auto_reg encounters no errors.

The backup file name is the same as the source file name, except an underscore is inserted at the beginning of the file extension. E.g., MyFile.h becomes Myfile._h.

The backup file will be removed by auto_reg if the -r flag is included on the command line and auto_reg has successfully written the entire destination file.

Because the backup file name depends only upon the source file name, any existing backup file will be overwritten if auto_reg is called repeatedly with the same arguments.