-------------------------------------------------
-- TERMBOX-ADA - a termbox binding for Ada
-------------------------------------------------

-- INTRODUCTION

termbox-ada is a variable thickness binding for the Ada programming language.
This means that the C API remains largely in tact, but the C types are converted
into Ada standard types.

This repository contains a demo program and makefile to show how to use termbox-ada
in your projects.  This file also includes a detailed tutorial on how this
binding was made, so programmers new to Ada can make their own bindings.

This repository contains termbox binaries compiled on amd64 linux from the
termbox source, located at https://github.com/nsf/termbox .

-- STATUS

This library is in development, incomplete, but functional.  Below is a table of the
functions and how they are implemented.  Termbox.ads is the variable thickness
binding, whereas termbox_h.ads is the auto generated header file, which uses
the generated C types (basically, it's functional, but not convenient).

Function                            Termbox.ads                termbox_h.ads
tb_init				    yes, Init()                yes
tb_init_file                        no                         yes
tb_init_fd                          no                         yes
tb_shutdown                         yes, Shutdown              yes
tb_width                            yes, Width                 yes
tb_height                           yes, Height                yes
tb_clear                            yes, Clear                 yes
tb_set_clear_attributes             yes, Set_Clear_Attributes  yes
tb_present                          yes, Present               yes
tb_set_cursor                       yes, Set_Cursor            yes
tb_put_cell                         yes, Put_Cell              yes
tb_change_cell                      yes, Change_Cell           yes
tb_blit                             no                         yes
tb_cell_buffer                      no                         yes
tb_select_input_mode                yes, Select_Input_Mode     yes
tb_select_output_mode               yes, Select_Output_Mode    yes
tb_peek_event                       yes, Peek_Event            yes
tb_poll_event                       yes, Poll_Event            yes
tb_utf8_char_length                 no                         yes
tb_utf8_char_to_unicode             no                         yes
tb_utf8_unicode_to_char             no                         yes

-- DEMO
To build, you'll need the GNAT compiler, which is part of the GCC.  On my
system, I have v7.5.0.  You'll also need GNU Make.  To build the demo, run:

make all

You should then have a binary in the working directory.  Run:

./demo

To run the demo program. Press the ESC key to quit.

-- TUTORIAL
Generating this binding was a fairly simple process.

First, I downloaded and compiled the termbox C library using the
instructions at https://github.com/nsf/termbox .  I then added the
header file, termbox.h, and the resulting .so file to this repository.

Next, I ran

gcc -c -fdump-ada-spec -C termbox/include/termbox.h

This command is a gcc built-in that generates Ada specs from a .h
file.  It results in termbox_h.ads and several other .ads files that
deal with converting C types to Ada types.  These were all placed
in the include folder.  For more information on the Ada spec generation,
see https://www.adacore.com/gems/gem-59 .

The termbox_h.ads file makes the C functions callable from Ada, but it
isn't very convenient because of the type conversions.  For example,
every Integer in Ada needs to be converted to a Interfaces.C.int type
to work with the generated Ada spec.  Because this makes the source
code messy and repetitive, I created another package based on
termbox_h.ads for convenience.

The resulting files, termbox.ads and termbox.adb, use more conventional
Ada types.  Essentially, for each procedure or function listed in
termbox_h.ads, I create another procedure or function in termbox.ads.
The body of these functions simply convert the data types of the parameters
to be able to be used with the termbox_h.ads functions, and then converts
their return values back to more convenient Ada types.

The advantage to doing bindings this way is that it preserves the
general structure of the API, but makes it convenient to use that
API in Ada programs.

The makefile is a good introduction for how to use this library in your
own projects.  Make sure to add the include folder during build using the

-aI./include

switch, and then during linking, add

-Wl,-rpath=./termbox/lib/

To preserve the library path for the executable.

For more information about Ada bindings, see these articles:

Writing Ada Bindings for C Libraries: https://flyx.org/ada-bindings/
Interfacing with C: https://learn.adacore.com/courses/intro-to-ada/chapters/interfacing_with_c.html