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');