On 1/22/19 7:15 AM, Michal Privoznik wrote:
> Strictly speaking, this should go near vshCompleter typedef
> declaration. However, I find it more useful near actual completer
> implementations.
>
> Signed-off-by: Michal Privoznik <mprivozn@xxxxxxxxxx>
> ---
> tools/virsh-completer.c | 32 ++++++++++++++++++++++++++++++++
> 1 file changed, 32 insertions(+)
>
> diff --git a/tools/virsh-completer.c b/tools/virsh-completer.c
> index cfbfeae328..7a637a0cfa 100644
> --- a/tools/virsh-completer.c
> +++ b/tools/virsh-completer.c
> @@ -35,6 +35,38 @@
> #include "virxml.h"
>
>
> +/**
> + * A completer callback is a function that accepts three arguments:
> + *
> + * @ctl: virsh control structure
> + * @cmd: parsed input
> + * @flags: optional flags to alter completer's behaviour
> + *
> + * The @ctl contains connection to the daemon (should completer
^^^
should the
> + * need it). Any completer that requires connection must check
^^^^
requires a
> + * whether connection is still alive.
^^^
the connection
> + *
> + * The @cmd then holds parsed user input which might be missing
The @cmd contains parsed
> + * some arguments (user is still typing the command), but may
^^^
(if user
> + * already contain important data. For instance if completer
^^^
if the
> + * needs domain XML it may inspect @cmd to find --domain. Using
^^
XML,
> + * existing wrappers is advised. If @cmd does not contain all
> + * necessary bits, completer might return sensible defaults (i.e.
^^^
the completer
> + * generic values not tailored to specific use case) or return
> + * NULL (i.e. no strings are offered to the user for completion).
> + *
> + * The @flags then contain .completer_flags value defined for
The @flags contains a
> + * each use or 0 if no .completer_flags were specified. If a
> + * completer is generic enough @flags can be used to alter it's
> + * behaviour. For instance, a completer to fetch names of domains
> + * can use @flags to return names of only domains in particular
^^^
in a particular
> + * state that the command accepts.
> + *
> + * Under no circumstances a completer can output anything. Nor to
Under no circumstances should a completer output anything. Neither to
stdout nor to stderr.
> + * stdout nor to stderr. This would harm the user experience.
> + */
> +
> +
> char **
> virshDomainNameCompleter(vshControl *ctl,
> const vshCmd *cmd ATTRIBUTE_UNUSED,
>
Hope the edits make sense ...
Reviewed-by: John Ferlan <jferlan@xxxxxxxxxx>
John
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list
