• Publicity: Public Only All

00-proc-procs.tcl

Routines for defining procedures and libraries of procedures (-procs.tcl files).

Location:
packages/acs-bootstrap-installer/tcl/00-proc-procs.tcl
Created:
7 Jun 2000
Author:
Jon Salz <jsalz@mit.edu>
CVS Identification:
$Id: 00-proc-procs.tcl,v 1.66.2.24 2021/07/29 15:58:44 antoniop Exp $

Procedures in this file

Detailed information

acs_package_root_dir (public)

 acs_package_root_dir package_key

Returns the path root for a particular package within the OpenACS installation. For example /web/yourserver/packages/foo, i.e., a full filesystem path with no ending slash.

Parameters:
package_key

Partial Call Graph (max 5 caller/called nodes):
%3 test_apm__test_info_file apm__test_info_file (test acs-tcl) acs_package_root_dir acs_package_root_dir test_apm__test_info_file->acs_package_root_dir test_auth_authenticate auth_authenticate (test acs-authentication) test_auth_authenticate->acs_package_root_dir test_documentation__check_typos documentation__check_typos (test acs-tcl) test_documentation__check_typos->acs_package_root_dir ad_core_docs_html_redirector ad_core_docs_html_redirector (private) ad_core_docs_html_redirector->acs_package_root_dir apm::metrics_internal apm::metrics_internal (private) apm::metrics_internal->acs_package_root_dir apm_bootstrap_load_libraries apm_bootstrap_load_libraries (private) apm_bootstrap_load_libraries->acs_package_root_dir apm_get_package_files apm_get_package_files (public) apm_get_package_files->acs_package_root_dir apm_mark_version_for_reload apm_mark_version_for_reload (public) apm_mark_version_for_reload->acs_package_root_dir

Testcases:
auth_authenticate, apm__test_info_file, documentation__check_typos

acs_root_dir (public)

 acs_root_dir

Returns the path root for the OpenACS installation.

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_api_browser_api_read_script_documentation acs_api_browser_api_read_script_documentation (test acs-api-browser) acs_root_dir acs_root_dir test_acs_api_browser_api_read_script_documentation->acs_root_dir test_acs_api_browser_api_script_documentation acs_api_browser_api_script_documentation (test acs-api-browser) test_acs_api_browser_api_script_documentation->acs_root_dir test_acs_mail_lite_inbound_procs_check acs_mail_lite_inbound_procs_check (test acs-mail-lite) test_acs_mail_lite_inbound_procs_check->acs_root_dir test_oacs_dav_put oacs_dav_put (test oacs-dav) test_oacs_dav_put->acs_root_dir Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->acs_root_dir acs_mail_lite::imap_email_parse acs_mail_lite::imap_email_parse (private) acs_mail_lite::imap_email_parse->acs_root_dir acs_mail_lite::maildir_email_parse acs_mail_lite::maildir_email_parse (private) acs_mail_lite::maildir_email_parse->acs_root_dir fs::install::upgrade fs::install::upgrade (private) fs::install::upgrade->acs_root_dir install::xml::action::load-categories install::xml::action::load-categories (public) install::xml::action::load-categories->acs_root_dir

Testcases:
acs_api_browser_api_read_script_documentation, acs_api_browser_api_script_documentation, acs_mail_lite_inbound_procs_check, oacs_dav_put

ad_arg_parser (public)

 ad_arg_parser allowed_args argv

Parses an argument list for a database call (switches at the end). Switch values are placed in corresponding variable names in the calling environment. GN: This function is a hack to overcome shortcomings of argument parsing at the first place, since the old-style argument parser of OpenACS does NOT support non-positional arguments after the positional ones. Since the advent of XOTcl2, this limitation is gone and just used for installations without XOTcl.... but since XOTcl is required since many years, this is not an issue anymore.

Parameters:
allowed_args - a list of allowable switch names.
argv - a list of command-line options. May end with args to indicate that extra values should be tolerated after switches and placed in the args list.
Error:
if the list of command-line options is not valid.

Partial Call Graph (max 5 caller/called nodes):
%3 ad_page_contract ad_page_contract (public) ad_arg_parser ad_arg_parser ad_page_contract->ad_arg_parser db_blob_get db_blob_get (public) db_blob_get->ad_arg_parser db_blob_get_file db_blob_get_file (public) db_blob_get_file->ad_arg_parser db_dml db_dml (public) db_dml->ad_arg_parser db_foreach db_foreach (public) db_foreach->ad_arg_parser

Testcases:
No testcase defined.

ad_assert_arg_value_in_list (public, deprecated)

 ad_assert_arg_value_in_list arg_name allowed_values_list
Deprecated. Invoking this procedure generates a warning.

For use at the beginning of the body of a procedure to check that an argument has one of a number of allowed values.

Parameters:
arg_name - The name of the argument to check
allowed_values_list - The list of values that are permissible for the argument Deprecated: this proc can be replaced via very simple expr or if idioms
Returns:
Returns 1 if the argument has a valid value, throws an informative error otherwise.
Author:
Peter Marklund

See Also:
  • native if or expr idioms

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

Testcases:
No testcase defined.

ad_call_method (public, deprecated)

 ad_call_method method_name object_id [ args... ]
Deprecated. Invoking this procedure generates a warning.

Calls method_name for the type of object_id with object_id as the first arg, and the remaining args are the remainder of the args to method_name. Example: ad_call_method method1 foo bar baz calls the method1 associated with the type of foo, with foo bar and baz as the 3 arguments.

Parameters:
method_name - method name
object_id - the target, it is the first arg to the method

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

Testcases:
No testcase defined.

ad_dispatch (public, deprecated)

 ad_dispatch method_name type [ args... ]
Deprecated. Invoking this procedure generates a warning.

Calls method_name with the type as the first arg, and the remaining args are the remainder of the args to method_name. Example: "ad_dispatch method1 foo bar baz" calls the method1 associated with the type foo, with foo bar and baz as the 3 arguments.

Parameters:
method_name - method name
type - associated type

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

Testcases:
No testcase defined.

ad_file (public)

 ad_file subcmd arg1 [ args... ]

Tcl supports csh-style tilde substitution. If a filename starts with a tilde, then the filename will be interpreted as if the first element is replaced with the location of the home directory for the given user. If the user does not exist, an exception is raised. (e.g. [file dirname ~gustafn.foo]). https://www.tcl-lang.org/man/tcl/TclCmd/filename.htm#M20 This little proc can be used in cases, where (a) the tilde-substitution is unwanted, and where the "name" argument (usually the first argument after the subcommand) might contain user provided values.

Parameters:
subcmd
arg1

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_file ad_file (test acs-bootstrap-installer) ad_file ad_file test_ad_file->ad_file test_files__check_upgrade_ordering files__check_upgrade_ordering (test acs-tcl) test_files__check_upgrade_ordering->ad_file test_files__check_xql_files files__check_xql_files (test acs-tcl) test_files__check_xql_files->ad_file test_files__page_contracts files__page_contracts (test acs-tcl) test_files__page_contracts->ad_file test_files__tcl_file_common_errors files__tcl_file_common_errors (test acs-tcl) test_files__tcl_file_common_errors->ad_file Object ::throttle Object ::throttle (public) Object ::throttle->ad_file ad_acs_require_basic_schemata ad_acs_require_basic_schemata (private) ad_acs_require_basic_schemata->ad_file apm_bootstrap_load_file apm_bootstrap_load_file (private) apm_bootstrap_load_file->ad_file apm_get_changed_watched_files apm_get_changed_watched_files (private) apm_get_changed_watched_files->ad_file apm_guess_db_type apm_guess_db_type (public) apm_guess_db_type->ad_file

Testcases:
ad_file, files__tcl_file_syntax_errors, files__tcl_file_common_errors, files__check_upgrade_ordering, files__check_xql_files, files__trailing_whitespace, files__page_contracts

ad_library (public)

 ad_library doc_string

Provides documentation for a library (-procs.tcl file).

Parameters:
doc_string

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-admin/tcl/acs-admin-init.tcl packages/acs-admin/ tcl/acs-admin-init.tcl ad_library ad_library packages/acs-admin/tcl/acs-admin-init.tcl->ad_library packages/acs-admin/tcl/apm-admin-init.tcl packages/acs-admin/ tcl/apm-admin-init.tcl packages/acs-admin/tcl/apm-admin-init.tcl->ad_library packages/acs-authentication/tcl/sync-init.tcl packages/acs-authentication/ tcl/sync-init.tcl packages/acs-authentication/tcl/sync-init.tcl->ad_library packages/acs-automated-testing/tcl/authority-init.tcl packages/acs-automated-testing/ tcl/authority-init.tcl packages/acs-automated-testing/tcl/authority-init.tcl->ad_library packages/acs-core-docs/www/files/note-procs.tcl packages/acs-core-docs/ www/files/note-procs.tcl packages/acs-core-docs/www/files/note-procs.tcl->ad_library

Testcases:
No testcase defined.

ad_make_relative_path (public)

 ad_make_relative_path path

Returns the relative path corresponding to absolute path $path.

Parameters:
path

Partial Call Graph (max 5 caller/called nodes):
%3 ad_library ad_library (public) ad_make_relative_path ad_make_relative_path ad_library->ad_make_relative_path apm_get_watchable_files apm_get_watchable_files (private) apm_get_watchable_files->ad_make_relative_path apm_source apm_source (public) apm_source->ad_make_relative_path db_qd_get_fullname db_qd_get_fullname (public) db_qd_get_fullname->ad_make_relative_path db_qd_internal_load_queries db_qd_internal_load_queries (private) db_qd_internal_load_queries->ad_make_relative_path

Testcases:
No testcase defined.

ad_method (public, deprecated)

 ad_method method_name type argblock docblock body
Deprecated. Invoking this procedure generates a warning.

Defines a method for type based dispatch. This method can be called using ad_call_method. The first arg to the method is the target on which the type dispatch happens. Use this with care.

Parameters:
method_name - the method name
type - the type for which this method will be used
argblock - the argument description block, is passed to ad_proc
docblock - the documentation block, is passed to ad_proc
body - the body, is passed to ad_proc

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

Testcases:
No testcase defined.

ad_proc (public)

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

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 (boolean) (optional)
specifies that the procedure is part of a public API.
-private (boolean) (optional)
specifies that the procedure is package-private.
-deprecated (boolean) (optional)
specifies that the procedure should not be used.
-warn (boolean) (optional)
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 - the list of switches and positional parameters which can be provided to the procedure.
[doc_string] - documentation for the procedure (optional, but greatly desired).
body - 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):
%3 test_ad_proc_create_callback ad_proc_create_callback (test acs-tcl) ad_proc ad_proc test_ad_proc_create_callback->ad_proc Class ::xo::db::Class Class ::xo::db::Class (public) Class ::xo::db::Class->ad_proc Object ::throttle Object ::throttle (public) Object ::throttle->ad_proc aa_register_case aa_register_case (public) aa_register_case->ad_proc aa_register_component aa_register_component (public) aa_register_component->ad_proc aa_register_init_class aa_register_init_class (public) aa_register_init_class->ad_proc

Testcases:
ad_proc_create_callback

ad_with_deprecated_code_p (public)

 ad_with_deprecated_code_p

Check, if we should load deprecated code. In order to skip loading of deprecated code, use the following snippet in your config file # ns_section ns/server/${server}/acs # ns_param WithDeprecatedCode 0

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

Testcases:
No testcase defined.

callback (public)

 callback [ -catch ] [ -impl impl ] callback [ args... ]

Invoke the registered callback implementations for the given callback. The callbacks terminate on error unless -catch is provided. The value returned by the callback function is determined by the return codes from the callback implementations.

The callbacks are executed one level below the calling function so passing arrays to a callback can be done normally via

upvar arrayname $arrayref

The return codes returned from the implementation are treated as follows:

return -code ok or "return"
With a plain return, a nonempty return value will be lappended to the list of returns from the callback function
return -code error or "error"
errors will simply propagate (and no value returned) unless -catch is specified in which case the callback processing will continue but no value will be appended to the return list for the implementation which returned an error.
return -code return
Takes the return value if the implementation returning -code return and returns a one element list with that return value. Note that this means if you have code which returns return -code return {x y}, you will get {{x y}} as the return value from the callback. This is done in order to unambiguously distinguish a pair of callbacks returning x and y respectively from this single callback.
return -code break
return the current list of returned values including this implementations return value if nonempty
return -code continue
Continue processing, ignore the return value from this implementation

Switches:
-catch (boolean) (optional)
if catch specified errors in the callback will be caught, tracebacks logged as errors to the server log, but other callbacks called and the list of returns still returned. If not given an error simply is passed further on.
-impl (defaults to "*") (optional)
invoke a specific implementation rather than all implementations of the given callback
Parameters:
callback - the callback name without leading or trailing ::
Returns:
list of the returns from each callback that does a normal (nonempty) return

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_proc_create_callback ad_proc_create_callback (test acs-tcl) callback callback test_ad_proc_create_callback->callback test_ad_proc_fire_callback ad_proc_fire_callback (test acs-tcl) test_ad_proc_fire_callback->callback Class ::ms::Graph Class ::ms::Graph (public) Class ::ms::Graph->callback Class ::xo::oauth::TempCredentials Class ::xo::oauth::TempCredentials (public) Class ::xo::oauth::TempCredentials->callback acs_mail_lite::inbound_queue_pull acs_mail_lite::inbound_queue_pull (private) acs_mail_lite::inbound_queue_pull->callback acs_mail_lite::load_mails acs_mail_lite::load_mails (public, deprecated) acs_mail_lite::load_mails->callback acs_mail_lite::send_immediately acs_mail_lite::send_immediately (private) acs_mail_lite::send_immediately->callback

Testcases:
ad_proc_create_callback, ad_proc_fire_callback

empty_string_p (public, deprecated)

 empty_string_p query_string
Deprecated. Invoking this procedure generates a warning.

returns 1 if a string is empty; this is better than using == because it won't fail on long strings of numbers. This might have been needed in the old good days, but not anymore.

Parameters:
query_string

See Also:
  • string equal

Partial Call Graph (max 5 caller/called nodes):
%3 dir_alpha_nav_bar dir_alpha_nav_bar (public) empty_string_p empty_string_p dir_alpha_nav_bar->empty_string_p etp::get_page_attributes etp::get_page_attributes (public) etp::get_page_attributes->empty_string_p irc::logger::update_log irc::logger::update_log (public) irc::logger::update_log->empty_string_p packages/directory/www/index.tcl packages/directory/ www/index.tcl packages/directory/www/index.tcl->empty_string_p packages/edit-this-page/www/etp-edit.tcl packages/edit-this-page/ www/etp-edit.tcl packages/edit-this-page/www/etp-edit.tcl->empty_string_p

Testcases:
No testcase defined.
[ show source ]