• Publicity: Public Only All

utilities-procs.tcl

Provides a variety of non-ACS-specific utilities, including the procs to support the who's online feature.

Location:
packages/acs-tcl/tcl/utilities-procs.tcl
Created:
13 April 2000
Author:
Various <acs@arsdigita.com>
CVS Identification:
$Id: utilities-procs.tcl,v 1.196 2024/10/24 14:09:09 gustafn Exp $

Procedures in this file

Detailed information

ad_apply (public, deprecated)

 ad_apply func arglist
Deprecated. Invoking this procedure generates a warning.

Evaluates the first argument with ARGLIST as its arguments, in the environment of its caller. Analogous to the Lisp function of the same name. DEPRECATED: modern Tcl can achieve the same result simply by expanding a list as arguments of a command.

Parameters:
func (required)
arglist (required)
See Also:
  • {*}

Partial Call Graph (max 5 caller/called nodes):
%3 ad_dispatch ad_dispatch (public, deprecated) ad_apply ad_apply ad_dispatch->ad_apply ad_log_deprecated ad_log_deprecated (public) ad_apply->ad_log_deprecated

Testcases:
No testcase defined.

ad_cache_returnredirect (public)

 ad_cache_returnredirect url [ persistent ] [ excluded_vars ]

An addition to ad_returnredirect. It caches all variables in the redirect except those in excluded_vars and then calls ad_returnredirect with the resultant string.

Parameters:
url (required)
persistent (optional, defaults to "f")
excluded_vars (optional)
Author:
Brad Duell <bduell@ncacasi.org>

Partial Call Graph (max 5 caller/called nodes):
%3 template::forward template::forward (public) ad_cache_returnredirect ad_cache_returnredirect template::forward->ad_cache_returnredirect ad_conn ad_conn (public) ad_cache_returnredirect->ad_conn ad_get_client_property ad_get_client_property (public) ad_cache_returnredirect->ad_get_client_property ad_returnredirect ad_returnredirect (public) ad_cache_returnredirect->ad_returnredirect ad_set_client_property ad_set_client_property (public) ad_cache_returnredirect->ad_set_client_property export_vars export_vars (public) ad_cache_returnredirect->export_vars

Testcases:
No testcase defined.

ad_decode (public)

 ad_decode value [ args... ]

This procedure is analogous to sql decode procedure. The first parameter is the value we want to decode. This parameter is followed by a list of pairs where first element in the pair is convert from value and second element is convert to value. The last value is default value, which will be returned in the case convert from values matches the given value to be decoded. Note that in most cases native Tcl idioms such as expr or switch will do the trick. This proc CAN make sense when one has many alternatives to decode, as in such cases a switch statement would not be as compact.

Good usage:
ad_decode $value f Foo b Bar d Dan s Stan l Lemon m Melon Unknown
---> a oneliner as opposed to a long switch statement

Bad usage:
ad_decode $boolean_p t 0 1
---> just use expr {!$boolean_p}

Parameters:
value (required)
input value
Returns:
matched value or default

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_decode ad_decode (test acs-tcl) ad_decode ad_decode test_ad_decode->ad_decode test_datamodel__named_constraints datamodel__named_constraints (test acs-tcl) test_datamodel__named_constraints->ad_decode Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->ad_decode Class ::xowiki::includelet::book Class ::xowiki::includelet::book (public) Class ::xowiki::includelet::book->ad_decode Class ::xowiki::includelet::toc Class ::xowiki::includelet::toc (public) Class ::xowiki::includelet::toc->ad_decode acs_admin::posture_status acs_admin::posture_status (private) acs_admin::posture_status->ad_decode bm_delete_permission_p bm_delete_permission_p (public) bm_delete_permission_p->ad_decode

Testcases:
ad_decode, datamodel__named_constraints

ad_generate_random_string (public)

 ad_generate_random_string [ length ]

Generates a random string made of numbers and letters

Parameters:
length (optional, defaults to "8")

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_content_repository_trivial_smoke_test acs_content_repository_trivial_smoke_test (test acs-content-repository) ad_generate_random_string ad_generate_random_string test_acs_content_repository_trivial_smoke_test->ad_generate_random_string test_auth_create_user auth_create_user (test acs-authentication) test_auth_create_user->ad_generate_random_string test_auth_driver_get_parameter_values auth_driver_get_parameter_values (test acs-authentication) test_auth_driver_get_parameter_values->ad_generate_random_string test_auth_email_on_password_change auth_email_on_password_change (test acs-authentication) test_auth_email_on_password_change->ad_generate_random_string test_auth_use_email_for_login_p auth_use_email_for_login_p (test acs-authentication) test_auth_use_email_for_login_p->ad_generate_random_string sec_random_token sec_random_token (public) ad_generate_random_string->sec_random_token acs::test::user::create acs::test::user::create (public) acs::test::user::create->ad_generate_random_string auth::local::password::ResetPassword auth::local::password::ResetPassword (private) auth::local::password::ResetPassword->ad_generate_random_string auth::local::registration::Register auth::local::registration::Register (private) auth::local::registration::Register->ad_generate_random_string faq::twt::insert_after_Q_A faq::twt::insert_after_Q_A (private) faq::twt::insert_after_Q_A->ad_generate_random_string forums::test::new forums::test::new (private) forums::test::new->ad_generate_random_string

Testcases:
auth_create_user, auth_driver_get_parameter_values, auth_use_email_for_login_p, auth_email_on_password_change, sync_actions, sync_snapshot, sync_batch_ims_test, acs_content_repository_trivial_smoke_test, content_item, content_item_nested_structure

ad_get_tcl_call_stack (public)

 ad_get_tcl_call_stack [ level ]

Returns a stack trace from where the caller was called. See also ad_print_stack_trace which generates a more readable stack trace at the expense of truncating args.

Parameters:
level (optional, defaults to "-2")
The level to start from, relative to this proc. The value -2 refers to the proc that called this proc's caller. Per default, don't show "ad_log", when this calls ad_get_tcl_call_stack.
Author:
Lars Pind <lars@pinds.com>
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 permission::permission_p permission::permission_p (public) ad_get_tcl_call_stack ad_get_tcl_call_stack permission::permission_p->ad_get_tcl_call_stack

Testcases:
No testcase defined.

ad_job (public)

 ad_job [ -queue queue ] [ -timeout timeout ] [ args... ]

Convenience wrapper for simple usages of ns_job provided by NaviServer. The provided command (args) is executed in a separate thread of the specified job queue. On success the function returns the result of the provided command. If the queue does not exist, the queue is generated on the fly with default settings. When the timeout is specified and it expires, the client side will raise an error. Note that the executing job is not canceled but will run to its end.

Switches:
-queue (optional, defaults to "jobs")
Name of job queue
-timeout (optional)
timeout for job, specified in seconds or as a number with a time unit (e.g., 10ms)
Returns:
result of the specified command
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_job ad_job (test acs-tcl) ad_job ad_job test_ad_job->ad_job download_file_downloader download_file_downloader (public) download_file_downloader->ad_job

Testcases:
ad_job

ad_log (public)

 ad_log level [ args... ]

Output ns_log message with detailed context. This function is intended to be used typically with "error" to ease debugging. Repeated messages are reported only once, with a reference to the first occurrence.

Parameters:
level (required)
Severity level such as "error" or "warning".
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 test_create_folder_with_page create_folder_with_page (test xowf) ad_log ad_log test_create_folder_with_page->ad_log test_create_form_with_form_instance create_form_with_form_instance (test xowiki) test_create_form_with_form_instance->ad_log test_create_workflow_with_instance create_workflow_with_instance (test xowf) test_create_workflow_with_instance->ad_log util::request_info util::request_info (public) ad_log->util::request_info Class ::acs::LockfreeCache Class ::acs::LockfreeCache (public) Class ::acs::LockfreeCache->ad_log Class ::xo::Context Class ::xo::Context (public) Class ::xo::Context->ad_log Class ::xo::db::Class Class ::xo::db::Class (public) Class ::xo::db::Class->ad_log Class ::xo::db::CrClass Class ::xo::db::CrClass (public) Class ::xo::db::CrClass->ad_log Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->ad_log

Testcases:
create_folder_with_page, create_workflow_with_instance, create_form_with_form_instance

ad_mktmpdir (public)

 ad_mktmpdir [ prefix ]

Create a temporary directory. The function respects the server's tmpdir settings.

Parameters:
prefix (optional, defaults to "oacsd")
optional parameter, for easier identification of the directory
Returns:
name of the created directory

Partial Call Graph (max 5 caller/called nodes):
%3 test_apm_bootstrap_upgrade apm_bootstrap_upgrade (test acs-bootstrap-installer) ad_mktmpdir ad_mktmpdir test_apm_bootstrap_upgrade->ad_mktmpdir test_zip_and_unzip zip_and_unzip (test acs-tcl) test_zip_and_unzip->ad_mktmpdir apm_load_apm_file apm_load_apm_file (public) apm_load_apm_file->ad_mktmpdir fs::publish_object_to_file_system fs::publish_object_to_file_system (public) fs::publish_object_to_file_system->ad_mktmpdir fs::publish_url_to_file_system fs::publish_url_to_file_system (public) fs::publish_url_to_file_system->ad_mktmpdir fs::publish_versioned_object_to_file_system fs::publish_versioned_object_to_file_system (public) fs::publish_versioned_object_to_file_system->ad_mktmpdir packages/file-storage/www/download-zip.tcl packages/file-storage/ www/download-zip.tcl packages/file-storage/www/download-zip.tcl->ad_mktmpdir

Testcases:
apm_bootstrap_upgrade, zip_and_unzip

ad_ns_set_to_tcl_vars (public, deprecated)

 ad_ns_set_to_tcl_vars [ -duplicates duplicates ] [ -level level ] \
    set_id
Deprecated. Invoking this procedure generates a warning.

Takes an ns_set and sets variables in the caller's environment correspondingly, i.e. if key is foo and value is bar, the Tcl var foo is set to bar. DEPRECATED: the few remaining usages of this API in upstream code were found to be easily replaceable with much saner and clearer idioms.

Switches:
-duplicates (optional, defaults to "overwrite")
This argument defines what happens when the Tcl variable already exists, or if there are duplicate entries for the same key. overwrites just overwrites the var, which amounts to letting the ns_set win over pre-defined vars, and later entries in the ns_set win over earlier ones. ignore means the variable isn't overwritten. fail will make this proc fail with an error. This makes it easier to track subtle errors that could occur because of unpredicted name clashes.
-level (optional, defaults to "1")
The level to upvar to.
Parameters:
set_id (required)
Author:
Lars Pind <lars@pinds.com>
See Also:
  • upvar
  • for
  • ns_set

Partial Call Graph (max 5 caller/called nodes):
%3 ad_user_class_description ad_user_class_description (public, deprecated) ad_ns_set_to_tcl_vars ad_ns_set_to_tcl_vars ad_user_class_description->ad_ns_set_to_tcl_vars ad_log_deprecated ad_log_deprecated (public) ad_ns_set_to_tcl_vars->ad_log_deprecated

Testcases:
No testcase defined.

ad_opentmpfile (public)

 ad_opentmpfile varFilename [ template ]

Wrapper for Tcl's "file tempfile ...", but respects the server's tmpdir settings, e.g. when admin want to specify the temporary directory. The function is similar to "ns_opentmpfile", but provides a default template and uses always the configured tmp directory.

Parameters:
varFilename (required)
template (optional, defaults to "oacs")

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_opentmpfile ad_opentmpfile test_ad_page_contract_filters->ad_opentmpfile test_apm_bootstrap_upgrade apm_bootstrap_upgrade (test acs-bootstrap-installer) test_apm_bootstrap_upgrade->ad_opentmpfile test_safe_tmpfile_p safe_tmpfile_p (test acs-tcl) test_safe_tmpfile_p->ad_opentmpfile test_util_http_json_encoding util_http_json_encoding (test acs-tcl) test_util_http_json_encoding->ad_opentmpfile test_zip_and_unzip zip_and_unzip (test acs-tcl) test_zip_and_unzip->ad_opentmpfile apm_build_repository apm_build_repository (private) apm_build_repository->ad_opentmpfile apm_git_build_repository apm_git_build_repository (private) apm_git_build_repository->ad_opentmpfile file_storage::test::add_file_to_folder file_storage::test::add_file_to_folder (private) file_storage::test::add_file_to_folder->ad_opentmpfile packages/file-storage/www/file-add.tcl packages/file-storage/ www/file-add.tcl packages/file-storage/www/file-add.tcl->ad_opentmpfile packages/xotcl-core/www/show-class-graph.tcl packages/xotcl-core/ www/show-class-graph.tcl packages/xotcl-core/www/show-class-graph.tcl->ad_opentmpfile

Testcases:
apm_bootstrap_upgrade, ad_page_contract_filters, util_http_json_encoding, safe_tmpfile_p, zip_and_unzip

ad_return_top_of_page (public)

 ad_return_top_of_page first_part_of_page [ content_type ]

Returns HTTP headers plus the top of the user-visible page. To be used with streaming HTML output

Parameters:
first_part_of_page (required)
content_type (optional, defaults to "text/html")

Partial Call Graph (max 5 caller/called nodes):
%3 Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) ad_return_top_of_page ad_return_top_of_page Class ::xowf::test_item::Answer_manager->ad_return_top_of_page packages/acs-admin/www/apm/package-load-2.tcl packages/acs-admin/ www/apm/package-load-2.tcl packages/acs-admin/www/apm/package-load-2.tcl->ad_return_top_of_page packages/acs-admin/www/apm/packages-install-4.tcl packages/acs-admin/ www/apm/packages-install-4.tcl packages/acs-admin/www/apm/packages-install-4.tcl->ad_return_top_of_page packages/acs-admin/www/apm/write-all-specs.tcl packages/acs-admin/ www/apm/write-all-specs.tcl packages/acs-admin/www/apm/write-all-specs.tcl->ad_return_top_of_page packages/download/www/admin/spam-users-2.tcl packages/download/ www/admin/spam-users-2.tcl packages/download/www/admin/spam-users-2.tcl->ad_return_top_of_page util_return_headers util_return_headers (public) ad_return_top_of_page->util_return_headers

Testcases:
No testcase defined.

ad_returnredirect (public)

 ad_returnredirect [ -message message ] [ -html ] \
    [ -allow_complete_url ] target_url

Write the HTTP response required to get the browser to redirect to a different page, to the current connection. This does not cause execution of the current page, including serving an ADP file, to stop. If you want to stop execution of the page, you should call ad_script_abort immediately following this call.

This proc is a replacement for ns_returnredirect, but improved in two important respects:

  • When the supplied target_url isn't complete, (e.g. /foo/bar.tcl or foo.tcl) the prepended location part is constructed by looking at the HTTP 1.1 Host header.
  • If a URL relative to the current directory is supplied (e.g. foo.tcl) it prepends location and directory.

Switches:
-message (optional)
A message to display to the user. See util_user_message.
-html (optional, boolean)
Set this flag if your message contains HTML. If specified, you're responsible for proper quoting of everything in your message. Otherwise, we quote it for you.
-allow_complete_url (optional, boolean)
By default we disallow redirecting to URLs outside the current host. This is based on the currently set host header or the hostname in the config file if there is no host header. Set allow_complete_url if you are redirecting to a known safe external web site. This prevents redirecting to a site by URL query hacking.
Parameters:
target_url (required)
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 Class ::Generic::Form Class ::Generic::Form (public) ad_returnredirect ad_returnredirect Class ::Generic::Form->ad_returnredirect Class ::xowf::test_item::Question_manager Class ::xowf::test_item::Question_manager (public) Class ::xowf::test_item::Question_manager->ad_returnredirect ad_cache_returnredirect ad_cache_returnredirect (public) ad_cache_returnredirect->ad_returnredirect ad_redirect_for_registration ad_redirect_for_registration (public) ad_redirect_for_registration->ad_returnredirect ad_restrict_to_https ad_restrict_to_https (public) ad_restrict_to_https->ad_returnredirect acs::icanuse acs::icanuse (public) ad_returnredirect->acs::icanuse ad_urlencode_folder_path ad_urlencode_folder_path (public) ad_returnredirect->ad_urlencode_folder_path util::external_url_p util::external_url_p (public) ad_returnredirect->util::external_url_p util_absolute_path_p util_absolute_path_p (public) ad_returnredirect->util_absolute_path_p util_complete_url_p util_complete_url_p (public) ad_returnredirect->util_complete_url_p

Testcases:
No testcase defined.

ad_safe_eval (public)

 ad_safe_eval [ args... ]

Version of "eval" that checks its arguments for brackets that may be used to execute unsafe code. There are actually better ways in Tcl to achieve this, but it is kept for backwards compatibility.

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_safe_eval ad_safe_eval (test acs-tcl) ad_safe_eval ad_safe_eval test_ad_safe_eval->ad_safe_eval acs_mail_lite::imap_check_incoming acs_mail_lite::imap_check_incoming (private) acs_mail_lite::imap_check_incoming->ad_safe_eval acs_mail_lite::maildir_check_incoming acs_mail_lite::maildir_check_incoming (private) acs_mail_lite::maildir_check_incoming->ad_safe_eval

Testcases:
ad_safe_eval

ad_sanitize_filename (public)

 ad_sanitize_filename [ -no_resolve ] \
    [ -existing_names existing_names ] [ -collapse_spaces ] \
    [ -replace_with replace_with ] [ -tolower ] str

Sanitize the provided filename for modern Windows, OS X, and Unix filesystems (NTFS, ext, etc.). FAT 8.3 filenames are not supported. The generated strings should be safe against https://github.com/minimaxir/big-list-of-naughty-strings

Switches:
-no_resolve (optional, boolean)
-existing_names (optional)
-collapse_spaces (optional, boolean)
-replace_with (optional, defaults to "-")
-tolower (optional, boolean)
Parameters:
str (required)
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad__sanitize_filename ad__sanitize_filename (test acs-tcl) ad_sanitize_filename ad_sanitize_filename test_ad__sanitize_filename->ad_sanitize_filename test_fs_add_file_to_folder fs_add_file_to_folder (test file-storage) test_fs_add_file_to_folder->ad_sanitize_filename Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->ad_sanitize_filename content::item::upload_file content::item::upload_file (public) content::item::upload_file->ad_sanitize_filename fs::get_file_system_safe_object_name fs::get_file_system_safe_object_name (public) fs::get_file_system_safe_object_name->ad_sanitize_filename fs::publish_folder_to_file_system fs::publish_folder_to_file_system (public) fs::publish_folder_to_file_system->ad_sanitize_filename fs::publish_url_to_file_system fs::publish_url_to_file_system (public) fs::publish_url_to_file_system->ad_sanitize_filename

Testcases:
ad__sanitize_filename, fs_add_file_to_folder

ad_schedule_proc (public)

 ad_schedule_proc [ -thread thread ] [ -once once ] [ -debug debug ] \
    [ -all_servers all_servers ] [ -schedule_proc schedule_proc ] \
    interval proc [ args... ]

Replacement for ns_schedule_proc and friends, allowing us to track what's going on. Can be monitored via /admin/monitoring/schedule-procs.tcl. The procedure defaults to run on only the canonical server unless the all_servers flag is set to true.

Switches:
-thread (optional, defaults to "t")
t/f If true run scheduled proc in its own thread. Note that when scheduled procs executed in the main thread these procs can delay processing of other scheduled procs for a potentially long time, no other jobs will be scheduled. If scheduled procs should be running at certain times, it is highly recommended to run all scheduled procs in separate (job execution) thread and use the main scheduled thread mainly for scheduling.
-once (optional, defaults to "f")
t/f. If true only run the scheduled proc once
-debug (optional, defaults to "f")
t/f If true log debugging information
-all_servers (optional, defaults to "f")
If true run on all servers in a cluster
-schedule_proc (optional)
ns_schedule_daily, ns_schedule_weekly or blank
Parameters:
interval (required)
If schedule_proc is empty, the interval to run the proc in seconds, otherwise a list of interval arguments to pass to ns_schedule_daily or ns_schedule_weekly
proc (required)
The proc to schedule

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_schedule_proc ad_schedule_proc (test acs-tcl) ad_schedule_proc ad_schedule_proc test_ad_schedule_proc->ad_schedule_proc ad_canonical_server_p ad_canonical_server_p (private) ad_schedule_proc->ad_canonical_server_p server_cluster_enabled_p server_cluster_enabled_p (public) ad_schedule_proc->server_cluster_enabled_p packages/acs-admin/tcl/acs-admin-init.tcl packages/acs-admin/ tcl/acs-admin-init.tcl packages/acs-admin/tcl/acs-admin-init.tcl->ad_schedule_proc 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_schedule_proc packages/acs-admin/www/server-restart.tcl packages/acs-admin/ www/server-restart.tcl packages/acs-admin/www/server-restart.tcl->ad_schedule_proc packages/acs-api-browser/tcl/api-doc-init.tcl packages/acs-api-browser/ tcl/api-doc-init.tcl packages/acs-api-browser/tcl/api-doc-init.tcl->ad_schedule_proc packages/acs-authentication/tcl/sync-init.tcl packages/acs-authentication/ tcl/sync-init.tcl packages/acs-authentication/tcl/sync-init.tcl->ad_schedule_proc

Testcases:
ad_schedule_proc

ad_tcl_list_list_to_ns_set (public)

 ad_tcl_list_list_to_ns_set [ -set_id set_id ] [ -put ] kv_pairs

Takes a list of lists of key/value pairs and ns_set updates values in an ns_set.

Switches:
-set_id (optional)
If this switch is specified, it'll use this set instead of creating a new one.
-put (optional, boolean)
If this boolean switch is specified, it'll use ns_set put instead of ns_set update (update is default)
Parameters:
kv_pairs (required)
A list of lists containing key/value pairs to be stuffed into the ns_set
Author:
Yonatan Feldman <yon@arsdigita.com>

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

Testcases:
No testcase defined.

ad_tcl_vars_list_to_ns_set (public, deprecated)

 ad_tcl_vars_list_to_ns_set [ -set_id set_id ] [ -put ] vars_list
Deprecated. Invoking this procedure generates a warning.

Takes a Tcl list of variable names and ns_set updates values in an ns_set correspondingly: key is the name of the var, value is the value of the var. The caller is (obviously) responsible for freeing the set if need be. DEPRECATED 5.10.1: modern ns_set idioms make this proc obsolete

Switches:
-set_id (optional)
If this switch is specified, it'll use this set instead of creating a new one.
-put (optional, boolean)
If this boolean switch is specified, it'll use ns_set put instead of ns_set update (update is default)
Parameters:
vars_list (required)
A Tcl list of variable names that will be transported into the ns_set.
Author:
Lars Pind <lars@pinds.com>
See Also:
  • ns_set

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) ad_tcl_vars_list_to_ns_set ad_tcl_vars_list_to_ns_set ad_tcl_vars_list_to_ns_set->ad_log_deprecated

Testcases:
No testcase defined.

ad_tcl_vars_to_ns_set (public, deprecated)

 ad_tcl_vars_to_ns_set [ -set_id set_id ] [ -put ] [ args... ]
Deprecated. Invoking this procedure generates a warning.

Takes a list of variable names and ns_set updates values in an ns_set correspondingly: key is the name of the var, value is the value of the var. The caller is (obviously) responsible for freeing the set if need be. DEPRECATED 5.10.1: modern ns_set idioms make this proc obsolete

Switches:
-set_id (optional)
If this switch is specified, it'll use this set instead of creating a new one.
-put (optional, boolean)
If this boolean switch is specified, it'll use ns_set put instead of ns_set update (update is default)
Author:
Lars Pind <lars@pinds.com>
See Also:
  • ns_set

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) ad_tcl_vars_to_ns_set ad_tcl_vars_to_ns_set ad_tcl_vars_to_ns_set->ad_log_deprecated

Testcases:
No testcase defined.

ad_tmpdir (public)

 ad_tmpdir

Convenience function to return the tmp directory

Partial Call Graph (max 5 caller/called nodes):
%3 test_csv_foreach csv_foreach (test acs-tcl) ad_tmpdir ad_tmpdir test_csv_foreach->ad_tmpdir test_process_objects_csv process_objects_csv (test acs-tcl) test_process_objects_csv->ad_tmpdir acs::disk_cache_eval acs::disk_cache_eval (public) acs::disk_cache_eval->ad_tmpdir acs::disk_cache_flush acs::disk_cache_flush (public) acs::disk_cache_flush->ad_tmpdir acs_mail_lite::send_immediately acs_mail_lite::send_immediately (private) acs_mail_lite::send_immediately->ad_tmpdir db_load_sql_data db_load_sql_data (public) db_load_sql_data->ad_tmpdir email_image::edit_email_image email_image::edit_email_image (public) email_image::edit_email_image->ad_tmpdir

Testcases:
csv_foreach, process_objects_csv

ad_tmpnam (public)

 ad_tmpnam [ template ]

A stub function to replace the deprecated "ns_tmpnam", which uses the deprecated C-library function "tmpnam()". However, also ns_mktemp is not recommended any more due to a potential race between the name creation and the file open command.

Parameters:
template (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 apm_extract_tarball apm_extract_tarball (public) ad_tmpnam ad_tmpnam apm_extract_tarball->ad_tmpnam apm_generate_tarball apm_generate_tarball (public) apm_generate_tarball->ad_tmpnam apm_load_apm_file apm_load_apm_file (public) apm_load_apm_file->ad_tmpnam cr_item_search::test_setup cr_item_search::test_setup (private) cr_item_search::test_setup->ad_tmpnam fs::publish_folder_to_file_system fs::publish_folder_to_file_system (public) fs::publish_folder_to_file_system->ad_tmpnam

Testcases:
No testcase defined.

ad_urlencode (public)

 ad_urlencode string

same as ns_urlencode except that dash and underscore are left unencoded.

Parameters:
string (required)

Partial Call Graph (max 5 caller/called nodes):
%3 Class ::xowiki::includelet::my-yahoo-publisher Class ::xowiki::includelet::my-yahoo-publisher (public) ad_urlencode ad_urlencode Class ::xowiki::includelet::my-yahoo-publisher->ad_urlencode attachments::detach_url attachments::detach_url (public) attachments::detach_url->ad_urlencode packages/acs-authentication/lib/search.tcl packages/acs-authentication/ lib/search.tcl packages/acs-authentication/lib/search.tcl->ad_urlencode packages/acs-subsite/www/admin/group-types/groups-display.tcl packages/acs-subsite/ www/admin/group-types/groups-display.tcl packages/acs-subsite/www/admin/group-types/groups-display.tcl->ad_urlencode packages/acs-subsite/www/admin/group-types/one.tcl packages/acs-subsite/ www/admin/group-types/one.tcl packages/acs-subsite/www/admin/group-types/one.tcl->ad_urlencode _ _ (public) ad_urlencode->_

Testcases:
No testcase defined.

ad_urlencode_url (public)

 ad_urlencode_url url

Perform an urlencode operation on a potentially full url (containing a location, but without query part).

Parameters:
url (required)
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_export_vars export_vars (test acs-tcl) ad_urlencode_url ad_urlencode_url test_export_vars->ad_urlencode_url ad_try ad_try (public) ad_urlencode_url->ad_try ad_urlencode_folder_path ad_urlencode_folder_path (public) ad_urlencode_url->ad_urlencode_folder_path util::join_location util::join_location (public) ad_urlencode_url->util::join_location export_vars export_vars (public) export_vars->ad_urlencode_url xowiki::FormPage instproc www-edit xowiki::FormPage instproc www-edit (public) xowiki::FormPage instproc www-edit->ad_urlencode_url

Testcases:
export_vars

db_html_select_options (public)

 db_html_select_options [ -bind bind ] [ -select_option select_option ] \
    stmt_name sql

Generate html option tags for an HTML selection widget. If select_option is passed, this option will be marked as selected.

Switches:
-bind (optional)
-select_option (optional)
Parameters:
stmt_name (required)
sql (required)
Author:
yon [yon@arsdigita.com]

Partial Call Graph (max 5 caller/called nodes):
%3 db_list db_list (public) db_html_select_options db_html_select_options db_html_select_options->db_list

Testcases:
No testcase defined.

db_html_select_value_options (public)

 db_html_select_value_options [ -bind bind ] \
    [ -select_option select_option ] [ -value_index value_index ] \
    [ -option_index option_index ] stmt_name sql

Generate html option tags with values for an HTML selection widget. If select_option is passed and there exists a value for it in the values list, this option will be marked as selected. The "select_option" can be a list, in which case all options matching a value in the list will be marked as selected.

Switches:
-bind (optional)
-select_option (optional)
-value_index (optional, defaults to "0")
-option_index (optional, defaults to "1")
Parameters:
stmt_name (required)
sql (required)
Author:
yon [yon@arsdigita.com]

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-admin/www/users/index.tcl packages/acs-admin/ www/users/index.tcl db_html_select_value_options db_html_select_value_options packages/acs-admin/www/users/index.tcl->db_html_select_value_options packages/chat/www/search.tcl packages/chat/ www/search.tcl packages/chat/www/search.tcl->db_html_select_value_options db_list_of_lists db_list_of_lists (public) db_html_select_value_options->db_list_of_lists

Testcases:
No testcase defined.

export_entire_form (public, deprecated)

 export_entire_form
Deprecated. Invoking this procedure generates a warning.

Exports everything in ns_getform to the ns_set. This should generally not be used. It's much better to explicitly name the variables you want to export. export_vars is now the preferred interface.

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) export_entire_form export_entire_form export_entire_form->ad_log_deprecated

Testcases:
No testcase defined.

export_entire_form_as_url_vars (public, deprecated)

 export_entire_form_as_url_vars [ vars_to_passthrough ]
Deprecated. Invoking this procedure generates a warning.

export_vars is now the preferred interface. Returns a URL parameter string of name-value pairs of all the form parameters passed to this page. If vars_to_passthrough is given, it should be a list of parameter names that will be the only ones passed through.

Parameters:
vars_to_passthrough (optional)
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) ad_urlencode_query ad_urlencode_query (public) export_entire_form_as_url_vars export_entire_form_as_url_vars export_entire_form_as_url_vars->ad_log_deprecated export_entire_form_as_url_vars->ad_urlencode_query

Testcases:
No testcase defined.

export_ns_set_vars (public, deprecated)

 export_ns_set_vars [ format ] [ exclusion_list ] [ setid ]
Deprecated. Invoking this procedure generates a warning.

Returns all the params in an ns_set with the exception of those in exclusion_list. If no setid is provide, ns_getform is used. If format = url, a URL parameter string will be returned. If format = form, a block of hidden form fragments will be returned. export_vars is now the preferred interface.

Parameters:
format (optional, defaults to "url")
either url or form
exclusion_list (optional)
list of fields to exclude
setid (optional)
if null then it is ns_getform
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 dir_alpha_nav_bar dir_alpha_nav_bar (public) export_ns_set_vars export_ns_set_vars dir_alpha_nav_bar->export_ns_set_vars packages/directory/www/index.tcl packages/directory/ www/index.tcl packages/directory/www/index.tcl->export_ns_set_vars ad_log_deprecated ad_log_deprecated (public) export_ns_set_vars->ad_log_deprecated ad_urlencode_query ad_urlencode_query (public) export_ns_set_vars->ad_urlencode_query

Testcases:
No testcase defined.

export_vars (public)

 export_vars [ -sign ] [ -form ] [ -url ] [ -quotehtml ] \
    [ -entire_form ] [ -no_empty ] [ -base base ] [ -no_base_encode ] \
    [ -anchor anchor ] [ -exclude exclude ] [ -override override ] \
    [ -set set ] [ -formvars formvars ] [ vars ]

Exports variables either as a URL or in the form of hidden form variables. The result is properly urlencoded, unless flags prohibit this.

Example usages:

    set html [export_vars -form { foo bar baz }]
    set url [export_vars { foo bar baz }]

This will export the three variables foo, bar and baz as hidden HTML form fields. It does exactly the same as [export_vars -form {foo bar baz}].

Example usage:

    export_vars -sign -override {{foo "new value"}} -exclude { bar } { foo bar baz }

This will export a variable named foo with the value "new value" and a variable named baz with the value of baz in the caller's environment. Since we've specified that bar should be excluded, bar won't get exported even though it's specified in the last argument. Additionally, even though foo is specified also in the last argument, the value we use is the one given in the override argument. Finally, both variables are signed, because we specified the -sign switch.

You can specify variables with three different precedences, namely override, exclude or vars. If a variable is present in override, that's what'll get exported, no matter what. If a variable is in exclude and not in override, then it will not get output. However, if it is in vars and not in either of override or exclude, then it'll get output. In other words, we check override, exclude and vars in that order of precedence.

The two variable specs, vars and override both look the same: They take a list of variable specs. Examples of variable specs are:

  • foo
  • foo:multiple,sign
  • {foo "the value"}
  • {foo {[my_function arg]}}
  • {foo:array,sign {[array get my_array]}}
In general, there's one or two elements. If there are two, the second element is the value we should use. If one, we pull the value from the variable of the same name in the caller's environment. Note that when you specify the value directly here, we call the Tcl command subst on it, so backslashes, square brackets and variables will get substituted correctly. Therefore, make sure you use curly braces to surround this instead of the [list] command; otherwise the contents will get substituted twice, and you'll be in trouble.

Right after the name, you may specify a colon and some flags, separated by commas. Valid flags are:

multiple
Treat the value as a list and output each element separately.
array
The value is an array and should be exported in a way compliant with the :array flag of ad_page_contract, which means that each entry will get output as name.key=value.

If you don't specify a value directly, but want it pulled out of the Tcl environment, then you don't need to specify :array. If you do, and the variable is in fact not an array, an error will be thrown.

sign
Sign this variable. This goes hand-in-hand with the :verify flag of ad_page_contract and makes sure that the value isn't tampered with on the client side. The -sign switch to export_vars, is a short-hand for specifying the :sign switch on every variable.

For example, one can use "user_id:sign(max_age=60)" in export_vars to let the exported variable after 60 seconds. Other potential arguments for sign are "user" or "csrf" to bind the signature to a user or to the CSRF token.

The argument exclude simply takes a list of names of variables that you don't want exported, even though they're specified in vars.

Intended use: A page may have a set of variables that it cares about. You can store this in a variable once and pass that to export_vars like this:

set my_vars { user_id sort_by filter_by }
... [export_vars $my_vars] ...

Then, say one of them contains a column to filter on. When you want to clear that column, you can say [export_vars -exclude { filter_by } $my_vars].

Similarly, if you want to change the sort order, you can say [export_vars -override { { sort_by $column } } $my_vars], and sorting will be done according to the new value of column.

If the variable name contains a colon (:), that colon must be escaped with a backslash, so for example "form:id" becomes "form\:id". Sorry.

Switches:
-sign (optional, boolean)
Sign all variables.
-form (optional, boolean)
Export in form format. You can't specify both URL and form format.
-url (optional, boolean)
Export in URL format. This is the default.
-quotehtml (optional, boolean)
HTML quote the entire resulting string. This is an interim solution while we're waiting for the templating system to do the quoting for us.
-entire_form (optional, boolean)
Export the entire form from the GET query string or the POST.
-no_empty (optional, boolean)
If specified, variables with an empty string value will be suppressed from being exported. This avoids cluttering up the URLs with lots of unnecessary variables.
-base (optional)
The base URL to make a link to. The provided value should be a plain value (i.e. urldecoded). In case the provided value is urlencoded, use the flag "-no_base_encode". The value of this parameter will be prepended to the query string along with a question mark (?), if the query is nonempty. The returned string can be used directly in a link (when output is in URL format).
-no_base_encode (optional, boolean)
Decides whether argument passed as base option will be encoded by ad_urlencode_url proc
-anchor (optional)
fragment component that will be preceded by a hash (#) in the result URL
-exclude (optional)
list of variables that will not be exported
-override (optional)
variable specs, overriding the specs in 'vars'
-set (optional)
an ns_set that we want to export together with our variables. It has no effect when also the '-entire_form' flag is specified and will otherwise behave as if the current request form data was the supplied ns_set.
-formvars (optional)
a list of parameters that will be looked up into the current request and exported. Won't have any effect if '-entire_form' or '-set' are specified and will otherwise behave as if the current request form data was a subset of the whole form containing only the selected variables.
Parameters:
vars (optional)
variable specs for export
Author:
Lars Pind <lars@pinds.com>
Created:
December 7, 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_subsite_test_email_confirmation acs_subsite_test_email_confirmation (test acs-subsite) export_vars export_vars test_acs_subsite_test_email_confirmation->export_vars test_create_form_with_form_instance create_form_with_form_instance (test xowiki) test_create_form_with_form_instance->export_vars test_create_workflow_with_instance create_workflow_with_instance (test xowf) test_create_workflow_with_instance->export_vars test_export_vars export_vars (test acs-tcl) test_export_vars->export_vars test_form_validate form_validate (test xowiki) test_form_validate->export_vars ad_urlencode_query ad_urlencode_query (public) export_vars->ad_urlencode_query ad_urlencode_url ad_urlencode_url (public) export_vars->ad_urlencode_url export_vars_sign export_vars_sign (private) export_vars->export_vars_sign util::skip_suspicious_query_vars util::skip_suspicious_query_vars (private) export_vars->util::skip_suspicious_query_vars Class ::Generic::Form Class ::Generic::Form (public) Class ::Generic::Form->export_vars Class ::Generic::List Class ::Generic::List (public) Class ::Generic::List->export_vars Class ::ms::Authorize Class ::ms::Authorize (public) Class ::ms::Authorize->export_vars Class ::xo::Authorize Class ::xo::Authorize (public) Class ::xo::Authorize->export_vars Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->export_vars

Testcases:
acs_subsite_test_email_confirmation, export_vars, postman_echo, util_http_post_vars, create_workflow_with_instance, package_normalize_path, xowiki_test_cases, link_tests, slot_interactions, path_resolve, create_form_with_form_instance, form_validate

oacs_util::csv_foreach (public)

 oacs_util::csv_foreach -file file [ -header_line header_line ] \
    [ -override_headers override_headers ] -array_name array_name \
    code_block

Reads a CSV string and executes code block for each row in the CSV.

Switches:
-file (required)
the CSV file to read.
-header_line (optional, defaults to "1")
the line with the list of var names
-override_headers (optional)
the list of variables in the CSV
-array_name (required)
the name of the array to set with the values from the CSV as each line is read.
Parameters:
code_block (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_csv_foreach csv_foreach (test acs-tcl) oacs_util::csv_foreach oacs_util::csv_foreach test_csv_foreach->oacs_util::csv_foreach

Testcases:
csv_foreach

oacs_util::process_objects_csv (public)

 oacs_util::process_objects_csv -object_type object_type -file file \
    [ -header_line header_line ] \
    [ -override_headers override_headers ] [ -constants constants ]

This processes a comma separated set of objects, taking the CSV and calling package_instantiate_object for each one.

Switches:
-object_type (required)
-file (required)
-header_line (optional, defaults to "1")
-override_headers (optional)
-constants (optional)
Returns:
a list of the created object_ids

Partial Call Graph (max 5 caller/called nodes):
%3 test_process_objects_csv process_objects_csv (test acs-tcl) oacs_util::process_objects_csv oacs_util::process_objects_csv test_process_objects_csv->oacs_util::process_objects_csv db_transaction db_transaction (public) oacs_util::process_objects_csv->db_transaction package_instantiate_object package_instantiate_object (public) oacs_util::process_objects_csv->package_instantiate_object

Testcases:
process_objects_csv

oacs_util::vars_to_ns_set (public, deprecated)

 oacs_util::vars_to_ns_set -ns_set ns_set -var_list var_list
Deprecated. Invoking this procedure generates a warning.

Does an ns_set put on each variable named in var_list DEPRECATED 5.10.1: modern ns_set idioms make this proc obsolete

Switches:
-ns_set (required)
an ns_set id that already exists.
-var_list (required)
list of variable names in the calling scope
See Also:
  • ns_set

Partial Call Graph (max 5 caller/called nodes):
%3 bug_tracker::bug::insert bug_tracker::bug::insert (public) oacs_util::vars_to_ns_set oacs_util::vars_to_ns_set bug_tracker::bug::insert->oacs_util::vars_to_ns_set preference::type::new preference::type::new (public) preference::type::new->oacs_util::vars_to_ns_set ad_log_deprecated ad_log_deprecated (public) oacs_util::vars_to_ns_set->ad_log_deprecated

Testcases:
No testcase defined.

util::age_pretty (public)

 util::age_pretty -timestamp_ansi timestamp_ansi \
    -sysdate_ansi sysdate_ansi [ -hours_limit hours_limit ] \
    [ -days_limit days_limit ] [ -mode_2_fmt mode_2_fmt ] \
    [ -mode_3_fmt mode_3_fmt ] [ -locale locale ]

Formats past time intervals in one of three different modes depending on age. The first mode is "1 hour 3 minutes" and is NOT currently internationalized. The second mode is e.g. "14:10, Thursday" and is internationalized. The third mode is "14:10, 01 Mar 2001" and is internationalized. Both the locale and the exact format string for modes 2 and 3 can be overridden by parameters. (Once mode 1 is i18nd, the following sentence will be true:'In mode 1, only the locale can be overridden.' Until then, move along. These aren't the timestamps you're looking for.)

Switches:
-timestamp_ansi (required)
The older timestamp in full ANSI: YYYY-MM-DD HH24:MI:SS
-sysdate_ansi (required)
The newer timestamp.
-hours_limit (optional, defaults to "12")
The upper limit, in hours, for mode 1.
-days_limit (optional, defaults to "3")
The upper limit, in days, for mode 2.
-mode_2_fmt (optional, defaults to "%X, %A")
A formatting string, as per lc_time_fmt, for mode 2
-mode_3_fmt (optional, defaults to "%X, %d %b %Y")
A formatting string, as per lc_time_fmt, for mode 3
-locale (optional)
If present, overrides the default locale
Returns:
Interval between timestamp and sysdate, as localized text string.

Partial Call Graph (max 5 caller/called nodes):
%3 test_util__age_pretty util__age_pretty (test acs-tcl) util::age_pretty util::age_pretty test_util__age_pretty->util::age_pretty lc_time_fmt lc_time_fmt (public) util::age_pretty->lc_time_fmt Class ::xowiki::includelet::presence Class ::xowiki::includelet::presence (public) Class ::xowiki::includelet::presence->util::age_pretty packages/categories/lib/contributions.tcl packages/categories/ lib/contributions.tcl packages/categories/lib/contributions.tcl->util::age_pretty

Testcases:
util__age_pretty

util::array_list_spec_pretty (public)

 util::array_list_spec_pretty list [ indent ]

Pretty-format an array-list spec with proper indentation.

Parameters:
list (required)
indent (optional, defaults to "0")

Partial Call Graph (max 5 caller/called nodes):
%3 workflow::test::run_bug_tracker_test workflow::test::run_bug_tracker_test (public) util::array_list_spec_pretty util::array_list_spec_pretty workflow::test::run_bug_tracker_test->util::array_list_spec_pretty

Testcases:
No testcase defined.

util::backup_file (public)

 util::backup_file -file_path file_path \
    [ -backup_suffix backup_suffix ]

Backs up (move) the file or directory with given path to a file/directory with a backup suffix. Will avoid overwriting old backup files by adding a number to the filename to make it unique. For example, suppose you are backing up /web/my-server/packages/my-package/file.txt and the file has already been backed up to /web/my-server/packages/my-package/file.txt.bak. Invoking this proc will then generate the backup file /web/my-server/packages/my-package/file.txt.bak.2

Switches:
-file_path (required)
-backup_suffix (optional, defaults to ".bak")
The suffix to add to the backup file.
Author:
Peter Marklund

Partial Call Graph (max 5 caller/called nodes):
%3 apm_package_install apm_package_install (public) util::backup_file util::backup_file apm_package_install->util::backup_file ad_file ad_file (public) util::backup_file->ad_file

Testcases:
No testcase defined.

util::block_request (public)

 util::block_request -condition condition [ -target target ]

Block a request for certain kind of requests. This proc can be used to disallow, e.g., requests from bots in login pages or similar. Example:

    ::util::block_request -condition {[ns_conn pool] eq "bots"} -target bots
The proc either terminates the requests by responding a blocking message to the client, or it continues and returns nothing.

Switches:
-condition (required)
Tcl expression, blocking condition
-target (optional, defaults to "you")
part of the message string presented to the blocked user

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-subsite/lib/user-new.tcl packages/acs-subsite/ lib/user-new.tcl util::block_request util::block_request packages/acs-subsite/lib/user-new.tcl->util::block_request packages/acs-subsite/www/register/index.tcl packages/acs-subsite/ www/register/index.tcl packages/acs-subsite/www/register/index.tcl->util::block_request ad_return_complaint ad_return_complaint (public) util::block_request->ad_return_complaint ad_script_abort ad_script_abort (public) util::block_request->ad_script_abort util::request_info util::request_info (public) util::block_request->util::request_info

Testcases:
No testcase defined.

util::catch_exec (public)

 util::catch_exec command result_var

Catch a call to Tcl exec. Handle shell return codes consistently. Works like catch. The result of the exec is put into the variable named in result_var. Inspired by https://wiki.tcl-lang.org/1039

Parameters:
command (required)
A list of arguments to pass to exec
result_var (required)
Variable name in caller's scope to set the result in
Returns:
0 or 1. 0 if no error, 1 if an error occurred. If an error occurred the error message will be put into result_var in the caller's scope.
Author:
Dave Bauer
Created:
2008-01-28

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

Testcases:
No testcase defined.

util::configured_location (public)

 util::configured_location [ -suppress_port ]

Return the configured location as configured for the current network driver. While [util_current_location] honors the virtual host information of the host header field, util::configured_location returns the main configured location (probably the main subsite). This also differs from [ad_url], which returns always the same value from the kernel parameter, since it returns either the https or http result.

Switches:
-suppress_port (optional, boolean)
Returns:
the configured location in the form "proto://hostname?:port?"
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-subsite/www/admin/index.tcl packages/acs-subsite/ www/admin/index.tcl util::configured_location util::configured_location packages/acs-subsite/www/admin/index.tcl->util::configured_location util::join_location util::join_location (public) util::configured_location->util::join_location util_driver_info util_driver_info (public) util::configured_location->util_driver_info

Testcases:
No testcase defined.

util::external_url_p (public)

 util::external_url_p url

check if this URL is external to the current host or a valid alternative valid alternatives include HTTPS or HTTP protocol change HTTP or HTTPS port number added or removed from current hostname or another hostname that the host responds to (from host_node_map)

Parameters:
url (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) util::external_url_p util::external_url_p test_ad_page_contract_filters->util::external_url_p security::locations security::locations (public) util::external_url_p->security::locations util_complete_url_p util_complete_url_p (public) util::external_url_p->util_complete_url_p ad_dom_sanitize_html ad_dom_sanitize_html (public) ad_dom_sanitize_html->util::external_url_p ad_page_contract_filter_proc_localurl ad_page_contract_filter_proc_localurl (public) ad_page_contract_filter_proc_localurl->util::external_url_p ad_returnredirect ad_returnredirect (public) ad_returnredirect->util::external_url_p packages/bug-tracker/www/bug-add.tcl packages/bug-tracker/ www/bug-add.tcl packages/bug-tracker/www/bug-add.tcl->util::external_url_p packages/bug-tracker/www/bulk-update-op.tcl packages/bug-tracker/ www/bulk-update-op.tcl packages/bug-tracker/www/bulk-update-op.tcl->util::external_url_p

Testcases:
ad_page_contract_filters

util::file_content_check (public)

 util::file_content_check -type type -filename filename

Check whether the provided file is of the requested type. This function is more robust and portable than relying on external programs and their output, but it does not work on all possible file types. It checks a few common cases that could lead to problems otherwise, like when uploading archives.

Switches:
-type (required)
-filename (required)
Returns:
Boolean value (0 or 1)

Partial Call Graph (max 5 caller/called nodes):
%3 test_apm_tarballs apm_tarballs (test acs-tcl) util::file_content_check util::file_content_check test_apm_tarballs->util::file_content_check test_util__file_content_check util__file_content_check (test acs-tcl) test_util__file_content_check->util::file_content_check test_zip_and_unzip zip_and_unzip (test acs-tcl) test_zip_and_unzip->util::file_content_check util::zip util::zip (public) util::file_content_check->util::zip packages/file-storage/www/file-add.tcl packages/file-storage/ www/file-add.tcl packages/file-storage/www/file-add.tcl->util::file_content_check packages/file-storage/www/folder-zip-add.tcl packages/file-storage/ www/folder-zip-add.tcl packages/file-storage/www/folder-zip-add.tcl->util::file_content_check packages/xowiki/www/admin/import.tcl packages/xowiki/ www/admin/import.tcl packages/xowiki/www/admin/import.tcl->util::file_content_check search::convert::binary_to_text search::convert::binary_to_text (public) search::convert::binary_to_text->util::file_content_check

Testcases:
apm_tarballs, zip_and_unzip, util__file_content_check

util::find_all_files (public)

 util::find_all_files [ -include_dirs include_dirs ] \
    [ -max_depth max_depth ] [ -check_file_func check_file_func ] \
    [ -extension extension ] -path path

Returns a list of lists with full paths and filename to all files under $path in the directory tree (descending the tree to a depth of up to $max_depth). Clients should not depend on the order of files returned. DOES NOT WORK ON WINDOWS (you have to change the splitter and I don't know how to detect a windows system)

Switches:
-include_dirs (optional, defaults to "0")
Should directories be included in the list of files.
-max_depth (optional, defaults to "1")
How many levels of directories should be searched. Defaults to 1 which is the current directory
-check_file_func (optional)
Function which can be executed upon the file to determine if it is worth the effort
-extension (optional)
Only return files with this extension (single value !)
-path (required)
The path in which to search for the files. Note that this is an absolute Path
Returns:
list of lists (filename and full_path) of all files found.

Partial Call Graph (max 5 caller/called nodes):
%3 ad_file ad_file (public) util::find_all_files util::find_all_files util::find_all_files->ad_file

Testcases:
No testcase defined.

util::get_referrer (public)

 util::get_referrer [ -relative ] [ -trusted ]
Switches:
-relative (optional, boolean)
return the refer without protocol and host
-trusted (optional, boolean)
Returns:
referrer from the request headers.

Partial Call Graph (max 5 caller/called nodes):
%3 ad_page_contract ad_page_contract (public) util::get_referrer util::get_referrer ad_page_contract->util::get_referrer ad_page_contract_handle_datasource_error ad_page_contract_handle_datasource_error (public) ad_page_contract_handle_datasource_error->util::get_referrer packages/acs-lang/www/change-locale-include.tcl packages/acs-lang/ www/change-locale-include.tcl packages/acs-lang/www/change-locale-include.tcl->util::get_referrer packages/acs-subsite/www/shared/session-update.tcl packages/acs-subsite/ www/shared/session-update.tcl packages/acs-subsite/www/shared/session-update.tcl->util::get_referrer packages/categories/lib/map.tcl packages/categories/ lib/map.tcl packages/categories/lib/map.tcl->util::get_referrer util::external_url_p util::external_url_p (public) util::get_referrer->util::external_url_p

Testcases:
No testcase defined.

util::inline_svg_from_dot (public)

 util::inline_svg_from_dot [ -css css ] dot_code

Transform a dot source code into an inline svg image based on code from xotcl-core; should be probably made more configurable in the future.

Switches:
-css (optional)
Parameters:
dot_code (required)
grapviz dot code
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 Class ::xowiki::includelet::references-graph Class ::xowiki::includelet::references-graph (public) util::inline_svg_from_dot util::inline_svg_from_dot Class ::xowiki::includelet::references-graph->util::inline_svg_from_dot api_proc_documentation api_proc_documentation (public) api_proc_documentation->util::inline_svg_from_dot packages/xotcl-core/www/show-object.tcl packages/xotcl-core/ www/show-object.tcl packages/xotcl-core/www/show-object.tcl->util::inline_svg_from_dot ad_file ad_file (public) util::inline_svg_from_dot->ad_file ad_tmpdir ad_tmpdir (public) util::inline_svg_from_dot->ad_tmpdir util::which util::which (public) util::inline_svg_from_dot->util::which

Testcases:
No testcase defined.

util::interval_pretty (public)

 util::interval_pretty [ -seconds seconds ]

Takes a number of seconds and returns a pretty interval of the form "3h 49m 13s"

Switches:
-seconds (optional, defaults to "0")

Partial Call Graph (max 5 caller/called nodes):
%3 test_util__interval_pretty util__interval_pretty (test acs-tcl) util::interval_pretty util::interval_pretty test_util__interval_pretty->util::interval_pretty aa_test::parse_install_file aa_test::parse_install_file (public) aa_test::parse_install_file->util::interval_pretty packages/acs-admin/www/auth/authority.tcl packages/acs-admin/ www/auth/authority.tcl packages/acs-admin/www/auth/authority.tcl->util::interval_pretty

Testcases:
util__interval_pretty

util::join_location (public)

 util::join_location [ -noabbrev ] [ -proto proto ] \
    [ -hostname hostname ] [ -port port ]

Join hostname and port and use IP-literal notation when necessary. The function is the inverse function of util::split_location.

Switches:
-noabbrev (optional, boolean)
when specified, the location is joined as requested. Otherwise, default ports are omitted from the result.
-proto (optional)
-hostname (optional)
-port (optional)
Returns:
location consisting of hostname and optionally port
Author:
Gustaf Neumann
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_util__split_and_join_location util__split_and_join_location (test acs-tcl) util::join_location util::join_location test_util__split_and_join_location->util::join_location Class ::acs::Cluster Class ::acs::Cluster (public) Class ::acs::Cluster->util::join_location acs::Cluster instproc current_server_locations acs::Cluster instproc current_server_locations (protected) acs::Cluster instproc current_server_locations->util::join_location acs::Cluster instproc external_location acs::Cluster instproc external_location (protected) acs::Cluster instproc external_location->util::join_location acs::Cluster instproc map_inaddr_any acs::Cluster instproc map_inaddr_any (protected) acs::Cluster instproc map_inaddr_any->util::join_location acs::Cluster instproc qualified_location acs::Cluster instproc qualified_location (public) acs::Cluster instproc qualified_location->util::join_location

Testcases:
util__split_and_join_location

util::max (public)

 util::max [ args... ]

Returns the maximum of a list of numbers. Example: max 2 3 1.5 returns 3. Since Tcl8.5, numerical min and max are among the math functions supported by expr. The reason why this proc is still around is that it supports also non-numerical values in the list, in a way that is not so easily replaceable by a lsort idiom (but could).

Author:
Lars Pind <lars@pinds.com>
Created:
31 August 2000
See Also:
  • expr
  • lsort

Partial Call Graph (max 5 caller/called nodes):
%3 test_min_max min_max (test acs-tcl) util::max util::max test_min_max->util::max

Testcases:
min_max

util::min (public)

 util::min [ args... ]

Returns the minimum of a list of numbers. Example: min 2 3 1.5 returns 1.5. Since Tcl8.5, numerical min and max are among the math functions supported by expr. The reason why this proc is still around is that it supports also non-numerical values in the list, in a way that is not so easily replaceable by a lsort idiom (but could).

Author:
Ken Mayer <kmayer@bitwrangler.com>
Created:
26 September 2002
See Also:
  • expr
  • lsort

Partial Call Graph (max 5 caller/called nodes):
%3 test_min_max min_max (test acs-tcl) util::min util::min test_min_max->util::min

Testcases:
min_max

util::name_to_path (public)

 util::name_to_path -name name

Transforms a pretty name to a reasonable pathname.

Switches:
-name (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_name_to_path name_to_path (test acs-tcl) util::name_to_path util::name_to_path test_name_to_path->util::name_to_path

Testcases:
name_to_path

util::ns_set_to_tcl_string (public)

 util::ns_set_to_tcl_string set_id

Return a plain text version of the passed-in ns_set, useful for debugging and introspection.

Parameters:
set_id (required)
Returns:
text string conisting of multiple lines of the form "key: value"

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

Testcases:
No testcase defined.

util::pdfinfo (public)

 util::pdfinfo file

Calls the pdfinfo command line utility on a given pdf file. The command pdfinfo must be installed on the server for this to work. On linux this is usually part of the poppler-utils (https://poppler.freedesktop.org/).

Parameters:
file (required)
absolute path to the pdf file
Returns:
a dict containing all the pdfinfo returned fields as keys and their respective values

Partial Call Graph (max 5 caller/called nodes):
%3 util::which util::which (public) util::pdfinfo util::pdfinfo util::pdfinfo->util::which

Testcases:
No testcase defined.

util::potentially_unsafe_eval_p (public)

 util::potentially_unsafe_eval_p [ -warn ] string

Check content of the string to identify potentially unsafe content in the provided string. The content is unsafe, when it contains externally provided content, which might be provided e.g. via query variables, or via user values stored in the database. When such content contains square braces, a "subst" command on it can evaluate arbitrary commands, which is dangerous.

Switches:
-warn (optional, boolean)
Parameters:
string (required)

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log ad_log (public) util::potentially_unsafe_eval_p util::potentially_unsafe_eval_p util::potentially_unsafe_eval_p->ad_log

Testcases:
No testcase defined.

util::random (public)

 util::random

Return a pseudo-random number between 0 and 1. The reason to have this proc is that seeding can be controlled by the user and the generation is independent of Tcl.

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_mail_lite_inbound_procs_check acs_mail_lite_inbound_procs_check (test acs-mail-lite) util::random util::random test_acs_mail_lite_inbound_procs_check->util::random test_parameter__check_procs parameter__check_procs (test acs-tcl) test_parameter__check_procs->util::random util::random_range util::random_range (public) util::random_range->util::random

Testcases:
acs_mail_lite_inbound_procs_check, parameter__check_procs

util::random_init (public)

 util::random_init seed

Seed the random number generator.

Parameters:
seed (required)

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-tcl/tcl/utilities-init.tcl packages/acs-tcl/ tcl/utilities-init.tcl util::random_init util::random_init packages/acs-tcl/tcl/utilities-init.tcl->util::random_init

Testcases:
No testcase defined.

util::random_list_element (public)

 util::random_list_element list

Returns a random element from the list.

Parameters:
list (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_mail_lite_inbound_procs_check acs_mail_lite_inbound_procs_check (test acs-mail-lite) util::random_list_element util::random_list_element test_acs_mail_lite_inbound_procs_check->util::random_list_element

Testcases:
acs_mail_lite_inbound_procs_check

util::random_range (public)

 util::random_range range

Returns a pseudo-random number between 0 and range.

Parameters:
range (required)
Returns:
integer

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_mail_lite_inbound_procs_check acs_mail_lite_inbound_procs_check (test acs-mail-lite) util::random_range util::random_range test_acs_mail_lite_inbound_procs_check->util::random_range test_set_get_timezone set_get_timezone (test acs-lang) test_set_get_timezone->util::random_range test_util__randomize_list util__randomize_list (test acs-tcl) test_util__randomize_list->util::random_range util::random util::random (public) util::random_range->util::random acs_mail_lite::unique_id_create acs_mail_lite::unique_id_create (private) acs_mail_lite::unique_id_create->util::random_range util::randomize_list util::randomize_list (public) util::randomize_list->util::random_range

Testcases:
set_get_timezone, acs_mail_lite_inbound_procs_check, util__randomize_list

util::randomize_list (public)

 util::randomize_list list

Returns a random permutation of the list.

Parameters:
list (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_mail_lite_inbound_procs_check acs_mail_lite_inbound_procs_check (test acs-mail-lite) util::randomize_list util::randomize_list test_acs_mail_lite_inbound_procs_check->util::randomize_list test_util__randomize_list util__randomize_list (test acs-tcl) test_util__randomize_list->util::randomize_list util::random_range util::random_range (public) util::randomize_list->util::random_range

Testcases:
acs_mail_lite_inbound_procs_check, util__randomize_list

util::request_info (public)

 util::request_info [ -with_headers ]

Produce a string containing the detailed request information. This is in particular useful for debugging, when errors are raised.

Switches:
-with_headers (optional, boolean, defaults to "false")
Include request headers
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 Object ::boomerang::handler Object ::boomerang::handler (public) util::request_info util::request_info Object ::boomerang::handler->util::request_info ad_log ad_log (public) ad_log->util::request_info boomerang::handler proc record boomerang::handler proc record (public) boomerang::handler proc record->util::request_info util::block_request util::block_request (public) util::block_request->util::request_info util::suspicious_query_variable util::suspicious_query_variable (public) util::suspicious_query_variable->util::request_info ad_conn ad_conn (public) util::request_info->ad_conn util::get_referrer util::get_referrer (public) util::request_info->util::get_referrer util::ns_set_pretty_print util::ns_set_pretty_print (private) util::request_info->util::ns_set_pretty_print util_current_location util_current_location (public) util::request_info->util_current_location

Testcases:
No testcase defined.

util::resources::can_install_locally (public)

 util::resources::can_install_locally -resource_info resource_info \
    [ -version_segment version_segment ]

Check, whether the operating system's permissions allow us to install in the configured directories.

Switches:
-resource_info (required)
a dict containing at least resourceDir
-version_segment (optional)
an optional directory, under the resource directory
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-tcl/lib/check-installed.tcl packages/acs-tcl/ lib/check-installed.tcl util::resources::can_install_locally util::resources::can_install_locally packages/acs-tcl/lib/check-installed.tcl->util::resources::can_install_locally util::resources::download util::resources::download (public) util::resources::download->util::resources::can_install_locally ad_file ad_file (public) util::resources::can_install_locally->ad_file

Testcases:
No testcase defined.

util::resources::cdnjs_get_newest_version (public)

 util::resources::cdnjs_get_newest_version -resource_info resource_info

Return the newest version for the library denoted by 'resource_info' from cdnjs.

Switches:
-resource_info (required)

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-admin/www/posture-overview.tcl packages/acs-admin/ www/posture-overview.tcl util::resources::cdnjs_get_newest_version util::resources::cdnjs_get_newest_version packages/acs-admin/www/posture-overview.tcl->util::resources::cdnjs_get_newest_version packages/acs-tcl/lib/check-installed.tcl packages/acs-tcl/ lib/check-installed.tcl packages/acs-tcl/lib/check-installed.tcl->util::resources::cdnjs_get_newest_version util::json2dict util::json2dict (public) util::resources::cdnjs_get_newest_version->util::json2dict util::resources::cdnjs_version_API util::resources::cdnjs_version_API (public) util::resources::cdnjs_get_newest_version->util::resources::cdnjs_version_API util::resources::http_get_with_default util::resources::http_get_with_default (private) util::resources::cdnjs_get_newest_version->util::resources::http_get_with_default

Testcases:
No testcase defined.

util::resources::cdnjs_version_API (public)

 util::resources::cdnjs_version_API -library library [ -count count ]

Return a link to the version API of cdnjs. The "-library" is the name under which the package is available from cdnjs.

Switches:
-library (required)
-count (optional, integer, defaults to "1")

Partial Call Graph (max 5 caller/called nodes):
%3 util::resources::cdnjs_get_newest_version util::resources::cdnjs_get_newest_version (public) util::resources::cdnjs_version_API util::resources::cdnjs_version_API util::resources::cdnjs_get_newest_version->util::resources::cdnjs_version_API

Testcases:
No testcase defined.

util::resources::check_vulnerability (public)

 util::resources::check_vulnerability -service service -library library \
    -version version

Return a dict containing vulnerability info with the keys "hasVulnerability", "libraryURL" and "versionURL"

Switches:
-service (required)
name of the vulnerability checking service (currently only synk)
-library (required)
name of the library as named by the vulnerability service
-version (required)
version of the library to be checked

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-admin/www/posture-overview.tcl packages/acs-admin/ www/posture-overview.tcl util::resources::check_vulnerability util::resources::check_vulnerability packages/acs-admin/www/posture-overview.tcl->util::resources::check_vulnerability packages/acs-tcl/lib/check-installed.tcl packages/acs-tcl/ lib/check-installed.tcl packages/acs-tcl/lib/check-installed.tcl->util::resources::check_vulnerability util::resources::http_get_with_default util::resources::http_get_with_default (private) util::resources::check_vulnerability->util::resources::http_get_with_default

Testcases:
No testcase defined.

util::resources::download (public)

 util::resources::download -resource_info resource_info \
    [ -version_segment version_segment ]

Download resources typically from a CDN and install it for local usage. The installed files are as well gzipped for faster delivery, when gzip is available.-

Switches:
-resource_info (required)
a dict containing resourceDir, cdn, cssFiles, jsFiles, and extraFiles
-version_segment (optional)
an optional directory, under the resource directory
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 bootstrap_icons::download bootstrap_icons::download (private) util::resources::download util::resources::download bootstrap_icons::download->util::resources::download fa_icons::download fa_icons::download (private) fa_icons::download->util::resources::download highcharts::download highcharts::download (private) highcharts::download->util::resources::download packages/cookie-consent/www/sitewide-admin/download.tcl packages/cookie-consent/ www/sitewide-admin/download.tcl packages/cookie-consent/www/sitewide-admin/download.tcl->util::resources::download packages/openacs-bootstrap3-theme/www/sitewide-admin/download.tcl packages/openacs-bootstrap3-theme/ www/sitewide-admin/download.tcl packages/openacs-bootstrap3-theme/www/sitewide-admin/download.tcl->util::resources::download ad_file ad_file (public) util::resources::download->ad_file util::resources::can_install_locally util::resources::can_install_locally (public) util::resources::download->util::resources::can_install_locally util::resources::download_helper util::resources::download_helper (public) util::resources::download->util::resources::download_helper util::which util::which (public) util::resources::download->util::which

Testcases:
No testcase defined.

util::resources::download_helper (public)

 util::resources::download_helper [ -url url ]

Helper for ::util::resources::download, since some download sites tend to redirect.

Switches:
-url (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 richtext::ckeditor4::download richtext::ckeditor4::download (private) util::resources::download_helper util::resources::download_helper richtext::ckeditor4::download->util::resources::download_helper util::resources::download util::resources::download (public) util::resources::download->util::resources::download_helper

Testcases:
No testcase defined.

util::resources::is_installed_locally (public)

 util::resources::is_installed_locally -resource_info resource_info \
    [ -version_segment version_segment ]

Check, if the required resource files are installed locally. When there should not be a version_segment segment used, provide an empty one via resource_info.

Switches:
-resource_info (required)
a dict containing resourceDir, cssFiles, jsFiles, and extraFiles
-version_segment (optional)
an optional directory, under the resource directory
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-admin/www/posture-overview.tcl packages/acs-admin/ www/posture-overview.tcl util::resources::is_installed_locally util::resources::is_installed_locally packages/acs-admin/www/posture-overview.tcl->util::resources::is_installed_locally packages/acs-tcl/lib/check-installed.tcl packages/acs-tcl/ lib/check-installed.tcl packages/acs-tcl/lib/check-installed.tcl->util::resources::is_installed_locally ad_file ad_file (public) util::resources::is_installed_locally->ad_file util::resources::version_segment util::resources::version_segment (public) util::resources::is_installed_locally->util::resources::version_segment

Testcases:
No testcase defined.

util::resources::register_urns (public)

 util::resources::register_urns -prefix prefix

Convenience function to register URNs based on the information provided by the resource_info dict. The dict members "urnMap", "prefix", and optionally "csp_lists" are used.

Switches:
-prefix (required)
needed for locating the resource_info_procs

Partial Call Graph (max 5 caller/called nodes):
%3 packages/bootstrap-icons/tcl/resource-init.tcl packages/bootstrap-icons/ tcl/resource-init.tcl util::resources::register_urns util::resources::register_urns packages/bootstrap-icons/tcl/resource-init.tcl->util::resources::register_urns packages/fa-icons/tcl/resource-init.tcl packages/fa-icons/ tcl/resource-init.tcl packages/fa-icons/tcl/resource-init.tcl->util::resources::register_urns packages/highcharts/tcl/resource-init.tcl packages/highcharts/ tcl/resource-init.tcl packages/highcharts/tcl/resource-init.tcl->util::resources::register_urns packages/openacs-bootstrap3-theme/tcl/resource-init.tcl packages/openacs-bootstrap3-theme/ tcl/resource-init.tcl packages/openacs-bootstrap3-theme/tcl/resource-init.tcl->util::resources::register_urns packages/openacs-bootstrap5-theme/tcl/resource-init.tcl packages/openacs-bootstrap5-theme/ tcl/resource-init.tcl packages/openacs-bootstrap5-theme/tcl/resource-init.tcl->util::resources::register_urns template::register_urn template::register_urn (public) util::resources::register_urns->template::register_urn util::resources::resource_info_procs util::resources::resource_info_procs (public) util::resources::register_urns->util::resources::resource_info_procs

Testcases:
No testcase defined.

util::resources::resource_info_procs (public)

 util::resources::resource_info_procs [ -prefix prefix ]

Returns a list of "resource_info" procs, potentially prefixed by some namespace.

Switches:
-prefix (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 test_resource_info_dicts resource_info_dicts (test acs-tcl) util::resources::resource_info_procs util::resources::resource_info_procs test_resource_info_dicts->util::resources::resource_info_procs api_get_body api_get_body (public) util::resources::resource_info_procs->api_get_body packages/acs-admin/www/posture-overview.tcl packages/acs-admin/ www/posture-overview.tcl packages/acs-admin/www/posture-overview.tcl->util::resources::resource_info_procs util::resources::register_urns util::resources::register_urns (public) util::resources::register_urns->util::resources::resource_info_procs

Testcases:
resource_info_dicts

util::resources::version_segment (public)

 util::resources::version_segment -resource_info resource_info

Return the partial directory, where a certain version is/will be installed.

Switches:
-resource_info (required)

Partial Call Graph (max 5 caller/called nodes):
%3 highcharts::download highcharts::download (private) util::resources::version_segment util::resources::version_segment highcharts::download->util::resources::version_segment packages/acs-tcl/lib/check-installed.tcl packages/acs-tcl/ lib/check-installed.tcl packages/acs-tcl/lib/check-installed.tcl->util::resources::version_segment util::resources::is_installed_locally util::resources::is_installed_locally (public) util::resources::is_installed_locally->util::resources::version_segment

Testcases:
No testcase defined.

util::roll_server_log (public)

 util::roll_server_log

Invoke the AOLserver ns_logroll command with some bookend log records. This rolls the error log, not the access log.

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

Testcases:
No testcase defined.

util::split_host (public)

 util::split_host hostspec hostnameVar portVar

Split host potentially into a hostname and a port

Parameters:
hostspec (required)
hostnameVar (required)
portVar (required)

Partial Call Graph (max 5 caller/called nodes):
%3 util_current_location util_current_location (public) util::split_host util::split_host util_current_location->util::split_host

Testcases:
No testcase defined.

util::split_location (public)

 util::split_location location protoVar hostnameVar portVar

Split the provided location into "proto", "hostname" and "port". The results are returned on success to the provided output variables. The function supports IP-literal notation according to RFC 3986 section 3.2.2.

Parameters:
location (required)
protoVar (required)
hostnameVar (required)
portVar (required)
Returns:
boolean value indicating success
Author:
Gustaf Neumann
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_util__split_and_join_location util__split_and_join_location (test acs-tcl) util::split_location util::split_location test_util__split_and_join_location->util::split_location util::ns_set_pretty_print util::ns_set_pretty_print (private) util::split_location->util::ns_set_pretty_print security::get_insecure_location security::get_insecure_location (private) security::get_insecure_location->util::split_location security::get_register_subsite security::get_register_subsite (public) security::get_register_subsite->util::split_location security::get_secure_location security::get_secure_location (public) security::get_secure_location->util::split_location security::validated_host_header security::validated_host_header (public) security::validated_host_header->util::split_location util_current_location util_current_location (public) util_current_location->util::split_location

Testcases:
util__split_and_join_location

util::string_check_urlsafe (public, deprecated)

 util::string_check_urlsafe s1
Deprecated. Invoking this procedure generates a warning.

This proc accepts a string and verifies if it is url safe. - make sure there is no space - make sure there is no special characters except '-' or '_' Returns 1 if yes and 0 if not. Meant to be used in the validation section of ad_form. DEPRECATED: this proc is not in use in upstream code as of 2022-09-5. It also looks as if this will return true when a string is NOT safe.

Parameters:
s1 (required)

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) util::string_check_urlsafe util::string_check_urlsafe util::string_check_urlsafe->ad_log_deprecated

Testcases:
No testcase defined.

util::string_length_compare (public)

 util::string_length_compare s1 s2

String length comparison function for use with lsort's -command switch.

Parameters:
s1 (required)
s2 (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_string_length_compare string_length_compare (test acs-tcl) util::string_length_compare util::string_length_compare test_string_length_compare->util::string_length_compare

Testcases:
string_length_compare

util::subst_safe (public)

 util::subst_safe string

Make string safe for subst'ing.

Parameters:
string (required)

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

Testcases:
No testcase defined.

util::suspicious_query_variable (public)

 util::suspicious_query_variable [ -proc proc ] key [ value ]

Guess if a query variable was encoded twice

Switches:
-proc (optional)
Parameters:
key (required)
value (optional)
Returns:
boolean result

Partial Call Graph (max 5 caller/called nodes):
%3 ad_dimensional ad_dimensional (public) util::suspicious_query_variable util::suspicious_query_variable ad_dimensional->util::suspicious_query_variable packages/xotcl-core/www/show-object.tcl packages/xotcl-core/ www/show-object.tcl packages/xotcl-core/www/show-object.tcl->util::suspicious_query_variable util::skip_suspicious_query_vars util::skip_suspicious_query_vars (private) util::skip_suspicious_query_vars->util::suspicious_query_variable xo::update_query xo::update_query (private) xo::update_query->util::suspicious_query_variable xo::update_query_variable xo::update_query_variable (private) xo::update_query_variable->util::suspicious_query_variable util::request_info util::request_info (public) util::suspicious_query_variable->util::request_info

Testcases:
No testcase defined.

util::trim_leading_zeros (public)

 util::trim_leading_zeros string

Returns a string with leading zeros trimmed. Used to get around Tcl interpreter problems without thinking leading zeros are octal.

If string is real and mod(number)<1, then we have pulled off the leading zero; i.e. 0.231 -> .231 - this is still fine for Tcl though...

Parameters:
string (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_util__trim_leading_zeros util__trim_leading_zeros (test acs-tcl) util::trim_leading_zeros util::trim_leading_zeros test_util__trim_leading_zeros->util::trim_leading_zeros ad_page_contract_filter_proc_float ad_page_contract_filter_proc_float (public) ad_page_contract_filter_proc_float->util::trim_leading_zeros ad_page_contract_filter_proc_integer ad_page_contract_filter_proc_integer (public) ad_page_contract_filter_proc_integer->util::trim_leading_zeros ad_page_contract_filter_proc_negative_float ad_page_contract_filter_proc_negative_float (public) ad_page_contract_filter_proc_negative_float->util::trim_leading_zeros ad_page_contract_filter_proc_object_id ad_page_contract_filter_proc_object_id (public) ad_page_contract_filter_proc_object_id->util::trim_leading_zeros ad_page_contract_filter_proc_range ad_page_contract_filter_proc_range (public) ad_page_contract_filter_proc_range->util::trim_leading_zeros

Testcases:
util__trim_leading_zeros

util::unzip (public)

 util::unzip -source source -destination destination [ -overwrite ]
Switches:
-source (required)
must be the name of a valid zip file to be decompressed
-destination (required)
must be the name of a valid directory to contain decompressed files
-overwrite (optional, boolean)

Partial Call Graph (max 5 caller/called nodes):
%3 test_zip_and_unzip zip_and_unzip (test acs-tcl) util::unzip util::unzip test_zip_and_unzip->util::unzip util::which util::which (public) util::unzip->util::which util::zip_file_contains_valid_filenames util::zip_file_contains_valid_filenames (private) util::unzip->util::zip_file_contains_valid_filenames bootstrap_icons::download bootstrap_icons::download (private) bootstrap_icons::download->util::unzip fa_icons::download fa_icons::download (private) fa_icons::download->util::unzip highcharts::download highcharts::download (private) highcharts::download->util::unzip packages/file-storage/www/folder-zip-add.tcl packages/file-storage/ www/folder-zip-add.tcl packages/file-storage/www/folder-zip-add.tcl->util::unzip richtext::ckeditor4::download richtext::ckeditor4::download (private) richtext::ckeditor4::download->util::unzip

Testcases:
zip_and_unzip

util::var_subst_quotehtml (public)

 util::var_subst_quotehtml [ -ulevel ulevel ] string

Substitute in the provided string all variables with their values (like "subst -nobackslashes -nocommands ..."), and perform HTML quoting on the variable values before substitution. This command supports Tcl array syntax, and Tcl scalar variables with and without curly braces.

Switches:
-ulevel (optional, defaults to "1")
Where we should uplevel to when doing the subst's. Defaults to '1', meaning the caller's scope.
Parameters:
string (required)
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 ad_form ad_form (public) util::var_subst_quotehtml util::var_subst_quotehtml ad_form->util::var_subst_quotehtml template::element::validate template::element::validate (private) template::element::validate->util::var_subst_quotehtml

Testcases:
No testcase defined.

util::which (public)

 util::which prog

Use environment variable PATH to search for the specified executable program. Replacement for UNIX command "which", avoiding exec. exec which: 3368.445 microseconds per iteration ::util::which: 282.372 microseconds per iteration In addition of being more than 10 time faster than the version via exec, this version is less platform dependent.

Parameters:
prog (required)
name of the program to be located on the search path
Returns:
fully qualified name including path, when specified program is found, or otherwise empty string
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_lang_exec_dependencies acs_lang_exec_dependencies (test acs-lang) util::which util::which test_acs_lang_exec_dependencies->util::which test_acs_subsite_exec_dependencies acs_subsite_exec_dependencies (test acs-subsite) test_acs_subsite_exec_dependencies->util::which test_acs_tcl_exec_optional_dependencies acs_tcl_exec_optional_dependencies (test acs-tcl) test_acs_tcl_exec_optional_dependencies->util::which test_acs_tcl_exec_required_dependencies acs_tcl_exec_required_dependencies (test acs-tcl) test_acs_tcl_exec_required_dependencies->util::which test_file_storage_exec_dependencies file_storage_exec_dependencies (test file-storage) test_file_storage_exec_dependencies->util::which ad_file ad_file (public) util::which->ad_file Object ::throttle Object ::throttle (public) Object ::throttle->util::which aa_test::write_test_file aa_test::write_test_file (private) aa_test::write_test_file->util::which acs_admin::check_expired_certificates acs_admin::check_expired_certificates (private) acs_admin::check_expired_certificates->util::which apm_gzip_cmd apm_gzip_cmd (public) apm_gzip_cmd->util::which apm_tar_cmd apm_tar_cmd (public) apm_tar_cmd->util::which

Testcases:
acs_lang_exec_dependencies, acs_subsite_exec_dependencies, acs_tcl_exec_required_dependencies, acs_tcl_exec_optional_dependencies, file_storage_exec_dependencies

util::word_diff (public)

 util::word_diff -old old -new new [ -split_by split_by ] \
    [ -filter_proc filter_proc ] [ -start_old start_old ] \
    [ -end_old end_old ] [ -start_new start_new ] [ -end_new end_new ]

Does a word (or character) diff on two lines of text and indicates text that has been deleted/changed or added by enclosing it in start/end_old/new.

Switches:
-old (required)
The original text.
-new (required)
The modified text.
-split_by (optional)
If split_by is a space, the diff will be made on a word-by-word basis. If it is the empty string, it will be made on a char-by-char basis.
-filter_proc (optional, defaults to "ns_quotehtml")
A filter to run the old/new text through before doing the diff and inserting the HTML fragments below. Keep in mind that if the input text is HTML, and the start_old, etc... fragments are inserted at arbitrary locations depending on where the diffs are, you might end up with invalid HTML unless the original HTML is quoted.
-start_old (optional, defaults to "<strike><i><font color="blue">")
HTML fragment to place before text that has been removed.
-end_old (optional, defaults to "</font></i></strike>")
HTML fragment to place after text that has been removed.
-start_new (optional, defaults to "<u><b><font color="red">")
HTML fragment to place before new text.
-end_new (optional, defaults to "</font></b></u>")
HTML fragment to place after new text.
Author:
Gabriel Burca
See Also:
  • ns_quotehtml

Partial Call Graph (max 5 caller/called nodes):
%3 test_word_diff word_diff (test acs-tcl) util::word_diff util::word_diff test_word_diff->util::word_diff ad_tmpdir ad_tmpdir (public) util::word_diff->ad_tmpdir util::which util::which (public) util::word_diff->util::which

Testcases:
word_diff

util::zip (public)

 util::zip -source source -destination destination

Create a zip file.

Switches:
-source (required)
is the content to be zipped. If it is a directory, archive will contain all files into directory without the trailing directory itself.
-destination (required)
is the name of the created file

Partial Call Graph (max 5 caller/called nodes):
%3 test_zip_and_unzip zip_and_unzip (test acs-tcl) util::zip util::zip test_zip_and_unzip->util::zip ad_file ad_file (public) util::zip->ad_file packages/file-storage/www/download-zip.tcl packages/file-storage/ www/download-zip.tcl packages/file-storage/www/download-zip.tcl->util::zip util::file_content_check util::file_content_check (public) util::file_content_check->util::zip

Testcases:
zip_and_unzip

util_AnsiDatetoPrettyDate (public, deprecated)

 util_AnsiDatetoPrettyDate sql_date
Deprecated. Invoking this procedure generates a warning.

Converts 1998-09-05 to September 5, 1998 DEPRECATED: this proc hardcodes the date format and the language to American English. Better alternatives exist in acs-lang.

Parameters:
sql_date (required)
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 dt_widget_list dt_widget_list (public, deprecated) util_AnsiDatetoPrettyDate util_AnsiDatetoPrettyDate dt_widget_list->util_AnsiDatetoPrettyDate dt_widget_week dt_widget_week (public, deprecated) dt_widget_week->util_AnsiDatetoPrettyDate ad_log_deprecated ad_log_deprecated (public) util_AnsiDatetoPrettyDate->ad_log_deprecated

Testcases:
No testcase defined.

util_absolute_path_p (public)

 util_absolute_path_p path

Check whether the path begins with a slash

Parameters:
path (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_util__absolute_path_p util__absolute_path_p (test acs-tcl) util_absolute_path_p util_absolute_path_p test_util__absolute_path_p->util_absolute_path_p ad_returnredirect ad_returnredirect (public) ad_returnredirect->util_absolute_path_p

Testcases:
util__absolute_path_p

util_background_exec (public)

 util_background_exec [ -pass_vars pass_vars ] -name name code_chunk

Executes a chunk of code in the background. The code is run exclusively, meaning that no two threads with the same name can run at the same time.

Switches:
-pass_vars (optional)
Names of variables which you want passed to the code chunk
-name (required)
The name of the thread. No two chunks with the same name can run at the same time.
Parameters:
code_chunk (required)
The chunk you want executed

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

Testcases:
No testcase defined.

util_background_get_result (public)

 util_background_get_result -name name

Gets the result of a completed background thread execution.

Switches:
-name (required)

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

Testcases:
No testcase defined.

util_background_reset (public)

 util_background_reset -name name

Gets the result of a completed background thread execution.

Switches:
-name (required)

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

Testcases:
No testcase defined.

util_background_running_p (public)

 util_background_running_p -name name
Switches:
-name (required)
Returns:
a boolean telling whether a background execution with this name is currently running.

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

Testcases:
No testcase defined.

util_commify_number (public, deprecated)

 util_commify_number num
Deprecated. Invoking this procedure generates a warning.

Returns the number with commas inserted where appropriate. Number can be positive or negative and can have a decimal point. e.g. -1465.98 => -1,465.98 DEPRECATED: this proc has been long superseded by lc_numeric, which also supports different locales and formats.

Parameters:
num (required)
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) util_commify_number util_commify_number util_commify_number->ad_log_deprecated

Testcases:
No testcase defined.

util_complete_url_p (public)

 util_complete_url_p url

Determine whether the provided argument is a complete URL, i.e., it contains a scheme, and a host

Parameters:
url (required)
Returns:
boolean value

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) util_complete_url_p util_complete_url_p test_ad_page_contract_filters->util_complete_url_p test_subsite_api subsite_api (test acs-subsite) test_subsite_api->util_complete_url_p test_util__complete_url_p util__complete_url_p (test acs-tcl) test_util__complete_url_p->util_complete_url_p ad_returnredirect ad_returnredirect (public) ad_returnredirect->util_complete_url_p util::external_url_p util::external_url_p (public) util::external_url_p->util_complete_url_p

Testcases:
subsite_api, ad_page_contract_filters, util__complete_url_p

util_current_directory (public)

 util_current_directory

Returns the directory of the current URL.

We can't just use [file dirname [ad_conn url]] because we want /foo/bar/ to return /foo/bar/ and not /foo .

Also, we want to return directory WITH the trailing slash so that programs that use this proc don't have to treat the root directory as a special case.

Partial Call Graph (max 5 caller/called nodes):
%3 ad_returnredirect ad_returnredirect (public) util_current_directory util_current_directory ad_returnredirect->util_current_directory ad_conn ad_conn (public) util_current_directory->ad_conn ad_file ad_file (public) util_current_directory->ad_file

Testcases:
No testcase defined.

util_current_location (public)

 util_current_location

This function behaves like [ad_conn location], since it returns the location string of the current request in the form protocol://hostname?:port? but it honors the "Host:" header field (when the client addressed the server with a hostname different to the default one from the server configuration file) and therefore as well the host-node mapping. If the "Host" header field is missing or empty this function falls back to [ad_conn location].

Returns:
the current location in the form "protocol://hostname?:port?"
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_dom_sanitize_html ad_dom_sanitize_html (test acs-tcl) util_current_location util_current_location test_ad_dom_sanitize_html->util_current_location test_get_insecure_location get_insecure_location (test acs-tcl) test_get_insecure_location->util_current_location test_sync_http_get_document sync_http_get_document (test acs-authentication) test_sync_http_get_document->util_current_location ad_conn ad_conn (public) util_current_location->ad_conn ad_url ad_url (public) util_current_location->ad_url apm_package_id_from_key apm_package_id_from_key (public) util_current_location->apm_package_id_from_key parameter::get parameter::get (public) util_current_location->parameter::get security::validated_host_header security::validated_host_header (public) util_current_location->security::validated_host_header Class ::xo::Authorize Class ::xo::Authorize (public) Class ::xo::Authorize->util_current_location ad_dom_sanitize_html ad_dom_sanitize_html (public) ad_dom_sanitize_html->util_current_location ad_html_qualify_links ad_html_qualify_links (public) ad_html_qualify_links->util_current_location ad_returnredirect ad_returnredirect (public) ad_returnredirect->util_current_location packages/acs-subsite/www/members/member-state-change.tcl packages/acs-subsite/ www/members/member-state-change.tcl packages/acs-subsite/www/members/member-state-change.tcl->util_current_location

Testcases:
sync_http_get_document, get_insecure_location, ad_dom_sanitize_html

util_driver_info (public)

 util_driver_info [ -array array ] [ -driver driver ]

Returns the protocol and port for the specified (or current) driver.

Switches:
-array (optional)
the array to populate with proto, address and port
-driver (optional)
the driver to query (defaults to [ad_conn driver])
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 security::get_http_port security::get_http_port (private) util_driver_info util_driver_info security::get_http_port->util_driver_info security::get_https_port security::get_https_port (private) security::get_https_port->util_driver_info security::get_register_subsite security::get_register_subsite (public) security::get_register_subsite->util_driver_info security::validated_host_header security::validated_host_header (public) security::validated_host_header->util_driver_info subsite::get_url subsite::get_url (public) subsite::get_url->util_driver_info ad_conn ad_conn (public) util_driver_info->ad_conn

Testcases:
No testcase defined.

util_email_unique_p (public)

 util_email_unique_p email

Returns 1 if the email passed in does not yet exist in the system.

Parameters:
email (required)
Author:
yon <yon@openforce.net>

Partial Call Graph (max 5 caller/called nodes):
%3 Class ::xo::Authorize Class ::xo::Authorize (public) util_email_unique_p util_email_unique_p Class ::xo::Authorize->util_email_unique_p xo::Authorize instproc register_new_user xo::Authorize instproc register_new_user (protected) xo::Authorize instproc register_new_user->util_email_unique_p db_string db_string (public) util_email_unique_p->db_string

Testcases:
No testcase defined.

util_email_valid_p (public)

 util_email_valid_p query_email

Returns 1 if an email address has more or less the correct form. The initial regexp was taken from Jeff Friedls book "Mastering Regular Expressions". It was later updated with the version proposed by mozilla for the email input type validation. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email#validation

Parameters:
query_email (required)
Authors:
Philip Greenspun <philg@mit.edu>
Jeff Friedl <jfriedl@oreilly.com>
Lars Pind <lars@arsdigita.com>
Héctor Romojaro
Günter Ernst

Partial Call Graph (max 5 caller/called nodes):
%3 test_host_admin_and_outgoing_sender host_admin_and_outgoing_sender (test acs-tcl) util_email_valid_p util_email_valid_p test_host_admin_and_outgoing_sender->util_email_valid_p test_util_email_valid_p util_email_valid_p (test acs-tcl) test_util_email_valid_p->util_email_valid_p acs_mail_lite::check_bounces acs_mail_lite::check_bounces (private) acs_mail_lite::check_bounces->util_email_valid_p acs_mail_lite::utils::valid_email_p acs_mail_lite::utils::valid_email_p (private, deprecated) acs_mail_lite::utils::valid_email_p->util_email_valid_p ad_page_contract_filter_proc_email ad_page_contract_filter_proc_email (public) ad_page_contract_filter_proc_email->util_email_valid_p auth::validate_account_info auth::validate_account_info (private) auth::validate_account_info->util_email_valid_p packages/acs-admin/www/users/user-batch-add-2.tcl packages/acs-admin/ www/users/user-batch-add-2.tcl packages/acs-admin/www/users/user-batch-add-2.tcl->util_email_valid_p

Testcases:
host_admin_and_outgoing_sender, util_email_valid_p

util_escape_quotes_for_csv (public)

 util_escape_quotes_for_csv string

Returns its argument with double quote replaced by backslash double quote

Parameters:
string (required)

Partial Call Graph (max 5 caller/called nodes):
%3 test_util__escape_quotes_for_csv util__escape_quotes_for_csv (test acs-tcl) util_escape_quotes_for_csv util_escape_quotes_for_csv test_util__escape_quotes_for_csv->util_escape_quotes_for_csv

Testcases:
util__escape_quotes_for_csv

util_get_current_url (public, deprecated)

 util_get_current_url
Deprecated. Invoking this procedure generates a warning.

Returns a URL for re-issuing the current request, with query variables. If a form submission is present, that is converted into query vars as well. DEPRECATED: ad_return_url is a complete replacement for this API that also allows better control over the behavior.

Returns:
URL for the current page
Author:
Lars Pind <lars@pinds.com>
Created:
February 11, 2003
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 ad_conn ad_conn (public) ad_log_deprecated ad_log_deprecated (public) export_vars export_vars (public) util_get_current_url util_get_current_url util_get_current_url->ad_conn util_get_current_url->ad_log_deprecated util_get_current_url->export_vars

Testcases:
No testcase defined.

util_get_subset_missing (public)

 util_get_subset_missing list1 list2

Returns the elements in list1 that are not in list2. Ignores duplicates.

Parameters:
list1 (required)
list2 (required)
Returns:
The list of elements from list1 that could not be found in list2.
Author:
Peter Marklund

Partial Call Graph (max 5 caller/called nodes):
%3 test_message__get_embedded_vars message__get_embedded_vars (test acs-lang) util_get_subset_missing util_get_subset_missing test_message__get_embedded_vars->util_get_subset_missing test_util_get_subset_missing util_get_subset_missing (test acs-tcl) test_util_get_subset_missing->util_get_subset_missing lang::message::check lang::message::check (public) lang::message::check->util_get_subset_missing

Testcases:
message__get_embedded_vars, util_get_subset_missing

util_get_user_messages (public)

 util_get_user_messages [ -keep ] -multirow multirow

Gets and clears the message to be displayed on the next page load.

Switches:
-keep (optional, boolean)
If set, then we will not clear the list of messages after getting them. Normal behavior is to clear them, so we only display the same messages once.
-multirow (required)
Name of a multirow in the current template namespace where you want the user messages set. The multirow will have one column, which is 'message'.
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_util_user_messages util_user_messages (test acs-tcl) util_get_user_messages util_get_user_messages test_util_user_messages->util_get_user_messages ad_get_client_property ad_get_client_property (public) util_get_user_messages->ad_get_client_property ad_set_client_property ad_set_client_property (public) util_get_user_messages->ad_set_client_property template::multirow template::multirow (public) util_get_user_messages->template::multirow packages/acs-subsite/www/admin/plain-master.tcl packages/acs-subsite/ www/admin/plain-master.tcl packages/acs-subsite/www/admin/plain-master.tcl->util_get_user_messages packages/acs-subsite/www/group-master.tcl packages/acs-subsite/ www/group-master.tcl packages/acs-subsite/www/group-master.tcl->util_get_user_messages packages/acs-subsite/www/plain-master.tcl packages/acs-subsite/ www/plain-master.tcl packages/acs-subsite/www/plain-master.tcl->util_get_user_messages packages/acs-subsite/www/shared/plain-master.tcl packages/acs-subsite/ www/shared/plain-master.tcl packages/acs-subsite/www/shared/plain-master.tcl->util_get_user_messages packages/openacs-default-theme/lib/plain-master.tcl packages/openacs-default-theme/ lib/plain-master.tcl packages/openacs-default-theme/lib/plain-master.tcl->util_get_user_messages

Testcases:
util_user_messages

util_list_of_ns_sets_to_list_of_lists (public)

 util_list_of_ns_sets_to_list_of_lists -list_of_ns_sets list_of_ns_sets

Transform a list of ns_sets (most likely produced by db_list_of_ns_sets) into a list of lists that match the array set format in the sublists (key value key value ...)

Switches:
-list_of_ns_sets (required)
A list of ns_set ids
Author:
Ola Hansson <ola@polyxena.net>
Created:
September 27, 2002

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

Testcases:
No testcase defined.

util_remove_nulls_from_ns_set (public)

 util_remove_nulls_from_ns_set old_set_id

Creates and returns a new ns_set without any null value fields

Parameters:
old_set_id (required)
Returns:
new ns_set

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

Testcases:
No testcase defined.

util_report_library_entry (public, deprecated)

 util_report_library_entry [ extra_message ]
Deprecated. Invoking this procedure generates a warning.

Should be called at beginning of private Tcl library files so that it is easy to see in the error log whether or not private Tcl library files contain errors. DEPRECATED: this proc is a leftover from the past, OpenACS does inform about libraries being loaded in the logfile. If one needs a special statement for debugging purposes, a custom ns_log oneliner will do.

Parameters:
extra_message (optional)
See Also:
  • ns_log

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) util_report_library_entry util_report_library_entry util_report_library_entry->ad_log_deprecated

Testcases:
No testcase defined.

util_report_successful_library_load (public, deprecated)

 util_report_successful_library_load [ extra_message ]
Deprecated. Invoking this procedure generates a warning.

Should be called at end of private Tcl library files so that it is easy to see in the error log whether or not private Tcl library files contain errors. DEPRECATED: this proc is a leftover from the past, OpenACS does inform about libraries being loaded in the logfile. If one needs a special statement for debugging purposes, a custom ns_log oneliner will do.

Parameters:
extra_message (optional)
See Also:
  • ns_log

Partial Call Graph (max 5 caller/called nodes):
%3 ad_log_deprecated ad_log_deprecated (public) util_report_successful_library_load util_report_successful_library_load util_report_successful_library_load->ad_log_deprecated

Testcases:
No testcase defined.

util_return_headers (public)

 util_return_headers [ content_type ] [ content_length ]

We use this when we want to send out just the headers and then do incremental writes with ns_write. This way the user doesn't have to wait for streamed output (useful when doing bulk uploads, installs, etc.). It returns status 200 and all headers including any added to outputheaders.

Parameters:
content_type (optional, defaults to "text/html")
content_length (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 ad_progress_bar_begin ad_progress_bar_begin (public) util_return_headers util_return_headers ad_progress_bar_begin->util_return_headers ad_return_top_of_page ad_return_top_of_page (public) ad_return_top_of_page->util_return_headers cr_write_content-lob cr_write_content-lob (private) cr_write_content-lob->util_return_headers packages/acs-subsite/www/shared/1pixel.tcl packages/acs-subsite/ www/shared/1pixel.tcl packages/acs-subsite/www/shared/1pixel.tcl->util_return_headers util_WriteWithExtraOutputHeaders util_WriteWithExtraOutputHeaders (private) util_return_headers->util_WriteWithExtraOutputHeaders

Testcases:
No testcase defined.

util_sets_equal_p (public)

 util_sets_equal_p list1 list2

Tests whether each unique string in list1 occurs as many times in list1 as in list2 and vice versa (regardless of order).

Parameters:
list1 (required)
list2 (required)
Returns:
1 if the lists have identical sets and 0 otherwise
Author:
Peter Marklund

Partial Call Graph (max 5 caller/called nodes):
%3 test_message__get_embedded_vars message__get_embedded_vars (test acs-lang) util_sets_equal_p util_sets_equal_p test_message__get_embedded_vars->util_sets_equal_p test_spellcheck__get_element_formtext spellcheck__get_element_formtext (test acs-templating) test_spellcheck__get_element_formtext->util_sets_equal_p test_sync_actions sync_actions (test acs-authentication) test_sync_actions->util_sets_equal_p test_sync_batch_ims_example_doc sync_batch_ims_example_doc (test acs-authentication) test_sync_batch_ims_example_doc->util_sets_equal_p test_util__sets_equal_p util__sets_equal_p (test acs-tcl) test_util__sets_equal_p->util_sets_equal_p template::list::prepare_filters template::list::prepare_filters (private) template::list::prepare_filters->util_sets_equal_p workflow::test::assert_case_state workflow::test::assert_case_state (public) workflow::test::assert_case_state->util_sets_equal_p workflow::test::assert_user_actions workflow::test::assert_user_actions (public) workflow::test::assert_user_actions->util_sets_equal_p

Testcases:
sync_actions, sync_batch_ims_example_doc, message__get_embedded_vars, util__sets_equal_p, spellcheck__get_element_formtext

util_subset_p (public)

 util_subset_p list1 list2

Tests whether list1 is a subset of list2.

Parameters:
list1 (required)
list2 (required)
Returns:
1 if list1 is a subset of list2.
Author:
Peter Marklund

Partial Call Graph (max 5 caller/called nodes):
%3 test_util_subset_p util_subset_p (test acs-tcl) util_subset_p util_subset_p test_util_subset_p->util_subset_p

Testcases:
util_subset_p

util_text_to_url (public)

 util_text_to_url [ -existing_urls existing_urls ] [ -no_resolve ] \
    [ -replacement replacement ] [ -text text ] [ _text ]

Modify a string so that it is suited as a well formatted URL path element. Also, if given a list of existing URLs it can catch duplicate or optionally create an unambiguous url by appending a dash and a digit.

Examples:
util_text_to_url -text "Foo Bar" returns foo-bar
util_text_to_url -existing_urls {foo-bar some-other-item} -text "Foo Bar" returns foo-bar-2

Switches:
-existing_urls (optional)
a list of URLs that already exist on the same level and would cause a conflict
-no_resolve (optional, boolean)
Specify this flag if you do not want util_text_to_url to automatically generate "foo-bar-2" if "foo-bar" is already in existing_urls, and would rather have an error thrown.
-replacement (optional, defaults to "-")
the character that is used to replace illegal characters
-text (optional)
the text to modify, e.g. "Foo Bar"
Parameters:
_text (optional)
the text to modify, e.g. "Foo Bar" (Deprecated, use -text instead. Fails when the value starts with a dash.)
Author:
Tilmann Singer

Partial Call Graph (max 5 caller/called nodes):
%3 test_auth_authenticate auth_authenticate (test acs-authentication) util_text_to_url util_text_to_url test_auth_authenticate->util_text_to_url test_auth_create_user auth_create_user (test acs-authentication) test_auth_create_user->util_text_to_url test_auth_driver_get_parameter_values auth_driver_get_parameter_values (test acs-authentication) test_auth_driver_get_parameter_values->util_text_to_url test_auth_email_on_password_change auth_email_on_password_change (test acs-authentication) test_auth_email_on_password_change->util_text_to_url test_auth_get_registration_elements auth_get_registration_elements (test acs-authentication) test_auth_get_registration_elements->util_text_to_url acs_sc_generate_name acs_sc_generate_name (private) acs_sc_generate_name->util_text_to_url auth::authority::create auth::authority::create (public) auth::authority::create->util_text_to_url packages/acs-subsite/www/admin/site-map/application-new.tcl packages/acs-subsite/ www/admin/site-map/application-new.tcl packages/acs-subsite/www/admin/site-map/application-new.tcl->util_text_to_url packages/xowiki/www/ckeditor-images/upload_image.tcl packages/xowiki/ www/ckeditor-images/upload_image.tcl packages/xowiki/www/ckeditor-images/upload_image.tcl->util_text_to_url rel_types::create_role rel_types::create_role (public) rel_types::create_role->util_text_to_url

Testcases:
auth_authenticate, auth_create_user, auth_get_registration_elements, auth_password_change, auth_password_recover, auth_password_get_forgotten_url, auth_password_retrieve, auth_password_reset, auth_driver_get_parameter_values, auth_use_email_for_login_p, auth_email_on_password_change, sync_batch_ims_example_doc, sync_batch_ims_test, sync_http_get_document

util_url_valid_p (public)

 util_url_valid_p [ -relative ] query_url

Check if an absolute Web URL (HTTP, HTTPS or FTP) is valid. If the 'relative' flag is set, also relative URLs are accepted. Refined regexp from https://mathiasbynens.be/demo/url-regex

Switches:
-relative (optional, boolean)
Boolean. If true, Accept also relative URLs.
Parameters:
query_url (required)
The URL to check.
Returns:
1 if the web URL is valid, 0 otherwise.
Authors:
Philip Greenspun <philg@mit.edu>
Héctor Romojaro

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_tcl__util_url_valid_p acs_tcl__util_url_valid_p (test acs-tcl) util_url_valid_p util_url_valid_p test_acs_tcl__util_url_valid_p->util_url_valid_p apidoc::format_see apidoc::format_see (public) apidoc::format_see->util_url_valid_p auth::validate_account_info auth::validate_account_info (private) auth::validate_account_info->util_url_valid_p template::data::validate::url template::data::validate::url (public) template::data::validate::url->util_url_valid_p

Testcases:
acs_tcl__util_url_valid_p

util_user_message (public)

 util_user_message [ -replace ] [ -html ] [ -message message ]

Sets a message to be displayed on the next page request.

Switches:
-replace (optional, boolean)
Set this if you want to replace existing messages. Default behavior is to append to a list of messages.
-html (optional, boolean)
Set this flag if your message contains HTML. If specified, you're responsible for proper quoting of everything in your message. Otherwise, we quote it for you.
-message (optional)
The message to display.
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_util_user_messages util_user_messages (test acs-tcl) util_user_message util_user_message test_util_user_messages->util_user_message ad_get_client_property ad_get_client_property (public) util_user_message->ad_get_client_property ad_set_client_property ad_set_client_property (public) util_user_message->ad_set_client_property Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) Class ::xowf::test_item::Answer_manager->util_user_message Class ::xowf::test_item::Question_manager Class ::xowf::test_item::Question_manager (public) Class ::xowf::test_item::Question_manager->util_user_message Class ::xowiki::formfield::numeric Class ::xowiki::formfield::numeric (public) Class ::xowiki::formfield::numeric->util_user_message Class ::xowiki::includelet::child-resources Class ::xowiki::includelet::child-resources (public) Class ::xowiki::includelet::child-resources->util_user_message ad_progress_bar_end ad_progress_bar_end (public) ad_progress_bar_end->util_user_message

Testcases:
util_user_messages

util_wrap_list (public)

 util_wrap_list [ -eol eol ] [ -indent indent ] [ -length length ] \
    items

Wraps text to a particular line length.

Switches:
-eol (optional, defaults to " \")
the string to be used at the end of each line.
-indent (optional, defaults to "4")
the number of spaces to use to indent all lines after the first.
-length (optional, defaults to "70")
the maximum line length.
Parameters:
items (required)
the list of items to be wrapped. Items are HTML-formatted. An individual item will never be wrapped onto separate lines.

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_api_browser_api_describe_function acs_api_browser_api_describe_function (test acs-api-browser) util_wrap_list util_wrap_list test_acs_api_browser_api_describe_function->util_wrap_list test_acs_api_browser_api_proc_documentation acs_api_browser_api_proc_documentation (test acs-api-browser) test_acs_api_browser_api_proc_documentation->util_wrap_list api_proc_documentation api_proc_documentation (public) api_proc_documentation->util_wrap_list

Testcases:
acs_api_browser_api_describe_function, acs_api_browser_api_proc_documentation

xml_get_child_node_attribute_by_path (public)

 xml_get_child_node_attribute_by_path node path_list attribute_name

Return the attribute of a child node down a give path from the current node. Example:

    set tree [xml_parse -persist "
<enterprise>
  <properties>
    <datasource>University of Durham: SIS</datasource>
    <target>University of Durham: LMS</target>
    <type>CREATE</type>
    <datetime>2001-08-08</datetime>
  </properties>
  <group recstatus = "1">
    <sourcedid>
      <source>University of Durham</source>
      <id>CS1</id>
    </sourcedid>
    <grouptype>
      <scheme>University of Durham</scheme>
      <typevalue level = "2"/>
    </grouptype>

    .....

  </group>
</enterprise>

"]
    set root_node [xml_doc_get_first_node $tree]
    set group_node [xml_node_get_children_by_name $root_node "group"]
    set typevalue [xml_get_child_node_attribute_by_path $group_node {grouptype typevalue} "level"]
    

Parameters:
node (required)
The node to start from
path_list (required)
List of the node to try, e.g. { grouptype typevalue }.
attribute_name (required)
Attribute name at the very end of the very bottom of the tree route at path_list.
Author:
Rocael Hernandez <roc@viaro.net>

Partial Call Graph (max 5 caller/called nodes):
%3 xml_node_get_attribute xml_node_get_attribute (public) xml_node_get_first_child_by_name xml_node_get_first_child_by_name (public) xml_get_child_node_attribute_by_path xml_get_child_node_attribute_by_path xml_get_child_node_attribute_by_path->xml_node_get_attribute xml_get_child_node_attribute_by_path->xml_node_get_first_child_by_name

Testcases:
No testcase defined.

xml_get_child_node_content_by_path (public)

 xml_get_child_node_content_by_path node path_list

Return the first nonempty contents of a child node down a given path from the current node.

Example:

    set tree [xml_parse -persist {
        <enterprise>
        <properties>
        <datasource>Dunelm Services Limited</datasource>
        <target>Telecommunications LMS</target>
        <type>DATABASE UPDATE</type>
        <datetime>2001-08-08</datetime>
        </properties>
        <person recstatus = "1">
        <comments>Add a new Person record.</comments>
        <sourcedid>
        <source>Dunelm Services Limited</source>
        <id>CK1</id>
        </sourcedid>
        <name>
        <fn>Clark Kent</fn>
        <sort>Kent, C</sort>
        <nickname>Superman</nickname>
        </name>
        <demographics>
        <gender>2</gender>
        </demographics>
        <adr>
        <extadd>The Daily Planet</extadd>
        <locality>Metropolis</locality>
        <country>USA</country>
        </adr>
        </person>
        </enterprise>
    }]

    set root_node [xml_doc_get_first_node $tree]

    aa_equals "person -> name -> nickname is Superman"  [xml_get_child_node_content_by_path $root_node { { person name nickname } }] "Superman"

    aa_equals "Same, but after trying a couple of non-existent paths or empty notes"  [xml_get_child_node_content_by_path $root_node { { does not exist } { properties } { person name nickname } { person sourcedid id } }] "Superman"
    aa_equals "properties -> datetime"  [xml_get_child_node_content_by_path $root_node { { person comments foo } { person name first_names } { properties datetime } }] "2001-08-08"
    

Parameters:
node (required)
The node to start from
path_list (required)
List of list of nodes to try, e.g. { { user_id } { sourcedid id } }, or { { name given } { name fn } }.
Author:
Lars Pind <lars@collaboraid.biz>

Partial Call Graph (max 5 caller/called nodes):
%3 test_xml_get_child_node_content_by_path xml_get_child_node_content_by_path (test acs-tcl) xml_get_child_node_content_by_path xml_get_child_node_content_by_path test_xml_get_child_node_content_by_path->xml_get_child_node_content_by_path xml_node_get_content xml_node_get_content (public) xml_get_child_node_content_by_path->xml_node_get_content xml_node_get_first_child_by_name xml_node_get_first_child_by_name (public) xml_get_child_node_content_by_path->xml_node_get_first_child_by_name auth::sync::process_doc::ims::GetAcknowledgementDocument auth::sync::process_doc::ims::GetAcknowledgementDocument (private) auth::sync::process_doc::ims::GetAcknowledgementDocument->xml_get_child_node_content_by_path auth::sync::process_doc::ims::ProcessDocument auth::sync::process_doc::ims::ProcessDocument (private) auth::sync::process_doc::ims::ProcessDocument->xml_get_child_node_content_by_path

Testcases:
xml_get_child_node_content_by_path
[ show source ]