Structured Comments
Structured Comments are an extension to your SQL programming
which is
unique to SQL Explorer. By adding specially formatted
comments to your code you can instruct SQL Explorer to perform
additional tasks, such as conditional compilation and macro expansion.
The design of Structured Comments is such that using these
extensions,
while specific to SQL Explorer, will not make your code incompatible
with other tools (including those that came out-of-the-box with your
database product). This is because the commands are embeded
inside specially formatted comments which (because they are comments)
will be ignored by other products. The commands allow you to
define defaults and alternatives so that when your script is executed
by another tool they can have a sensible default behaviour, and it's
only when SQL Explorer runs them that they have special meaning.
Structured Comment Syntax
A Structured Comment consists of "${" at the very start
of a comment - no spaces should appear between the comment start and
the "${". For example:
/*${define
mymacro} 12345*/ |
Correct |
/* ${define mymacro} */ |
Incorrect |
Once SQL Explorer has identified a comment as a Structured Comment, it
then looks for a command and parameters in the following form:
${ command [parameter [parameter [...]] } [data]
I.E., the "${" at the start of the comment, followed by a
command, zero or more parameters, and then a "}"; after this
can optionally come some arbitrary data - we'll see how this can be
used later.
In the example above, the command is "define", it is given a parameter
of "mymacro", and has "12345" as the data; it's not hard to
guess that this Structured Comment defines a macro named "mymacro" and
sets it's value to "12345"!
Inline vs. Grouped Commands
Most Structured Comment commands are inline, which is to say that they
exist in a single comment; however, some commands span several
comments, similar to begin...end constructs in programming languages
(called a Grouped command). Typically, whether a command is
inline or grouped depends on how you use it; for example, the ifdef command is an inline command if you provide non-whitespace after the "}" but grouped if not. For example:
--${ifdef DEBUG} this is an inline ifdef
--$(ifdef !DEBUG}
this is a grouped ifdef
--${endif}
Commands
${define macro-name} [value]
Defines a macro called "macro-name" and assigns it the value "value";
"value" is optional and if not present an empty string is assigned.
For example:
--+${define DEBUG} true
defines a macro called DEBUG and sets its value to" true".
${undef macro-name}
Removes a macro definition and discards the value.
For example:
--+${undef DEBUG}
${ifdef [!]macro-name} [data]
Conditionally executes code if macro-name is defined; if the exclamation mark is included before the macro-name then the code will only be executed if the macro-name is not defined. If data is given, then the ifdef command is an inline command, otherwise it becomes a grouped command and must be paired with a corresponding endif.
--${ifdef DEBUG} this is an inline ifdef
--$(ifdef DEBUG}
this is a grouped ifdef
--${endif}
In this example, if the macro DEBUG is defined then the code output by SQL Explorer will be:
this is an inline ifdef
this is a grouped ifdef
${else} [data]
Counterpart to a grouped ifdef command; if data
is provided then it is an inline command, otherwise it is a grouped
command that must be paired with a corresponding endif. For
example:
--$(ifdef DEBUG}
in debug mode
--${else}
not in debug mode
--${endif}
${endif}
Closes a grouped ifdef.
${ref macro-name} [data]
This comment is replaced with the value of the macro identified by macro-name; if the macro does not exist then the optional data is used instead. If followed by an endref and data is not provided then the value between the ref and endref is used if the macro macro-name is not defined. For example:
--${define mymacro} hello world
--${ref mymacro} test
--${ref anothermacro} my default value
--${ref somethingelse}
this is
a longer
alternative
--${endref}
will produce:
hello world
my default value
this is
a longer
alternative
${endref}
Completes a grouped ref command.
Tips & Tricks
The principal purpose of the conditional compilation features in
Structured Comments is to enable debug-mode code which is invisible if
a standard deployment tool is used.
--${define DEBUG} true
--${ifdef DEBUG} log('some state info');