/***************************************************************************
*
plugins.h - description
*
-------------------
*
begin
: Sat 10 Dec 2005 02:07:07 PM EST
*
copyright
: (C) 2005 by Terry D. Boldt
*
email
: fastsnip-wm1@yahoo.com
***************************************************************************/
/***************************************************************************
*
*
* This program is free software; you can redistribute
it and/or modify *
* it under the terms of the GNU General Public
License as published by *
* the Free Software Foundation; either version 2 of
the License, or *
* (at your option) any later
version.
*
*
*
***************************************************************************/
/*
*
* Header file for QTAwk plugins -
* constants definition
* function prototypes
*/
/* define constants for builtin functions
* used in 'QTAwk_execute_builtin_function' call
*
* NOTE: QTAWK_SUB QTAWK_GSUB QTAWK_GENSUB functions
not available
* to be called from dynamically
loaded user functions
*/
#define QTAWK_PRINT
1 /* QTAWK 'print'
function */
#define QTAWK_FPRINT
2 /* QTAWK 'fprint'
function */
#define QTAWK_PRINTF
3 /* QTAWK 'printf'
funtion */
#define QTAWK_FPRINTF 4
/* QTAWK 'fprintf'
function */
#define
QTAWK_PUTC
5 /* QTAWK 'putc'
function
*/
#define QTAWK_FPUTC
6 /* QTAWK 'fputc'
function */
#define QTAWK_GETLINE 7
/* QTAWK 'getline'
function */
#define QTAWK_FGETLINE 8 /*
QTAWK 'fgetlione' function */
#define
QTAWK_GETC
9 /* QTAWK 'getc'
function
*/
#define QTAWK_FGETC
10 /* QTAWK 'fgetc'
function */
#define QTAWK_SRCHRECORD 11 /* QTAWK
'srchrecord' function */
#define QTAWK_FSRCHRECORD 12 /* QTAWK 'fsrchrecord'
function */
#define QTAWK_APPEND 13
/* QTAWK 'append'
function */
#define QTAWK_FINDFILE 14 /* QTAWK
'findfile' function */
#define QTAWK_CLOSE
15 /* QTAWK 'close'
function */
#define QTAWK_GET_FNR 16 /*
QTAWK 'get_FNR'
function */
#define QTAWK_FFLUSH 17
/* QTAWK 'fflush'
function */
#define QTAWK_STRLEN 18
/* QTAWK 'length'
function */
#define QTAWK_TOUPPER 19 /*
QTAWK 'toupper'
function */
#define QTAWK_TOLOWER 20 /*
QTAWK 'tolower'
function */
#define QTAWK_MATCH
21 /* QTAWK 'match'
function */
/* #define
QTAWK_SUB
22 */ /* QTAWK 'sub'
function
*/
/* #define QTAWK_GSUB
23 *//* QTAWK 'gsub'
function
*/
/* #define QTAWK_GENSUB
24 *//* QTAWK 'gensub'
function */
#define QTAWK_INDEX
25 /* QTAWK 'index'
function */
#define QTAWK_SPLIT
26 /* QTAWK 'split'
function */
#define QTAWK_SUBSTR 27
/* QTAWK 'substr'
function */
#define QTAWK_REV
28 /* QTAWK 'srev'
function
*/
#define QTAWK_TRIM
29 /* QTAWK 'trim'
function
*/
#define QTAWK_TRANS
30 /* QTAWK 'trans'
function */
#define QTAWK_CENTER 31
/* QTAWK 'center'
function */
#define QTAWK_COPIES 32
/* QTAWK 'copies'
function */
#define QTAWK_DELETE 33
/* QTAWK 'delete'
function */
#define QTAWK_INSERT 34
/* QTAWK 'insert'
function */
#define QTAWK_OVERLAY 35 /*
QTAWK 'overlay'
function */
#define QTAWK_REMOVE 36
/* QTAWK 'remove'
function */
#define QTAWK_REPLACE 37 /*
QTAWK 'replace'
function */
#define QTAWK_JUSTIFY 38 /*
QTAWK 'justify'
function */
#define QTAWK_SRANGE 39
/* QTAWK 'srange'
function */
#define QTAWK_SPRINTF 40 /*
QTAWK sprintf''
function */
#define QTAWK_TIME
41 /* QTAWK '_time'
function */
#define QTAWK_FTIME
42 /* QTAWK '_ftime'
function */
#define QTAWK_JDN
43 /* QTAWK 'jdn'
function
*/
#define QTAWK_ROTATE 44
/* QTAWK 'rotate'
function */
#define QTAWK_ATAN2
45 /* QTAWK 'atan2'
function */
#define QTAWK_COS
46 /* QTAWK 'cos'
function
*/
#define QTAWK_EXP
47 /* QTAWK 'exp'
function
*/
#define QTAWK_INT
48 /* QTAWK 'int'
function
*/
#define QTAWK_LOG
49 /* QTAWK 'log'
function
*/
#define QTAWK_SIN
50 /* QTAWK 'sin'
function
*/
#define QTAWK_SQRT
51 /* QTAWK 'sqrt'
function
*/
#define QTAWK_COSH
52 /* QTAWK 'cosh'
function
*/
#define QTAWK_SINH
53 /* QTAWK 'sinh'
function
*/
#define QTAWK_ACOS
54 /* QTAWK 'acos'
function
*/
#define QTAWK_ASIN
55 /* QTAWK 'asin'
function
*/
#define QTAWK_LOG10
56 /* QTAWK 'log10'
function */
#define QTAWK_FRACT
57 /* QTAWK 'fract'
function */
#define
QTAWK_PI
58 /* QTAWK 'pi'
function
*/
#define QTAWK_SRAND
59 /* QTAWK 'srand'
function */
#define QTAWK_RAND
60 /* QTAWK 'rand'
function
*/
#define QTAWK_SYSTEM 61
/* QTAWK 'system'
function */
#define QTAWK_EXECUTE 62 /*
QTAWK 'execute'
function */
#define QTAWK_PSYM
63 /* QTAWK 'psym'
function
*/
#define QTAWK_USYM
64 /* QTAWK 'usym'
function
*/
#define QTAWK_ETYPE
65 /* QTAWK 'etype'
function */
#define QTAWK_RESETRE 66 /*
QTAWK 'resetre'
function */
#define QTAWK_SETLOCALE 67 /* QTAWK
'setlocale' function */
/*
* Define Values For Variable Class Type
*/
#define NO_VAL 0
#define REGEXP_VAL 1 /* regular
expression type */
#define STRING_VAL 2 /* string
type
*/
#define STRING_INT 3 /* string
type
*/
#define STRING_FLT 4 /* string
type
*/
#define CHAR_VAL 5 /*
character
type
*/
#define LONG_VAL 6 /*
qta_long
type
*/
#define DOUBLE_VAL 7 /* double
type
*/
#define QTA_LONG_MAX LLONG_MAX
#define QTA_ULONG_MAX ULLONG_MAX
/* Define Types Of Array Indices
*/
#define
NO_INDEX 0
#define STRING_INDEX_TYPE 1
#define NUM_INDEX_TYPE 2
/* define QTAwk integral types under Linux
*/
typedef long long int qta_long;
typedef unsigned long long int qta_ulong;
/* define pointer to QTAwk variable
*/
typedef struct var_inst *Variable_ptr;
/* Pointer To Variable Index Structure
*/
typedef struct QTAwk_index *QTAwk_index_ptr;
typedef union index_rep {
unsigned long numeric_index; /*
Numeric Index */
unsigned char
*char_index; /* String Index */
} index_rep;
/* structure used to define and pass array indices
*/
typedef struct QTAwk_index {
unsigned char
index_type; /* Type Of Index -
Numeric/String */
index_rep index_rep;
} QTAwk_index;
/* QTAwk function prototypes
*/
/* prototype for function to prepare to register dynamically function
names
* call once before calling next function to register each function
* This call passes the number of functions to register.
*/
void
QTAwk_register_function_count(
unsigned function_count);
/* prototype for function to register function names loaded
* dynamically - call for each function loaded
* Returns:
* 0 --> function name successfully registered and
available
* -1 --> Error in registering function name
*
* This function is called by the 'initialization' function of a
module
* loaded with the QTAwk built-in function:
* load_module(filename,initialization_function_name)
* when the 'load_module' built-in function is called, QTAwk has
the file named
* in the first argument loaded into memory and linked
* with QTAwk. The function named in the second argument, which is
* in the module loaded, is called. That function then initializes
* the loaded module and must call the following function to
register with QTAwk
* each function name loaded. If the following function is not
* called to register the function names, then none of the
functions
* in the loaded module are known and cannot be called.
*
* A module may be "unloaded" by calling the QTAwk built-in
function:
* unload_module(filename)
* All functions which have been registered for the module are
automatically
* unregistered and the module unloaded from memory.
*
* The arguments are:
* function_name --> string containg the name of the
function to be called
* argument_names --> array of pointers to strings
containing the names of the function
*
arguments starting with the first argument and proceeding in order.
*
NULL terminated list.
*
Pass NULL for zero arguments or if all arguments are optional.
* variable_arguments --> if non-zero, then any arguments
after the number specified by
*
'argument_names' are determined by the calling command. If
*
'argument_namess' is NULL, then all arguments are optional.
*
The number of arguments actually used in the call is passed at run time.
*
This allows functions similar in calling sequence to the 'print'
*
functions.
*
The number of variable arguments passed is specified in the 'vargc'
*
QTAwk variable argument, and the arguments are array elements of
the
*
singly dimensioned 'vargv' QTAwk variable argument. 'vargc' is
passed
*
as the first argument after the arguments specified in 'argument_names'
*
and 'vargv' is the second argument after the arguments specified in
*
'argument_names'
*
* When registered functions are called, all function arguments
have been pushed onto the
* QTAwk stack. The registered function must use the
'QTAwk_get_argument'
* function to retrieve the arguments.
*
* The registered function is called with one argument, an
unsigned integer specifying the
* number of arguments on the stack.
*
* all registered functions are assumed to return a QTAwk
variable, i.e., all registered functions
* are assumed to have a function prototype of:
*
* Variable_ptr registered_function(unsigned
argument_count);
*
* Returning a NULL pointer, is equivalent to returning no value
to the calling QTAwk utility.
*
* This function returns NULL if no error occurred in registering
the function(s) or a pointer
* to an error string if an error occurred.
*
*/
unsigned char *QTAwk_register_function(
unsigned char *function_name,
unsigned char **argument_names,
unsigned variable_arguments);
/* prototype for QTAwk function to set the module exit function
contained in the module to call when
* the module is unloaded.
*/
void
QTAwk_set_module_exit_function(
unsigned char *function_name);
/* prototype for QTAwk function to set the function contained in the
module to call when
* QTAwk exits normally and the module is still loaded. This could
be the same as the
* normal module exit function.
*/
void
QTAwk_set_module_shutdown_function(
unsigned char *function_name);
/* QTAwk function to get argument for dynamically loaded function.
* May pass either the argument count (starting with 1 for first
argument), or
* the argument variable name.
*
* The variable name to to used is the name specified in the call
to 'QTAwk_register_function'
*
* Search by name takes precedence over search by count.
*
*/
Variable_ptr QTAwk_get_argument(
unsigned arg_cnt,
unsigned char *arg_name);
/* prototype to retrieve value of QTAwk variable
* use variable class defined constants above to specify value
desired.
*
* The function returns a pointer to 'void' type which must be
cast to the
* type speicified in the call.
*
* The following value types all return an 'unsigned char *' value
* REGEXP_VAL
* STRING_VAL
* STRING_INT
* STRING_FLT
*
* The "CHAR_VAL" type returns an "unsigned char" value
*
* The "LONG_VAL" returns a pointer to a "qta_long" value ==
"qta_long *"
*
* The "DOUBLE_VAL" returns a pointer to a "double" value ==
"double *"
*
* Cast the return value to the desired value or pointer type and
copy to
* a local value. The storage used for the return value
* WILL be overwritten by subsequent calls.
*
*
* NOTE: if the return type is specified as "NO_VAL", then the
value returned
* is whatever type the QTAwk variable already is and
'return_type' is set to
* the appropriate type value. This is one method of ascertaining
the type of
* a QTAwk variable. The 'QTAwk_get_type' function is a better way.
*
* If the QTAwk variable is not of the type requested, then it is
converted
* where possible to that type.
*/
void
*QTAwk_get_value(
Variable_ptr QTAwk_variable,
unsigned *return_type);
/* prototype to set QTAwk variable value. Any previous variable values
are discarded.
* The first argument is the QTAwk variable to set
* The second argument is a pointer to the value (caller casts to
a "void *"
* the third argument is one of the variable class defined
constants above
* The value in the caller is not changed. If a string type, one
of:
* REGEXP_VAL
* STRING_VAL
* STRING_INT
* STRING_FLT
* The string value is copied and the value of the variable is set
to the copy.
*
* If a type of "NO_VAL" is specified, the variable is initialized
to a value
* of the null string and a zero integral value.
*
* Also see the QTAwk function 'QTAwk_assign' for assigning the
value of one
* variable to another.
*
*/
Variable_ptr QTAwk_set_value(
Variable_ptr QTAwk_variable,
void const *value,
unsigned set_type);
/* prototype for the QTAwk function for determining the type of a QTAwk
variable.
* the return value is an unsigned integer value for one of the
type defined constants
* above:
* NO_VAL
* REGEXP_VAL
* STRING_VAL
* STRING_INT
* STRING_FLT
* CHAR_VAL
* LONG_VAL
* DOUBLE_VAL
*
*/
unsigned QTAwk_get_type(
Variable_ptr QTAwk_variable);
/* prototype for QTAwk function to get the name of the specified
variable.
*
* Return a pointer to unsigned char.
*
* The returned value is a copy of the variable name and the
memory has been allocated
* by a call to 'calloc'.
*
* The calling function must ensure that the memory is released
prior to returning
*
*
*/
unsigned char *QTAwk_get_name(
Variable_ptr QTAwk_variable);
/* prototype for QTAwk function to get the named variable specified
* The name specified may be any built-in variable or variable
named by the
* user utility.
*
* Note that local variable names are searched first, then global
names.
* Note that "local" names are those 'local' to the braced
statement within
* which the dynamically loaded user function is called.
*
* NOTE: If a local or global variable with the specified name
does not exist
* a global variable with the specified name will be created.
*
*/
Variable_ptr QTAwk_get_named_variable(
unsigned char *variable_name);
/* prototype for QTAwk function to get a QTAwk variable initialized to
a specified value.
* The returned variable is assigned the value specified, c.f.,
'QTAwk_set_value' function
* call for the the values that may be used for the first and
second arguments.
*
* If a type of "NO_VAL" is specifed, this call returns an
initialized variable set
* set to zero
*
* This is a "temporary" variable. This variable will disappear
"magically" when the
* dynamically loaded user function returns.
*
*/
Variable_ptr QTAwk_get_variable_set(
void const *value,
unsigned set_type);
/* QTAwk function top get a 'local' variable. The returned variable is
local to the
* calling dynamically loaded user function - identical to using
the "local" keyword.
* The Variable will be "lost" when the function returns.
*
* Note: the variable MUST be named, i.e., a non-NULL value must
be passed for the
* first argument, 'vname'
*
* This variable will disappear "magically" when the dynamically
loaded user function
* returns.
*
*/
Variable_ptr QTAwk_get_local_variable_set(
unsigned char *vname,
void const *value,
unsigned set_type);
/* prototype of QTAwk function to set the value of one QTAwk variable
to another
* QTAwk variable.
*
* Assign the value of QTAwk_r_variable to QTAwk_l_variable.
* Equivalent to:
* QTAwk_l_variable = QTAwk_r_variable;
*
*/
Variable_ptr QTAwk_assign(
Variable_ptr QTAwk_l_variable,
Variable_ptr QTAwk_r_variable);
/* prototype for QTAwk function to duplicate a QTAwk variable. The
specified
* variable value is duplicated and returned. Note that the
duplicate variable
* is NOT named even if the duplicated variable is named.
*/
Variable_ptr QTAwk_dup(
Variable_ptr QTAwk_variable);
/* prototype for function to execute a specified built-in function.
* 'push' function calling arguments unto the QTAwk stack prior to
the call
* returns a pointer to a QTAwk variable.
* The built-in function pops all calling arguments off the stack.
*
* The first argument is one of the defined function constants
defined above
* The second argument is the number of QTAwk variables which have
been pushed
* onto the QTAwk stack prior to the call.
*
* The second argument specifies the number of arguments in this
call for the
* arguments to the desired builtin function.
*
* The arguments for the builtin function are then the remaining
arguments in
* the call. All of these arguments are QTAwk variables.
* ALWAYS put a NULL argument at the end of the argument list to
signal the end.
* DO NOT include the terminating NULL pointer in the argument
count in the
* second argument
*
* All built-in functions except 'sub', 'gsub' and 'gensub' may be
called.
*
*/
Variable_ptr QTAwk_execute_builtin_function(
unsigned function_number,
unsigned argument_count,
...);
/* prototype for QTAwk function to determine whether variable value
represents a TRUE
* or FALSE value.
*
*/
unsigned QTAwk_true_false(
Variable_ptr QTAwk_variable);
/* prototype for QTAwk function to determine if variable indexed.
* Returns:
* -1 --> variable NOT indexed
* 0 --> indexed variable
and base variable
* index --> integer specifying the number of
indices
*
* Examples:
* assume the following QTAwk variables
* var1 is unindexed, i.e., a scalar
* var2 is indexed and has three levels of
indices, e.g., var2[3][2][4]
* Then the following calls return the values indicated:
* QTAwk_index_var(var1,&index_lvl) ==
-1
index_lvl == 0
* QTAwk_index_var(var2,&index_lvl) ==
0
index_lvl == 3
* QTAwk_index_var(var2[1],&index_lvl) ==
1 index_lvl
== 3
* QTAwk_index_var(var2[1][2],&index_lvl) ==
2 index_lvl == 3
* QTAwk_index_var(var2[1][2][2],&index_lvl) ==
3 index_lvl == 3
*
* Using the functions 'QTAwk_get_named_variable' and
'QTAwk_get_array_element' and
* 'var3' is a variable declared in the module function:
* qta_long lcl_long = 3;
* var3 = QTAwk_get_local_variable_set("var1",(void
*)&lcl_long,LONG_VAL);
* QTAwk_index_var(var3,&index_lvl) == -1
* var3 = QTAwk_get_named_variable("var2");
* QTAwk_index_var(var3,&index_lvl) == 0
* var3 = QTAwk_get_array_element(var3,"n",1); // retrieves var2[1]
* QTAwk_index_var(var3,&index_lvl) == 1
* var3 = QTAwk_get_array_element(var3,"nn",1,2); // retrieves
var2[1][2]
* QTAwk_index_var(var3,&index_lvl) == 2
* var3 = QTAwk_get_array_element(var3,"nnn",1,2,2); // retrieves
var2[1][2][2]
* QTAwk_index_var(var3,&index_lvl) == 3
*
*
* The second argument returns the number of index levels for the
variable, e.g., if
* var2 above is a 3x3 matrix, then 3 is returned in all the above
calls.
*
* NOTE: since QTAwk uses "sparse" arrays, the returned value in
the second argument
* can vary with calls usin diferent array elements within the
same array.
*
*/
int
QTAwk_index_var(
Variable_ptr QTAwk_variable,
unsigned *index_levels);
/* prototype for QTAwk function to create an array element. The indices
are specified in the
* calling arguments. The arguments are:
* 1. Variable_ptr QTAwk_variable --> the
base array variable
* 2.
void
*value -->
pointer to desired value
* 3. unsigned
set_type --> integer specifying
value type
* 4. unsigned char *index_str
--> string indicating types of indices (case ignored)
*
n == integer index
*
s == string index
* 5. index_1
* 6. index_2
* .
* .
* .
*
* For Example, to create an array element with both integer and
string indices, the first index
* being integer, 2, the second index being a string, "State", and
the third index being an
* integer, 35. We would have the following calling arguments:
*
*
QTAwk_create_array_element(var,val,type,"nsn",2,"State",35);
*
*
* Return 1, TRUE, if element successfully created, O, FALSE,
otherwise.
*
*/
unsigned QTAwk_create_array_element(
Variable_ptr QTAwk_variable,
void *value,
unsigned set_type,
unsigned char *index_str,
...);
/* prototype for QTAwk function to get an array element. The indices
are specified in the
* calling arguments. The arguments are:
* 1. Variable_ptr QTAwk_variable --> the
base array variable
* 2. unsigned char *index_str
--> string indicating types of indices (case ignored)
*
n == integer index
*
s == string index
* 3. index_1
* 4. index_2
* .
* .
* .
*
*/
Variable_ptr QTAwk_get_array_element(
Variable_ptr QTAwk_variable,
unsigned char *index_str,
...);
/* prototype for QTAwk function to return array indices for variable
specified
*
* Return integer indicates the number of indices used to specify
the array element
* passed,
*
* The second argument is set to the total number of indices for
the array element.
*
* For example if the array has been created using:
* tmp_variable =
varray[2]["State"][35]
* tmp_variable_1 =
varray[2]["State"]
* and tmp_variable_1 is passed, then the return value is 2 with
the second argument
* set to 3.
*
*/
QTAwk_index_ptr QTAwk_get_indices(
Variable_ptr QTAwk_variable,
unsigned *index_count);
/* QTAwk function to initialize array element sequence function and
* return first array element.
* Call with the variable at which to start the index sequencing.
*
* The index sequencing will be at the next level of index, e.g.,
* assuming ar is a 3x3 matrix, calling with ar would sequence
* through the elements ar[1], ar[2], ar[3]
* and calling with ar[1] would sequence through the elements
* ar[1][1] ar[1][2] ar[1][3]
*
* If there is no next level of index, this function returns zero,
0.
*
* Thus, the above two calls is similar to the statements:
* for ( i in ar )
* for ( j in ar[i] )
print(ar[i][j]);
*
* This function will return the first array element or a NULL
pointer if the
* variable specified in the first argument is not indexed. The
second argument
* is a pointer to an "unsigned" in which an integer is returned
identifying the
* array index sequence.
*
* IMPORTANT: DO NOT change the value of this integer,
*
* This integer will be passed to the sequencing function below.
*
* Arguments:
* 1. QTAwk variable to sequence through the indices
* 2. pointer to unsigned in which to store the sequencing
index
* 3. Pointer to QTAwk index structure in which to return
the index.
* If NULL then no index returned
*
*/
Variable_ptr QTAwk_first_array_element(
Variable_ptr QTAwk_variable,
unsigned *sequence_state,
QTAwk_index_ptr index_variable);
/* prototype for QTAwk function to sequence through variable indices.
Called with
* 2 arguments:
* 1. pointer to index structure defined above. The index of
the current array element
* is returned in this structure
* 2. pointer to void which is the pointer returned by the
'QTAwk_array_start' function
*
* This function returns a pointer to the next array element or
NULL if no more elements.
*
* Arguments:
* 1. integer index returned by call to
'QTAwk_first_array_element'
* 2. Pointer to QTAwk index structure in which to return
the index.
* If NULL then no index returned
*/
Variable_ptr QTAwk_next_array_element(
unsigned sequence_state,
QTAwk_index_ptr index_variable);
/* QTAwk function to terminate array element sequence function
* Call with arguments:
* 1. integer index returned by call to
'QTAwk_first_array_element'
*
*
*/
void QTAwk_array_finish(
unsigned sequence_state);
/* prototype for QTAwk function to delete array element or all of array
*
*/
void
QTAwk_array_delete(
Variable_ptr QTAwk_variable);
/* prototype for QTAwk function to retrieve field variable of current
input record
* NOTE: do Note directly change any values of the variable.
ALWAYS use the 'QTAwk_assign'
* function to change the value.
*
* f_index specifies the field variable desired and corresponds to
'$f_index'
*
*/
Variable_ptr QTAwk_get_field_var(
int f_index);
/* prototype for QTAwk function to set up a file accessable by QTAwk
utility. Return string
* by which the file is known
* NOTE: NOT IMPLEMENTED
*/
#if defined( FILE_INTERFACE )
unsigned char *QTAwk_set_file(
unsigned char *filename,
unsigned char *path,
FILE *stream);
/* prototype for QTAwk function to get a file accessable by QTAwk
utility. Return FILE stream
* pointer
* NOTE: NOT IMPLEMENTED
*/
FILE
*QTAwk_get_file(
FILE *stream);
#endif /* FILE_INTERFACE */
/* memory allocation routines - use these calls instead of the normal
* calloc/realloc/free function calls
*/
void
*QTGrep_getmem(
unsigned cnt,
size_t size);
void
*QTGrep_regetmem(
void *crnt_ptr,
size_t size);
void
*QTGrep_free_mem(
void *ptr_to_free);