.. index:: single: lemmatizer_protocol
.. _lemmatizer_protocol/0:

.. rst-class:: right

**protocol**

``lemmatizer_protocol``
=======================

Lemmatization protocol for words represented as atoms, lists of characters, or lists of character codes.

| **Availability:** 
|    ``logtalk_load(lemmatization(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-09-08

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: lemma/2
.. _lemmatizer_protocol/0::lemma/2:

``lemma/2``
^^^^^^^^^^^

Enumerates the distinct lemmas of a word in provider preference order. Returns the normalized word when no lemma is recognized.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``lemma(Word,Lemma)``
| **Mode and number of proofs:**
|    ``lemma(+text,-text)`` - ``one_or_more_or_error``

| **Exceptions:**
|    The ``Representation`` parameter is a variable:
|        ``instantiation_error``
|    The ``Representation`` parameter is neither a variable nor ``atom``, ``chars``, or ``codes``:
|        ``domain_error(text_representation,Representation)``
|    The ``Language`` parameter is a variable:
|        ``instantiation_error``
|    The ``Language`` parameter neither a variable nor an object identifier:
|        ``type_error(object_identifier,Language)``
|    The ``Language`` parameter is an object identifier but not an object conforming to ``lemmatizer_language_protocol``:
|        ``domain_error(lemmatizer_language_protocol,Language)``
|    ``Word`` is not ground:
|        ``instantiation_error``
|    The ``Representation`` parameter is ``atom`` but ``Word`` is not an atom:
|        ``type_error(atom,Word)``
|    The ``Representation`` parameter is ``chars`` but ``Word`` is not a list of characters:
|        ``type_error(chars,Word)``
|    The ``Representation`` parameter is ``codes`` but ``Word`` is not a list of character codes:
|        ``type_error(codes,Word)``


------------

.. index:: lemma/3
.. _lemmatizer_protocol/0::lemma/3:

``lemma/3``
^^^^^^^^^^^

Lemmatizes a word using the given options. Recognized options are ``part_of_speech(PartOfSpeech)``, ``ambiguity(Policy)``, where ``Policy`` is ``first`` or ``all``, and ``unknown(Policy)``, where ``Policy`` is ``normalize``, ``preserve``, or ``fail``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``lemma(Word,Lemma,Options)``
| **Mode and number of proofs:**
|    ``lemma(+text,-text,+list(compound))`` - ``zero_or_more_or_error``

| **Exceptions:**
|    The ``Representation`` parameter is a variable:
|        ``instantiation_error``
|    The ``Representation`` parameter is neither a variable nor ``atom``, ``chars``, or ``codes``:
|        ``domain_error(text_representation,Representation)``
|    The ``Language`` parameter is a variable:
|        ``instantiation_error``
|    The ``Language`` parameter neither a variable nor an object identifier:
|        ``type_error(object_identifier,Language)``
|    The ``Language`` parameter is an object identifier but not an object conforming to ``lemmatizer_language_protocol``:
|        ``domain_error(lemmatizer_language_protocol,Language)``
|    ``Word`` is not ground:
|        ``instantiation_error``
|    The ``Representation`` parameter is ``atom`` but ``Word`` is not an atom:
|        ``type_error(atom,Word)``
|    The ``Representation`` parameter is ``chars`` but ``Word`` is not a list of characters:
|        ``type_error(chars,Word)``
|    The ``Representation`` parameter is ``codes`` but ``Word`` is not a list of character codes:
|        ``type_error(codes,Word)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    An element of the list ``Options`` is a ``parts_of_speech/1`` option, which is only valid for ``lemmas/3``:
|        ``domain_error(option,parts_of_speech(A))``


------------

.. index:: lemmas/2
.. _lemmatizer_protocol/0::lemmas/2:

``lemmas/2``
^^^^^^^^^^^^

Lemmatizes a list of words, selecting the first lemma for each word and preserving order. Returns normalized words when no lemma is recognized.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``lemmas(Words,Lemmas)``
| **Mode and number of proofs:**
|    ``lemmas(+list(text),-list(text))`` - ``one_or_error``

| **Exceptions:**
|    The ``Representation`` parameter is a variable:
|        ``instantiation_error``
|    The ``Representation`` parameter is neither a variable nor ``atom``, ``chars``, or ``codes``:
|        ``domain_error(text_representation,Representation)``
|    The ``Language`` parameter is a variable:
|        ``instantiation_error``
|    The ``Language`` parameter neither a variable nor an object identifier:
|        ``type_error(object_identifier,Language)``
|    The ``Language`` parameter is an object identifier but not an object conforming to ``lemmatizer_language_protocol``:
|        ``domain_error(lemmatizer_language_protocol,Language)``
|    ``Words`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Words`` is neither a variable nor a list:
|        ``type_error(list,Words)``
|    An element ``Word`` of the list ``Words`` is not ground:
|        ``instantiation_error``
|    The ``Representation`` parameter is ``atom`` but a ground element ``Word`` of the list ``Words`` is not an atom:
|        ``type_error(atom,Word)``
|    The ``Representation`` parameter is ``chars`` but an element ``Word`` of the list ``Words`` is not a list of characters:
|        ``type_error(chars,Word)``
|    The ``Representation`` parameter is ``codes`` but an element ``Word`` of the list ``Words`` is not a list of character codes:
|        ``type_error(codes,Word)``


------------

.. index:: lemmas/3
.. _lemmatizer_protocol/0::lemmas/3:

``lemmas/3``
^^^^^^^^^^^^

Lemmatizes a list of words using the given options. In addition to the scalar options, accepts ``parts_of_speech(PartsOfSpeech)`` for per-word hints. The ``part_of_speech/1`` and ``parts_of_speech/1`` options are mutually exclusive.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``lemmas(Words,Lemmas,Options)``
| **Mode and number of proofs:**
|    ``lemmas(+list(text),-list(text),+list(compound))`` - ``zero_or_more_or_error``

| **Exceptions:**
|    The ``Representation`` parameter is a variable:
|        ``instantiation_error``
|    The ``Representation`` parameter is neither a variable nor ``atom``, ``chars``, or ``codes``:
|        ``domain_error(text_representation,Representation)``
|    The ``Language`` parameter is a variable:
|        ``instantiation_error``
|    The ``Language`` parameter neither a variable nor an object identifier:
|        ``type_error(object_identifier,Language)``
|    The ``Language`` parameter is an object identifier but not an object conforming to ``lemmatizer_language_protocol``:
|        ``domain_error(lemmatizer_language_protocol,Language)``
|    ``Words`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Words`` is neither a variable nor a list:
|        ``type_error(list,Words)``
|    An element ``Word`` of the list ``Words`` is not ground:
|        ``instantiation_error``
|    The ``Representation`` parameter is ``atom`` but a ground element ``Word`` of the list ``Words`` is not an atom:
|        ``type_error(atom,Word)``
|    The ``Representation`` parameter is ``chars`` but an element ``Word`` of the list ``Words`` is not a list of characters:
|        ``type_error(chars,Word)``
|    The ``Representation`` parameter is ``codes`` but an element ``Word`` of the list ``Words`` is not a list of character codes:
|        ``type_error(codes,Word)``
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    The ``part_of_speech(POS)`` and ``parts_of_speech(PsOS)`` options are both present:
|        ``consistency_error(mutually_exclusive_options,part_of_speech(POS),parts_of_speech(PsOS))``
|    The ``Words`` and ``PartsOfSpeech`` lists have different lengths:
|        ``consistency_error(same_length,Words,PartsOfSpeech)``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`lemmatizer_language_protocol <lemmatizer_language_protocol/0>`, :ref:`lemmatizer(Representation,Language) <lemmatizer/2>`