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.

BASELINE_* (:baselines)

Pen attribute value constants for the baseline attribute.

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.

SELECTION_* (:selections)

Selection bitmask constants for send_selection and selection callback events.

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, $str )

Where $command contains the parsed command number (or -1 if none was found) and $str contains the full text after the ;.

on_dcs => CODE
$on_dcs->( $command, $str )

Where $command contains the parsed DCS command identifier string and $str contains the full text after it.

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.

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>