Chapter 12 - Built-in Functions

12.1 - Purpose        top

Perform frequently needed routine tasks.

12.2 - Usage        top

Built-in functions are used in the same way as user-defined functions are used:

   [call] <built-in-function>(<parameter-list>)
   <call-key><built-in-function>(<parameter-list>)

12.3 - Description        top

A <built-in-function> is one of the subroutines and functions listed below.

Built-in functions have a higher precedence in comparison with file functions or subroutines, so that it is not possible to override a built-in function with a file function or subroutine carrying the same name.

By default built-in functions carry the lower-case names listed below, unless <control-variable> CMD_CASE is switched to upper-case mode, in which case their names are also switched to upper-case.

12.3.1 - File Handling        top

• cur_input
  Return name of current input file.

• cur_input(n)
  Return name of Tefigel input file at nesting level n. Nesting level starts at 0, thus CUR_INPUT(0) is equivalent to cur_input.

• cur_input_line
  Return current line number of current input file.

• cur_input_line(n)
  Return current line number of Tefigel input file at nesting level n. Nesting level starts at 0, thus CUR_INPUT_LINE(0) is equivalent to cur_input_line.

• cur_output
  Return name of current output file.

• cur_output_line
  Return current line number of current output file.

• file_readable(filename)
  Return 1 if filename can be opened for reading, 0 otherwise.

12.3.2 - Tag File Processing        top

• tag_file_process(filename,subroutine dir,case sensitive)
  Process tag file filename (typically, an XML or HTML file) applying corresponding user-defined Tefigel scripts from directory subroutine dir. The optional case sensitive flag, which defaults to 1, can be set to 0 for case-insensitive tag identifiers, such as HTML tags. Additional information on this subject is provided in a later chapter.

12.3.3 - CSV File Processing        top

• csv_file_process(filename,subroutine,separator)
  Process comma-separated value (CSV) file filename through subroutine using character separator as value delimiter. Additional information on this subject is provided in a later chapter.

12.3.4 - Output Formatting        top

• format(to_format,width,hdr,trl,h_line,t_line,filler)
  Format to_format, which can be a string or a file name, producing output lines of width characters, using filler as "background" character, according to the following scheme:

   A heading line, as specified by h_line
   hdr Text line #1, width characters long trl
   hdr Text line #2, width characters long trl
   hdr ................................... trl
   A trailing line, as specified by t_line

• tabs(string,t1,t2,t3,...)
  Return edited copy of input string, replacing tabs with blanks aligned to the positions specified by numerical parameters t1, t2, t3, etc. Default alignment values for t1, t2, t3, etc., are 8, 16, 24, etc.

12.3.5 - Variable Formatting        top

• fmt_float(printf_fmt,variable)
  Return string value of variable formatted as per double floating-point printf_fmt. Refer to the technical literature for valid printf_fmt strings.

12.3.6 - String Handling        top

• chr(number)
  Return the character (ASCII or ISO 8859-1) corresponding to the given number, which can be specified as a decimal, octal or hexadecimal number.

• length(string)
  Return length of string.

• make_id(<base-identifier>,<id-pattern>)
  Return an identifier built by applying the <id-pattern> to the given <base-identifier>, as explained in further detail below.

• replace(string,old string,new string)
  Return a string with all occurrences of old string replaced with corresponding occurrences of new string.

• substr(string,offset,n)
  Return substring of n characters starting from position offset (zero-based) of the given string.

• to_lower(STRING)
  Return STRING converted to lower case as in string.

• to_UPPER(string)
  Return string converted to upper case as in STRING.

• to_Upper(string)
  Return string with the first letter converted to upper case as in String.

• value(string)
  Return final value of string, which can be an arbitrarily complex sequence of dash-concatenated variables. This function is used to expand complex name-value associations, also referred to as <associative-variable>'s, such as plain or multi-dimensional arrays, or nested records.

12.3.7 - Data Group Handling        top

• group(separator,data field 1,data field 2,...)
  Return a data group (a dynamic record) with the specified data fields separated by the specified single-character separator.

• ungroup(data group,separator,variable 1,variable 2,...)
  Assigns the data fields from the specified data group to the specified variables using the specified single-character separator.

12.3.8 - List Processing        top

• new_list(list id)
  Create a new empty list identified by list id.

• new_list(list id,item1,item2,...)
  Create a new list identified by list id containing the specified items.

• delete_list(list id)
  Delete the list identified by list id.

• add_item(list id,item)
  Add item at the end of the list identified by list id.

• list_item_count(list id)
  Return number of items contained in the list identified by list id.

• list_contents(list id,prefix,suffix,separator)
  Return a string containing the items of the list separated by separator. If separator is omitted, it defaults to comma.
  The optional prefix and suffix allow to specify a leading and a trailing string for each item of the list.

• list_process(list id,processor)
  Apply processor (a user-defined Tefigel script) to each item contained in the list identified by list id. The processor is called with three arguments:
  1. the position (zero-based) of the current item in the list;
  2. the total number of items in the list;
  3. the current item.
  

12.3.9 - Word List Processing        top

• word(string,n,separator list)
  Return n-th word (zero-based) from string, using separator list as the set of separator characters. The separator list may be omitted, in which case its content defaults to blank and tab.

• word_count(string,separator list)
  Return number of words from string, using separator list as the set of separator characters. The separator list may be omitted, in which case its content defaults to blank and tab.

• word_list_process(string,processor,separator list)
  Apply processor (a user-defined Tefigel script) to each word contained in string, using separator list as the set of separator characters. The separator list may be omitted, in which case its content defaults to blank and tab. The processor is called with three arguments:
  1. the position (zero-based) of the current word in the string;
  2. the total number of words in string;
  3. the current word.
  

12.3.10 - Record Processing        top

• field(string,n,separator)
  Return n-th field (zero-based) from string, using separator as the field separator.

• field_count(string,separator)
  Return number of fields from string, using separator as the field separator.

12.3.11 - Date and Time        top

• date
  Return current system date, formatted as in "Tue Jan 14 2003".

• time
  Return current system time, formatted as in "23:17:51.255".

12.3.12 - Environment        top

• cur_platform
  Return name of current execution platform, one of "Linux", "Mac_OS_X", or "Windows".

• get_env(variable)
  Return value of the specified environment variable.

12.3.13 - Miscellaneous        top

• hook(which)
  Return name of <hook-subroutine> currently associated with the <hook-event> specified by which. Hook events are listed later in this guide.

• switch(which)
  Return current value of Tefigel internal switch specified by which. Internal switches are listed later in this guide.

12.3.14 - Additional Details on make_id        top

A <base-identifier> is the identifier of a variable, defined as a string of letters, decimal digits and underscores ('_'), as in this_is_a_Valid_BASE_id. An <id-pattern> is one of the strings listed below, providing a mnemonic identifier pattern specifying the desired format for the conversion of a given <base-identifier>. The following list shows the identifier resulting by applying an <id-pattern> to this_is_a_Valid_BASE_id.

• "abcdef": thisisavalidbaseid

• "abcDef": thisIsAValidBaseId

• "abcDEF": thisISAVALIDBASEID

• "Abcdef": Thisisavalidbaseid

• "AbcDef": ThisIsAValidBaseId

• "AbcDEF": ThisISAVALIDBASEID

• "ABCdef": THISisavalidbaseid

• "ABCDef": THISIsAValidBaseId

• "ABCDEF": THISISAVALIDBASEID

• "abc_def": this_is_a_valid_base_id

• "abc_Def": this_Is_A_Valid_Base_Id

• "abc_DEF": this_IS_A_VALID_BASE_ID

• "Abc_def": This_is_a_valid_base_id

• "Abc_Def": This_Is_A_Valid_Base_Id

• "Abc_DEF": This_IS_A_VALID_BASE_ID

• "ABC_def": THIS_is_a_valid_base_id

• "ABC_Def": THIS_Is_A_Valid_Base_Id

• "ABC_DEF": THIS_IS_A_VALID_BASE_ID