The Actual Syntax for a Convertible String

In Basics, we said that the following is the syntax for a string convertible to an object:

   %ResourceBundleKeyName
| $ArgumentMapKeyName
| &GlobalVariableName
| LiteralString


where | means "or" and LiteralString is a string that conforms to the converter-specific syntax, for example the Integer converter expects that LiteralString consists of an optional '-', then a string of digits.

However, this is not quite correct, for four reasons.

First of all, an argument map reference can be followed by several options described in Argument Maps.

Secondly, as described in Global Variables, a literal string can be prefixed by an ampersand ('&'), the name of the global to assign the converted value to, and a colon (':').

Thirdly, LiteralString does not need to conform to the converter-specific syntax if it's a BeanShell script with the syntax:

<{ ScriptContents }>


Last and least of all, there is some ambiguity that arises if LiteralString begins with a '%', '$', or '&'. These reserved characters are not allowed for the first character of literals. To get these characters, the character must be escaped with a backslash. If the string appears in a properties resource bundle, the backslash itself must be escaped, so a total of two backslashes are needed:

textfield.text=\\$19.95

creates a text field with its text set to "$19.95". Because the text property is converted by a quoted string converter, the following is preferred:

textfield.text="$19.95"

which doesn't need escaping since the first character isn't a reserved character anymore.

Now, we can give the real syntax for a convertible string,
using Perl-style regular expression syntax:
  %ResourceBundleKeyName
| $ArgumentMapKeyName(:[ruw]+)?(#defaultValue(#fromMapConverter(#toMapConverter)?)?)?#?
| &GlobalVariableName
| (&GlobalVariableName:)?(EscapedLiteralString | <{ BeanShell script }>)
In the syntax above, '%', '$', '&', '<', '>', '{''}', and '#'  are literal characters. '[', ']', '+', '?', '|', '(', and ')' have their usual Perl-style regex meaning (see the Javadoc for java.util.regex.Pattern for details).