/ 
Term-VTerm-0.05
River stage one • 1 direct dependent • 4 total dependents
/ Term::VTerm

NAME

Term::VTerm - emulate a virtual terminal using libvterm

EXPORTED CONSTANTS

The following sets of constants are exported, with the given tag names.

VALUETYPE_* (:types)

Type constants for the types of VTermValue, as returned by get_attr_type and get_prop_type.

ATTR_* (:attrs)

Attribute constants for pen attributes.

PROP_* (:props)

Property constants for terminal properties.

MOD_* (:mod)

Keyboard modifier bitmask constants for keyboard_* and mouse_*.

DAMAGE_* (:damage)

Size constants for VTermScreen damage merging.

KEY_* (:keys)

Key symbol constants for keyboard_key.

CONSTRUCTOR

new

$vterm = Term::VTerm->new( %args )

Constructs a new Term::VTerm instance of the initial size given by the arguments.

rows, cols => INT

Gives the initial size of the terminal area.

METHODS

get_size

( $rows, $cols ) = $vterm->get_size

Returns the current size of the terminal area.

set_size

$vterm->set_size( $rows, $cols )

Sets the new size of the terminal area.

get_utf8

set_utf8

$utf8 = $vterm->get_utf8

$vterm->set_utf8( $utf8 )

Return or set UTF-8 mode on the parser.

input_write

$len = $vterm->input_write( $str )

Writes the bytes of the given string into the terminal parser buffer.

output_read

$len = $vterm->output_read( $buf, $maxlen )

Reads bytes from the output buffer of the terminal into the given variable, up to the maximum length requested. Returns the number of bytes actually read.

keyboard_unichar

$vterm->keyboard_unichar( $char, $mod )

Sends a keypress to the output buffer, encoding the given Unicode character number (i.e. not a string), with the optional modifier (as a bitmask of one or more of the MOD_* constants).

keyboard_key

$vterm->keyboard_key( $key, $mod )

Sends a keypress to the output buffer, encoding the given key symbol (as a KEY_* constant), with the optional modifier (as a bitmask of one or more of the MOD_* constants).

mouse_move

$vterm->mouse_move( $row, $col, $mod )

Moves the mouse cursor to the given position, with optional modifier (as a bitmask of one or more of the MOD_* constants). It is OK to call this regardless of the current mouse mode; if the mode doesn't want move report events or drag events then no output will be generated.

mouse_button

$vterm->mouse_button( $button, $is_pressed, $mod )

Performs a mouse button report event on the given button, to either press or release it, with optional modifier (as a bitmask of one or more of the MOD_* constants). It is OK to call this regardless of the current mouse mode; if mouse reporting is disabled then no output will be generated.

parser_set_callbacks

$vterm->parser_set_callbacks( %cbs )

Sets the parser-layer callbacks. Takes the following named arguments:

on_text => CODE
$on_text->( $text )
on_control => CODE
$on_control->( $ctrl )

$ctrl is an integer giving a C0 or C1 control byte value.

on_escape => CODE
$on_escape->( $str )
on_csi => CODE
$on_csi->( $leader, $command, @args )

Where $leader may be undef, and each element of @args is an ARRAY reference containing sub-arguments. Each sub-argument may be undef.

on_osc => CODE
$on_osc->( $command )
on_dcs => CODE
$on_dcs->( $str )
on_resize => CODE
$on_resize->( $rows, $cols )

obtain_state

$state = $vterm->obtain_state

Returns a Term::VTerm::State object representing the terminal state layer, creating it if necessary. After calling this method, any parser callbacks will no longer work.

obtain_screen

$screen = $vterm->obtain_screen

Returns a Term::VTerm::Screen object representing the terminal screen layer, creating it if necessary. After calling this method, any parser or state callbacks will no longer work.

COLOR OBJECTS

A VTermColor instance can be constructed by

$color = Term::VTerm::Color->new( red => $r, green => $g, blue => $b )

A VTermColor instance has the following field accessors:

$bool = $color->is_indexed

True if the colour is a palette index.

$bool = $color->is_rgb

True if the colour contains RGB values directly.

$idx = $color->index

The palette index for indexed colours.

$r = $color->red

$g = $color->green

$b = $color->blue

The components of the colour as an integer between 0 and 255 for RGB colours.

$hex = $color->rgb_hex

A 6-character string containing the three colour components, hex encoded.

$bool = $color->is_default_fg

$bool = $color->is_default_bg

True if the colour is the default colour for terminal foreground or background.

GLYPH INFO OBJECTS

A VTermGlyphInfo instance has the following field accessors:

@chars = $info->chars

A list of Unicode character numbers. This list does not include the terminating 0.

$width = $info->width

The width of this glyph in screen columns.

$str = $info->str

A Unicode string containing the characters.

POSITION OBJECTS

A VTermPos instance can be constructed by

$pos = Term::VTerm::Pos->new( row => $row, col => $col )

A VTermPos instance has the following field accessors:

$row = $pos->row

$col = $pos->col

The row and column number of the position, 0-indexed.

RECTANGLE OBJECTS

A VTermRect instance can be constructed by

$rect = Term::VTerm::Rect->new( start_row => ..., end_row => ..., start_col => ..., end_col => ... )

A VTermRect instance has the following field accessors:

$row = $rect->start_row

$col = $rect->start_col

The row and column number of the top left corner of the rectangle.

$row = $rect->end_row

$col = $rect->end_col

The row and column number of the cell just after the bottom right corner of the rectangle; i.e. exclusive limit.

FUNCTIONS

The following utility functions are also exported.

get_attr_type

$type = get_attr_type( $attr )

Returns the type of the given pen attribute.

get_prop_type

$type = get_prop_type( $prop )

Returns the type of the given terminal property.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>