Purpose
Mark the start of a #text .. #endtext region.
The #text directive also defines the nature of the region. This region can either assign a value to a local variable or process the contents of the region.
There are 2 variations of the #text directibe
1. #text [:= | +=] VarName [, LineDelimiter [, LineFunc, [, EndFunc]] ]
2. #text LineFunc [, EndFunc]
1.This variation can be recognized by the := or += operator that follows the #text directive. This declares a #text .. #endtext region that stores the value to a local variable for which the name is specified behind the operator. The text declaration may also contain (optional) tokens that will be used as "line delimiters", an optional function that will be used to calculate each line and an optional function name that will be called from the #endtext line
2.This variation does not have a variable name and declares up to 2 function names for each line and the #endtext line
Arguments
| VarName | is the Name of the variable that should be assigned the value of the Text block |
| LineDelimiter | is the delimiter that should be added to the end of every line in the block |
| LineFunc | is the Name of a function that should be called on every line in the block. The function gets passed the line and should return a string |
| EndFunc | is the Name of a function that gets called after all the lines were created. This function receives the string value of the block when the block is assigned to a variable and should return a string. When the block is not assigned to a variable then this function gets called without parameters. |
Example 1
Please note that the 3 UDCs below are already defined in XSharpDefs.xh
#xcommand ENDTEXT => #endtext
#xcommand TEXT TO <varname> ;
=> #text := <varname>, chr(13)+chr(10)
#xcommand TEXT TO <varname> ADDITIVE ;
=> #text += <varname>, chr(13)+chr(10)
LOCAL cResult AS STRING
TEXT TO cResult
line 1
line 2
line 3
line 4
TEXT
? cResult
This code is converted to
LOCAL cResult AS STRING
var tempLocal := System.Text.StringBuilder{}
tempLocal:Append("Line 1"+chr(13)+chr(10) )
tempLocal:Append("Line 2"+chr(13)+chr(10) )
tempLocal:Append("Line 3"+chr(13)+chr(10) )
cResult := tempLocal:ToString()
? cResult
Please note that the compiler declares different TEXT commands for different dialects. The TEXT command above works in all dialects.
The TEXT command below is for the Non-Core dialects (with the exception of FoxPro):
#xcommand TEXT INTO <varname> WRAP [<lnbreak>] TRIMMED ;
=> #text := <varname>, iif(<.lnbreak.>,<!lnbreak!>, CRLF) , LTrim
This command allows a user defined end of line character and calls the LTrim() function on each string before assigning it to the variable
FoxPro declares a special TEXT command that looks like this:
#xcommand TEXT TO <varname> [<tm:TEXTMERGE>] [<noshow:NOSHOW>] [FLAGS <flags>] [PRETEXT <expression> ] ;
=> __TextInit(<.tm.>, <.noshow.>, iif(<.flags.>, <!flags!>, 0), <!expression!> ) ;;
#text := <varname>, ,__TextWriteLine , __TextEnd
As you can see the command gets translated into a function call to __TextInit() with the values of the various TEXT command options. Each line is send to the __TextWriteLine function and the #endtext directive is replaced with a call to __TextEnd(). There are NO delimiters added for each line. This is handled inside __TextWriteLine. This function is also responsible for expanding expressions inside the text when the TEXTMERGE option is chosen, or when the global SET TEXTMERGE is enabled.
Example 2
Please note that the 2 UDCs below are already defined in XSharpDefs.xh
#xcommand ENDTEXT => #endtext
#xcommand TEXT TO FILE <(file)> ;
=> _TextSave( <(file)> ) ;;
#text QOut, _TextRestore
TEXT TO FILE EXAMPLE.TXT
line 1
line 2
line 3
line 4
ENDTEXT
The TEXT TO FILE command is translated into a call to the function _TextSave(), followed by the #text directive, that specifies that each line must be sent to the QOut() function and that also declares that the #endtext line must be replaced by a call to the _TextRestore() function. The QOut() and _TextRestore function names are specified without parameters. Each line in the block will be sent to the QOut() function as parameter.
So this code is converted to
_TextSave("EXAMPLE.TXT");
QOut("line 1")
QOut("line 2")
QOut("line 3")
QOut("line 4")
_TextRestore()
See also
