gretl_func

gretl_func

Functions

#define ok_function_return_type()
int n_user_functions ()
int n_free_functions ()
ufunc * get_user_function_by_name ()
const ufunc * get_user_function_by_index ()
fncall * fncall_new ()
void fncall_destroy ()
int fn_n_params ()
int fn_param_type ()
const char * fn_param_name ()
const char * fn_param_descrip ()
const char ** fn_param_value_labels ()
int fn_param_has_default ()
double fn_param_default ()
double fn_param_minval ()
double fn_param_maxval ()
double fn_param_step ()
int fn_param_optional ()
int fn_param_uses_xlist ()
int fn_param_uses_mylist ()
int fn_param_set_const ()
int user_func_get_return_type ()
int user_func_is_noprint ()
int user_func_is_menu_only ()
const char * user_function_name_by_index ()
int user_function_index_by_name ()
int user_function_set_debug ()
void function_names_init ()
const char * next_available_function_name ()
int gretl_compiling_function ()
int gretl_compiling_python ()
int gretl_function_depth ()
int gretl_function_recursing ()
void current_function_info ()
int gretl_start_compiling_function ()
int gretl_function_append_line ()
int gretl_is_public_user_function ()
int gretl_function_exec ()
int attach_loop_to_function ()
int detach_loop_from_function ()
int set_function_should_return ()
int current_function_size ()
char * gretl_func_get_arg_name ()
int object_is_const ()
int object_is_function_arg ()
void allow_full_data_access ()
void sample_range_get_extrema ()
int function_return_type_from_string ()
int gretl_function_print_code ()
char ** gretl_function_retrieve_code ()
int print_function_package_sample ()
void set_current_function_package ()
fnpkg * function_package_new ()
int function_package_connect_funcs ()
int function_package_set_properties ()
int function_package_get_properties ()
const char * function_package_get_string ()
int function_package_set_data_files ()
char ** function_package_get_data_files ()
const char * function_package_get_name ()
int function_package_write_file ()
int create_and_write_function_package ()
int function_set_package_role ()
int function_ok_for_package_role ()
const char * package_role_get_key ()
int check_function_needs ()
int package_version_ok ()
int write_loaded_functions_file ()
int read_session_functions_file ()
fnpkg * get_function_package_by_name ()
fnpkg * get_function_package_by_filename ()
const char * get_function_package_path_by_name ()
int load_function_package_by_filename ()
int function_package_is_loaded ()
int gfn_is_loaded ()
void function_package_unload_by_filename ()
void function_package_unload_full_by_filename ()
int delete_function_package ()
int uninstall_function_package ()
int print_function_package_info ()
int print_function_package_code ()
ufunc * get_function_from_package ()
int get_function_file_header ()
double function_package_get_version ()
int user_function_help ()
int function_package_has_PDF_doc ()
int function_package_has_gui_help ()
void function_package_set_editor ()
void * function_package_get_editor ()
int package_has_menu_attachment ()
int package_needs_zipping ()
void gretl_functions_cleanup ()
int push_function_arg ()
void adjust_indent ()

Types and Values

enum DataReq
enum UfunRole
enum UfunAttrs
#define NEEDS_TS
#define NEEDS_QM
#define NEEDS_PANEL
#define NO_DATA_OK
#define FN_NAMELEN
typedef ufunc
typedef fncall
typedef fnpkg

Description

Functions

ok_function_return_type()

#define             ok_function_return_type(r)

n_user_functions ()

int
n_user_functions (void);

Returns

the number of hansl functions currently loaded in memory.


n_free_functions ()

int
n_free_functions (void);

Returns

the number of functions loaded in memory that are not currently attached to any function package, and are therefore available for packaging.


get_user_function_by_name ()

ufunc *
get_user_function_by_name (const char *name);

Parameters

name

name to test.

 

Returns

pointer to a user-function, if there exists a function of the given name and it is accessible in context (i.e. it's not private to a package other than the one that's currently active, if any), otherwise NULL.


get_user_function_by_index ()

const ufunc *
get_user_function_by_index (int idx);

Parameters

idx

index number.

 

Returns

pointer to the user-function that currently occupies (0-based) slot idx in the array of loaded functions, or NULL if idx is out of bounds.


fncall_new ()

fncall *
fncall_new (ufunc *fun);

fncall_destroy ()

void
fncall_destroy (fncall *call);

fn_n_params ()

int
fn_n_params (const ufunc *fun);

Parameters

fun

pointer to user-function.

 

Returns

the number of parameters associated with fun .


fn_param_type ()

int
fn_param_type (const ufunc *fun,
               int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

the type of parameter i of function fun .


fn_param_name ()

const char *
fn_param_name (const ufunc *fun,
               int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

the name of parameter i of function fun .


fn_param_descrip ()

const char *
fn_param_descrip (const ufunc *fun,
                  int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

the description of parameter i of function fun (if any), otherwise NULL.


fn_param_value_labels ()

const char **
fn_param_value_labels (const ufunc *fun,
                       int i,
                       int *n);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

n

location to receive number of labels.

 

Returns

the value-labels associated with parameter i of function fun (if any), otherwise NULL.


fn_param_has_default ()

int
fn_param_has_default (const ufunc *fun,
                      int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

1 if the (scalar) parameter i of function fun (if any) has a default value set, otherwise 0.


fn_param_default ()

double
fn_param_default (const ufunc *fun,
                  int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

the default value of (scalar) parameter i of function fun (if any), otherwise NADBL.


fn_param_minval ()

double
fn_param_minval (const ufunc *fun,
                 int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

the minimum value of (scalar) parameter i of function fun (if any), otherwise NADBL.


fn_param_maxval ()

double
fn_param_maxval (const ufunc *fun,
                 int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

the maximum value of (scalar) parameter i of function fun (if any), otherwise NADBL.


fn_param_step ()

double
fn_param_step (const ufunc *fun,
               int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

the step value for (scalar) parameter i of function fun (if any), otherwise NADBL.


fn_param_optional ()

int
fn_param_optional (const ufunc *fun,
                   int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

1 if parameter i of function fun is optional, otherwise 0.


fn_param_uses_xlist ()

int
fn_param_uses_xlist (const ufunc *fun,
                     int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

1 if parameter i of function fun is designed to select an integer based on a gretl model's list of regressors, otherwise 0.


fn_param_uses_mylist ()

int
fn_param_uses_mylist (const ufunc *fun,
                      int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

1 if parameter i of function fun is designed to select an integer based on a custom list, constructed by the function, otherwise 0.


fn_param_set_const ()

int
fn_param_set_const (ufunc *fun,
                    int i);

Parameters

fun

pointer to user-function.

 

i

0-based parameter index.

 

Returns

0 on successful setting of the "const" flag on parameter i of function fun , otherwise non-zero error code.


user_func_get_return_type ()

int
user_func_get_return_type (const ufunc *fun);

Parameters

fun

pointer to user-function.

 

Returns

the return type of function fun .


user_func_is_noprint ()

int
user_func_is_noprint (const ufunc *fun);

Parameters

fun

pointer to user-function.

 

Returns

1 if the function is not designed to print anything.


user_func_is_menu_only ()

int
user_func_is_menu_only (const ufunc *fun);

Parameters

fun

pointer to user-function.

 

Returns

1 if the function is not designed to be called other than via a GUI menu.


user_function_name_by_index ()

const char *
user_function_name_by_index (int i);

Parameters

i

the position of a user-function in the array of loaded functions.

 

Returns

the name of the function, or NULL if i is out of bounds.


user_function_index_by_name ()

int
user_function_index_by_name (const char *name,
                             fnpkg *pkg);

Looks up the 0-based index of the named function in the current array of user-functions. If pkg is non-NULL the search for name is confined to functions that belong to pkg ; otherwise the index of the first match is returned.

Parameters

name

function name.

 

pkg

reference function package, or NULL.

 

Returns

0-based index or -1 on failure.


user_function_set_debug ()

int
user_function_set_debug (const char *name,
                         int debug);

Enables or disables debugging for a user-defined function.

Parameters

name

the name of the function.

 

debug

boolean, if 1 then start debugging function, if 0 then stop debugging.

 

Returns

0 on success, non-zero if no function is specified or if the function is not found.


function_names_init ()

void
function_names_init (void);

next_available_function_name ()

const char *
next_available_function_name (fnpkg *pkg,
                              int *idxp);

gretl_compiling_function ()

int
gretl_compiling_function (void);

gretl_compiling_python ()

int
gretl_compiling_python (const char *line);

gretl_function_depth ()

int
gretl_function_depth (void);

gretl_function_recursing ()

int
gretl_function_recursing (void);

current_function_info ()

void
current_function_info (char const **funcname,
                       char const **pkgname);

gretl_start_compiling_function ()

int
gretl_start_compiling_function (const char *line,
                                PRN *prn);

Responds to a statement of the form "function ...". In most cases, embarks on compilation of a function, but this also handles the construction "function foo delete".

Parameters

line

command line.

 

prn

printing struct for feedback.

 

Returns

0 on success, non-zero on error.


gretl_function_append_line ()

int
gretl_function_append_line (const char *line);

Continuation of definition of user-function.

Parameters

line

line of code to append.

 

Returns

0 on success, non-zero on error.


gretl_is_public_user_function ()

int
gretl_is_public_user_function (const char *name);

Parameters

name

name to test.

 

Returns

1 if name is the name of a user-defined function that is not a private member of a function package, otherwise 0.


gretl_function_exec ()

int
gretl_function_exec (fncall *call,
                     int rtype,
                     DATASET *dset,
                     void *ret,
                     char **descrip,
                     PRN *prn);

attach_loop_to_function ()

int
attach_loop_to_function (void *ptr);

detach_loop_from_function ()

int
detach_loop_from_function (void *ptr);

set_function_should_return ()

int
set_function_should_return (const char *line);

current_function_size ()

int
current_function_size (void);

gretl_func_get_arg_name ()

char *
gretl_func_get_arg_name (const char *argvar,
                         int *err);

object_is_const ()

int
object_is_const (const char *name);

Checks whether the named object currently has 'const' status, by virtue of its being made available as a const argument to a user-defined function.

Parameters

name

name of object (e.g. matrix).

 

Returns

non-zero if the object is const, 0 if it is not.


object_is_function_arg ()

int
object_is_function_arg (const char *name);

Checks whether the named object has been made available as a function argument.

Parameters

name

name of object (e.g. matrix).

 

Returns

1 if the object has arg status, 0 otherwise.


allow_full_data_access ()

void
allow_full_data_access (int s);

sample_range_get_extrema ()

void
sample_range_get_extrema (const DATASET *dset,
                          int *t1,
                          int *t2);

Fills out t1 and/or t2 , making allowance for the possibility that we're currently executing a function, on entry to which the sample range was restricted: within the function, we are not allowed to overstep the bounds set on entry.

Parameters

dset

dataset info.

 

t1

location to receive earliest possible starting observation, or NULL.

 

t2

location to receive latest possible ending observation, or NULL.

 

function_return_type_from_string ()

int
function_return_type_from_string (const char *s);

gretl_function_print_code ()

int
gretl_function_print_code (ufunc *u,
                           int tabwidth,
                           PRN *prn);

Prints out function fun to prn , script-style.

Parameters

u

pointer to user-function.

 

tabwidth

number of spaces per "tab" (logical indent).

 

prn

printing struct.

 

Returns

0 on success, non-zero if fun is NULL.


gretl_function_retrieve_code ()

char **
gretl_function_retrieve_code (ufunc *u,
                              int *nlines);

print_function_package_sample ()

int
print_function_package_sample (const char *fname,
                               int tabwidth,
                               PRN *prn);

set_current_function_package ()

void
set_current_function_package (fnpkg *pkg);

function_package_new ()

fnpkg *
function_package_new (const char *fname,
                      char **pubnames,
                      int n_pub,
                      char **privnames,
                      int n_priv,
                      int *err);

Allocates a new package with filename-member fname , including the public and private functions named in pubnames and privnames . Note that this function does not cause the package to be written to file; for that, see write_function_package().

Parameters

fname

filename for package.

 

pubnames

array of names of public functions.

 

n_pub

number of strings in pubnames .

 

privnames

array of names of private functions (or NULL).

 

n_priv

number of strings in privnames (may be 0).

 

err

location to receive error code.

 

Returns

pointer to package on success, NULL on error.


function_package_connect_funcs ()

int
function_package_connect_funcs (fnpkg *pkg,
                                char **pubnames,
                                int n_pub,
                                char **privnames,
                                int n_priv);

Looks up the functions named in pubnames and privnames and adds pointers to these functions to pkg , hence marking the functions as belonging to pkg .

Parameters

pkg

function package.

 

pubnames

array of names of public functions.

 

n_pub

number of strings in pubnames .

 

privnames

array of names of private functions (or NULL).

 

n_priv

number of strings in privnames (may be 0).

 

Returns

0 on success, non-zero on error.


function_package_set_properties ()

int
function_package_set_properties (fnpkg *pkg,
                                 ...);

function_package_get_properties ()

int
function_package_get_properties (fnpkg *pkg,
                                 ...);

function_package_get_string ()

const char *
function_package_get_string (fnpkg *pkg,
                             const char *id);

function_package_set_data_files ()

int
function_package_set_data_files (fnpkg *pkg,
                                 char **S,
                                 int n);

function_package_get_data_files ()

char **
function_package_get_data_files (fnpkg *pkg,
                                 int *n);

function_package_get_name ()

const char *
function_package_get_name (fnpkg *pkg);

Parameters

pkg

function package.

 

Returns

the name of the package.


function_package_write_file ()

int
function_package_write_file (fnpkg *pkg);

Write out pkg as an XML file, using the filename recorded in the package.

Parameters

pkg

function package.

 

Returns

0 on success, non-zero on error.


create_and_write_function_package ()

int
create_and_write_function_package (const char *fname,
                                   gretlopt opt,
                                   PRN *prn);

Create a package based on the functions currently loaded, and write it out as an XML file. Responds to the makepkg command.

Parameters

fname

filename for function package.

 

opt

may include OPT_I to write a package-index entry, OPT_T to write translatable strings.

 

prn

printer struct for feedback.

 

Returns

0 on success, non-zero on error.


function_set_package_role ()

int
function_set_package_role (const char *name,
                           fnpkg *pkg,
                           const char *attr,
                           PRN *prn);

function_ok_for_package_role ()

int
function_ok_for_package_role (const char *name,
                              int role);

package_role_get_key ()

const char *
package_role_get_key (int flag);

check_function_needs ()

int
check_function_needs (const DATASET *dset,
                      DataReq dreq,
                      int minver);

Checks whether the requirements in dreq and minver are jointly satisfied by the current dataset and gretl version.

Parameters

dset

pointer to dataset info.

 

dreq

function data requirements flag.

 

minver

function minimum program version requirement.

 

Returns

0 if all is OK; E_DATA if the current dataset (or lack thereof) does not satisfy dreq ; 1 otherwise.


package_version_ok ()

int
package_version_ok (int minver,
                    char *reqstr);

Parameters

minver

function package minimum program version requirement.

 

reqstr

location to write required version string (should be at least 8 bytes), or NULL.

 

Returns

1 if the running version of gretl satisfies the minimum version requirement in minver ; otherwise returns 0, in which case the string representation of minver is written reqstr if this is non-NULL.


write_loaded_functions_file ()

int
write_loaded_functions_file (const char *fname,
                             int mpicall);

read_session_functions_file ()

int
read_session_functions_file (const char *fname);

get_function_package_by_name ()

fnpkg *
get_function_package_by_name (const char *pkgname);

Parameters

pkgname

name of function package.

 

Returns

pointer to function package if a package named pkgname is already in memory, otherwise NULL.


get_function_package_by_filename ()

fnpkg *
get_function_package_by_filename (const char *fname,
                                  int *err);

If the package whose filename is fname is already loaded, returns the package pointer, otherwise attempts to load the package from file. Similar to load_function_package_from_file() but returns the package pointer rather than just a status code.

Parameters

fname

gfn filename.

 

err

location to receive error code.

 

Returns

package-pointer on success, NULL on error.


get_function_package_path_by_name ()

const char *
get_function_package_path_by_name (const char *pkgname);

Parameters

pkgname

name of function package.

 

Returns

the full path to the named function package if it is already in memory, otherwise NULL.


load_function_package_by_filename ()

int
load_function_package_by_filename (const char *fname,
                                   gretlopt opt,
                                   PRN *prn);

Loads the function package located by fname into memory, if possible. Supports gretl's "include" command for gfn files.

Parameters

fname

full path to gfn file.

 

opt

may include OPT_F to force loading even when the package is already loaded.

 

prn

gretl printer.

 

Returns

0 on success, non-zero code on error.


function_package_is_loaded ()

int
function_package_is_loaded (const char *fname,
                            const char **version);

Parameters

fname

full path to gfn file.

 

version

location to receive version info, or NULL.

 

Returns

1 if the function package with filename fname is loaded in memory, otherwise 0.


gfn_is_loaded ()

int
gfn_is_loaded (const char *gfnname);

Parameters

gfnname

basename of gfn file, including suffix.

 

Returns

1 if the function package with basename gfnname is loaded in memory, otherwise 0.


function_package_unload_by_filename ()

void
function_package_unload_by_filename (const char *fname);

Unloads the specified function package from memory, if it is currently loaded. The functions 'owned' by the package are not destroyed; they become available for inclusion in other packages.

Parameters

fname

package filename.

 

function_package_unload_full_by_filename ()

void
function_package_unload_full_by_filename
                               (const char *fname);

Unloads the specified function package from memory, if it is currently loaded. The functions 'owned' by the package are also unloaded from memory.

Parameters

fname

package filename.

 

delete_function_package ()

int
delete_function_package (const char *gfnname);

Deletes gfnname , taking care of deleting its enclosing specific subdirectory and all of its contents if applicable.

Parameters

gfnname

full path to gfn file.

 

Returns

0 on success, non-zero code on error.


uninstall_function_package ()

int
uninstall_function_package (const char *package,
                            gretlopt opt,
                            PRN *prn);

Parameters

package

name of package (with or without .gfn extension).

 

opt

option flag(s).

 

prn

gretl printer.

 

Returns

0 on success, non-zero code on error.


print_function_package_info ()

int
print_function_package_info (const char *fname,
                             PRN *prn);

print_function_package_code ()

int
print_function_package_code (const char *fname,
                             int tabwidth,
                             PRN *prn);

get_function_from_package ()

ufunc *
get_function_from_package (const char *funname,
                           fnpkg *pkg);

Parameters

funname

name if fuction to retrieve.

 

pkg

function package.

 

Returns

pointer to a user-function, if there exists a function of the given funname that is associated with function package pkg , otherwise NULL. This is used in the gretl function package editor.


get_function_file_header ()

int
get_function_file_header (const char *fname,
                          char **pdesc,
                          char **pver,
                          char **pdate,
                          char **pauthor,
                          int *pdfdoc);

function_package_get_version ()

double
function_package_get_version (const char *fname);

user_function_help ()

int
user_function_help (const char *fnname,
                    gretlopt opt,
                    PRN *prn);

Looks for a function named fnname and prints as much help information as possible.

Parameters

fnname

name of function.

 

opt

may include OPT_M for adding markup, OPT_G for preferring GUI-specific help, if available.

 

prn

printing struct.

 

Returns

0 on success, non-zero if the function is not found.


function_package_has_PDF_doc ()

int
function_package_has_PDF_doc (fnpkg *pkg,
                              char **pdfname);

Checks whether pkg is documented in the form of a PDF file.

Parameters

pkg

function-package pointer.

 

pdfname

location to receive basename of PDF file, if applicable (or NULL if this is not wanted).

 

Returns

1 if so (in which case the name of that file is returned via pdfname ), 0 otherwise.


function_package_has_gui_help ()

int
function_package_has_gui_help (fnpkg *pkg);

Checks whether pkg has GUI-specific help text.

Parameters

pkg

function-package pointer.

 

Returns

1 if so, 0 otherwise.


function_package_set_editor ()

void
function_package_set_editor (fnpkg *pkg,
                             void *editor);

function_package_get_editor ()

void *
function_package_get_editor (fnpkg *pkg);

package_has_menu_attachment ()

int
package_has_menu_attachment (const char *fname,
                             char **pkgname,
                             char **attach,
                             char **label);

package_needs_zipping ()

int
package_needs_zipping (const char *fname,
                       int *pdfdoc,
                       char ***datafiles,
                       int *n_files);

gretl_functions_cleanup ()

void
gretl_functions_cleanup (void);

For internal use: frees all resources associated with user-defined functions and function packages.


push_function_arg ()

int
push_function_arg (fncall *fc,
                   const char *name,
                   GretlType type,
                   void *value);

Writes a new argument of the specified type and value into the argument array of fun .

Parameters

fc

pointer to function call.

 

name

name of variable (or NULL for anonymous)

 

type

type of argument to add.

 

value

pointer to value to add.

 

Returns

0 on success, non-zero on failure.


adjust_indent ()

void
adjust_indent (const char *line,
               int *this_indent,
               int *next_indent);

Types and Values

enum DataReq

Members

FN_NEEDS_DATA

   

FN_NEEDS_TS

   

FN_NEEDS_QM

   

FN_NEEDS_PANEL

   

FN_NODATA_OK

   

enum UfunRole

Members

UFUN_ROLE_NONE

   

UFUN_BUNDLE_PRINT

   

UFUN_BUNDLE_PLOT

   

UFUN_BUNDLE_TEST

   

UFUN_BUNDLE_FCAST

   

UFUN_BUNDLE_EXTRA

   

UFUN_GUI_MAIN

   

UFUN_GUI_PRECHECK

   

UFUN_LIST_MAKER

   

UFUN_ROLE_MAX

   

enum UfunAttrs

Members

UFUN_PRIVATE

   

UFUN_PLUGIN

   

UFUN_NOPRINT

   

UFUN_MENU_ONLY

   

NEEDS_TS

#define NEEDS_TS    "needs-time-series-data"

NEEDS_QM

#define NEEDS_QM    "needs-qm-data"

NEEDS_PANEL

#define NEEDS_PANEL "needs-panel-data"

NO_DATA_OK

#define NO_DATA_OK  "no-data-ok"

FN_NAMELEN

#define FN_NAMELEN 32

ufunc

typedef struct ufunc_ ufunc;

fncall

typedef struct fncall_ fncall;

fnpkg

typedef struct fnpkg_ fnpkg;