Repository list

This file describes the content of the repository.

1. Program frameworks

Three frameworks are available for the programs:

Direct input

The program has no blocking input at all (ex: reads files) or reads stdin and blocks on it (and puts on stdout/stderr).

⇒ The program can use Basic_Proc or Sys_Calls (or even Ada.Text_Io) for its Ios. It can use Key_Pressed to check asynchronously for keyboard input while processing.

Multiplexed inputs

The program multiplexes several inputs and stimuli: file descriptors (UDP or TCP socket), stdin, signals (SIGCHILD and SIGTERM), timers.

⇒ The program must use Event_Mng.Wait as the single blocking point. This allows dispatching the FD events, timers and signals to the proper callbacks.

Event_Mng allows defining callbacks for handling signal and FD events,
Timers allows defining timers, expiration and callback,
Socket and Tcp_Util allow sending and reading on socket FDs,
Async_Stdin allows defining a callback on stdin,
Sys_Calls allows direct access to other FDs.

X11 mutiplexed inputs

The program uses X11 and multiplexes X11 events with other inputs (see above).

⇒ The program must use either X_Mng.X_Wait_Event or Con_Io.Put_Then_Get (or Con_Io.Get) or Afpx.Put_Then_Get. It can also use more specialized tools based on X11 like Curve (compatible with Con_Io) and Select_File (compatible with Afpx).

Several tasks can be defined, for example one for each window.

Notes:

Using Event_Mng in X11 programs requires caution (see Event_Mng.Wait and Command).
Using X_Mng is exclusive with Con_Io and Afpx.
Using Con_Io and Afpx simultaneously requires caution (see Con_Io.Suspend/Resume and Afpx.Suspend/Resume).

Notes on X11 resources:

The following env variables can be set to statically tune the X11 resources:
- X_COLOR_MAP: "PRIVATE" or "PUBLIC" (default "PUBLIC") defines the way the color map (of 14 entries) is allocated,
- X_FONT_KIND: "courier", "fixed" or "lucidatypewriter" (default "lucidatypewriter") defines the font family
- CON_IO_FONT: can be set to "small" or "large" to use a font smaller or larger than the default.
The colors can be defined by each application.
- For X_Mng the default colors are: black, blue, dark green, cyan, red, magenta, brown, light grey, grey, light blue, lime green, orange, yellow and white.
- For Con_Io (and Afpx) the default colors are: light grey, blue, dark green, cyan, red, magenta, brown, white, dark grey, light blue, lime green, orange, yellow and black.

2. Families of tools

2.1. Execution environment

Argument provides a simple parsing by keys, while Argument_Parser provides a more strict policy and higher level parsing. Use the later if the arguments are many, are optional, support options…
Environ allows retrieving and checking environmental variables.
Basic_Proc allows setting the exit code of the process and provides basic input/output.
Basic_Proc, Protected_Put, Async_Stdin, Key_Pressed (and Sys_Calls) provide input from stdin and output to stdout and stderr.
Trace allows logging traces in the code. The output is filtered according to environment variables.

2.2. Strings

As.U and As.B are implementations of Ada.Strings.Unbounded and Ada.Strings.Bounded with extra features.
Str_Util provides several operations on strings.
Normalization, Images and Gets provide ways tro transform numeric values to strings and reverse.
Scanner scans booleans, integers, reals, strings… from a string, according to a given format.
Many_Strings allows storing several strings successively in a string and extracting them.
Parser allows extracting the successive words of a string according to a given separator.
Xml_Parser parses (and/or generates) XML files or flows of characters.
Http fetches the target of a URL.
Ada_Parser parses a Ada file or flow of characters.

2.3. Character encoding

Language allows the selection of character encoding, between C and Utf-8, and provides associated string operations.
Utf_8 and Utf_16 provide basic encoding functions.
Byte_To_Unicode allows converting bytes to unicode numbers according to a XML file definition of encoding.

2.4. Numbers

Arbitrary provides operations on integers with arbitray precision.
My_Math provides logarithm and trigonometry on real numbers and conversion to integers.
Complexes implements complex numbers.
Gets allows getting a number (integer, float…) from a string.
Normalisation generates formatted image of integer, digits, delta or fixed real.
Round_At rounds a real at a given precision.
Hexa_Utils handles hexadecimal represntation of numbers.

2.5. Data containers

Dyn_Data allocates and frees data, relying on a free list to reuse memory.
Long_Long_Limited_List, Limited_List and Dynamic_List are linked lists of data, limited or simply private.
Long_Long_Limited_Pool, Limited_Pool and Unlimited_Pool are simple dynamic lists with push/pop operations.
Hashing provides basic hashing table, while Hashed_List provides a hashed storage of data, possibly with unicity of each data.
Queues provides various kinds of storage of data (FIFO, LIFO, prio, timed) in container of fixed size.
Trees allows organizing data in trees.
Unbounded_Arrays provides unbounded arrays of data.
Smart_reference provides automatic deallocation of unreferenced data.

2.6. Tasking tools

Mutexe provides simple and read-write mutexes, while Doors provides doors, Locks provides locks and Conditions provides conditions.
Control_Pool provides exclusive access to an item in a pool.
Task_Mng controls a task of periodic activity.

2.7. Time

Virtual_Time provide clocks that can slow down, speed up, freeze or jump. The are notifying when they change.
Timers provides timers (single shot or periodics) that are based on virtual times. They are active in the sense that they invoque a callback when they expire.
Chronos provides individual chronometers that can start/stop and are based on virtual times. It also provides Passive_Timers (single shot or periodics) on which one can check the expiration from time to time.
Perpet is a perpetual calendar.
Day_Mng converts durations to and from hours/minutes/seconds/milliseconds.
Date_Text scans and puts dates in variable formats.

2.8. Forking child process

Proc_Family provides the basic fork/exec features while Command waits (using Event_Mng) until the end of execution of the child and collects its outputs and errors.

2.9. Sockets

Socket provides all the basic functions for UDP (including IPM) and TCP sockets.
Tcp_Util automaticall and asynchronously connects TCP sockets, accepts TCP connection, handles sending overflow and reception on socket (including underflow and disconnection).
Autobus automatically transfers to subscribers of the bus the messages that are sent by publishers on the bus.
Channels (deprecated) provides channel (connected) or bus (not connected) of communication. Use Autobus instead.

2.10. Files

Text_Line allows reading a file line by line.
Text_Char allows reading a file character by character and "un-getting" characters.
Output_Flows provides homogeneous access to Stdout, Stderr (synchronous or not) or Text_Line files
Bloc_Io allows reading and writing in a file block by block (a block is an array of bytes).
Directory provides all the basic functions for changing to, and scanning directories, and tools for building and splitting directory path.
Dir_Mng fills a dynamic list with the content of a directory.

3. List of packages

Packages are rated from 1 (simple) to 3 (very complex), on subjective criteria. A d indicates that there is a specific documentation of the package.

ada_parser (2): Parses a text input flow, identifies ada lexical elements.
ada_words ada_words.keywords (2): Basic ada parsing of delimiters, separators and reserved words.
address_ops (1): Add, sub and returns image of a System.Address.
afpx afpx.utils (3d): Graphic (text oriented) manager of input screens that are off-line defined.
afpx_bld (2d): Process that compiles XML text description of screens for AFPX.
afpx_rnb (3d): Process that re-organises a AFPX XML file (insertion, deletion, move, copy of fields in a descriptor) and updates associated references.
any_def (1): Definition of variant type that contains any value.
app (2d): Preprocessor that selects pieces of text and expands names according to definitions.
arbitrary arbitrary.prime_list arbitrary.factors arbitrary.fractions (2): Arbitrary precision operations, prime factor decomposition, fractions.
arbitrary.limited_list (3): Dynamic list of (limited) private objects, search/sort, unlimited length.
argument (1): Program name and arguments extraction (based on keys).
argument_parser (2): Parser of program arguments (based on keys and options).
as as.b as.u as.u.utils (2): Bounded and unbounded strings and associated containers.
aski aski.unicode (1): Strict ANSI characters definition and conversions
assertion(1): Raise exception or trace when assertion fails.
async_stdin (2): Asynchronous reading and buffer of characters from input flow.
autobus (3): Simple bus to exchange strings between processes.
basic_proc (1): Basic IO operations and exit code setting.
bencode (2): Encodes a Bencoded stream to/from a XML stream
bit_ops (1): Bit operations.
bloc_io (2): Read/writes arrays of bytes from/to a file.
byte_to_unicode (1): Map a character (e.g. ISO-8859-xx) to unicode according to a xml-defined map.
c_types (1): Types for portable interfacing with C.
channels (2): Diffuse messages to several destinations in TCP (channel) or IPM (bus).
chronos (1): Handle chronometers.
chronos.passive_timers (1): Arm and check if timer has expired.
clear_screen (1): Process that clears the screen.
command (2): Uses Proc_Family to fork-exec and collect output and error flows.
complexes (1): Complex numbers operations.
computer (2): Evaluate expressions based on numbers, variables, operations.
con_io (3): Console IOs (keyboard, mouse, screen) in text and graphic.
conditions (1): Allow several tasks to wait until unblocked all together or one by one.
console (1): ANSI management of text/cursor console.
control_pool (2): Control exclusive access to data in a pool.
convert (1): Converts network ←→ host integer.
copy_file (1): Copy a file.
curve (3): Draw a curve of function y=f(x) and draw a set of points in 2D.
date_text (2): Scan or put a date at a given format.
day_mng (2): Split/pack a duration into hours, minutes, seconds.
dir_mng (2): Makes a dynamic list of directory content.
directory (2): Change/read directory, dirname, basename…
doors (1): Allow several tasks to wait until a given amount or waiters is reached.
dyn_data (2): Allocate/free data from a pool, use a free list to reuse memory.
environ (2): Environment variable extraction and basic tests.
euro_franc (1): Euro ←→ Franc convertion.
event_mng event_mng.handling (2): Multiplex reception of events (timers, fd, signals).
evp_digest (1): Compute Hash with OpenSSL.
exception_messenger (1): Allow transmission of un-truncated long exception message.
file_hash (1): Store the content of file (1 word per line) in a hashed dynlist.
forker (2): API to a standalone (in C) forker process.
get_line (2): Parse a file ans split its lines into words.
gets (1): Get an integer, float or duration from a string.
hash hashing (2): Hash table storage of keyed data.
hash_function (1): Function for hashing a string into integer.
hashed_list (1): Hashed access to a dynamic list of items.
hashed_list.unique (1): Hashed access to a dynamic list of items with unique keys.
hexa_utils (1): Convert strings to hexa and reverse (ex: "1A" ←→ 26).
http (2): Fetch the target of a HTTP URL.
images (1): Image of integer, long long integer, modulus, float, integer in base 16 (no leading space), duration and time.
init_mng (1): Manage atomic init of state while concurent update events are bufferized.
input_buffer (1): Extract sentences from a flow of characters.
ip_addr (1): Parse IP address or port.
k_rand (2): Kiss random number generator.
key_pressed (1): Uses Sys_Calls handling of stdin to get a character asynchronously.
language (2): Support Utf6 - Unicode - wide char conversions.
locks (1): Allow several tasks to wait until the lock is open.
long_long_limited_list limited_list dynamic_list (3): Dynamic list of (limited) private objects, search/sort.
long_long_limited_pool limited_pool unlimited_pool (2): Simple pool of (limited) private objects, push/pop.
long_longs (1): Definition of long long integer and associated subtypes.
lower_char lower_str mixed_str upper_char upper_str (1): Upper, lower, mixed string and character conversion.
lz4 (2): Very fast lossless compression / uncompression algorithm.
lz4l (2): Lz4 modified to support large buffer and larger reference offset
lzf (2): Very fast lossless compression / uncompression algorithm.
magic_numbers (1): Generates random magic numbers.
many_strings (2): Concatenate strings in string.
match (1): Checks if a number matches a range based criteria.
mod_utils (1): Some utilities for modulus and natural types.
multiget (2): Allow getting/ungetting items from an input flow.
mutexes (2): Mutex for exclusive access or read/write access to shared data.
my_math (2): Math library (round, trunc, trigo, exp, ln).
ndbm (1): Interface to C ndbm library.
network (2): Simulate a network of inter-connected nodes.
normalization, normal (1): Formatted images of integers and reals.
null_procedure (1): Null (dummy) procedure.
num_letters (2): Converts a number into english text and reverse.
output_flows (2): Pool of shared and standardized output flows
parser parser.all_in_one parser.keywords (2): Parse a string, separate words and separators.
pattern (2): Check a string versus several patterns.
perpet (2): Perpetual calendar.
proc_family (2): Fork/exec unix process.
property_def (1): Definition of a Property type and array
protected_pool (1): Store and retrieve data (by key) in a protected pool.
protected_put (1): Output on Stdout or Stderr, protected by a mutex.
protected_var (1): Generic protected variable (write-read).
queues queues.timed (1): Fifo, Lifo, Prio, Timed queues.
recurs (1): Recursive operation on subdirs.
regex_filters (2): Check a string versus chained regex criteria.
reg_exp (2): Check a string versus a regular expression.
rnd (1): Random number generator (using K_Rand, S_Rand or U_Rand).
romanic (1): Decimal to romanic conversion (11 ←→ XI).
rounds (1): Round / trunc a float.
s_rand (1): Simple random number generator.
scanner (2): Scan a string and extract fields according to a given format.
schedule (1): Allow task schduling (delay 0.0).
select_file (2): Afpx-based file selection in a dir.
smart_alias (2): Smart aliases to global objects (notifier of releases).
smart_reference (2): Smart reference (automatic free).
snappy (2): Very fast lossless compression / uncompression algorithm.
socket (2): Socket (Udp/Tpc/Tcp_Header, Ipm, Afunix) operations. Relies on a quite complex C library.
socket_util (1): General Set_Dest and Link of socket.
sorts (2): Sort array.
split_lines (1): Split a string into several lines.
state_machine (2): Generic state machine manager.
str_util str_util.navigator str_util.regex (2): Various string utilites, including regexp and navigation.
sys_calls sys_calls.file_access (2): Various low level Unix calls.
syslin (2): Linear system (Gauss) resolver.
task_mng (2): Calls a callback periodically.
tcp_util (3): Automatic connect/accept Tcp connections, receive, send on them.
temp_file (2): Create a temporary file.
text_char (2): Get/unget chars from an input flow.
text_line (2): Get/put lines of text from/to a flow.
timers timers.expiration (2): Asynchronous timer management.
timeval (1): Conversion from and to timeval structure.
trace trace.loggers trace.queue (2): Tracing utility library and logger object.
trees (2): Tree of items (father/children) management.
trilean (1): An enum with 3 values (False, True and Other, or Maybe).
u_rand (2): Universal random number generator.
unbounded_arrays (1): Handle unbounded generic arrays, as Unbounded_String does.
unicode (1): Definition of unicode numbers
utf_16 (2): Utf_16 encoding/decoding
utf_8 (2): Utf_8 encoding/decoding
virtual_time (2): Define virtual time that can shift, accelerate, freeze…
x_mng (3): Low level interface to X11 (text, basic graphics, Mouse and keyboard).
x_mng.cards (1): Low level interface to X11 for card games.
xml_parser (3): Parse Xml files or strings, including check of dtd.
It is documented with the xml_parser tool. It is partially is documented with the xml_parser tool.
xml_parser.generator (2): Generate Xml output in flow/file/string.
It is partially is documented with the xml_parser tool.

4. Examples

This section provides, for the major packages of the repository, a list of programs or packages that can be refered as examples of usage. Some other examples can be found in the tests directory.

Ada_Parser	astub
Afpx	agite
Arbitrary	prime, mcd
Argument_Parser	asubst, als
As.B	enigma
As.U	asubst
Async_Stdin	mcd
Autobus	mcd
Bloc_Io	alook
Chronos	lem
Command	agite
Computer	afpx_bld
Con_Io	sokoban, Afpx
Curve	approx
Dynamic_List	lsadeps
Event_Mng	mcd, tcpchat
Exception_Messenger	Xml_Parser
Hashing	Xml_Parser, lsadeps
Http	Xml_Parser
Input_Buffer	tcpchat
Language	asubst
Limited_List	see Dynamic_List
Many_Strings	agite
Multiget	astub
Parser	dictio
Reg_Exp	asubst
Select_File	account
Smart_Reference	timers
Socket	Dictio
Str_Util	asubst
Syslin	approx
Tcp_Util	Dictio
Text_Char	Xml_Parser
Text_Line	trail_spaces
Timers	lem, tcpchat
Trees	Xml_Parser, lsadeps, tcpchat
Unbounded_Arrays	renardeau
Unlimited_Pool	tcpchat
Virtual_Time	lem
X_Mng	Con_Io
Xml_Parser	xml_checker