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 communicate special instructions or tasks to SQL Explorer in a repeatable, scriptable manner; for example, you can:

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 single line comments (--) a single space is allowed between the "--" and the "${" because some database systems require a space after "--" to detect it as a single line comment. For example:

/*${define mymacro} 12345*/
--${define mymacro2} 12345
-- ${define mymacro3} 12345

Correct
/*  ${define mymacro} */
--   ${define mymacro2} 12345
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}