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, $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.

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>