User-defined conversions are functions written by the programmer that follows a certain input and output (argument and result) standard so that it can be used as a BEE Conversion.  User-defined conversions take precedence over Intrinsic conversions, so that programmers can overwrite intrinsic conversions by providing his or her own.

Input

The conversion function will be given the following arguments:

arg%value                     The value string regardless of the input structure.  If the input happens to be in array form, this argument will contain the default element of the array.

                                    This is used for functions that expects a string input.

                                    This argument can be represented as "arg%function:value" (following the "arg" class convention) or "arg%value:".

arg%values                    The value array regardless of the input structure.  If the input happens to be a string, it will be put into the default element of arg%values.

                                    This is used for functions that expects an array input.  Avoid using this for string input.  Here is an example of a pitfall:

var petowner:katty = "John Smith";

display "{petowner:katty|myconv}";

...

function myconv

{

   // arg%function:value is "John Smith"

   // arg%values is katty=>"John Smith"

   // arg%values:katty is "John Smith"

   // but the default element of arg%values

   //    is undefined

}

arg%argv                       The argument array.  The first element is arg%argv:0, which is the function name.  The second element is arg%argv:1, which is the first argument, and so on.

arg%argc                      The number of elements in the argument array.  The value is the same as {#arg%argv}.  Please note that the counting includes the function name in arg%argv:0, so if you have one argument, arg%argc is 2.

                                    This argument can be represented as "arg%function:argc" (following the "arg" class convention) or "arg%argc:".

arg%arg                        The argument string of the conversion.  It is specified in the calling command after the conversion name and separate from it by a ':'.  The system will present the argument string to the function as it is after variable evaluation on the command line.  This allows the code to access the full argument string (instead of those in arg%argv).

                                    This argument can be represented as "arg%function:arg" (following the "arg" class convention) or "arg%arg:".

arg%var                         The variable name (this is valid only if converting a "bare" variable as in var myVar conv="myConv";  (Please note that user-defined conversion is operating in a local Context, so your need to link it to the parent.  e.g. parent "{arg%var}"; var argVar =& "{arg%var}"; and changes to argVar will be reflected to the converted variable.)

                                    This argument can be represented as "arg%function:var" (following the "arg" class convention) or "arg%var:".

Output

The conversion function is to return the value via result%function.  If the returned value contains the default element and no other elements, the conversion will return a string.  Otherwise, an array will be returned instead.  (Even when the array contains one single element, as long as it is not the default element, the conversion will still return an array.)