Re: [libvirt] [PATCH 6/6] Add documentation new ways to access members of variables
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(a)redhat.com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
Attachments:
- signature.asc (application/pgp-signature — 620 bytes)