Overview
========

This folder contains libraries of useful objects, categories, and
protocols. The currently available libraries can be grouped by theme as
follows (note that some libraries naturally span multiple themes):

Library groups
--------------

- Application metadata, configuration, and logging: ``application``,
  ``expand_library_alias_paths``, ``command_line_options``, ``logging``,
  and ``options``.
- Types, collections and generic data processing: ``basic_types``,
  ``types``, ``assignvars``, ``deques``, ``dictionaries``,
  ``nested_dictionaries``, ``graphs``, ``heaps``, ``hierarchies``,
  ``intervals``, ``lru_caches``, ``queues``, ``ripple_down_rules``,
  ``sets``, ``subsequences``, ``tries``, ``union_find``, and
  ``zippers``.
- Combinatorics: ``arrangements``, ``cartesian_products``,
  ``combinations``, ``derangements``, ``integer_partitions``,
  ``multisets``, ``partitions``, and ``permutations``.
- Meta-programming: ``meta`` and ``meta_compiler``
- Monoid implementations: ``expecteds``, ``optionals``, and
  ``validations``.
- Control, state, and developer support: ``dependents``, ``edcg``,
  ``events``, ``listing``, ``reader``, and ``term_io``.
- Term- and goal-expansion: ``hook_flows`` and ``hook_objects``.
- Portability: ``coroutining``, ``dif``, ``format``, ``process``,
  ``recorded_database``, and ``timeout``.
- Dates and time: ``dates``, ``dates_tz``, ``time_scales``, and
  ``tzif``.
- Geospatial data: ``crs_projections``, ``geojson``, ``geohash``,
  ``geospatial``, ``gpx``, ``nmea``, ``tle_orbits``, and ``wkt_wkb``
- Space communications and telemetry: ``ccsds_frames``,
  ``ccsds_link_profiles``, ``ccsds_packet_services``,
  ``ccsds_packetization``, ``ccsds_packets``, ``ccsds_tc_services``,
  ``ccsds_time_codes``, ``ccsds_time_fields``.
- Text and NLP: ``character_sets``, ``grammars``, ``string_distance``,
  and ``strings``, ``language_detection``, ``lemmatization``,
  ``n_grams``, ``stemming``, ``stop_words``, ``text_normalization``,
  ``text_vectorization``, and ``tokenization``.
- Web and HTTP APIs:

  - High-level libraries: ``html``, ``mime_types``, ``uri_template``,
    ``url``, ``http_client``, ``http_server``, ``http_sse``,
    ``http_websocket``, ``gravatar``, ``open_api``, ``open_ai``,
    ``open_id``, ``rest``, and ``s3``.
  - Supporting libraries: ``http_core``, ``http_authenticate``,
    ``http_client_core``, ``http_cookies``, ``http_cors``,
    ``http_digest``, ``http_directory_listing``, ``http_htmx``,
    ``http_multipart``, ``http_oauth``, ``http_parameters``,
    ``http_router``, ``http_server_core``, ``http_session``,
    ``http_socket_transport``, ``http_process_transport``,
    ``http_static_files``, ``http_websocket_messages``,
    ``http_websocket_service``, ``http_websocket_session``.

- Identifiers: ``cuid2``, ``genint``, ``gensym``, ``ids``, ``ksuid``,
  ``nanoid``, ``snowflakeid``, ``sqids``, ``typeid``, ``ulid``, and
  ``uuid``.
- International standards and reference data: ``iso_13616``,
  ``iso_3166``, ``iso_4217``, ``iso_639``, and ``iso_9362``.
- Interchange formats and wire protocols: ``amqp``, ``avro``,
  ``base32``, ``base58``, ``base64``, ``base85``, ``bson``, ``cbor``,
  ``csv``, ``json``, ``json_graph``, ``json_ld``, ``json_lines``,
  ``json_patch``, ``json_path``, ``json_pointer``, ``json_rpc``,
  ``json_schema``, ``message_pack``, ``mcp_server``, ``mqtt``,
  ``protobuf``, ``smtp``, ``stomp``, ``toml``, ``toon``, ``tsv``, and
  ``yaml``.
- Coordination and data stores: ``linda``, ``memcached``, and ``redis``.
- System and external integration: ``crontab``, ``git``, ``java``,
  ``os``, and ``sockets``.
- Logic and symbolic computing: ``datalog``.
- Security and integrity: ``block_ciphers``, ``cmac``, ``crypto``,
  ``hashes``, ``hmac``, ``jwt``, ``otp``, and ``paseto``.
- Randomness: ``arbitrary``, ``mutations``, and ``random``.
- Mathematics and statistics: ``byte_order``, ``ieee_754``,
  ``linear_algebra``, ``linear_programming``, ``numerical_analysis``,
  ``univariate_distributions``, ``multivariate_distributions``, and
  ``statistics``,
- Local and meta-heuristic optimization: ``local_optimization``,
  ``constrained_optimization``, ``ant_colony``,
  ``differential_evolution``, ``genetic_algorithm``,
  ``particle_swarm_optimization``, ``simulated_annealing``, and
  ``tabu_search``.
- Machine learning:

  - Classification: ``classification_protocols``,
    ``adaptive_boosting_classifier``, ``c45_classifier``,
    ``gradient_boosting_classifier``, ``kernel_svm_classifier``,
    ``knn_classifier``, ``lda_classifier``, ``linear_svm_classifier``,
    ``logistic_regression_classifier``, ``mlp_classifier``,
    ``naive_bayes_classifier``, ``nearest_centroid_classifier``,
    ``qda_classifier``, ``random_forest_classifier``, and
    ``sgd_classifier``.
  - Anomaly detection: ``anomaly_detection_protocols``,
    ``cusum_anomaly_detector``, ``ewma_anomaly_detector``,
    ``iqr_anomaly_detector``, ``isolation_forest_anomaly_detector``,
    ``knn_distance_anomaly_detector``, ``lof_anomaly_detector``,
    ``modified_z_score_anomaly_detector``,
    ``one_class_svm_anomaly_detector``, and
    ``z_score_anomaly_detector``.
  - Regression: ``regression_protocols``, ``bayesian_ridge_regression``,
    ``elastic_net_regression``, ``gradient_boosting_regression``,
    ``gaussian_process_regression``, ``knn_regression``,
    ``lasso_regression``, ``linear_regression``,
    ``random_forest_regression``, ``regression_tree``,
    ``ridge_regression``, and ``svr_regression``.
  - Ranking: ``ranking_protocols``, ``borda_ranker``,
    ``bradley_terry_ranker``, ``colley_ranker``, ``copeland_ranker``,
    ``elo_ranker``, ``glicko2_ranker``, ``glicko2_periodic_ranker``,
    ``hodge_rank``, ``kemeny_young_ranker``, ``massey_ranker``,
    ``plackett_luce_ranker``, ``plackett_luce_last_ranker``,
    ``rank_centrality``, ``ranked_pairs``,
    ``regularized_bradley_terry_ranker``, ``schulze_ranker``,
    ``thurstone_mosteller_ranker``, and ``trueskill_ranker``.
  - Clustering: ``clustering_protocols``, ``agglomerative_clusterer``,
    ``dbscan_clusterer``, ``gaussian_mixture_clusterer``,
    ``hdbscan_clusterer``, ``hierarchical_clustering``,
    ``kcenters_clusterer``, ``kmeans_clusterer``,
    ``kmedians_clusterer``, ``kmedoids_clusterer``,
    ``kmodes_clusterer``, ``kprototypes_clusterer``,
    ``optics_clusterer``, and ``spectral_clusterer``.
  - Dimension reduction: ``dimension_reduction_protocols``,
    ``ica_projection``, ``kernel_pca_projection``, ``lda_projection``,
    ``nmf_projection``, ``pca_projection``, ``pls_projection``,
    ``probabilistic_pca_projection``, and ``random_projection``,
    ``truncated_svd_projection``, ``tsne_projection``, and
    ``umap_projection``.
  - Pattern mining: ``pattern_mining_protocols``,
    ``frequent_pattern_mining_protocols``,
    ``sequential_pattern_mining_protocols``, ``association_rule_miner``,
    ``apriori_pattern_miner``, ``clo_span_pattern_miner``,
    ``eclat_pattern_miner``, ``fp_growth_pattern_miner``,
    ``gsp_pattern_miner``, ``prefix_span_pattern_miner``, and
    ``spade_pattern_miner``.

In addition to the loader-based libraries, this directory also contains
a small number of standalone reusable entities, namely ``attributes``,
``cloning``, ``counters``, and ``streamvars``.

See also the libraries provided in the "Contributions" and "Ports"
sections.

Specific notes about individual libraries can be found in the
corresponding library directory ``NOTES.md`` files.

The ``unicode_data`` library is a plain Prolog version of the Unicode
17.0 standard. See its documentation file for details.

A ``parallel_logtalk_processes_setup.pl`` Prolog file is also provided
with sample code for selected backend Prolog compilers for initializing
Logtalk processes such that each process uses a unique scratch
directory, therefore allowing parallel process execution (e.g., for
usage at continuous integration servers). Starting with Logtalk 3.48.0,
this setup is only required in general when running with the ``clean``
flag turned off. See the comments in the file itself for usage
instructions.

Library documentation
---------------------

Specific notes about each library can be found in the corresponding
``NOTES.md`` files. HTML documentation for each library API can be found
on the ``docs`` directory (open the ``../docs/handbook/index.html`` file
with your web browser).

Loading libraries
-----------------

All the individual libraries can be loaded using the
``<library name>(loader)`` notation as argument for the compiling and
loading predicates. For example:

::

   | ?- logtalk_load(random(loader)).

There is also a file named ``all_loader.lgt`` that will load all
libraries. Simply type the goal:

::

   | ?- logtalk_load(library(all_loader)).

As a general rule, always use the corresponding loader file to load a
library. Most library entities are part of small hierarchies or depend
on other libraries and thus cannot be loaded and compiled separately
(e.g., the ``list`` object implements the ``listp`` protocol and is part
of a basic types hierarchy). Using the loader files takes care of all
dependencies and also ensures compilation in optimized mode.

Testing libraries
-----------------

Most of the libraries include unit tests in their directory, together
with a ``tester.lgt`` file for running them. For example, to run the
tests for the ``random`` library, we can use the goal:

::

   | ?- logtalk_load(random(tester)).

To run all library tests, we can use the ``logtalk_tester`` automation
script from the ``library`` directory at the root of the Logtalk
distribution. For example, assuming the Logtalk user directory is
``~/logtalk`` and that we want to run the tests using ECLiPSe as the
backend Prolog compiler:

::

   $ cd ~/logtalk/library
   $ logtalk_tester -p eclipse

Library requirements
--------------------

Some of the libraries (notably, for the HTTP and SMTP functionality)
have third-party dependencies. The ``openssl`` (version 3.0.0 or later),
``ncat`` (version 7.96 or later), and ``socat`` (version 1.7.3.0 or
later) commands must be available on the system ``PATH``. The
``http_process_transport`` library uses by default ``socat`` on POSIX
systems and ``ncat`` on Windows. Both the ``http_process_transport`` and
the ``smtp`` libraries use the ``openssl`` command.

On macOS, these commands can be installed using e.g. Homebrew:

::

   $ brew install openssl nmap socat

Or using MacPorts:

::

   $ sudo port install openssl nmap socat

On Ubuntu, both commands can be installed using:

::

   $ sudo apt install openssl ncat socat

On RedHat distributions (8.x and later):

::

   $ sudo dnf install openssl nmap-ncat socat

For older RedHat distributions:

::

   $ sudo yum install openssl nmap-ncat socat

On Windows, ``openssl`` and ``ncat`` commands can be installed using
e.g. Chocolatey:

::

   > choco install openssl
   > choco install nmap

The ``socat`` command doesn't have an easy install solution on Windows;
use ``ncat`` instead.

Credits
-------

Some code in this library is based on public domain Prolog code, in
particular, code adopted from the Edinburgh Prolog library. The
definition of the predicate ``reverse/2`` in the ``list`` object is from
Richard O'Keefe and can be found in its book "The Craft of Prolog".

Some elements of this library are inspired by Richard O'Keefe library
proposal available at:

http://www.cs.otago.ac.nz/staffpriv/ok/pllib.htm

Some libraries, or parts of libraries, are either ports of Prolog system
libraries or inspired by Prolog system libraries. See the individual
library notes for details. See also the ``NOTICE.txt`` file at the root
of the Logtalk distribution for copyright information on third-party
source code.

Other notes
-----------

Some files contained in this directory represent work in progress and
are not loaded by default by any loader utility file.
