``format``
==========

The ``format`` object provides a portable abstraction over how the de
facto standard ``format/2-3`` predicates are made available by the
supported backend Prolog systems. Some system provide these predicates
as built-in predicates while others make them available using a library
that must be explicitly loaded.

Calls to the library predicates are inlined when compiled with the
``optimize`` flag turned on for most of the backends. When that's the
case, there is no overhead compared with calling the abstracted
predicates directly.

Portability
-----------

Some Prolog systems provide only a subset of the expected format
specifiers. Notably, table related format specifiers are only fully
supported by a few systems. See the section below on testing.

Only some of the supported Prolog backends provide implementations of
the ``format/2-3`` predicates that allow using not only an atom or a
list of character codes for the format string (as de facto standard) but
also using a list of characters. These currently include ECLiPSe, LVM,
Scryer Prolog, SICStus Prolog, SWI-Prolog, and YAP. Therefore, when wide
portability is sought, atoms must be used for the format specifier
argument. Some systems, like Scryer Prolog and Tau Prolog, only accept a
list of characters for the format string. In this case, this library
will convert the atom format string before calling these systems native
implementations.

API documentation
-----------------

Open the
`../../docs/library_index.html#format <../../docs/library_index.html#format>`__
link in a web browser.

Loading
-------

To load all entities in this library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(format(loader)).

Testing
-------

Minimal tests for this library predicates can be run by loading the
``tester.lgt`` file:

::

   | ?- logtalk_load(format(tester)).

Detailed tests for the ``format/2-3`` predicates are available in the
``tests/prolog/predicates`` directory as part of the Prolog standards
conformance test suite. Use those tests to confirm the portability of
the format specifiers that you want to use.
