In a formal syntax notation, how should I indicate many optional elements?
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?
1 answer
The problem here is that you are conflating two separate things: the syntax for parameters in a function expression and the list of available parameters. The syntax itself is straightforward enough:
CREATE PARSER [schema.]function
[WITH [parameter='value' [, parameter='value']+]
];
The list of parameters is:
LANGUAGE='language'
MODE='[FENCED | UNFENCED]'
STUFF='anotherParameter'
Most API documentation separates these two things, which would seem to solve your problem.
BTW, you might point out to your developers that since the parameter values are quoted, the comma is syntactically redundant. Removing it would simplify your diagram and even let you continue to conflate parameter syntax with the list of parameters if you really wanted to.
0 comment threads
0 comment threads