| FUNCTION |
Contents
| Purpose: | Create, modify or display user-defined variable functions |
| Format: | Display mode: |
FUNCTION [/GL /LL /P] [wildname]
Direct definition mode:
FUNCTION [/= /GL /LL] name[=]definition
Definition file mode:
FUNCTION [/= /G /GL /L /LL /O /Z] /R [file...]
| file | One or more input files to read function definitions from. |
| wildname | Name of function whose definition is to be displayed (may contain * and ? wildcards) |
| name | The name of the function you want to define. |
| definition | The value or definition of what the function should return. |
See also: UNFUNCTION and ESET.
File Completion Syntax:
The default filename completion syntax is: [/r] * [1] functions [2*] *
Usage:
Saving and Reloading Your Functions
FUNCTION allows you to create or display user-defined variable functions that can be used anywhere Variable Functions can be used. User-defined functions are powerful alternatives to subroutines.
If you invoke the FUNCTION command with no parameters, it will display the current function list (the local function list if you have set local functions in TCMD.INI or the TCC startup command line; otherwise the global function list):
function
If you include a wildname, which may include wildcards (* or ?), with no equal sign and no definition, FUNCTION will display the current values, if any, of all functions matching wildname, .e.g.:
function *dx*
will display all functions which contain dx in their name.
You can use the /P option to control display scrolling when displaying functions.
If you include the equal sign and definition, FUNCTION will create or update the function referred to by name. Any previous definition associated with name is discarded. Instead of the = sign, you may use one or more spaces or tab characters to separate name and definition.
Once a function is defined, the definition may be edited using ESET /F.
A function can optionally use references to parameters numbered from %0 to %511 which will be replaced with the matching parameter value when the function is called. %0 refers to the function name, %1 to the first parameter, etc. For example, the function
function leftmost=`%@left[1,%1]`
will return the leftmost character in its parameter, e.g. %@leftmost[xyz] will return x.
The parameter %n$ has a special meaning. TCC interprets it to mean "all arguments, from parameter n to the end." If n is not specified, it has a default value of 1, so %$ means "all arguments passed to the function."
The parameter %-n$ means "the arguments from parameter 1 to n - 1".
The special variable reference %# expands to the number of parameters passed to the function.
A function definition need not reference any parameters at all. For example:
function tomorrow=`%@makedate[%@inc[%@date[%_date]]]`
could be simply invoked as %@tomorrow[].
To use the function name you invoke is as %@name[parameters],where you must specify enough parameters to assign a value to the highest numbered parameter referenced in the function definition. It may have more parameters, which will be silently ignored.
The Colors, Color Names and Codes topic shows a simple example of the use of a function in a batch file.
The normal method is to use the UNFUNCTION command. However, it is also possible to delete a function by redefining it without a definition, e.g., the command
function fs=
deletes the function fs.
Functions can be stored in local and/or global lists.
With a local function list, any changes made to the functions will only affect the current copy of TCC. They will not be visible in other shells or other sessions.
With a global function list, all copies of TCC will share the same function list, and any changes made to the functions in one copy will affect all other copies. This is the default in TCC.
You can control the type of function list to use with the /GL and /LL options in FUNCTION, Local Functions and Global Functions configuration options, with the /L and /LF options of the START command, and with the /L and /LF startup options.
If you don't specify /GL or /LL, TCC will first look for functions in the local list. If there is no local list or the function is not found, TCC will search the global list (if it exists).
There is no fixed rule for determining whether to use a local or global function list. Depending on your work style, you may find it most convenient to use one type, or a mixture of types in different sessions or shells. We recommend that you start with the default approach, then modify it if you find a situation where the default is not convenient.
Whenever you start a second copy of TCC which uses a local function list, it inherits a copy of the functions from the previous shell. However, any changes to the functions made in the second shell will affect only that shell. If you want changes made in the second shell to affect the previous shell, use a global function list in both shells.
Saving and Reloading Your Functions
You can save your functions to a file (e.g., FUNCTIONS.LST) this way:
function > function.lst
You can then reload all the function definitions in the file the next time you start up with the command:
function /r function.lst
This is much faster than defining each function individually in a batch file. If you keep your function definitions in a separate file which you load when TCC starts, you can edit them with a text editor, reload the edited file with FUNCTION /R, and know that the same function list will be loaded the next time you start TCC.
When you define functions in a file that will be processed by the FUNCTION /R command, you do not need back quotes around definition, even if back quotes would normally be required when defining the same function at the command line or in a batch file.
When you define a function in the command line (i.e., without using the /R option), variables and functions not protected by back quotes or doubled % signs are immediately evaluated, and the result becomes part of the function definition.
Syntax errors in a function definition are not detected until it is used.
Options:
| /= | Display the FUNCTION command dialog to help you set the command line options. The /= option can be anywhere on the line; additional options will set the appropriate fields in the command dialog. |
| /G | Switch from a local to a global function list. If you already have a global function list (for example, in another TCC instance or in SHRALIAS), FUNCTION will not do the conversion. |
| /GL | Read from and write to the global function list. If you have both local and global function lists defined and do not specify /GL, FUNCTION will default to using the local list. |
| /R | This option loads a list of functions from a file. If no filename is specified and input is redirected, /R will read from stdin. The format of the file is the same as that of the FUNCTION display: |
name=definition
where name is the name of the function and definition specifies how to determine its value. You may use the equal sign = or whitespace to separate name and definition. Back-quotes are not required.
You can add comments to the file by starting each comment line with a colon :.
You can load multiple files with one FUNCTION /R command by placing the names on the command line, separated by spaces:
function /r func1.lst func2.lst
FUNCTION /R definitions can span multiple lines in the file if each line, except the last, is terminated with an Escape Character.
If there is no filename parameter and input is redirected, FUNCTION /R will read from stdin.