package GNATCOLL.Terminal is
type Terminal_Info is tagged private;
type Terminal_Info_Access is access all Terminal_Info'Class;
-- Information about a terminal on which we output.
-- This structure does not encapsulate the terminal itself, which is a
-- limited type.
-- By default, this is configured without support for colors. It is thus
-- recommended to first call Init before you use this type.
-- This type is almost always used in conjunction with a File_Type, which
-- is where text is actually output. The properties of that File_Type are
-- queried and cached in the Terminal_Info.
------------
-- Colors --
------------
type Supports_Color is (Yes, No, Auto);
procedure Init_For_Stdout
(Self : in out Terminal_Info;
Colors : Supports_Color := Auto);
procedure Init_For_Stderr
(Self : in out Terminal_Info;
Colors : Supports_Color := Auto);
procedure Init_For_File
(Self : in out Terminal_Info;
Colors : Supports_Color := Auto);
-- Checks whether the terminal supports colors. By default, automatic
-- detection is attempted, but this can be overridden by the use of the
-- Colors parameter.
-- The three variants depend on which type of terminal you are outputting
-- to. Unfortunately, the type Ada.Text_IO.File_Type is opaque and it is
-- not possible to check what is applies to, or what are the properties of
-- the underling file handle.
function Has_Colors (Self : Terminal_Info) return Boolean;
-- Whether the terminals supports colors.
function Has_ANSI_Colors (Self : Terminal_Info) return Boolean;
-- Whether the terminal supports ANSI escape sequences for colors.
-- On Windows, it is possible for a terminal to support colors, but not
-- ANSI sequences. This package will take care of doing the appropriate
-- system calls to setup colors, but if you want to directly output
-- ANSI sequences that will not work.
type ANSI_Color is
(Unchanged,
Black,
Red,
Green,
Yellow,
Blue,
Magenta,
Cyan,
Grey,
Reset);
-- The colors that can be output in a terminal (ANSI definitions). The
-- actual color that the user will see might be different, since a terminal
-- might associate a different color to the same escape sequence.
type ANSI_Style is
(Unchanged,
Bright,
Dim,
Normal,
Reset_All);
-- The style for the text. Some styles are not supported on some
-- terminals, like Dim on the Windows console.
procedure Set_Color
(Self : in out Terminal_Info;
Term : Ada.Text_IO.File_Type := Ada.Text_IO.Standard_Output;
Foreground : ANSI_Color := Unchanged;
Background : ANSI_Color := Unchanged;
Style : ANSI_Style := Unchanged);
-- Change the colors that will be used for subsequent output on the
-- terminal.
-- This procedure has no effect if Has_Colors returns False.
-- In general, it is not recommended to output colors to files, so you
-- should not use Set_Color in such a context.
procedure Set_Fg
(Self : in out Terminal_Info;
Color : ANSI_Color;
Term : Ada.Text_IO.File_Type := Ada.Text_IO.Standard_Output);
procedure Set_Bg
(Self : in out Terminal_Info;
Color : ANSI_Color;
Term : Ada.Text_IO.File_Type := Ada.Text_IO.Standard_Output);
procedure Set_Style
(Self : in out Terminal_Info;
Style : ANSI_Style;
Term : Ada.Text_IO.File_Type := Ada.Text_IO.Standard_Output);
-- Override specific colors.
-------------
-- Cursors --
-------------
procedure Beginning_Of_Line (Self : in out Terminal_Info);
-- Move the cursor back to the beginning of the line.
-- This has no impact on files, only in interactive terminals.
procedure Clear_To_End_Of_Line (Self : in out Terminal_Info);
-- Delete from the cursor position to the end of line
function Get_Width (Self : Terminal_Info) return Integer;
-- Return the width of the terminal, or -1 if that width is either
-- unknown or does not apply (as is the case for files for instance).
function Get_Lines (Self : Terminal_Info) return Integer;
-- Return the height of the terminal, or -1 if that height is either
-- unknown or does not apply (as is the case for files for instance).
-----------
-- Utils --
-----------
type Full_Style is record
Fg : ANSI_Color := Unchanged;
Bg : ANSI_Color := Unchanged;
Style : ANSI_Style := Unchanged;
end record;
-- A convenient record to group all style-related attributes
function Get_ANSI_Sequence (Style : Full_Style) return String;
-- Append the ANSI escape sequence representing the style.
-- Note that these sequences are not supported by all terminals, see
-- Has_ANSI_Colors.
end GNATCOLL.Terminal;