[asterisk-dev] Syntax for application parameters

[Mark Michelson]

Tilghman Lesher wrote:
> On Tuesday 09 June 2009 10:58:48 Mark Michelson wrote:
>> Tilghman Lesher wrote:
>>> On Tuesday 09 June 2009 09:52:04 Philipp Kempgen wrote:
>>>> Will schrieb:
>>>>> On Tue, Jun 9, 2009 at 8:31 AM, Jared Smith<jsmith at digium.com> wrote:
>>>>>> Eliel and I started a vigorous discussion on the asterisk-dev IRC
>>>>>> channel earlier today regarding the syntax for application parameters
>>>>>> in the built-in help, and I'd like to open up the discussion for more
>>>>>> members of the development community before we agree on a format.
>>>>>>
>>>>>> >From what we've discussed this morning, it appears we have four
>>>>>>
>>>>>> different proposed versions of the syntax:
>>>>>>
>>>>>> 1) Application([param1][,param2[,param3]])
>>>>>> 2) Application([param1[,param2[,param3]]])
>>>>>> 3) Application([[param1][,[param2][,[param3]]])
>>>>>> 4) Application([param1][,[param2][,[param3]]])
>>>>> #3 looks like it's missing a ] somewhere. Assuming the missing ] is on
>>>>> the end, #3 and #4 are functionally equivalent (unless I missed
>>>>> something) and is what I prefer, since it allows parameter index to
>>>>> stay the same, even if you choose to leave out parameters.  If you
>>>>> want to leave out a parameter, just put nothing in it's position so
>>>>> you end up with (param1,,param3).
>>>> The same goes for #1 and #2 provided the user knows that params can
>>>> be empty. I get your point but it might not be worth the additional
>>>> "clutter" in #3 and #4. #1 and #2 are easier to "parse". jm2c
>>> That assumes that certain parameters are allowed to be empty.  If a
>>> parameter is required, and the user assumes, according to the syntax,
>>> that it can be omitted, that would be considered unclear and thus poor
>>> documentation.  This is why I favor #4.
>> The presence of square brackets around the parameter means that it is
>> optional. If a parameter is required, then it would not have square
>> brackets around it. Therefore a user would know that the parameter could
>> not be omitted.
>>
>> Can you give an example of what you are talking about?
> 
> A good example would be the L option of the Dial command.  The first parameter
> is required, the second and third are optional.  However, if the third option
> is specified, then the second option is mandatory.  Thus, the fields are not
> all exclusively optional, but rather one option's specification mandates the
> specification of another.  You need the proper inclusion of square brackets to
> make the documentation clear.
> 

Good example. What's interesting is that I don't really think you can accurately 
convey such a dependency without allowing for degenerate cases to form from the 
grammar.

A naive method of showing the L option would be:

L(param1[:param2[:[param3]]])

While this would not allow a string like "L(360000::5000)", it would allow a 
string like "L(360000:20000:)."

Really, if you want a notation that is 100% correct, you need to allow 
alternation. In the example below the || is the alternation character. You can 
think of it as reading the word "or." I also have used () for grouping and 
escaped the literal () with backslashes.

L\(param1[(:param2||:param2:param3)]\)

This shows that param1 is required and that params 2 and 3 are optional. 
However, if you wish to include param3, param2 must also be present. I can't 
think of a clear way to express this without alternation and without allowing 
awkward legal strings.

Mark Michelson