This procedure proivdes a mechanism to report messages of various priorities within programs. A message is passed to verbiage, along with the message's priority and the maximum priority to report. If the message priority is equal to or less than the required report priority, the message is printed to the terminal. Otherwise, the program exits quietly.
For example, consider the following program: pro talk, verbose = verbose verbiage, 'report level is 1', 1, verbose verbiage, 'report level is 2', 2, verbose end
This program would produce the following messages: IDL> talk, verbose = 0 [nothing happens] IDL> talk, verbose = 1 'report level is 1' IDL> talk, verbose = 2 'report level is 1' 'report level is 2' IDL> talk [nothing happens]
Note that, in the last case, verbiage handles the case where 'verbose' is undefined. This is nice, since keywords like 'verbose' are usually optional.
The program is designed to facilitate a hierarchy of messages, which the user can switch between. For example, verboose = 0 will turn off all messages for running in batch mode. verbose = 4 might produce very detailed output for debugging purposes.
When using verbiage in programs, I recommend the following hierarchy for message priorities: 0: No messages have priority of 0 1: Messages indicate program failure 2: Messages tersely summarize program results 3: Detailed summary / progress report of a program 4: Debugging messages
The message is printed if report_lvl >= msg_lvl
- msg in required
The message to (perhaps) print
- msg_lvl in required
The priority of the message (see the recommendation above)
- report_lvl in required
The maximum priority to report. This is usually provided by the end user, through a keyword like verbose. The program gracefully handles the case where report_lvl is missing. This means that, if report_lvl is passed a value of a user defined keyword (like verbose, for example), you don't need to check to make sure that keyword was defined.
June 2009: Written by Chris Beaumont December 2009: Messages are indented proportional to the calling function's depth in the stack. April 2010: Fixed a bug that crashed verbiage if help, /trace overflows onto multiple lines
|Modifcation date:||Tue Apr 20 15:33:19 2010|