PRN

PRN — gretl printing struct

Synopsis

#include <libgretl.h>

typedef             PRN;
enum                PrnType;
enum                PrnFormat;
PRN *               gretl_print_new                     (PrnType ptype,
                                                         int *err);
void                gretl_print_destroy                 (PRN *prn);
PRN *               gretl_print_new_with_filename       (const char *fname,
                                                         int *err);
PRN *               gretl_print_new_with_tempfile       (int *err);
int                 gretl_print_has_tempfile            (PRN *prn);
const char *        gretl_print_get_tempfile_name       (PRN *prn);
PRN *               gretl_print_new_with_buffer         (char *buf);
PRN *               gretl_print_new_with_stream         (FILE *fp);
void                gretl_print_detach_stream           (PRN *prn);
int                 gretl_print_reset_buffer            (PRN *prn);
int                 gretl_print_rename_file             (PRN *prn,
                                                         const char *oldpath,
                                                         const char *newpath);
const char *        gretl_print_get_buffer              (PRN *prn);
const char *        gretl_print_get_trimmed_buffer      (PRN *prn);
char *              gretl_print_steal_buffer            (PRN *prn);
void                gretl_print_get_size                (PRN *prn,
                                                         int *width,
                                                         int *height);
FILE *              gretl_print_read_tempfile           (PRN *prn);
int                 gretl_print_stop_tempfile_read      (PRN *prn,
                                                         FILE *fp);
int                 gretl_print_set_save_position       (PRN *prn);
void                gretl_print_unset_save_position     (PRN *prn);
char *              gretl_print_get_chunk               (PRN *prn);
void                gretl_print_set_format              (PRN *prn,
                                                         PrnFormat format);
void                gretl_print_toggle_doc_flag         (PRN *prn);
void                gretl_print_set_utf_flag            (PRN *prn);
int                 gretl_print_supports_utf            (PRN *prn);
void                gretl_print_set_delim               (PRN *prn,
                                                         char delim);
int                 pprintf                             (PRN *prn,
                                                         const char *format,
                                                         ...);
int                 pputs                               (PRN *prn,
                                                         const char *s);
int                 pputc                               (PRN *prn,
                                                         int c);
void                gretl_prn_newline                   (PRN *prn);
void                gretl_print_flush_stream            (PRN *prn);
int                 printing_to_standard_stream         (PRN *prn);
int                 printing_is_redirected              (PRN *prn);
int                 print_start_redirection             (PRN *prn,
                                                         FILE *fp);
int                 print_end_redirection               (PRN *prn);
int                 plain_format                        (PRN *prn);
int                 rtf_format                          (PRN *prn);
int                 rtf_doc_format                      (PRN *prn);
int                 tex_format                          (PRN *prn);
int                 tex_doc_format                      (PRN *prn);
int                 tex_eqn_format                      (PRN *prn);
int                 csv_format                          (PRN *prn);
int                 prn_format                          (PRN *prn);
char                prn_delim                           (PRN *prn);
int                 gretl_print_has_buffer              (PRN *prn);
int                 gretl_print_alloc                   (PRN *prn,
                                                         size_t s);
PRN *               set_up_verbose_printer              (gretlopt opt,
                                                         PRN *prn);
void                close_down_verbose_printer          (PRN *vprn);

Description

Most libgretl functions that print output call for a pointer-to-PRN as one of their arguments. The PRN type is an opaque structure, constructed and manipulated by the functions listed here. It is used as a means of generalizing the printing operation, which may be to a regular file, a temporary file or a buffer.

To get hold of a PRN use gretl_print_new() or one of the more specific constructors, and to free it use gretl_print_destroy(). If you want to use a PRN dirctly for printing in your own code, use the functions pprintf(), pputs() and pputc(). These are counterparts to the standard C functions fprintf, fputs and fputc, but note that with pputs and pputc the PRN argument must be given first (unlike fputs and fputc in which the FILE argument goes last).

Note that whenever a PRN appears as a function parameter in libgretl it is OK to give a NULL argument: in that case printing is suppressed. (This obviously makes sense only if the function in question does something besides just printing.)

Details

PRN

typedef struct PRN_ PRN;

An opaque structure accessed only via gretl_print functions.


enum PrnType

typedef enum {
    GRETL_PRINT_STDOUT,
    GRETL_PRINT_STDERR,
    GRETL_PRINT_FILE,
    GRETL_PRINT_BUFFER,
    GRETL_PRINT_TEMPFILE,
    GRETL_PRINT_STREAM
} PrnType;


enum PrnFormat

typedef enum {
    GRETL_FORMAT_TXT       = 1 << 0,
    GRETL_FORMAT_TEX       = 1 << 1,
    GRETL_FORMAT_DOC       = 1 << 2,
    GRETL_FORMAT_RTF       = 1 << 3,
    GRETL_FORMAT_RTF_TXT   = 1 << 4,
    GRETL_FORMAT_EQN       = 1 << 5,
    GRETL_FORMAT_SELECTION = 1 << 6,
    GRETL_FORMAT_CSV       = 1 << 7,
    GRETL_FORMAT_TAB       = 1 << 8,
    GRETL_FORMAT_MODELTAB  = 1 << 9,
    GRETL_FORMAT_LANDSCAPE = 1 << 10,
    GRETL_FORMAT_UTF       = 1 << 11
} PrnFormat;


gretl_print_new ()

PRN *               gretl_print_new                     (PrnType ptype,
                                                         int *err);

Create and initialize a gretl printing struct. If ptype is GRETL_PRINT_BUFFER, output will go to an automatically resized buffer; if ptype is GRETL_PRINT_STDOUT or GRETL_PRINT_STDERR output goes to stdout or stderr respectively.

If you want a named file associated with the struct, use gretl_print_new_with_filename instead; if you want to attach a fixed, pre-allocated text buffer, use gretl_print_new_with_buffer.

ptype :

code indicating the desired printing mode.

err :

location to receive error code, or NULL.

Returns :

pointer to newly created struct, or NULL on failure.

gretl_print_destroy ()

void                gretl_print_destroy                 (PRN *prn);

Close a gretl printing struct and free any associated resources.

prn :

pointer to gretl printing struct.

gretl_print_new_with_filename ()

PRN *               gretl_print_new_with_filename       (const char *fname,
                                                         int *err);

Create and initialize a gretl printing struct, with output directed to the named file.

fname :

name of the file to be opened for writing.

err :

location to receive error code.

Returns :

pointer to newly created struct, or NULL on failure.

gretl_print_new_with_tempfile ()

PRN *               gretl_print_new_with_tempfile       (int *err);

Create and initialize a gretl printing struct, with output directed to a temporary file, which is deleted when the printing struct is destroyed.

err :

location to receive error code.

Returns :

pointer to newly created struct, or NULL on failure.

gretl_print_has_tempfile ()

int                 gretl_print_has_tempfile            (PRN *prn);

prn :

printing struct to test.

Returns :

1 if prn has a tempfile attached, else 0.

gretl_print_get_tempfile_name ()

const char *        gretl_print_get_tempfile_name       (PRN *prn);

prn :

printing struct to test.

Returns :

if prn has a tempfile attached, return the name of that file, otherwise return NULL.

gretl_print_new_with_buffer ()

PRN *               gretl_print_new_with_buffer         (char *buf);

Creates and initializes a gretl printing struct, with fixed text buffer buf. Fails if buf is NULL. This is a convenience function: you can't use pprintf, pputs or pputc with a printing struct obtained in this way.

Note that buf will be freed if and when gretl_print_destroy is called on the PRN pointer obtained.

buf :

pre-allocated text buffer.

Returns :

pointer to newly created struct, or NULL on failure.

gretl_print_new_with_stream ()

PRN *               gretl_print_new_with_stream         (FILE *fp);

Creates and initializes a gretl printing struct, with printing to fp.

Note that fp will be closed if and when gretl_print_destroy is called on the PRN pointer obtained.

fp :

pre-opened stream.

Returns :

pointer to newly created struct, or NULL on failure.

gretl_print_detach_stream ()

void                gretl_print_detach_stream           (PRN *prn);

Sets the stream member of prn to NULL so that prn can be destroyed without closing the associated stream. May be used in conjunction with gretl_print_new_with_stream().

prn :

printing struct to operate on.

gretl_print_reset_buffer ()

int                 gretl_print_reset_buffer            (PRN *prn);

If prn has an attached buffer, write a NUL byte to the start of the buffer and reset the count of bytes printed to zero. The next call to pprintf or similar will then overwite rather than cumulating the printed content.

prn :

printing struct to operate on.

Returns :

0 on success, 1 if prn has no buffer.

gretl_print_rename_file ()

int                 gretl_print_rename_file             (PRN *prn,
                                                         const char *oldpath,
                                                         const char *newpath);

If prn is printing to a FILE pointer, rename the file to which it is printing and switch the stream to the new file.

prn :

printing struct to operate on.

oldpath :

name of current file (or NULL if prn was set up using gretl_print_new_with_tempfile).

newpath :

new name for file.

Returns :

0 on success, 1 on error.

gretl_print_get_buffer ()

const char *        gretl_print_get_buffer              (PRN *prn);

Obtain a pointer to the buffer associated with prn, if any. This pointer must not be modified in any way.

prn :

printing struct.

Returns :

the buffer, or NULL on failure.

gretl_print_get_trimmed_buffer ()

const char *        gretl_print_get_trimmed_buffer      (PRN *prn);

Obtain a pointer to the buffer associated with prn, if any. This pointer must not be modified in any way. An opening newline is skipped and any trailing white space is substituted by NULs.

prn :

printing struct.

Returns :

the buffer, or NULL on failure.

gretl_print_steal_buffer ()

char *              gretl_print_steal_buffer            (PRN *prn);

Obtain a pointer to the buffer associated with prn, if any. The pointer on prn itself is set to NULL and the caller takes responsibility for freeing the buffer.

prn :

printing struct.

Returns :

the buffer, or NULL on failure.

gretl_print_get_size ()

void                gretl_print_get_size                (PRN *prn,
                                                         int *width,
                                                         int *height);

If prn has a non-null buffer attached, provides the width and/or height of the buffer, the width in characters and the height in lines.

prn :

printing struct.

width :

location to receive width, or NULL.

height :

location to receive height, or NULL.

gretl_print_read_tempfile ()

FILE *              gretl_print_read_tempfile           (PRN *prn);

Obtain a read handle to the tempfile associated with prn, if any. This should be fclosed once you're finished with it.

prn :

printing struct.

Returns :

FILE pointer, or NULL on failure.

gretl_print_stop_tempfile_read ()

int                 gretl_print_stop_tempfile_read      (PRN *prn,
                                                         FILE *fp);

For prn with tempfile attached, stops reading of the tempfile and closes fp (recording the position at which reading stopped).

prn :

printing struct.

fp :

auxiliary stream.

Returns :

0 on success, error code if prn is not connected to a tempfile.

gretl_print_set_save_position ()

int                 gretl_print_set_save_position       (PRN *prn);

Sets the current buffer offset as the position from which a chunk of the current buffer may be saved, using gretl_print_get_chunk().

prn :

printing struct.

Returns :

0 on success, error code if prn is not connected to a buffer.

gretl_print_unset_save_position ()

void                gretl_print_unset_save_position     (PRN *prn);

Erases the "save position" offset as set by gretl_print_set_save_position().

prn :

printing struct.

gretl_print_get_chunk ()

char *              gretl_print_get_chunk               (PRN *prn);

Retrieves a copy of the buffer associated with prn, starting at the offset from the start of the buffer as set by gretl_print_set_save_position().

prn :

printing struct.

Returns :

allocated buffer on success, or NULL on error.

gretl_print_set_format ()

void                gretl_print_set_format              (PRN *prn,
                                                         PrnFormat format);

Sets the printing format on prn.

prn :

printing struct.

format :

desired format code.

gretl_print_toggle_doc_flag ()

void                gretl_print_toggle_doc_flag         (PRN *prn);

Toggles the GRETL_FORMAT_DOC flag on prn.

prn :

printing struct.

gretl_print_set_utf_flag ()

void                gretl_print_set_utf_flag            (PRN *prn);

Sets the GRETL_FORMAT_UTF flag on prn.

prn :

printing struct.

gretl_print_supports_utf ()

int                 gretl_print_supports_utf            (PRN *prn);

prn :

printing struct.

Returns :

1 if prn supports UTF-8 characters, else 0.

gretl_print_set_delim ()

void                gretl_print_set_delim               (PRN *prn,
                                                         char delim);

Sets the CSV delimiter on prn.

prn :

printing struct.

delim :

desired CSV field-delimiter.

pprintf ()

int                 pprintf                             (PRN *prn,
                                                         const char *format,
                                                         ...);

Multi-purpose printing function: can output to stream, to buffer or to nowhere (silently discarding the output), depending on how prn was initialized. It is not advisable to use this function for large chunks of fixed text: use pputs instead.

prn :

gretl printing struct.

format :

as in printf().

... :

arguments to be printed.

Returns :

the number of bytes printed, or -1 on memory allocation failure.

pputs ()

int                 pputs                               (PRN *prn,
                                                         const char *s);

prn :

gretl printing struct.

s :

constant string to print.

Returns :

the number of bytes printed, or -1 on memory allocation failure.

pputc ()

int                 pputc                               (PRN *prn,
                                                         int c);

prn :

gretl printing struct.

c :

character to print

Returns :

the number of bytes printed, or -1 on memory allocation failure.

gretl_prn_newline ()

void                gretl_prn_newline                   (PRN *prn);

Print a line break, in the mode appropriate to the format of prn (plain text, TeX or RTF).

prn :

gretl printing struct.

gretl_print_flush_stream ()

void                gretl_print_flush_stream            (PRN *prn);

If the output of prn is directed to a stream, flush that stream.

prn :

gretl printing struct.

printing_to_standard_stream ()

int                 printing_to_standard_stream         (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the output of prn is directed to one of the standard streams, stdout or stderr, else 0.

printing_is_redirected ()

int                 printing_is_redirected              (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the output of prn has been redirected relative to its original setting, else 0.

print_start_redirection ()

int                 print_start_redirection             (PRN *prn,
                                                         FILE *fp);

Redirects output of prn to fp.

prn :

gretl printing struct.

fp :

stream to which output should be redirected.

Returns :

0 on success, 1 on error.

print_end_redirection ()

int                 print_end_redirection               (PRN *prn);

If the output of prn has been diverted relative to its original setting, terminate the redirection.

prn :

gretl printing struct.

Returns :

0 on success, 1 on error.

plain_format ()

int                 plain_format                        (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the format of prn is plain text, else 0.

rtf_format ()

int                 rtf_format                          (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the format of prn is RTF, else 0.

rtf_doc_format ()

int                 rtf_doc_format                      (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the format of prn is RTF, and the RTF preamble should be printed, else 0.

tex_format ()

int                 tex_format                          (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the format of prn is TeX, else 0.

tex_doc_format ()

int                 tex_doc_format                      (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the format of prn is TeX and a complete TeX document is being produced, else 0.

tex_eqn_format ()

int                 tex_eqn_format                      (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the format of prn is TeX and a model is being represented as an equation, rather than in tabular form, else 0.

csv_format ()

int                 csv_format                          (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if the format of prn is CSV, else 0.

prn_format ()

int                 prn_format                          (PRN *prn);

prn :

gretl printing struct.

Returns :

The formatting flags for prn.

prn_delim ()

char                prn_delim                           (PRN *prn);

prn :

gretl printing struct.

Returns :

The character to be used as delimiter for CSV.

gretl_print_has_buffer ()

int                 gretl_print_has_buffer              (PRN *prn);

prn :

gretl printing struct.

Returns :

1 if prn is using a buffer for printing, otherwise 0 (e.g., if a file is being used).

gretl_print_alloc ()

int                 gretl_print_alloc                   (PRN *prn,
                                                         size_t s);

If prn is using a buffer for printing, try to ensure that at least s bytes are available for further printing. May speed things up if we know there is a large amount of text to be printed.

prn :

gretl printing struct.

s :

desired size in bytes.

Returns :

0 on success, non-zero on failure.

set_up_verbose_printer ()

PRN *               set_up_verbose_printer              (gretlopt opt,
                                                         PRN *prn);

opt :

OPT_V for verbosity.

prn :

currently active printing struct.

Returns :

printing struct for verbose output.

close_down_verbose_printer ()

void                close_down_verbose_printer          (PRN *vprn);

Turns off verbose printing and frees the resources associated with vprn.

vprn :

prn pointer obtained via set_up_verbose_printer().