search

ElektraInitiative / libelektra

Elektra serves as a universal and secure framework to access configuration settings in a global, hierarchical key database.
https://www.libelektra.org
BSD 3-Clause "New" or "Revised" License
208 stars 123 forks source link

create shell completion wrappers #4051

Closed markus2330 closed 10 months ago

markus2330 commented 3 years ago

In #3228 we develop a tool in Python which can answer the question: "Given a current command-line argument, what are the possibilities to complete such a command?".

This task here is to write shell completion wrappers for various shells to enable this improved and uniform autocompletion mechanism. It should replace:

max-thoma commented 3 years ago

Proposal

Authors: @4ydan & @muskater

Introduction

In this document we would like to give a concise overview and plan for the FLOSS project that we want to do for this course (194.114)

Project Type

We have chosen to contribute to the Elektra Initiative. Since we do not have a personal use case, where Elektra would not provide enough functionality, we would like to improve upon a known issue. In particular, we are both interested in this issue #4051 "create shell completion wrappers". There are three main reasons why we are interested in this task:

Motivation

The current shell completion wrappers are static and are located at

zsh: scripts/completion/kdb-zsh-noglob
     scripts/completion/kdb_zsh_completion
fish: scripts/completion/kdb.fish
bash: scripts/completion/kdb-bash-completion

In todays (20.10.2021) lecture @markus2330 shortly explained that every time a command line argument changes the shell completion wrappers needs to be updated manually. The process is tedious and prone to errors. To improve and automate this procedure, there is currently the following pull request in the making #3228. It is a python script that can do the following

[...] we develop a tool in Python which can answer the question: "Given a current command-line argument, what are the possibilities to complete such a command?".
see: #4051

Goals

The main goal is to have a spec file in which the possible command line "expressions" are well defined. From this spec file it shall be possible to derive the completion wrappers for the various shells. Also we would like to give the opportunity to list all available commands by pressing TAB and help the user narrow down his search by providing some letters of the desired command.

Immediate goals

The success of our project relies on the merge of #3228. Therefore we should have a close look and maybe offer to help the author in case they need help with the merge.

Implementation details

The programming language will be python. We could be using argcomplete and pythons built in cmd module but at this point of time it is no guarantee.

The completion wrapper themselves will of course be written in their respective shell language.

Relevance and Focus

Because every shell needs a customized wrapper there needs to be some sort of priority list for sub-goals. Since almost all big Linux distribution ship with bash as their standard shell, we would argue that in the beginning the focus should lie on good and reliable bash support. That being sad, I (muskater) am an avid fish user. Therefore I am very interested in also providing a good experience for the fish-shell. What is more, fish supports advanced auto completion mechanisms. We do not have prior experience working with zsh.

Issue tracker

Since Elektra uses git and GitHub we will also use this platform to track and discuss our progress.

Comparable initiatives

Good auto completion wrappers are the norm not the exception for most *Nix command line tools. Some utilities with exceptional auto completion that come to our mind are:

Since these are all FLOSS projects they might serve as reference on how to implement good shell wrappers.

For even more references on how to write completion wrappers we have found: bash-completion

Outlook

In case of success there is always the possibility to expand the idea and concept. There are many more shells that may would benefit from custom completion wrappers. Ksh or csh just to name a few.

Who does what

We do not have a fixed distribution of tasks yet. We both wrote on this proposal.

Suggestions are welcome!

markus2330 commented 2 years ago

Thank you for this excellent proposal!

This can improve the usability of Elektra (kdb) It makes Elektra more robust to refactoring and code/command changes.

Here is a small misunderstanding: the main goal is to make the specification language more useful. Because it already specifies which command-line options are available for an application (like kdb), we want to use this information to also offer auto-completion. So it is about usability but about the usability for applications using Elektra.

For kdb currently no complete specification has been written, so this would be also a task of this project.

The main goal is to have a spec file in which the possible command line "expressions" are well defined. From this spec file it shall be possible to derive the completion wrappers for the various shells.

This would be a possible implementation technique but it is much easier to have static shell completion wrappers and leave all the dynamic decision (derived from the spec file) to the python script.

Also we would like to give the opportunity to list all available commands by pressing TAB and help the user narrow down his search by providing some letters of the desired command.

"Also" is misleading: the shell completion is exactly about this TAB feature.

The success of our project relies on the merge of #3228. Therefore we should have a close look and maybe offer to help the author in case they need help with the merge.

:+1:

We could be using argcomplete and pythons built in cmd module but at this point of time it is no guarantee.

argcomplete or the cmd module will not be able to help you, as they use other python-specific specifications. The only connection to python is that the script that reads Elektra's specifications and computes possible commands is implemented in Python.

fish-shell

fish shell is actually already the best supported shell for the kdb completion. But currently the whole completion hard-codes everything that kdb could do (at moment of writing the fish completion). After using the spec, the fish completion should get much simpler.

What will the other two shells be? (as @lawli3t joins you)

Comparable initiatives

These are not comparable, we want to provide here a system where any application can write a spec file and gets auto-completion. So comparable initiatives are actually your previously mentioned ones: argcomplete or the cmd module.

4ydan commented 2 years ago

This can improve the usability of Elektra (kdb) It makes Elektra more robust to refactoring and code/command changes.

Here is a small misunderstanding: the main goal is to make the specification language more useful. Because it already specifies which command-line options are available for an application (like kdb), we want to use this information to also offer auto-completion. So it is about usability but about the usability for applications using Elektra.

As beginners in shell completion writing we are not fully sure what is meant by the specification language and where we can find a current one. Is this about the documentation of all commands and options or is it more an implementation thing.

markus2330 commented 2 years ago

Only the Python program needs to read+understand the specification language, in the shell completion file you "simply" need to execute the Python program with the correct arguments (the current arguments to complete and the application name this completion file is for).

markus2330 commented 2 years ago

https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org might be helpful for you.

github-actions[bot] commented 1 year ago

I mark this stale as it did not have any activity for one year. I'll close it in two weeks if no further activity occurs. If you want it to be alive again, ping by writing a message here or create a new issue with the remainder of this issue. Thank you for your contributions :sparkling_heart:

github-actions[bot] commented 10 months ago

I closed this now because it has been inactive for more than one year. If I closed it by mistake, please do not hesitate to reopen it or create a new issue with the remainder of this issue. Thank you for your contributions :sparkling_heart: