[libvirt] [PATCH] tools: Document completer callback

Michal Privoznik posted 1 patch 5 years, 2 months ago
Test syntax-check passed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/1cbe4a4ceabddd38ddc80889dd437177c43f645c.1548159353.git.mprivozn@redhat.com
tools/virsh-completer.c | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
[libvirt] [PATCH] tools: Document completer callback
Posted by Michal Privoznik 5 years, 2 months ago
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@redhat.com>
---
 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
+ * need it). Any completer that requires connection must check
+ * whether connection is still alive.
+ *
+ * The @cmd then holds parsed user input which might be missing
+ * some arguments (user is still typing the command), but may
+ * already contain important data. For instance if completer
+ * needs domain XML it may inspect @cmd to find --domain. Using
+ * existing wrappers is advised. If @cmd does not contain all
+ * necessary bits, completer might return sensible defaults (i.e.
+ * 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
+ * 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
+ * state that the command accepts.
+ *
+ * Under no circumstances a completer can output anything. Nor to
+ * stdout nor to stderr. This would harm the user experience.
+ */
+
+
 char **
 virshDomainNameCompleter(vshControl *ctl,
                          const vshCmd *cmd ATTRIBUTE_UNUSED,
-- 
2.19.2

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] tools: Document completer callback
Posted by John Ferlan 5 years, 2 months ago

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@redhat.com>
> ---
>  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@redhat.com>

John

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list