| Debugging Primitives | |
| Macros | |
| abort | Abnormal process. |
| debug | Control runtime debug and tracing. |
| debug_support | Internal debugger functionality. |
| dprintf | Formatted diagnostics output. |
| error | Issue an error message on the command line. |
| inq_debug | Retrieve the current debug setting. |
| message | Display a message on the command line. |
| pause_on_error | Set the error display mode. |
| pause_on_message | Set the message display mode. |
| printf | Print formatted string to stdout. |
| profile | Profiling support. |
| watch | Watch a symbol. |
int debug( [int flags|string flags|NULL], [int echo = TRUE] )
Control runtime debug and tracing.
The debug() primitive enables and disables run-time tracing of macros and system acts to the diagnostics log. The new debug flags shall be set to flags.
If flags is omitted, then the current trace mode is toggled from off to DB_TRACE(1) and from on to off.
Otherwise by specifying flags the associated events which shall be traced during subsequent macro operations. Flags can either be one or more DB_XXX constants OR’ed together or string containing a comma seperated list of flag names, see the table below. If the given flag value is either 0 or an empty string, all trace operations are disabled.
The echo flags controls whether the user is informed of the debug state change. When omitted or a non-zero any changes are echoed on the command prompt, informing the user of the new debug status, otherwise the macro is silent.
The following debug flags are available, enabling tracing of both general and specific macro operations:
| Constant |
Name |
Description |
|---|---|---|
| DB_TRACE |
trace |
General trace. |
| DB_REGEXP |
regexp |
Regular expression compilation and execution. |
| DB_UNDO |
undo |
Undo/red trace. |
| DB_FLUSH |
flush |
Flush output, shall cause the trace log to be flushed on each write; use should be avoided unless catching crash conditions due to associated high cost. |
| DB_TIME |
time |
Time stamp which trace log. |
| DB_TERMINAL |
terminal |
Terminal interface. |
| DB_VFS |
vfs |
Virtual file-system. |
| DB_NOTRAP |
notrap |
Disable SIGBUS/SIGSEGV trap handling. |
| DB_MEMORY |
memory |
Target specific debug memory service |
| DB_REFS |
refs |
Variable references. |
| DB_PROMPT |
prompt |
Command prompting. |
| DB_PURIFY |
purify |
Running under a memory analysis tool; |
| DB_HISTORY |
history |
Command history. |
Command lines Options;
The following command option also effect the generation of diagnostics trace.
| -d,--log | Enable trace (DB_TRACE) |
| -f,--flush | Enable log flushing (DB_FLUSH). |
| --nosig | Disable signal traps (DB_NOSIG). |
| -P,--dflags=x | Debug/profiling flags x, being a comma separated list of flag names, as defined above. |
| --rtc | Enable real-time memory checks, if available. |
| --native | Enable native memory allocator, if suitable. |
The default name of the diagnostics log is system dependent
| .grief.log | Unix and Unix systems, including Linux. |
| grief.log | WIN32 and DOS based systems. |
| GRIEF_LOG | If the GRIEF_LOG variable exists within the environment then it overrides the default trace log name. |
The debug() primitive returns the value of the debug flags prior to any changes, allowing the caller to restore later.
Enable debug, invoke our macro for testing and then restore the previous flags.
int odebug = debug(1, FALSE);
myfunction();
debug(odebug, FALSE):
The echo option is a GriefEdit extensions.
void debug_support( int what, declare object, declare arg )
Internal debugger functionality.
The debug_support() primitive supports GRIEF debug functions.
The primitive is a switcher to the actual sub-functions based upon what, the arguments object and arg are what specific.
nothing
int dprintf( string format, ... )
Formatted diagnostics output.
This primitive is used to write a diagnostic messages to the trace log when debug is enabled.
The dprintf() primitive produces formatted output according to the format specification format into the diagnostics log. The trailing arguments ... are the integer, string or list expressions used to satisfy the % formatting options; refer to (See: message) for details on the supported format specifications.
The format primitive is similar to the C fprintf() primitive, exporting the formatted result to an external stream.
This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.
| format | String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested. |
| ... | Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive. |
The dprintf() primitive returns the number of charaters stored within the result string buffer.
This is a GriefEdit extension.
int error( string format, ... )
Issue an error message on the command line.
The error() primitive is used to display a message on the prompt line at the bottom of the screen. format is a string and may contain printf-like % formatting characters. The following arguments format and so forth are integer or string expressions used to satisfy the % formatting options.
This primitive may be used to error messages on the bottom of the screen; if informational messages are required to be displayed then the message primitive macro should be used instead.
Error messages are printed in the error color (See: color) and truncated if they are too long.
In addition, upon enabling pause_on_error then the error message is displayed suffixed with a .. and GriefEdit waits for the user to type any key to continue; useful during debugging.
This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.
| format | String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested. |
| ... | Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive. |
The message() primitive returns the number of characters printed.
message("File: %s", current_name);Many of the format options are GriefEdit extensions, including %b, %n, %t, %B and * support.
The original implementation has a void declaration and returns nothing.
The standard interface only permits upto 6 arguments, whereas GriefEdit is unbound.
int inq_debug()
Retrieve the current debug setting.
The inq_debug() primitive retrieves the current debug flags.
The inq_debug() primitive returns an integer representing the debug flags which are currently in effect.
Enable debug of regular expressions, invoke our macro for testing and then restore the previous flags.
int odebug = inq_debug();
debug(odebug | DB_REGEXP, FALSE);
myfunction();
debug(odebug, FALSE):
int message( string format, ... )
Display a message on the command line.
The message() primitive is used to display a message on the prompt line at the bottom of the screen. format is a string and may contain printf-like % formatting characters. The following arguments format and so forth are integer or string expressions used to satisfy the % formatting options.
This primitive may be used to display informational messages on the bottom of the screen; if error messages are to be displayed then the error primitive macro should be used instead.
| format | String that contains the text to be written. It can optionally contain an embedded <Format Specification> that are replaced by the values specified in subsequent additional arguments and formatted as requested. |
| ... | Optional format specific arguments, depending on the format string, the primitive may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string. There should be at least as many of these arguments as the number of values specified in the format specifiers. Additional arguments are ignored by the primitive. |
A format specification, which consists of optional and required fields, has the following form:
%[FLAGS] [WIDTH] [.PRECISION] [PREFIXES] type
Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign is followed by a character that has no meaning as a format field, the character is simply copied. For example, to print a percent-sign character, use %%.
The optional fields, which appear before the type character, control other aspects of the formatting, as follows:
| type | Required character that determines whether the associated argument is interpreted as a character, a string, or a number. |
| flags | Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification. |
| width | Optional number that specifies the minimum number of characters output. |
| precision | Optional number that specifies the maximum number of characters printed for all or part of the output field, or the minimum number of digits printed for integer values. |
The following format types are supported;
| Type |
Description |
|---|---|
| %d |
Print an integer expression. Options such as %03d can be used to perform zero insertion and supply a field width. |
| %i |
Print an integer expression, same as %d. |
| %u |
Print an unsigned expression. |
| %x |
Print integer expression in hex. |
| %t |
Print using the symbol natural type (ie d = integers and s = strings). |
| %o |
Print integer expression in octal. |
| %s |
Print a string. Field width and alignments are allowed. |
| %c |
Print a character. |
| %p |
If its less than a second since the last call to message (or error), then don’t display the message. This is used by macros which want to print progress messages. |
| %e |
Double signed value having the form [-]d.dddd e[sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or. |
| %E |
Double identical to the e format except that E rather than e introduces the exponent. |
| %f |
Double signed value having the form [ ]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision. |
| %g |
Double signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than 4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it. |
| %G |
Double identical to the g format, except that E, rather than e, introduces the exponent (where appropriate). |
| %n |
Number of characters successfully written so far to the stream or buffer; this value is stored in the integer variable given as the argument. |
| %b |
Print integer expression in binary. |
| %B |
Print integer expression as a decoded binary, using the bit values as described within the secondary string parameter of the form;<base><arg>Where <base> is the output base expressed as a control character, e.g. \10 gives octal; \20 gives hex. Each arg is a sequence of characters, the first of which gives the bit number to be inspected (origin 1), and the next characters (up to a control character, i.e. a character <= 32), give the name of the register. Thus: |
The following flags are supported.
| Flag |
Description |
Default |
|---|---|---|
| - |
Left align the result within the given field width. |
Right align. |
| + |
Prefix the output value with a sign (+ or -) if the output value is of a signed type. |
Sign appears only for negative signed values (). |
| 0 |
If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored. |
No padding. |
| <space> |
Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear. |
No blank appears. |
| # |
When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively. When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases. When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. Ignored when used with c, d, i, u, or s. |
No blank appears. Decimal point appears only if digits follow it. Decimal point appears only if digits follow it. Trailing zeros are truncated. |
The following prefixes are supported.
| Prefix |
Description |
|---|---|
| l |
User long format for printing, e.g. floats are printed with full double-precision. |
The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values depending on whether the flag (for left alignment) is specified until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).
width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification).
If the width specification is an asterisk (*), an int argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. A nonexistent or small field width does not cause the truncation of a field; if the result of a conversion is wider than the field width, the field expands to contain the conversion result.
The third optional field of the format specification is the precision specification. It specifies a nonnegative decimal integer, preceded by a period (.), which specifies the number of characters to be printed, the number of decimal places, or the number of significant digits. Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. If precision is specified as 0 and the value to be converted is 0, the result is no characters output, as shown below:
"%.0d", 0 // characters output
If the precision specification is an asterisk (*), an int argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list.
The type determines the interpretation of precision and the default when precision is omitted, as shown in the following table.
| Type |
Description |
Default |
|---|---|---|
| c,C |
Character is printed. |
|
| d,i,u,o,x,X |
Minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. |
Default precision is 1. |
| e,E |
Number of digits to be printed after the decimal point. The last printed digit is rounded. |
Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed. |
| f |
Number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. |
Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed. |
| g,G |
Maximum number of significant digits printed. |
Six significant digits are printed, with any trailing zeros truncated. |
| s |
Maximum number of characters to be printed. |
Characters in excess of precision are not printed. Characters are printed until EOS is encountered. |
message("See %s %s.", "spot", "run");message("%pMacro completed: %d%%", (val*100)/total);message("val=%B", 3, "\\10\\2BITTWO\\1BITONE\\n")shall produce the output.
val=3<BITTWO,BITONE>
The message() primitive returns the number of characters printed.
Many of the format options are GriefEdit extensions, including %b, %n, %t, %B and * support.
The original implementation has a void declaration and returns nothing.
The standard interface only permits upto 6 arguments, whereas GriefEdit is unbound.
CRisPEdit™ allows the second argument to be a list expression, which emulates a vsprintf() style of operation. In this case, the first element of the list is assumed to be a string format descriptor, and subsequent elements of the list are the arguments to print; this feature is not currently supported.
int pause_on_error( [int pause = NULL], [int echo = TRUE] )
Set the error display mode.
The pause_on_error() primitive controls the automatic pausing upon a macro error; by default the pause status is off.
On the execution of the error primitive plus the internal equivalent, the pause status is checked and when enabled error messages shall be displayed with a .. suffix and GriefEdit shall await for the user to acknowledge the condition via a key-press before execution continues.
If pause is specified as a non-negative (>= 0) then the current setting is set to the pause value of the integer expression, whereas a negative value (-1) behaves like a inquiry primitive reporting the current value without change. Otherwise if omitted the current status is toggled.
Unless echo is stated as FALSE, upon modification of the pause state, the new status shall be echoed on the command as follows
Pausing errors on.
or
Pausing errors off.
| pause | Optional int flag, when a non-negative value (>=0) it states the new pause status, a negative value (-1) reports the current value without change, otherwise if omitted the current pause state is toggled. |
| echo | Optional int flag, when stated as FALSE the function is silent, otherwise the change in the pause state is echoed on the command prompt. |
The pause_on_error function returns the previous pause state.
echo is a GriefEdit extension.
The following examples enables error acknowledgement during the execution of the macro subshell() and restores the previous status on completion.
int state = pause_on_error(TRUE);
subshell();
pause_on_error(status, FALSE);
int pause_on_message( [int pause = NULL], [int echo = TRUE] )
Set the message display mode.
The pause_on_message() primitive controls the automatic pausing upon a macro message; by default the pause status is off.
On the execution of the message primitive plus the internal equivalent, the pause status is checked and when enabled error messages shall be displayed with a .. suffix and Grief shall await for the user to acknowledge the condition via a key-press before execution continues.
If pause is specified as a non-negative (>= 0) then the current setting is set to the pause value of the integer expression, whereas a negative value (-1) behaves like a inquiry primitive reporting the current value without change. Otherwise if omitted the current status is toggled.
Unless echo is stated as FALSE, upon modification of the pause state, the new status shall be echoed on the command as follows
Pausing all messages on.
or
Pausing all messages off.
| pause | Optional int flag, when a non-negative value (>=0) it states the new pause status, a negative value (-1) reports the current value without change, otherwise if omitted the current pause state is toggled. |
| echo | Optional int flag, when stated as FALSE the function is silent, otherwise the change in the pause state is echoed on the command prompt. |
The pause_on_message function returns the previous pause state.
echo is a GriefEdit extension.
The following examples enables error acknowledgement during the execution of the macro subshell() and restores the previous status on completion.
int state = pause_on_message(TRUE);
subshell();
pause_on_message(status, FALSE);
void printf( string format, ... )
Print formatted string to stdout.
The printf() primitive can be used for debugging macros, although its use is questionable. It exists for compatibility reasons with BRIEF. It causes the formatted string to be sent directly to stdout, bypassing all of Griefs internal screen manipulations.
The format primitive is similar to the C printf() primitive, exporting the formatted result to stdout. Use of this interface is debatable as output is written to standard out, which is also the primary interface to the terminal/display.
The printf() primitive produces formatted output according to the format specification format into the diagnostics log. The trailing arguments ... are the integer, string or list expressions used to satisfy the % formatting options; refer to (See: message) for details on the supported format specifications.
This function is one of a set of formatted output primitives each supporting a common feature set, see message for a complete discussion on the supported format specification syntax.
| format | String containing the <Format Specification>. |
| ... | Optional list of arguments which should correspond to the values required to satisfy the format specification. |
nothing
The standard function has a void declaration and returns nothing.
To send feedback on this topic email: griefedit@gmail.com
Copyright © Adam Young All Rights Reserved.
Abnormal process.
void abort()
Control runtime debug and tracing.
int debug( [int flags|string flags|NULL], [int echo = TRUE] )
Internal debugger functionality.
void debug_support( int what, declare object, declare arg )
Formatted diagnostics output.
int dprintf( string format, ... )
Issue an error message on the command line.
int error( string format, ... )
Retrieve the current debug setting.
int inq_debug()
Display a message on the command line.
int message( string format, ... )
Set the error display mode.
int pause_on_error( [int pause = NULL], [int echo = TRUE] )
Set the message display mode.
int pause_on_message( [int pause = NULL], [int echo = TRUE] )
Print formatted string to stdout.
void printf( string format, ... )
Profiling support.
void profile( [int flags] )
Watch a symbol.
void watch( string symbol )
Exit current process level.
void exit( [string y_or_w] )
Invoke a Grief engine.
void process()
Set the basic colors.
int color( [int background], [int normal], [int selected], [int message], [int error], [int hilite], [int hilite_fg], ... )
Formatted printing to a string.
int sprintf( string & buffer, string format, ... )