[asterisk-dev] Syntax for application parameters

[Tilghman Lesher]

On Tuesday 09 June 2009 13:21:37 Mark Michelson wrote:
> 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:)."

That's correct, but Asterisk will allow such a syntax and not malfunction.
Even if it looks weird, it works correctly and the documentation matches.

-- 
Tilghman