cufo/stream.h: Formatted Ouput Streams
[cufo: Formatted Output]

Data Structures
struct	cufo_prispec
struct	cufo_convinfo
struct	cufo_stream
Stream API Details
typedef void(*	cufo_print_fn_t )(cufo_stream_t fos, cufo_prispec_t spec, cu_va_ref_t va_ref)
typedef void(*	cufo_print_ptr_fn_t )(cufo_stream_t fos, cufo_prispec_t spec, void *ptr)
cu_bool_t	cufo_stream_init (cufo_stream_t fos, char const *encoding, cutext_sink_t target)
cu_bool_t	cufo_stream_clientstate (cufo_stream_t fos, void const *key, size_t state_size, cu_ptr_ptr_t state_out)
cu_bool_t	cufo_stream_drop_clientstate (cufo_stream_t fos, void const *key)
char	cufo_stream_lastchar (cufo_stream_t fos)
void *	cufo_stream_produce (cufo_stream_t fos, size_t len)
#define	CUFO_PRIFLAG_PLUS   1
#define	CUFO_PRIFLAG_MINUS   2
#define	CUFO_PRIFLAG_SPACE   4
#define	CUFO_PRIFLAG_HASH   8
#define	CUFO_PRIFLAG_ZERO   16
#define	CUFO_SFLAG_SHOW_TYPE_IF_UNPRINTABLE   (1u << 0)
#define	CUFO_SFLAG_HAVE_ERROR   (1u << 16)
Stream Construction and Cleanup
cufo_stream_t	cufo_stdout
cufo_stream_t	cufo_stderr
cufo_stream_t	cufo_open_sink (cutext_sink_t sink)
cufo_stream_t	cufo_open_strip_sink (cutext_sink_t sink)
cufo_stream_t	cufo_open_strip_fd (char const *encoding, int fd, cu_bool_t close_fd)
cufo_stream_t	cufo_open_strip_file (char const *encoding, char const *path)
cufo_stream_t	cufo_open_strip_str (void)
cufo_stream_t	cufo_open_strip_wstring (void)
cufo_stream_t	cufo_open_text_sink (cufo_textstyle_t style, cutext_sink_t sink)
cufo_stream_t	cufo_open_text_fd (char const *encoding, cufo_textstyle_t style, int fd, cu_bool_t close_fd)
cufo_stream_t	cufo_open_text_file (char const *encoding, cufo_textstyle_t style, char const *path)
cufo_stream_t	cufo_open_text_str (cufo_textstyle_t style)
cufo_stream_t	cufo_open_text_wstring (cufo_textstyle_t style)
cufo_stream_t	cufo_open_xml (cutext_sink_t target_sink)
cufo_stream_t	cufo_open_term_fd (char const *encoding, char const *term, int fd, cu_bool_t close_fd)
cufo_stream_t	cufo_open_auto_fd (int fd, cu_bool_t close_fd)
cu_box_t	cufo_close (cufo_stream_t fos)
void	cufo_close_discard (cufo_stream_t fos)
Stream Control
void	cufo_lock (cufo_stream_t fos)
void	cufo_unlock (cufo_stream_t fos)
void	cufo_flush (cufo_stream_t fos)
void	cufo_set_wide (cufo_stream_t fos, cu_bool_t be_wide)
void	cufo_flag_error (cufo_stream_t fos)
cu_bool_t	cufo_have_error (cufo_stream_t fos)
Basic Printing
void	cufo_fast_putc (cufo_stream_t fos, char ch)
void	cufo_fast_putwc (cufo_stream_t fos, cu_wchar_t wc)
void	cufo_putc (cufo_stream_t fos, char ch)
void	cufo_putwc (cufo_stream_t fos, cu_wchar_t wc)
void	cufo_fillc (cufo_stream_t fos, char ch, int n)
void	cufo_fillwc (cufo_stream_t fos, cu_wchar_t wc, int n)
void	cufo_puts (cufo_stream_t fos, char const *cs)
void	cufo_putws (cufo_stream_t fos, cu_wchar_t *wcs)
void	cufo_newline (cufo_stream_t fos)
void	cufo_space (cufo_stream_t fos)
void	cufo_print_charr (cufo_stream_t fos, char const *cs, size_t cs_len)
void	cufo_print_wcarr (cufo_stream_t fos, cu_wchar_t const *arr, size_t len)
void	cufo_print_wstring (cufo_stream_t fos, cu_wstring_t ws)
void	cufo_print_str (cufo_stream_t fos, cu_str_t str)
void	cufo_print_location (cufo_stream_t fos, cu_location_t loc)
void	cufo_print_ex (cufo_stream_t fos, cuex_t e)
void	cufo_printsp_ex (cufo_stream_t fos, cufo_prispec_t spec, cuex_t e)
Basic Markup
cu_bool_t	cufo_entera_va (cufo_stream_t fos, cufo_tag_t tag, va_list va)
cu_bool_t	cufo_enter (cufo_stream_t fos, cufo_tag_t tag)
void	cufo_leave (cufo_stream_t fos, cufo_tag_t tag)
void	cufo_leaveln (cufo_stream_t fos, cufo_tag_t tag)
void	cufo_empty (cufo_stream_t fos, cufo_tag_t tag,...)
void	cufo_tagputc (cufo_stream_t fos, cufo_tag_t tag, char ch)
void	cufo_tagputs (cufo_stream_t fos, cufo_tag_t tag, char const *s)
#define	cufo_entera(fos, tag,...)   cufoP_entera(fos, tag, __VA_ARGS__, NULL)
Formatted Printing and Markup
int	cufo_vprintf (cufo_stream_t fos, char const *fmt, va_list va)
int	cufo_printf (cufo_stream_t fos, char const *fmt,...)
int	cufo_lprintf (cufo_stream_t fos, char const *fmt,...)
int	cufo_oprintf (char const *fmt,...)
int	cufo_eprintf (char const *fmt,...)
int	cufo_printfln (cufo_stream_t fos, char const *fmt,...)
void	cufo_logf (cufo_stream_t fos, cu_log_facility_t facility, char const *fmt,...)
void	cufo_vlogf (cufo_stream_t fos, cu_log_facility_t facility, char const *fmt, va_list va)
void	cufo_vlogf_at (cufo_stream_t fos, cu_log_facility_t facility, cu_location_t loc, char const *fmt, va_list va)
Program Initialisation
void	cufo_register_ptr_format (char const *key, cufo_print_ptr_fn_t fn)
void	cufo_register_va_format (char const *key, cufo_print_fn_t fn)

---

Define Documentation

#define cufo_entera	(	fos,
		tag,
		...		)	cufoP_entera(fos, tag, __VA_ARGS__, NULL)

Starts a fragment marked up with tag with associated attributes specified in the variadic part. Attributes can be passed by using the cufoA_* macros found in cufo/attrdefs.h.

---

Typedef Documentation

typedef void(* cufo_print_ptr_fn_t)(cufo_stream_t fos, cufo_prispec_t spec, void *ptr)

The type of a CUOO_INTF_FOPRINT_FN callback used to print dynamic objects to a formatted stream.

---

Function Documentation

cu_box_t cufo_close

(

cufo_stream_t

fos

)

Flushes fos as frees up associated resources. If it's connected to a sink which produces data (such as a string), then the data will be returned. It's up to the callee to know the correct type to unbox.

void cufo_close_discard

(

cufo_stream_t

fos

)

Frees up associated resources of fos without flushing or returning anything.

See also:

cufo_close

cu_bool_t cufo_enter	(	cufo_stream_t	fos,
		cufo_tag_t	tag
	)

Starts a fragment marked up with tag.

int cufo_eprintf	(	char const *	fmt,
			...
	)

Calls cufo_printf then cufo_flush on cufo_stderr after acquiring a temporary lock.

void cufo_fillc	(	cufo_stream_t	fos,
		char	ch,
		int	n
	)

Writes n repetitions of the ASCII character ch to fos.

void cufo_fillwc	(	cufo_stream_t	fos,
		cu_wchar_t	wc,
		int	n
	)

Writes n repetitions of the wide character wc to fos.

void cufo_flush

(

cufo_stream_t

fos

)

Flushes buffered data down the stack of sinks.

void cufo_leave	(	cufo_stream_t	fos,
		cufo_tag_t	tag
	)

Ends a fragment which was started by cufo_enter or cufo_entera. The tag arguments of the matching calls must be the same.

void cufo_lock

(

cufo_stream_t

fos

)

Acquires an exclusive lock on fos in case it's shared by multiple threads. Pair it off with cufo_unlock.

void cufo_logf	(	cufo_stream_t	fos,
		cu_log_facility_t	facility,
		char const *	fmt,
			...
	)

This is a low-level function which invokes the cufo_vlogf_at handler directly, bypassing the handler in facility. Use cu/logging.h or cu/diag.h instead.

int cufo_lprintf	(	cufo_stream_t	fos,
		char const *	fmt,
			...
	)

A variant of cufo_printf which locks the stream while printing.

void cufo_newline

(

cufo_stream_t

fos

)

Writes a newline to fos unless the last character was a newline.

cufo_stream_t cufo_open_auto_fd	(	int	fd,
		cu_bool_t	close_fd
	)

Makes a conservative guess whether fd is a terminal and calls either cufo_open_text_fd or cufo_open_term_fd as appropriate. It also determines the character encoding from the current locale.

cufo_stream_t cufo_open_term_fd	(	char const *	encoding,
		char const *	term,
		int	fd,
		cu_bool_t	close_fd
	)

Opens a stream with terminal capabilities using default text and terminal styles. The encoding must be multibyte or byte compatible due to the terminfo escape sequences. If the culibs was configured without terminal support, this falls back to cufo_open_text_fd.

cufo_stream_t cufo_open_text_fd	(	char const *	encoding,
		cufo_textstyle_t	style,
		int	fd,
		cu_bool_t	close_fd
	)

Returns a text stream which convert (if necessary) to the character encoding encoding, and writes the result to fd. If close_fd is true, then fd will be closed when the returned stream is closed.

cufo_stream_t cufo_open_text_sink	(	cufo_textstyle_t	style,
		cutext_sink_t	sink
	)

Returns a text stream writing to sink.

int cufo_oprintf	(	char const *	fmt,
			...
	)

Calls cufo_printf then cufo_flush on cufo_stdout after acquiring a temporary lock.

void cufo_print_charr	(	cufo_stream_t	fos,
		char const *	cs,
		size_t	cs_len
	)

Write cs_len bytes from cs to fos, interpreted as UTF-8.

void cufo_print_ex	(	cufo_stream_t	fos,
		cuex_t	e
	)

Print an expression to fos.

void cufo_print_location	(	cufo_stream_t	fos,
		cu_location_t	loc
	)

Print the source reference loc to fos.

void cufo_print_str	(	cufo_stream_t	fos,
		cu_str_t	str
	)

Write the UTF-8 string str to fos.

void cufo_print_wcarr	(	cufo_stream_t	fos,
		cu_wchar_t const *	arr,
		size_t	len
	)

Write len wide characters from arr to fos.

void cufo_print_wstring	(	cufo_stream_t	fos,
		cu_wstring_t	ws
	)

Write the wide string ws to fos.

int cufo_printf	(	cufo_stream_t	fos,
		char const *	fmt,
			...
	)

Print fmt to fos, replacing format specifies with representations of the corresponding following arguments.

void cufo_putc	(	cufo_stream_t	fos,
		char	ch
	)

Writes the ASCII character ch to fos. Use cufo_puts or cufo_print_charr to write UTF-8 byte sequences.

void cufo_puts	(	cufo_stream_t	fos,
		char const *	cs
	)

Writes the null-terminated string cs to fos.

void cufo_putwc	(	cufo_stream_t	fos,
		cu_wchar_t	wc
	)

Writes the wide character wc to fos.

void cufo_putws	(	cufo_stream_t	fos,
		cu_wchar_t *	wcs
	)

Writes the null-terminated wide string wcs to fos.

void cufo_space

(

cufo_stream_t

fos

)

Writes a space to fos unless the last character was an ASCII white space. Non-ASCII white space may also be considered in the future.

char cufo_stream_lastchar

(

cufo_stream_t

fos

)

Returns the last character written to fos if it was an ASCII character, otherwise returns 0. This is mainly inteded as a convenient way for a client to check if it has written out spaces or newlines, instead of keeping track by itself.

void cufo_tagputc	(	cufo_stream_t	fos,
		cufo_tag_t	tag,
		char	ch
	)

A convenience function which wraps cufo_enter and cufo_leave around cufo_putc.

void cufo_tagputs	(	cufo_stream_t	fos,
		cufo_tag_t	tag,
		char const *	s
	)

A convenience function which wraps cufo_enter and cufo_leave around cufo_puts.

void cufo_unlock

(

cufo_stream_t

fos

)

Unlocks fos.

void cufo_vlogf	(	cufo_stream_t	fos,
		cu_log_facility_t	facility,
		char const *	fmt,
		va_list	va
	)

This is a low-level function which invokes the cufo_vlogf_at handler directly, bypassing the handler in facility. Use cu/logging.h or cu/diag.h instead.

void cufo_vlogf_at	(	cufo_stream_t	fos,
		cu_log_facility_t	facility,
		cu_location_t	loc,
		char const *	fmt,
		va_list	va
	)

This is the cu/logging.h callback installed by cufo_init. Its usually not needed except when defining new log binder logic.

int cufo_vprintf	(	cufo_stream_t	fos,
		char const *	fmt,
		va_list	va
	)

Print fmt to fos, replacing format specifies with representations of the corresponding arguments from va.

---

Variable Documentation

cufo_stream_t cufo_stderr

A stream tied to file descriptor 2 (standard error).

cufo_stream_t cufo_stdout

A stream tied to file descriptor 1 (stdandard output).