V.13 OpenACS conventions for TCL

OpenACS has introduced a couple of conventions for the use of TCL which have changed over the years while OpenACS has evolved. These conventions do not contradict anything you have learned so far, but when working within OpenACS, these Tips will help you get around:

Namespaces 

• why use them
• 
  

Procedures

Procedures in OpenACS are generated using "ad_proc". Issues to explain

ad_proc has the following advantages over proc

• A procedure can be declared as public, private, deprecated, and warn.
• Procedures can be declared with regular positional parameters (where you pass parameters in the order they were declared), or with named parameters, where the order doesn't matter because parameter names are specified explicitely when calling the parameter. Named parameters are preferred.
• If you use named parameters, you can specify which ones are required, optional, (including default values), and boolean. See the examples below.
• The declaration can (and should!) include documentation. This documentation may contain tags which are parsed for display by the api browser. Some tags are @param, @return, @error, @see, @author (probably this should be better documented).

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 (where some_boolean_value can be 0, 1, t, f, true, false), 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). Ignore the \ in "@param", I had to use it so the api-browser wouldn't think the parameter docs were for ad_proc itself:

namespace eval ::foobar {}

ad_proc -public ::foobar::new {
	{-oacs_user:boolean}
	{-shazam}
	{-user_id ""}
} {
	The documentation for this procedure should have a brief description of the 
	purpose of the procedure (the WHAT), but most importantly, WHY it does what it 
	does. One can read the code and see what it does (but it's quicker to see a
	description), but one cannot read the mind of the original programmer to find out 
	what s/he had in mind.

	@author Roberto Mello 
	@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. Required parameter.
	@param user_id The id for the user to process. Optional with default "" 
	                (api-browser will show the default automatically)
	@return Returns the result of the operation
} {
	if { [empty_string_p $user_id] } {
		# Do something if this is not an empty string
	}

	if { $oacs_user_p } {
		# Do something if this is an openacs user
	}
	return $result
}