User-Defined Expansion Tokens
User-defined expansion tokens are special tokens where a developer can determine both the name of the token as well as the value to be inserted when the token is encountered during code generation.
CodeGen supports several mechanisms to allow you to implement user-defined tokens, via:
If your template file depends on the developer providing a value for a particular user-defined token, you can tell CodeGen about that dependency. For more information refer to declaring user-defined token dependencies.
Environment Variables
As documented in generic tokens you can use the <ENV:variable> token in a template file and CodeGen will insert the value obtained from the environment variable into the output stream.
Include Files
Also documented in generic tokens you can use the <FILE:name.ext> token in a template file and CodeGen will read data from an external file and insert that data into the output stream.
Command Line Tokens
A quick way to declare used-defined tokens is to specify both a name and value on the command line using the -ut command line option, for example:
codegen –s <structure> -t <template> -ut MODEL_NS=MyApp.Model
You can specify multiple user-defined tokens on the command line, space separated after the -ut option, for example:
codegen –s <structure> -t <template> -ut MODEL_NS=MyApp.Model VIEW_NS=MyApp.View
If your user-defined token value (the part after the equal character) contains double quotes then Windows will strip the quotes before the value is passed to CodeGen. In that case you must escape the double quote characters with a back-slash character, like this:
-ut MYMESSAGE=\"Hello World\"
By default, the replacement value user-defined tokens that are defined on the command line may not contain other tokens. If you wish to enable that functionality then you must tell CodeGen to treat user-defined tokens as preprocessor tokens via the -utpp command line option.
User-Defined Token Files
If you need to define several user-defined tokens then it is sometimes convenient to define them in a user-defined token file and name the user-defined token file via the -u command line option.
An example of a user-defined token file is:
;
; User defined tokens for Synergex Inc.
;
<SUPPORT_PHONE>(800) 366-3472</SUPPORT_PHONE>
<SUPPORT_EMAIL>support@synergex.com</SUPPORT_EMAIL>
<WEBSITE>http://www.synergex.com</WEBSITE>
To tell CodeGen to read user-defined tokens from a file you would use the -u command line option. For example:
codegen –s <structure> -t <template> -u MYTOKENS:<usertokenfile>
You could then refer to your user defined tokens in your template files. For example:
display(tt,”Please call support at <SUPPORT_PHONE>”)
display(tt,” or send an email to <SUPPORT_EMAIL>.”)
Declaring User-Defined Token Dependencies
If CodeGen encounters something in a template file which is formatted like a token (i.e. delimited by < and > characters) but is not recognized as a token, then CodeGen will ignore it, and that text will remain in the output file that is created. This is necessary in order for CodeGen to be able to generate code for languages or dialects such as HTML, XML and XAML.
However, when it comes to user-defined tokens this can be a problem, because if a template contains something that the template developer intended to be a user-defined token which gets replaced, but someone who is subsequently generating code from the template neglects to specify the source of the user-defined tokens, the tokens will remain in the generated file and no error will be reported.
To address this situation template developers can use the <REQUIRES_USERTOKEN> token to declare that their template requires a particular user-defined token to be declared, either in a token file (-u) or on the command line (-ut).
If a templates declares that a user-defined token is required, but that user-defined token has not been declared when generating code, CodeGen will display an error and will stop processing the template.
Copyright © 2021 Synergex International, Inc.