Kevin Wolf <kw...@redhat.com> writes:
> This adds functions to the Visitor interface that can be used to define
> aliases and alias scopes.
>
> Signed-off-by: Kevin Wolf <kw...@redhat.com>
> ---
> include/qapi/visitor-impl.h | 12 ++++++++++++
> include/qapi/visitor.h | 37 +++++++++++++++++++++++++++++++++++++
> qapi/qapi-visit-core.c | 21 +++++++++++++++++++++
> 3 files changed, 70 insertions(+)
>
> diff --git a/include/qapi/visitor-impl.h b/include/qapi/visitor-impl.h
> index 7362c043be..e30da2599c 100644
> --- a/include/qapi/visitor-impl.h
> +++ b/include/qapi/visitor-impl.h
> @@ -113,6 +113,18 @@ struct Visitor
> The core takes care of the return type in the public interface. */
> void (*optional)(Visitor *v, const char *name, bool *present);
>
> + /*
> + * Optional; intended for input visitors. If not given, aliases are
> + * ignored.
> + */
> + void (*define_alias)(Visitor *v, const char *alias, const char **source);
> +
> + /* Must be set if define_alias is set */
> + void (*start_alias_scope)(Visitor *v);
> +
> + /* Must be set if define_alias is set */
> + void (*end_alias_scope)(Visitor *v);
> +
> /* Must be set */
> VisitorType type;
>
> diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h
> index ebc19ede7f..9bdc0ee03d 100644
> --- a/include/qapi/visitor.h
> +++ b/include/qapi/visitor.h
> @@ -459,6 +459,43 @@ void visit_end_alternate(Visitor *v, void **obj);
> */
> bool visit_optional(Visitor *v, const char *name, bool *present);
>
> +/*
> + * Defines a new alias rule.
> + *
> + * If @alias is non-NULL, the member named @alias in the external
> + * representation of the current struct is defined as an alias for the
> + * member described by @source.
> + *
> + * If @alias is NULL, all members of the struct described by @source are
> + * considered to have alias members with the same key in the current
> + * struct.
> + *
> + * @source is a NULL-terminated array of names that describe the path to
> + * a member, starting from the currently visited struct.
> + *
> + * The alias stays valid until the current alias scope ends.
> + * visit_start/end_struct() implicitly start/end an alias scope.
> + * Additionally, visit_start/end_alias_scope() can be used to explicitly
> + * create a nested alias scope.
> + */
> +void visit_define_alias(Visitor *v, const char *alias, const char **source);
> +
> +/*
> + * Begins an explicit alias scope.
> + *
> + * Alias definitions after here will only stay valid until the
> + * corresponding visit_end_alias_scope() is called.
> + */
> +void visit_start_alias_scope(Visitor *v);
> +
> +/*
> + * Ends an explicit alias scope.
> + *
> + * Alias definitions between the correspoding visit_start_alias_scope()
> + * call and here go out of scope and won't apply in later code any more.
> + */
> +void visit_end_alias_scope(Visitor *v);
> +
> /*
> * Visit an enum value.
> *
> diff --git a/qapi/qapi-visit-core.c b/qapi/qapi-visit-core.c
> index 7e5f40e7f0..719a9f5da2 100644
> --- a/qapi/qapi-visit-core.c
> +++ b/qapi/qapi-visit-core.c
> @@ -135,6 +135,27 @@ bool visit_optional(Visitor *v, const char *name, bool
> *present)
> return *present;
> }
>
> +void visit_define_alias(Visitor *v, const char *alias, const char **source)
> +{
> + if (v->define_alias) {
> + v->define_alias(v, alias, source);
> + }
> +}
> +
> +void visit_start_alias_scope(Visitor *v)
> +{
> + if (v->start_alias_scope) {
> + v->start_alias_scope(v);
> + }
> +}
> +
> +void visit_end_alias_scope(Visitor *v)
> +{
> + if (v->end_alias_scope) {
> + v->end_alias_scope(v);
> + }
> +}
> +
> bool visit_is_input(Visitor *v)
> {
> return v->type == VISITOR_INPUT;
The code is trivial and neat, the contracts look fine. What I'm missing
is "why do we want this", and "how should it be used". The cover letter
gives me a (somewhat vague) idea on the former, but on the latter, I can
only guess. I trust it'll become clear later in this series.
I think updating the big comment in visitor.h for aliases would help.
Let's postpone it until I've seen the rest of the series.
