[libvirt] [PATCH 6/6] Add documentation new ways to access members of variables

[Eric Blake]

On 12/09/2011 08:07 AM, Stefan Berger wrote:
> This patch adds documentation about the new 'ways' that users can
> access the contents of variables in filters:
> 
> - access via index: $TEST[2]
> - access via iterators $TEST[@1]
> 
> ---
>  docs/formatnwfilter.html.in |   32 +++++++++++++++++++++++++++++++-
>  1 file changed, 31 insertions(+), 1 deletion(-)
> 
> Index: libvirt-iterator/docs/formatnwfilter.html.in
> ===================================================================
> --- libvirt-iterator.orig/docs/formatnwfilter.html.in
> +++ libvirt-iterator/docs/formatnwfilter.html.in
> @@ -308,7 +308,37 @@
>    </rule>
>    ...
>  </pre>
> -
> +    <p>
> +      <span class="since">Since 0.9.9</span> it is possible to access

We missed the release; s/0.9.9/0.9.10/

> +      individual elements of a variable holding a list of elements.
> +      A filtering rule like the following accesses the 2nd element
> +      of the variable DSTPORTS.
> +    </p>
> +<pre>
> +  ...
> +  <rule action='accept' direction='in' priority='500'>
> +    <udp dstportstart='$DSTPORTS[1]'/>
> +  </rule>
> +  ...
> +</pre>
> +    <p>
> +      <span class="since">Since 0.9.9</span> it is possible to create

Likewise.

> +      filtering rules that instantiate all combinations of rules from
> +      different lists using the notation of
> +      <code>$VARIABLE[@<iterator ID>]</code>.
> +      The following rule allows a virtual machine to
> +      receive traffic on a set of ports, which are specified in DSTPORTS,
> +      from the set of source IP address specified in SRCIPADDRESSES.
> +      The rule generates all combinations of elements of the variable
> +      DSTPORT with those of SRCIPADDRESSES.

I would also mention:

$VARIABLE is short-hand for $VARIABLE[@0].  When combining variables,
each variable that uses the same iterator ID will be directly combined;
it is the use of different iterator IDs that causes all combinations to
be generated.

And maybe even mention an example:

If variable A is the list [1, 2], and variable B is the list [3, 4],
then combining $A[@0] and $B[@0] produces the list [1/3, 2/4], while
combining $A[@0] and $B[@1] produces the list [1/3, 1/4, 2/3, 2/4].

Overall, I like what is in this series, but I think I had enough minor
findings that it would be worth posting a v2 before pushing anything.

-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 620 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20120110/9a5f1138/attachment-0001.sig>