Post History

Source: https://writers.stackexchange.com/q/28978
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

We use a BNF style to convey syntax for SQL statements. For a (fictitious) example:

    CREATE PARSER [schema.]function  
    [WITH [LANGUAGE='language']  
        [, MODE='[FENCED | UNFENCED]'  
        [, STUFF='anotherParameter']  
    ];

This means that you must specify a function name (with optional schema), and you may specify zero, one, two, or three other parameters. (Some of our statements have ten or more optional parameters.) This is the style we've been using for a while.

Strictly speaking, though, it's incorrect -- if you omitted LANGUAGE but wanted to specify MODE, this would tell you to write something like:

    CREATE PARSER myFunctionName
    WITH , MODE='FENCED';

...which isn't correct. That comma is a syntax error. Most readers can figure out what's meant, but it's a bit of s stumbling block for some.

Some of our super-precision-minded users have pointed out this problem, but they (and we) have not found a solution that preserves the overall style. Our users like the notation overall; it's just that we don't know what to do when everything in a clause can be optional. We considered something like this, but it's technically wrong in a different way as well as being ugly:

    CREATE PARSER [schema.]function
    [WITH [LANGUAGE='language']
      [,] [MODE='[FENCED | UNFENCED]'
      [,] [STUFF='anotherParameter']
    ];

After the syntax synopsis we include a table of parameters and arguments (name, description). We're therefore considering reducing the syntax synopsis to something like this:

    CREATE PARSER [schema.]function
    [WITH parameters];

We haven't tried that idea out on our users yet. Before we do, I'd like to find out about other options for presenting syntax information in an _informative_ and _correct_ way. We're not the first people to use this style of syntax but I haven't found examples of this situation to look at. What do others do?

Original score: 4