[Xcb] [PATCH proto 1/3 V2] xml-xcb spec: describe switch-case

[Ran Benita]

On Wed, Aug 20, 2014 at 11:10:35AM +0200, Christian Linhart wrote:
> 
> V2: patch revised according to suggestion from Peter Harris:
> * add the restriction that <enumref>
>   inside <bitcase> can only refer to an enum's <bit> members, and
>   <enumref> inside <case> can only refer to an enum's <value> members.

Replied on the V1 before, sorry.

Reviewed-by: Ran Benita <ran234 at gmail.com>

But you also need to update proto/src/xcb.xsd in this series. Run
"make check" in proto and make sure that it passes.

Ran

> ---
>  doc/xml-xcb.txt | 38 ++++++++++++++++++++++++++++++--------
>  1 file changed, 30 insertions(+), 8 deletions(-)
> 
> diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
> index 97ce5bf..f93db7d 100644
> --- a/doc/xml-xcb.txt
> +++ b/doc/xml-xcb.txt
> @@ -239,26 +239,48 @@ enum; the value is restricted to one of the constants named in the enum.
>    defining the set of values included, and a list containing these values.
>    value-mask-type gives the type of the bitmask; this must be CARD16 or
>    CARD32.  value-mask-name gives the field name of the bitmask, and
>    value-list-name gives the field name of the list of values. Please use
>    <switch> instead for new protocol definitions.
>  
>  <switch name="identifier"> switch expression
> -    <bitcase> bitcase expression(s), fields </bitcase> </switch>
> +    <bitcase> bitcase expression(s), fields </bitcase>
> +    <case> case expression(s), fields </case>
> +</switch>
>  
>    This element represents conditional inclusion of fields. It can be viewed
> -  as sequence of multiple ifs: if ( switch expression & bitcase expression )
> -  is non-zero, bitcase fields are included in structure.  It can be used only
> -  as the last field of a structure.
> +  as sequence of multiple ifs:
>  
> -  When a bitcase includes multiple <enumref> clauses, the contents of the
> -  bitcase are only present once regardless of the number of bitcase expressions
> -  that match.
> +  <bitcase>:
> +    if ( switch expression & bitcase expression ) is non-zero,
> +    bitcase fields are included in structure.
> +
> +  <case>:
> +    if ( switch expression == case expression ) is true,
> +    then case fields are included in structure.
> +
> +  It can be used only as the last field of a structure.
> +
> +  When a bitcase or case includes multiple <enumref> clauses, the contents
> +  of the bitcase or case are only present once regardless of the number of
> +  bitcase or case expressions that match.
> +
> +  <enumref> inside <bitcase> can only refer to an enum's <bit> members.
> +  <enumref> inside <case> can only refer to an enum's <value> members.
> +
> +  A switch may contain multiple <bitcase> or <case> elements.
> +  Usually it will only contain <bitcase> elements
> +  or only contain <case> elements.
> +  That is, mixing of <case> and <bitcase> usually doesn't make any sense.
> +
> +  The same value may appear in multiple <case> or <bitcase> elements.
> +
> +  New protocol definitions should prefer to use this instead of <valueparam>
> +  and instead of <union>.
>  
> -  New protocol definitions should prefer to use this instead of <valueparam>.
>  
>  Expressions
>  -----------
>  
>    Expressions consist of a tree of <op> elements with leaves consisting of
>    <fieldref> or <value> elements.
>  
> -- 2.0.1
> 
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb