gretl_xml: Libgretl Reference Manual

gretl_xml

Functions

void	gretl_xml_header ()
int	gretl_xml_open_doc_root ()
int	gretl_xml_read_buffer ()
void	gretl_xml_put_int ()
void	gretl_xml_put_unsigned ()
void	gretl_xml_put_double ()
void	gretl_xml_put_double_array ()
void	gretl_xml_put_strings_array ()
void	gretl_xml_put_strings_array_quoted ()
void	gretl_xml_put_tagged_list ()
int	gretl_xml_put_string ()
int	gretl_xml_get_prop_as_int ()
int	gretl_xml_get_prop_as_opt ()
unsigned int	gretl_xml_get_prop_as_unsigned_int ()
int	gretl_xml_get_prop_as_uchar ()
int	gretl_xml_get_prop_as_double ()
int	gretl_xml_get_prop_as_string ()
int	gretl_xml_get_prop_as_bool ()
GretlType	gretl_xml_get_type_property ()
int	gretl_xml_node_get_int ()
int	gretl_xml_node_get_unsigned ()
int	gretl_xml_node_get_double ()
int *	gretl_xml_get_list ()
int	gretl_xml_node_get_string ()
char *	gretl_xml_get_string ()
int	gretl_xml_node_get_trimmed_string ()
int	gretl_xml_child_get_string ()
int *	gretl_xml_get_int_array ()
double *	gretl_xml_get_double_array ()
cmplx *	gretl_xml_get_cmplx_array ()
char **	gretl_xml_get_strings_array ()
int	gretl_xml_child_get_strings_array ()
gretl_matrix *	gretl_xml_get_matrix ()
int	gretl_xml_get_submask ()
void	gretl_xml_put_tagged_string ()
void	gretl_xml_put_tagged_string_plus ()
void	gretl_matrix_serialize ()
void	gretl_list_serialize ()
void	gretl_finite_scalar_serialize ()
void	gretl_string_serialize ()
int	gretl_matrix_write_as_gdt ()
int	gretl_write_gdt ()
int	gretl_write_gdt_to_prn ()
int	gretl_read_gdt ()
int	gretl_read_gdt_subset ()
int	gretl_read_gdt_varnames ()
char *	gretl_get_gdt_description ()
int	load_XML_functions_file ()
char *	gretl_XML_escape ()

Types and Values

#define

XUC

Description

Functions

gretl_xml_header ()

void
gretl_xml_header (PRN *prn);

gretl_xml_open_doc_root ()

int
gretl_xml_open_doc_root (const char *fname,
                         const char *rootname,
                         xmlDocPtr *pdoc,
                         xmlNodePtr *pnode);

gretl_xml_read_buffer ()

int
gretl_xml_read_buffer (const char *buf,
                       const char *rootname,
                       xmlDocPtr *pdoc,
                       xmlNodePtr *pnode);

gretl_xml_put_int ()

void
gretl_xml_put_int (const char *tag,
                   int i,
                   PRN *prn);

Writes to fp a string of the form "%s=%d".

Parameters

tag	name to give value.
i	value to put (as attribute)
fp	file to which to write.

gretl_xml_put_unsigned ()

void
gretl_xml_put_unsigned (const char *tag,
                        unsigned int u,
                        PRN *prn);

Writes to fp a string of the form "%s=%u".

Parameters

tag	name to give value.
i	value to put (as attribute)
fp	file to which to write.

gretl_xml_put_double ()

void
gretl_xml_put_double (const char *tag,
                      double x,
                      PRN *prn);

Writes to fp a string of the form "%s=%.17g" if the value of x is valid, otherwise "%s=NA".

Parameters

tag	name to give value.
x	value to put (as attribute)
fp	file to which to write.

gretl_xml_put_double_array ()

void
gretl_xml_put_double_array (const char *tag,
                            double *x,
                            int n,
                            PRN *prn);

Parameters

tag	name to give array.
x	values to put.
n	number of values in `x` .
fp	file to which to write.

gretl_xml_put_strings_array ()

void
gretl_xml_put_strings_array (const char *tag,
                             const char **strs,
                             int n,
                             PRN *prn);

Parameters

tag	name to give array.
strs	array of strings to put.
n	number of strings in `strs` .
fp	file to which to write.

gretl_xml_put_strings_array_quoted ()

void
gretl_xml_put_strings_array_quoted (const char *tag,
                                    const char **strs,
                                    int n,
                                    PRN *prn);

Parameters

tag	name to give array.
strs	array of strings to put.
n	number of strings in `strs` .
fp	file to which to write.

gretl_xml_put_tagged_list ()

void
gretl_xml_put_tagged_list (const char *tag,
                           const int *list,
                           PRN *prn);

Parameters

tag	tag in which list should be wrapped.
list	list of integers to be written.
fp	file to which to write.

gretl_xml_put_string ()

int
gretl_xml_put_string (const char *str,
                      PRN *prn);

Write str to fp . If str needs to have XML-special characters escaped, this will be done automatically. If str is NULL, this is considered a no-op.

Parameters

str	string to put.
fp	file to which to write.

Returns

0 on success, non-zero error code on failure.

gretl_xml_get_prop_as_int ()

int
gretl_xml_get_prop_as_int (xmlNodePtr node,
                           const char *tag,
                           int *i);

Parameters

node	XML node pointer.
tag	name by which integer property is known.
i	location to write int value.

Returns

1 if an int is found and read successfully, 0 otherwise.

gretl_xml_get_prop_as_opt ()

int
gretl_xml_get_prop_as_opt (xmlNodePtr node,
                           const char *tag,
                           gretlopt *o);

Parameters

node	XML node pointer.
tag	name by which integer property is known.
o	location to write gretlopt value.

Returns

1 if an int is found and read successfully, 0 otherwise.

gretl_xml_get_prop_as_unsigned_int ()

unsigned int
gretl_xml_get_prop_as_unsigned_int (xmlNodePtr node,
                                    const char *tag,
                                    unsigned int *u);

Parameters

node	XML node pointer.
tag	name by which unsigned integer property is known.
u	location to write value.

Returns

1 if an unsigned int is found and read successfully, 0 otherwise.

gretl_xml_get_prop_as_uchar ()

int
gretl_xml_get_prop_as_uchar (xmlNodePtr node,
                             const char *tag,
                             unsigned char *u);

Parameters

node	XML node pointer.
tag	name by which unsigned character property is known.
u	location to write value.

Returns

1 if an unsigned char is found and read successfully, 0 otherwise.

gretl_xml_get_prop_as_double ()

int
gretl_xml_get_prop_as_double (xmlNodePtr node,
                              const char *tag,
                              double *x);

Parameters

node	XML node pointer.
tag	name by which floating-point property is known.
x	location to write double value.

Returns

1 if a double is found and read successfully, 0 otherwise.

gretl_xml_get_prop_as_string ()

int
gretl_xml_get_prop_as_string (xmlNodePtr node,
                              const char *tag,
                              char **pstr);

Parameters

node	XML node pointer.
tag	name by which string property is known.
pstr	location to assign string.

Returns

1 if a string is found and read successfully, 0 otherwise.

gretl_xml_get_prop_as_bool ()

int
gretl_xml_get_prop_as_bool (xmlNodePtr node,
                            const char *tag);

Parameters

node	XML node pointer.
tag	name by which property is known.

Returns

1 if the named property is found and has value true, else 0.

gretl_xml_get_type_property ()

GretlType
gretl_xml_get_type_property (xmlNodePtr node);

Parameters

node

XML node pointer.

Returns

the gretl type identifier associated with the property tagged "type" on node , or 0 on failure.

gretl_xml_node_get_int ()

int
gretl_xml_node_get_int (xmlNodePtr node,
                        xmlDocPtr doc,
                        int *i);

Parameters

node	XML node pointer.
doc	XML document pointer.
i	location to receive integer.

Returns

1 if an int is found and read successfully, 0 otherwise.

gretl_xml_node_get_unsigned ()

int
gretl_xml_node_get_unsigned (xmlNodePtr node,
                             xmlDocPtr doc,
                             unsigned int *u);

Parameters

node	XML node pointer.
doc	XML document pointer.
i	location to receive integer.

Returns

1 if an unsigned int is found and read successfully, 0 otherwise.

gretl_xml_node_get_double ()

int
gretl_xml_node_get_double (xmlNodePtr node,
                           xmlDocPtr doc,
                           double *x);

Parameters

node	XML node pointer.
doc	XML document pointer.
x	location to receive double.

Returns

1 if a double is found and read successfully, 0 otherwise.

gretl_xml_get_list ()

int *
gretl_xml_get_list (xmlNodePtr node,
                    xmlDocPtr doc,
                    int *err);

Parameters

node	XML node pointer.
doc	XML document pointer.
err	location to receive error code.

Returns

allocated list read from node , or NULL on failure.

gretl_xml_node_get_string ()

int
gretl_xml_node_get_string (xmlNodePtr node,
                           xmlDocPtr doc,
                           char **pstr);

Parameters

node	XML node pointer.
doc	XML document pointer.
pstr	location to receive string.

Returns

1 if a string is found and read successfully, 0 otherwise.

gretl_xml_get_string ()

char *
gretl_xml_get_string (xmlNodePtr node,
                      xmlDocPtr doc);

Parameters

node	XML node pointer.
doc	XML document pointer.

Returns

allocated copy of the string content of node , or NULL on error.

gretl_xml_node_get_trimmed_string ()

int
gretl_xml_node_get_trimmed_string (xmlNodePtr node,
                                   xmlDocPtr doc,
                                   char **pstr);

Reads a string from node and trims both leading and trailing white space.

Parameters

node	XML node pointer.
doc	XML document pointer.
pstr	location to receive string.

Returns

1 if a string is found and read successfully, 0 otherwise.

gretl_xml_child_get_string ()

int
gretl_xml_child_get_string (xmlNodePtr node,
                            xmlDocPtr doc,
                            const char *name,
                            char **pstr);

Parameters

node	XML node pointer.
doc	XML document pointer.
name	name of child node.
pstr	location to receive string.

Returns

1 if a string is found and read successfully, 0 otherwise.

gretl_xml_get_int_array ()

int *
gretl_xml_get_int_array (xmlNodePtr node,
                         xmlDocPtr doc,
                         int *nelem,
                         int *err);

Parameters

node	XML node pointer.
doc	XML document pointer.
nelem	location to receive number of elements in array.
err	location to receive error code.

Returns

allocated array of integers read from node , or NULL on failure.

gretl_xml_get_double_array ()

double *
gretl_xml_get_double_array (xmlNodePtr node,
                            xmlDocPtr doc,
                            int *nelem,
                            int *err);

Parameters

node	XML node pointer.
doc	XML document pointer.
nelem	location to receive number of elements in array.
err	location to receive error code.

Returns

allocated array of doubles read from node , or NULL on failure.

gretl_xml_get_cmplx_array ()

cmplx *
gretl_xml_get_cmplx_array (xmlNodePtr node,
                           xmlDocPtr doc,
                           int *nelem,
                           int *err);

Parameters

node	XML node pointer.
doc	XML document pointer.
nelem	location to receive number of elements in array.
err	location to receive error code.

Returns

allocated array of cmplx (complex numbers) read from node , or NULL on failure.

gretl_xml_get_strings_array ()

char **
gretl_xml_get_strings_array (xmlNodePtr node,
                             xmlDocPtr doc,
                             int *nelem,
                             int slop,
                             int *err);

Parameters

node	XML node pointer.
doc	XML document pointer.
nelem	location to receive number of elements in array.
slop	if non-zero, allow the number of strings to fall short of the recorded string count by one.
err	location to receive error code.

Returns

allocated array of strings read from node , or NULL on failure.

gretl_xml_child_get_strings_array ()

int
gretl_xml_child_get_strings_array (xmlNodePtr node,
                                   xmlDocPtr doc,
                                   const char *name,
                                   char ***pstrs,
                                   int *nstrs);

Parameters

node	XML node pointer.
doc	XML document pointer.
name	name of child node.
pstrs	location to receive strings array.
nstrs	location to receive number of strings.

Returns

1 if an array of strings is found and read successfully, 0 otherwise.

gretl_xml_get_matrix ()

gretl_matrix *
gretl_xml_get_matrix (xmlNodePtr node,
                      xmlDocPtr doc,
                      int *err);

Parameters

node	XML node pointer.
doc	XML document pointer.
err	location to receive error code.

Returns

allocated gretl matrix read from node , or NULL on failure.

gretl_xml_get_submask ()

int
gretl_xml_get_submask (xmlNodePtr node,
                       xmlDocPtr doc,
                       char **pmask);

Parameters

node	XML node pointer.
doc	XML document pointer.
pmask	location to receive allocated mask.

Returns

0 on success, non-zero on failure.

gretl_xml_put_tagged_string ()

void
gretl_xml_put_tagged_string (const char *tag,
                             const char *str,
                             PRN *prn);

Write str to fp , enclosed in simple starting and ending tags specified by tag . If str needs to have XML-special characters escaped, this will be done automatically. If str is NULL, this is considered a no-op.

Parameters

tag	name to give string.
str	string to put.
fp	file to which to write.

Returns

0 on success, non-zero error code on failure.

gretl_xml_put_tagged_string_plus ()

void
gretl_xml_put_tagged_string_plus (const char *tag,
                                  const char *str,
                                  const char *attrib,
                                  const char *attval,
                                  PRN *prn);

Similar to gretl_xml_put_tagged_string(), but allows (in fact, requires) an attribute name and value along with the element name and value.

Parameters

tag	name to give string.
str	string to put.
attrib	name of attribute.
attval	value of attribute.
fp	file to which to write.

Returns

0 on success, non-zero error code on failure.

gretl_matrix_serialize ()

void
gretl_matrix_serialize (const gretl_matrix *m,
                        const char *name,
                        PRN *prn);

Parameters

m	matrix to be written.
name	name for matrix, or NULL.
fp	stream to which to print.

gretl_list_serialize ()

void
gretl_list_serialize (const int *list,
                      const char *name,
                      PRN *prn);

Parameters

list	list of integers to be written.
name	name to give list, or NULL.
fp	file to which to write.

gretl_finite_scalar_serialize ()

void
gretl_finite_scalar_serialize (double x,
                               const char *name,
                               PRN *prn);

Note: not suitable for writing non-finite values.

Parameters

x	numerical value.
name	name of object.
fp	stream for writing.

gretl_string_serialize ()

void
gretl_string_serialize (const char *s,
                        const char *name,
                        PRN *prn);

Parameters

s	UTF-8 string.
name	name of object.
fp	stream for writing.

gretl_matrix_write_as_gdt ()

int
gretl_matrix_write_as_gdt (const char *fname,
                           const gretl_matrix *X,
                           const char **varnames,
                           const char **labels);

Write out a .gdt data file containing the elements of of the given matrix.

Parameters

fname	name of file to write.
X	matrix, variable in columns.
varnames	column names.
labels	descriptive labels for the variables, or `NULL`.

Returns

0 on successful completion, non-zero on error.

gretl_write_gdt ()

int
gretl_write_gdt (const char *fname,
                 const int *list,
                 const DATASET *dset,
                 gretlopt opt,
                 int progress);

Write out in xml a data file containing the values of the given set of variables.

Parameters

fname	name of file to write.
list	list of variables to write (or `NULL` to write all).
dset	dataset struct.
opt	if `OPT_Z` write gzipped data, else uncompressed; if `OPT_F` write full data and include sample range data.
progress	may be 1 when called from gui to display progress bar in case of a large data write; generally should be 0.

Returns

0 on successful completion, non-zero on error.

gretl_write_gdt_to_prn ()

int
gretl_write_gdt_to_prn (PRN *prn,
                        const int *list,
                        const DATASET *dset);

gretl_read_gdt ()

int
gretl_read_gdt (const char *fname,
                DATASET *dset,
                gretlopt opt,
                PRN *prn);

Read data from native file into gretl's workspace.

Parameters

fname	name of file to open for reading.
dset	dataset struct.
opt	use OPT_B to display gui progress bar; may also use OPT_T when appending to panel data (see the "append" command in the gretl manual). Otherwise use OPT_NONE.
prn	where any messages should be written.

Returns

0 on successful completion, non-zero otherwise.

gretl_read_gdt_subset ()

int
gretl_read_gdt_subset (const char *fname,
                       DATASET *dset,
                       int *vlist,
                       gretlopt opt);

Read specified series from native file into dset , which should be "empty" on input.

Parameters

fname	name of file to open for reading.
dset	dataset struct.
vlist	list of series to extract.
opt	may include OPT_M to retrieve the observation markers associated with the data, if any.

Returns

0 on successful completion, non-zero otherwise.

gretl_read_gdt_varnames ()

int
gretl_read_gdt_varnames (const char *fname,
                         char ***vnames,
                         int *nvars);

Read the array of series names from the specified file.

Parameters

fname	name of file to open for reading.
vnames	location to receive array of series names.
nvars	location to receive the number of series.

Returns

0 on successful completion, non-zero otherwise.

gretl_get_gdt_description ()

char *
gretl_get_gdt_description (const char *fname,
                           int *err);

Read data description for gretl native data file.

Parameters

fname

name of file to try.

Returns

buffer containing description, or NULL on failure.

load_XML_functions_file ()

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

gretl_XML_escape ()

char *
gretl_XML_escape (const char *s);

Types and Values

XUC

#define XUC const xmlChar *