=begin pod

=head1 NAME

Termbox

=head1 DESCRIPTION

Termbox is "a library for writing text-based user interfaces". This module
provides Raku bindings to this library.

=head1 SYNOPSIS

    use Termbox :ALL;

    if tb-init() -> $ret {
        note "tb-init() failed with error code $ret";
        exit 1;
    }

    END tb-shutdown;

    for "Press ESC to exit!".encode.list -> $c {
        state $x = 5;
        tb-change-cell( $x++, 5, $c, TB_COLOR_BLACK, TB_COLOR_WHITE );
    }

    tb-present;

    my $events = Supplier.new;
    start {
        while tb-poll-event( my $ev = Termbox::Event.new ) { $events.emit: $ev }
    }

    react whenever $events.Supply -> $ev {
        given $ev.type {
            when TB_EVENT_KEY {
                given $ev.key {
                    when TB_KEY_ESC { done }
                }
            }
        }
    }

=head1 FUNCTIONS

None of the following functions are exported by default. They can be accessed
through the C<Termbox> package (as in C<Termbox::init>) or imported with the
C<:subs> tag. When imported, they gain the C<tb-> prefix (such that C<init>
becomes C<tb-init>, etc).

=head2 Basic functions

=head3 init

=head3 shutdown

=head3 width

=head3 height

=head3 clear

=head3 present

=head3 put-cell

=head3 change-cell

=head3 blit

=head3 select-input-mode

=head3 select-output-mode

=head3 peek-event

=head3 poll-event

=head3 utf8-char-length

=head3 utf8-char-to-unicode

See also C<encode-string> for a higher-level version of this function.

=head3 utf8-unicode-to-char

See also C<decode-string> for a higher-level version of this function.

=head2 Additional functions

The following functions are added as a convenience for the UTF-8 helpers
provided by Termbox itself. These are likely much simpler to use in Raku
code.

=head3 encode-string

Takes a non-empty string and returns an Int representing the number used
to encode it by Termbox.

On error throws an exception.

=head3 decode-string

Takes an Int with the integer representation of a string (such as that
returned by C<encode-string> and returns it decoded as a Str.

On error throws an exception.

=head1 CONSTANTS

Like with the functions described above, none of the following constants are
exported by default. They can be accessed through the C<Termbox> package (as
in C<Termbox::WHITE>) or imported with the different tags described below.

When imported, they gain the C<TB_> prefix (such that C<WHITE> becomes
C<TB_WHITE>, etc).

=head2 Keys

Imported with the C<:keys> tag.

These are a safe subset of terminfo keys, which exist on all popular
terminals. Use only these to stay "truly portable", according to the
Termbox documentation.

=item KEY_F1
=item KEY_F2
=item KEY_F3
=item KEY_F4
=item KEY_F5
=item KEY_F6
=item KEY_F7
=item KEY_F8
=item KEY_F9
=item KEY_F10
=item KEY_F11
=item KEY_F12
=item KEY_INSERT
=item KEY_DELETE
=item KEY_HOME
=item KEY_END
=item KEY_PGUP
=item KEY_PGDN
=item KEY_ARROW_UP
=item KEY_ARROW_DOWN
=item KEY_ARROW_LEFT
=item KEY_ARROW_RIGHT
=item KEY_MOUSE_LEFT
=item KEY_MOUSE_RIGHT
=item KEY_MOUSE_MIDDLE
=item KEY_MOUSE_RELEASE
=item KEY_MOUSE_WHEEL_UP
=item KEY_MOUSE_WHEEL_DOWN

The rest are ASCII code points below SPACE character and a BACKSPACE key.

=item KEY_CTRL_TILDE
=item KEY_CTRL_2
=item KEY_CTRL_A
=item KEY_CTRL_B
=item KEY_CTRL_C
=item KEY_CTRL_D
=item KEY_CTRL_E
=item KEY_CTRL_F
=item KEY_CTRL_G
=item KEY_BACKSPACE
=item KEY_CTRL_H
=item KEY_TAB
=item KEY_CTRL_I
=item KEY_CTRL_J
=item KEY_CTRL_K
=item KEY_CTRL_L
=item KEY_ENTER
=item KEY_CTRL_M
=item KEY_CTRL_N
=item KEY_CTRL_O
=item KEY_CTRL_P
=item KEY_CTRL_Q
=item KEY_CTRL_R
=item KEY_CTRL_S
=item KEY_CTRL_T
=item KEY_CTRL_U
=item KEY_CTRL_V
=item KEY_CTRL_W
=item KEY_CTRL_X
=item KEY_CTRL_Y
=item KEY_CTRL_Z
=item KEY_ESC
=item KEY_CTRL_LSQ_BRACKET
=item KEY_CTRL_3
=item KEY_CTRL_4
=item KEY_CTRL_BACKSLASH
=item KEY_CTRL_5
=item KEY_CTRL_RSQ_BRACKET
=item KEY_CTRL_6
=item KEY_CTRL_7
=item KEY_CTRL_SLASH
=item KEY_CTRL_UNDERSCORE
=item KEY_SPACE
=item KEY_BACKSPACE2
=item KEY_CTRL_8

These are modifier constants. C<MOD_MOTION> in a mouse event indicates a
dragging event.

=item MOD_ALT
=item MOD_MOTION

=head2 Styles

Imported with the C<:styles> tag.

=item DEFAULT
=item BLACK
=item RED
=item GREEN
=item YELLOW
=item BLUE
=item MAGENTA
=item CYAN
=item WHITE

These are font attributes. It is possible to use multiple attributes by
combining them using bitwise OR (C<+|>). Although, colors cannot be combined,
you can combine attributes and a single color.

=item BOLD
=item UNDERLINE
=item REVERSE

=head2 Errors

Imported with the C<:errors> tag.

=item EUNSUPPORTED_TERMINAL
=item EFAILED_TO_OPEN_TTY
=item EPIPE_TRAP_ERROR

=head2 Events

Imported with the C<:events> tag.

=item EVENT_KEY
=item EVENT_RESIZE
=item EVENT_MOUSE

=head2 Modes

Imported with the C<:modes> tag.

=item HIDE_CURSOR
=item INPUT_CURRENT
=item INPUT_ESC
=item INPUT_ALT
=item INPUT_MOUSE
=item OUTPUT_CURRENT
=item OUTPUT_NORMAL
=item OUTPUT_256
=item OUTPUT_216
=item OUTPUT_GRAYSCALE

=head1 AUTHOR

José Joaquín Atria <jjatria@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright 2020 José Joaquín Atria

This library is free software; you can redistribute it and/or modify it under
the Artistic License 2.0.

=end pod
