Filter: Methods rework

Methods can now be called as x.m(y), as long as x can have its type
inferred in config time. If used as a command, it modifies the object,
if used as a value, it keeps the original object intact.

Also functions add(x,y), delete(x,y), filter(x,y) and prepend(x,y) now
spit a warning and are considered deprecated.

It's also possible to call a method on a constant, see filter/test.conf
for examples like bgp_path = +empty+.prepend(1).

Inside instruction definitions (filter/f-inst.c), a METHOD_CONSTRUCTOR()
call is added, which registers the instruction as a method for the type
of its first argument. Each type has its own method symbol table and
filter parser switches between them based on the inferred type of the
object calling the method.

Also FI_CLIST_(ADD|DELETE|FILTER) instructions have been split to allow
for this method dispatch. With type inference, it's now possible.

1 files changed, 19 insertions, 19 deletions

diff --git a/doc/bird.sgml b/doc/bird.sgml
index 46e34c04..3fcf0025 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -1592,24 +1592,24 @@ in the foot).
 
 	<cf><m/P/.len</cf> returns the length of path <m/P/.
 
-	<cf><m/P/.empty</cf> makes the path <m/P/ empty.
+	<cf><m/P/.empty</cf> makes the path <m/P/ empty. Can't be used as a value, always modifies the object.
 
-	<cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
+	<cf><m/P/.prepend(<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
 	returns the result.
 
-	<cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from
+	<cf><m/P/.delete(<m/A/)</cf> deletes all instances of ASN <m/A/ from
 	from path <m/P/ and returns the result. <m/A/ may also be an integer
 	set, in that case the operator deletes all ASNs from path <m/P/ that are
 	also members of set <m/A/.
 
-	<cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are
-	not members of integer set <m/A/. I.e., <cf/filter/ do the same as
-	<cf/delete/ with inverted set <m/A/.
+	<cf><m/P/.filter(<m/A/)</cf> deletes all ASNs from path <m/P/ that are
+	not members of integer set <m/A/, and returns the result.
+	I.e., <cf/filter/ do the same as <cf/delete/ with inverted set <m/A/.
 
-	Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
-	<cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
-	(for example <cf/bgp_path/) or a local variable.
-	Similarly for <cf/delete/ and <cf/filter/.
+	Methods <cf>prepend</cf>, <cf>delete</cf> and <cf>filter</cf> keep the
+	original object intact as long as you use the result in any way. You can
+	also write e.g. <cf><m/P/.prepend(<m/A/);</cf> as a standalone statement.
+	This variant does modify the original object with the result of the operation.
 
 	<tag><label id="type-bgpmask">bgpmask</tag>
 	BGP masks are patterns used for BGP path matching (using <cf>path
@@ -1637,29 +1637,29 @@ in the foot).
 
 	<cf><m/C/.len</cf> returns the length of clist <m/C/.
 
-	<cf><m/C/.empty</cf> makes the list <m/C/ empty.
+	<cf><m/C/.empty</cf> makes the list <m/C/ empty. Can't be used as a value, always modifies the object.
 
-	<cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and
+	<cf><m/C/.add(<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and
 	returns the result. If item <m/P/ is already in clist <m/C/, it does
 	nothing. <m/P/ may also be a clist, in that case all its members are
 	added; i.e., it works as clist union.
 
-	<cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) <m/P/ from clist
+	<cf><m/C/.delete(<m/P/)</cf> deletes pair (or quad) <m/P/ from clist
 	<m/C/ and returns the result. If clist <m/C/ does not contain item
 	<m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that
 	case the operator deletes all items from clist <m/C/ that are also
 	members of set <m/P/. Moreover, <m/P/ may also be a clist, which works
 	analogously; i.e., it works as clist difference.
 
-	<cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are
-	not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same
+	<cf><m/C/.filter(<m/P/)</cf> deletes all items from clist <m/C/ that are
+	not members of pair (or quad) set <m/P/, and returns the result. I.e., <cf/filter/ do the same
 	as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which
 	works analogously; i.e., it works as clist intersection.
 
-	Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
-	<cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute (for
-	example <cf/bgp_community/) or a local variable.
-	Similarly for <cf/delete/ and <cf/filter/.
+	Methods <cf>add</cf>, <cf>delete</cf> and <cf>filter</cf> keep the
+	original object intact as long as you use the result in any way. You can
+	also write e.g. <cf><m/P/.add(<m/A/);</cf> as a standalone statement.
+	This variant does modify the original object with the result of the operation.
 
 	<cf><m/C/.min</cf> returns the minimum element of clist <m/C/.