ChafaTermInfo

ChafaTermInfo — Describes a particular terminal type

Functions

Types and Values

Description

A ChafaTermInfo describes the characteristics of one particular kind of display terminal. It stores control sequences that can be used to move the cursor, change text attributes, mark the beginning and end of sixel graphics data, etc.

ChafaTermInfo also implements an efficient low-level API for formatting these sequences with marshaled arguments so they can be sent to the terminal.

Functions

chafa_term_info_new ()

ChafaTermInfo *
chafa_term_info_new (void);

Creates a new, blank ChafaTermInfo.

Returns

The new ChafaTermInfo

Since: 1.6


chafa_term_info_copy ()

ChafaTermInfo *
chafa_term_info_copy (const ChafaTermInfo *term_info);

Creates a new ChafaTermInfo that's a copy of term_info .

Parameters

term_info

A ChafaTermInfo to copy.

 

Returns

The new ChafaTermInfo

Since: 1.6


chafa_term_info_ref ()

void
chafa_term_info_ref (ChafaTermInfo *term_info);

Adds a reference to term_info .

Parameters

term_info

ChafaTermInfo to add a reference to.

 

Since: 1.6


chafa_term_info_unref ()

void
chafa_term_info_unref (ChafaTermInfo *term_info);

Removes a reference from term_info .

Parameters

term_info

ChafaTermInfo to remove a reference from.

 

Since: 1.6


chafa_term_info_get_seq ()

const gchar *
chafa_term_info_get_seq (ChafaTermInfo *term_info,
                         ChafaTermSeq seq);

Gets the string equivalent of seq stored in term_info .

Parameters

term_info

A ChafaTermInfo.

 

seq

A ChafaTermSeq to query for.

 

Returns

An unformatted string sequence, or NULL if not set.

Since: 1.6


chafa_term_info_set_seq ()

gint
chafa_term_info_set_seq (ChafaTermInfo *term_info,
                         ChafaTermSeq seq,
                         const gchar *str,
                         GError **error);

Sets the control sequence string equivalent of seq stored in term_info to str .

The string may contain argument indexes to be substituted with integers on formatting. The indexes are preceded by a percentage character and start at 1, i.e. %1, %2, %3, etc.

The string's length after formatting must not exceed CHAFA_TERM_SEQ_LENGTH_MAX bytes. Each argument can add up to four digits, or three for those specified as 8-bit integers. If the string could potentially exceed this length when formatted, chafa_term_info_set_seq() will return FALSE.

If parsing fails or str is too long, any previously existing sequence will be left untouched.

Passing NULL for str clears the corresponding control sequence.

Parameters

term_info

A ChafaTermInfo.

 

seq

A ChafaTermSeq to query for.

 

str

A control sequence string, or NULL to clear.

 

error

A return location for error details, or NULL.

 

Returns

TRUE if parsing succeeded, FALSE otherwise

Since: 1.6


chafa_term_info_have_seq ()

gboolean
chafa_term_info_have_seq (const ChafaTermInfo *term_info,
                          ChafaTermSeq seq);

Checks if term_info can emit seq .

Parameters

term_info

A ChafaTermInfo.

 

seq

A ChafaTermSeq to query for.

 

Returns

TRUE if seq can be emitted, FALSE otherwise

Since: 1.6


chafa_term_info_emit_seq ()

gchar *
chafa_term_info_emit_seq (ChafaTermInfo *term_info,
                          ChafaTermSeq seq,
                          ...);

Formats the terminal sequence seq , inserting positional arguments. The seq's number of arguments must be supplied exactly.

The argument list must be terminated by -1, or undefined behavior will result.

If the wrong number of arguments is supplied, or an argument is out of range, this function will return NULL. Otherwise, it returns a zero-terminated string that must be freed with g_free().

If you want compile-time validation of arguments, consider using one of the specific chafa_term_info_emit_*() functions. They are also faster, but require you to allocate at least CHAFA_TERM_SEQ_LENGTH_MAX bytes up front.

Parameters

term_info

A ChafaTermInfo

 

seq

A ChafaTermSeq to emit

 

...

A list of int arguments to insert in seq , terminated by -1

 

Returns

A newly allocated, zero-terminated formatted string, or NULL on error

Since: 1.14


chafa_term_info_parse_seq ()

ChafaParseResult
chafa_term_info_parse_seq (ChafaTermInfo *term_info,
                           ChafaTermSeq seq,
                           gchar **input,
                           gint *input_len,
                           guint *args_out);

Attempts to parse a terminal sequence from an input data array. If successful, CHAFA_PARSE_SUCCESS will be returned, the input pointer will be advanced and the parsed length will be subtracted from input_len .

Parameters

term_info

A ChafaTermInfo

 

seq

A ChafaTermSeq to attempt to parse

 

input

Pointer to pointer to input data

 

input_len

Pointer to maximum input data length

 

args_out

Pointer to parsed argument values

 

Returns

A ChafaParseResult indicating success, failure or insufficient input data

Since: 1.14


chafa_term_info_supplement ()

void
chafa_term_info_supplement (ChafaTermInfo *term_info,
                            ChafaTermInfo *source);

Supplements missing sequences in term_info with ones copied from source .

Parameters

term_info

A ChafaTermInfo to supplement

 

source

A ChafaTermInfo to copy from

 

Since: 1.6

Types and Values

CHAFA_TERM_SEQ_LENGTH_MAX

#define CHAFA_TERM_SEQ_LENGTH_MAX 96

ChafaTermInfo

typedef struct ChafaTermInfo ChafaTermInfo;

CHAFA_TERM_INFO_ERROR

#define CHAFA_TERM_INFO_ERROR (chafa_term_info_error_quark ())

Error domain for ChafaTermInfo. Errors in this domain will be from the ChafaTermInfoError enumeration. See GError for information on error domains.


enum ChafaTermInfoError

Error codes returned by control sequence parsing.

Members

CHAFA_TERM_INFO_ERROR_SEQ_TOO_LONG

A control sequence could exceed CHAFA_TERM_SEQ_LENGTH_MAX bytes if formatted with maximum argument lengths.

 

CHAFA_TERM_INFO_ERROR_BAD_ESCAPE

An illegal escape sequence was used.

 

CHAFA_TERM_INFO_ERROR_BAD_ARGUMENTS

A control sequence specified more than the maximum number of arguments, or an argument index was out of range.