User-Defined Expansion Tokens
A user-defined token is a token where the programmer can determine both the name of a token which can be used in template files, as well as the value to be inserted when the token is encountered.
CodeGen supports three mechanisms which allow you to implement user-defined tokens, via:
If your template 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.
As discussed under 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 file.
As discussed under 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 file.
A quick way to declare used-defined tokens is to specify their name and value on the command line when you execute CodeGen, 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.
If you need to define several user-defined tokens then it is sometimes convenient to define them in a user-defined token file, and then tell CodeGen to read the tokens from the file before it processes a template by using 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>[email protected]</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 © 2012 Synergex International, Inc.