[asterisk-dev] Syntax for application parameters

[Jared Smith]

On Tue, 2009-06-09 at 12:07 -0500, Tilghman Lesher wrote:
> 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.

Let's be clear here... when you say "if the third option is specified,
then the second option is mandatory", we're *not* saying that you have
to have the second parameter, only that you have a comma there at a
minimum.  To use your example of the Dial application, specifying an
option (third parameter) doesn't mean we *have* to specify a timeout
(second parameter).

We can easily Dial(IAX2/some_peer/exten,,m), and not pass in a second
parameter.

I would argue that the second proposed syntax does just that.  To put
the Dial() application in this same syntax, it would look like:

Dial(Technology/Resource[&Technology2/Resource2[&...]][,timeout[,options[,URL]]])

This shows that the first Technology/Resource is required (no square
brackets), and that it can have additional (optional)
technology/resource pairs concatenated together with ampersands.

If you skip to the end and look at the URL parameter, it's *fairly*
obvious that if you want to use that parameter, that you must include
the options and timeout parameters.  If you want to use the options
parameter, you don't have to include the URL, but you have to include
the timeout.  What *isn't* super-obvious just from looking at the syntax
is whether or not you can leave the parameters blank (but still supply
the colon), but I think it's pretty safe to say that the majority of
Asterisk dialplan scripters already understand that you can.

If we want to err on the side of specificity, I'd say let's go with
option 4.  If we want to err on the side of simplicity, I say let's go
with option 2.  (And if we want to err on the side of being
self-inconsistent, let's go with options 1 or 3.)

-- 
Jared Smith
Training Manager
Digium, Inc.