PRN

PRN — gretl printing struct

Functions

Types and Values

typedef PRN
enum PrnType
enum PrnFormat

Object Hierarchy


Includes

#include <libgretl.h>

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 pprintf(), pputs() and pputc() are no-ops.

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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);

Parameters

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);

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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. This function is intended for use with text designed for printing in a GUI window, and with "reasonable" line lengths for that context; if the lines are too long (more than 120 UTF-8 characters) the values written to width and/or height will be zero.

Parameters

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 stream associated with with prn , if any. This should be matched with a call to gretl_print_stop_tempfile_read() once you're finished with reading.

Parameters

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).

Parameters

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().

Parameters

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().

Parameters

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().

Parameters

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 .

Parameters

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 .

Parameters

prn

printing struct.

 

gretl_print_set_has_minus ()

void
gretl_print_set_has_minus (PRN *prn);

Sets the GRETL_FORMAT_HAS_MINUS flag on prn , indicating that the Unicode minus sign is supported.

Parameters

prn

printing struct.

 

gretl_print_has_minus ()

int
gretl_print_has_minus (PRN *prn);

Parameters

prn

printing struct.

 

Returns

1 if prn supports Unicode minus sign, else 0.


gretl_print_set_delim ()

void
gretl_print_set_delim (PRN *prn,
                       char delim);

Sets the CSV delimiter on prn .

Parameters

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. Note that it's preferable to use pputs() for large chunks of fixed text.

Parameters

prn

gretl printing struct.

 

format

as in the C library's printf().

 

Returns

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


pputs ()

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

Parameters

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);

Parameters

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).

Parameters

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.

Parameters

prn

gretl printing struct.

 

gretl_print_close_stream ()

void
gretl_print_close_stream (PRN *prn);


printing_to_standard_stream ()

int
printing_to_standard_stream (PRN *prn);

Parameters

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);

Parameters

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 .

Parameters

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.

Parameters

prn

gretl printing struct.

 

Returns

0 on success, 1 on error.


plain_format ()

int
plain_format (PRN *prn);

Parameters

prn

gretl printing struct.

 

Returns

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


rtf_format ()

int
rtf_format (PRN *prn);

Parameters

prn

gretl printing struct.

 

Returns

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


rtf_doc_format ()

int
rtf_doc_format (PRN *prn);

Parameters

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);

Parameters

prn

gretl printing struct.

 

Returns

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


tex_doc_format ()

int
tex_doc_format (PRN *prn);

Parameters

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);

Parameters

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);

Parameters

prn

gretl printing struct.

 

Returns

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


prn_format ()

int
prn_format (PRN *prn);

Parameters

prn

gretl printing struct.

 

Returns

The formatting flags for prn .


prn_delim ()

char
prn_delim (PRN *prn);

Parameters

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);

Parameters

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.

Parameters

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);

Parameters

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 .

Parameters

vprn

prn pointer obtained via set_up_verbose_printer().

 

Types and Values

PRN

typedef struct PRN_ PRN;

An opaque structure accessed only via gretl_print functions.


enum PrnType

Members

GRETL_PRINT_STDOUT

   

GRETL_PRINT_STDERR

   

GRETL_PRINT_FILE

   

GRETL_PRINT_BUFFER

   

GRETL_PRINT_TEMPFILE

   

GRETL_PRINT_STREAM

   

enum PrnFormat

Members

GRETL_FORMAT_TXT

   

GRETL_FORMAT_TEX

   

GRETL_FORMAT_DOC

   

GRETL_FORMAT_RTF

   

GRETL_FORMAT_RTF_TXT

   

GRETL_FORMAT_EQN

   

GRETL_FORMAT_SELECTION

   

GRETL_FORMAT_CSV

   

GRETL_FORMAT_TAB

   

GRETL_FORMAT_MODELTAB

   

GRETL_FORMAT_LANDSCAPE

   

GRETL_FORMAT_HAS_MINUS