+ When a parameter is declared as boolean, it creates a variable $param_name_p. + For example: -foo:boolean will create a variable $foo_p. + If the parameter is passed, $foo_p will have value 1. Otherwise, + $foo_p will have value 0. +
++ Boolean named parameters can optionally take a boolean value than can + make your code cleaner. The following example by Michael Cleverly shows why: + If you had a procedure declared as ad_proc foobar {-foo:boolean} { ... }, + it could be invoked as foobar -foo, which could yield some code like + the following in your procedure: +
+
+if {$flush_p} {
+ some_proc -flush $key
+} else {
+ some_proc $key
+}
+
+
+ + However, you could invoke the procedure as foobar -foo=$some_boolean_value, + which could make your procedure cleaner because you could write instead: + some_proc -flush=$foo_p $key. + +
+ With named parameters, the same rule as the Tcl switch statement apply, + meaning that -- marks the end of the parameters. This is important if + your named parameter contains a value of something starting with a "-". +
+ +Here's an example with named parameters, and namespaces (notice the preferred way of - declaring namespaces and namespaced procedures). Disconsider the "\" in "\@param", + declaring namespaces and namespaced procedures). Ignore the "\" in "\@param", I had to use it so the api-browser wouldn't think the parameter docs were for ad_proc itself:
@@ -433,8 +458,8 @@ \@creation-date 2002-01-21 \@param oacs_user If this user is already an openacs user. oacs_user_p will be defined. - \@param shazam Magical incantation that calls Captain Marvel. - \@param user_id The id for the user to process. Default will be "" + \@param shazam Magical incantation that calls Captain Marvel. Required parameter. + \@param user_id The id for the user to process. Optional with default "" (api-browser will show the default automatically) } { if { [empty_string_p $user_id] } {