.. _root_api_app_autocompleter:

AutoCompleter
=====================

Объект ``AutoCompleter`` является компонентом ``Argenta``, отвечающим за интерактивное автодополнение команд. Его основная задача — улучшить опыт взаимодействия пользователя с командной строкой, предоставляя подсказки и автоматически завершая ввод на основе ранее введенных команд. Это значительно ускоряет работу и снижает вероятность опечаток.

``AutoCompleter`` использует ``pyreadline3`` для имплементации ``readline GNU`` на ``Windows`` для управления историей команд и реализации логики автодополнения.

-----

Инициализация
-------------

.. code:: python

  __init__(self, history_filename: str | None = None, 
           autocomplete_button: str = "tab") -> None

Создает и настраивает экземпляр ``AutoCompleter``.

* ``history_filename``: Имя файла для сохранения и загрузки истории команд. Если указано, история будет персистентной между сессиями приложения. Если **None**, история будет храниться только в памяти текущей сессии.
* ``autocomplete_button``: Название клавиши, которая активирует автодополнение. По умолчанию используется клавиша **"tab"**.

-----

Назначение и возможности
-------------------------

``AutoCompleter`` обладает следующими возможностями:

*   **Автодополнение по истории**: Основная логика автодополнения основана на истории команд, которые пользователь вводил ранее. Когда пользователь начинает вводить команду и нажимает клавишу автодополнения (по умолчанию **Tab**), система ищет в истории все команды, начинающиеся с введенного текста.

*   **Завершение по общему префиксу**: Если найдено несколько команд с общим префиксом, автодокомплитер подставит только общую часть. Например, если в истории есть команды ``show_users`` и ``show_profile``, при вводе ``sho`` и нажатии **Tab** будет подставлено ``show_``.

*   **Персистентная история**: При указании параметра ``history_filename`` в конструкторе, вся история команд сохраняется в файл при выходе из приложения и загружается при следующем запуске. Это делает автодополнение со временем все более "умным" и персонализированным.

*   **Очистка истории**: При сохранении истории ``AutoCompleter`` автоматически удаляет дубликаты и команды, которые больше не зарегистрированы в приложении, поддерживая актуальность и чистоту файла истории.

*   **Настройка клавиши активации**: Вы можете изменить клавишу, отвечающую за автодополнение, через параметр ``autocomplete_button``.
 
-----

Пример использования
--------------------

``AutoCompleter`` передается как аргумент при инициализации `App`.

.. literalinclude:: ../../../code_snippets/autocompleter_example_sample.py
    :language: python
    :linenos: