ad_proc

ad_proc (public)

 ad_proc [ -public ] [ -private ] [ -deprecated ] [ -warn ] \
    [ -callback callback ] [ -impl impl ] arg_list [doc_string] body

Defined in packages/acs-bootstrap-installer/tcl/00-proc-procs.tcl
Declare a procedure with the following enhancements over regular Tcl "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 explicitly 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.

Positional parameters are always required, unless they provide with a default value, making them optional. If the parameter follows another positional parameter with a default value, a default value for it is also required.

As well as in the original Tcl "proc", if the last parameter is called "args", the proc will accept a variable number of arguments, which will be assigned to the variable "args" as elements of a list.

There is now a callback facility. See 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 and positional parameters, and also 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:required}
    {-foo}
    {-user_id ""}
    {pos}
    {pos_opt ""}
} {
    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 is defined
                        per default as "false", when specified as "true". The parameter is optional.
    \@param shazam      Magical incantation that calls Captain Marvel. Required parameter.
    \@param foo         Parameter, which can be omitted. Check with [info exists ...] if was given.
    \@param user_id     The id for the user to process. Optional with default "".
                        (api-browser shows the default).
    \@param pos         Positional parameter. Required, as it does not provide a default value.
    \@param pos_opt     Positional parameter. Optional with default "".
                        (api-browser shows the default).
    \@return empty list

    \@see ::foobar::related_proc
} {
    if { $user_id eq "" } {
        # Do something if this is not an empty string
    }
    if { [info exists foo] } {
        # Do something if we got a value for "foo"
    }

    if { $oacs_user_p } {
        # Do something if this is an OpenACS user
    }

    # return empty list anyway...
    return [list]
}
(note, most of the info on callbacks here due to leeldn)
You can define callbacks, both generally (which you would do first) and specific to a particular implementation. The way you do so is:

you have to first define the callback contract with ad_proc -callback foo::bar::zip { arg1 arg2 } { docs } -
This defines the callback generally. (Note! Don't define a body here!)
then define an implementation with ad_proc -callback foo::bar::zip -impl myimpl { } { } { #code }
Two ways to call:

then you can call _all_ implementations (i.e. in an event / event handler type arrangement) with callback foo::bar::zip $arg1 $arg2
or you can call a specific implementation (i.e. in a service contract type arrangement) with callback -impl myimpl foo::bar::zip $arg1 $arg2

in both cases the result is a list of the results of each called implementation (with empty results removed), so in the case of calling a specific implementation you get a list of one element as the result
See callback for more info.

Switches:

-public (optional, boolean)
specifies that the procedure is part of a public API.
-private (optional, boolean)
specifies that the procedure is package-private.
-deprecated (optional, boolean)
specifies that the procedure should not be used.
-warn (optional, boolean)
specifies that the procedure should generate a warning when invoked (requires that -deprecated also be set)
-callback (optional)
the name of the callback contract being defined or implemented. When this flag is specified, -private and -public flags are ignored and the resulting proc will always be private.
-impl (optional)
the name of the callback implementation for the specified contract

Parameters:

arg_list (required)
the list of switches and positional parameters which can be provided to the procedure.

[doc_string] (required)
documentation for the procedure (optional, but greatly desired).

body (required)
the procedure body. Documentation may be provided for an arbitrary function by passing the body as a "-".

Partial Call Graph (max 5 caller/called nodes):

Testcases:
ad_proc_create_callback

[ show source ]