true and false command part options function unclear (and example broken)

[jrandall]

It appears that the command part options example for true and false given in the SPEC (https://github.com/broadinstitute/wdl/blob/develop/SPEC.md#true-and-false) is broken.

First of all, the parser does not seem to allow commas between command options (the list macro is invoked without the :comma second argument; https://github.com/broadinstitute/wdl/blob/develop/parsers/grammar.hgr#L388).

Secondly, it does not appear to be possible to assert a type of a command part by prefixing the expression with the type as is done in this example:

For example, ${true='--enable-foo', false='--disable-foo' Boolean yes_or_no} would evaluate to either --enable-foo or --disable-foo based on the value of yes_or_no.

Because the grammar does not seem to accept a type specification here, it is not clear to me when and how the true / false key values should be interpreted. In this example, it would be clear if the type of yes_or_no is Boolean because the expression is just a simple identifier, but if the expression was more complex (such as a function call) it would be harder to determine the type of it without understanding the execution environment.

We have come across this while trying to improve the wdl2cwl converter (https://github.com/common-workflow-language/wdl2cwl) to handle more complex command expressions, and in order to add the true and false handling we will need to understand when they are meant to be invoked.

After reading the docs and some of the example scripts (such as the WDL for HaplotypeCaller), it seems possible that we are meant to use true and false options (each with a default value of "") whenever the type of the expression is Boolean - but that they do not apply when the type is Boolean ? as in that case the default option is used instead and the true / false values are simply stringified as in this example (from https://github.com/broadinstitute/wdl/blob/develop/scripts/wrappers/gatk/WDLTasks_3.6/HaplotypeCaller_3.6.wdl#L141):

-allelesTrigger ${default="false" useAllelesTrigger} 

Which appears to evaluate to -allelesTrigger false if useAllelesTrigger is false or unset/null, and -allelesTrigger true if useAllelesTrigger is true.

If the true and false options apply to both Boolean and Boolean ? and we are meant to apply the default ("") values of the true and false options as the docs suggest -- in other words, if the above line was equivalent to:

-allelesTrigger ${true="" false="" default="false" useAllelesTrigger}

Then I would expect this to evaluate to -allelesTrigger false only when useAllelesTrigger is unset/null, and to -allelesTrigger when useAllelesTrigger is true or false.

Clarification of the documentation would be helpful!