- 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
- ad_apply (public, deprecated)
- ad_cache_returnredirect (public)
- ad_decode (public)
- ad_generate_random_string (public)
- ad_get_tcl_call_stack (public)
- ad_job (public)
- ad_log (public)
- ad_mktmpdir (public)
- ad_ns_set_to_tcl_vars (public, deprecated)
- ad_opentmpfile (public)
- ad_return_top_of_page (public)
- ad_returnredirect (public)
- ad_safe_eval (public)
- ad_sanitize_filename (public)
- ad_schedule_proc (public)
- ad_tcl_list_list_to_ns_set (public)
- ad_tcl_vars_list_to_ns_set (public, deprecated)
- ad_tcl_vars_to_ns_set (public, deprecated)
- ad_tmpdir (public)
- ad_tmpnam (public)
- ad_urlencode (public)
- ad_urlencode_url (public)
- db_html_select_options (public)
- db_html_select_value_options (public)
- export_entire_form (public, deprecated)
- export_entire_form_as_url_vars (public, deprecated)
- export_ns_set_vars (public, deprecated)
- export_vars (public)
- oacs_util::csv_foreach (public)
- oacs_util::process_objects_csv (public)
- oacs_util::vars_to_ns_set (public, deprecated)
- util::age_pretty (public)
- util::array_list_spec_pretty (public)
- util::backup_file (public)
- util::block_request (public)
- util::catch_exec (public)
- util::configured_location (public)
- util::external_url_p (public)
- util::file_content_check (public)
- util::find_all_files (public)
- util::get_referrer (public)
- util::inline_svg_from_dot (public)
- util::interval_pretty (public)
- util::join_location (public)
- util::max (public)
- util::min (public)
- util::name_to_path (public)
- util::ns_set_to_tcl_string (public)
- util::pdfinfo (public)
- util::potentially_unsafe_eval_p (public)
- util::random (public)
- util::random_init (public)
- util::random_list_element (public)
- util::random_range (public)
- util::randomize_list (public)
- util::request_info (public)
- util::resources::can_install_locally (public)
- util::resources::cdnjs_get_newest_version (public)
- util::resources::cdnjs_version_API (public)
- util::resources::check_vulnerability (public)
- util::resources::download (public)
- util::resources::download_helper (public)
- util::resources::is_installed_locally (public)
- util::resources::register_urns (public)
- util::resources::resource_info_procs (public)
- util::resources::version_segment (public)
- util::roll_server_log (public)
- util::split_host (public)
- util::split_location (public)
- util::string_check_urlsafe (public, deprecated)
- util::string_length_compare (public)
- util::subst_safe (public)
- util::suspicious_query_variable (public)
- util::trim_leading_zeros (public)
- util::unzip (public)
- util::var_subst_quotehtml (public)
- util::which (public)
- util::word_diff (public)
- util::zip (public)
- util_AnsiDatetoPrettyDate (public, deprecated)
- util_absolute_path_p (public)
- util_background_exec (public)
- util_background_get_result (public)
- util_background_reset (public)
- util_background_running_p (public)
- util_commify_number (public, deprecated)
- util_complete_url_p (public)
- util_current_directory (public)
- util_current_location (public)
- util_driver_info (public)
- util_email_unique_p (public)
- util_email_valid_p (public)
- util_escape_quotes_for_csv (public)
- util_get_current_url (public, deprecated)
- util_get_subset_missing (public)
- util_get_user_messages (public)
- util_list_of_ns_sets_to_list_of_lists (public)
- util_remove_nulls_from_ns_set (public)
- util_report_library_entry (public, deprecated)
- util_report_successful_library_load (public, deprecated)
- util_return_headers (public)
- util_sets_equal_p (public)
- util_subset_p (public)
- util_text_to_url (public)
- util_url_valid_p (public)
- util_user_message (public)
- util_wrap_list (public)
- xml_get_child_node_attribute_by_path (public)
- xml_get_child_node_content_by_path (public)
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):
- 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):
- 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 useexpr {!$boolean_p}
- Parameters:
- value (required)
- input value
- Returns:
- matched value or default
- Partial Call Graph (max 5 caller/called nodes):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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 update
s 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 ofns_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):
- 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 update
s 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 ofns_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):
- 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 update
s 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 ofns_set update
(update is default)- Author:
- Lars Pind <lars@pinds.com>
- See Also:
- ns_set
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_tmpdir (public)
ad_tmpdir
Convenience function to return the tmp directory
- Partial Call Graph (max 5 caller/called nodes):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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
andbaz
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 namedbaz
with the value ofbaz
in the caller's environment. Since we've specified thatbar
should be excluded,bar
won't get exported even though it's specified in the last argument. Additionally, even thoughfoo
is specified also in the last argument, the value we use is the one given in theoverride
argument. Finally, both variables are signed, because we specified the-sign
switch.You can specify variables with three different precedences, namely
override
,exclude
orvars
. If a variable is present inoverride
, that's what'll get exported, no matter what. If a variable is inexclude
and not inoverride
, then it will not get output. However, if it is invars
and not in either ofoverride
orexclude
, then it'll get output. In other words, we checkoverride
,exclude
andvars
in that order of precedence.The two variable specs,
vars
andoverride
both look the same: They take a list of variable specs. Examples of variable specs are: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
- foo
- foo:multiple,sign
- {foo "the value"}
- {foo {[my_function arg]}}
- {foo:array,sign {[array get my_array]}}
[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:
The argument
- 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 ofad_page_contract
, which means that each entry will get output asname.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 ofad_page_contract
and makes sure that the value isn't tampered with on the client side. The-sign
switch toexport_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.
exclude
simply takes a list of names of variables that you don't want exported, even though they're specified invars
.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 ofcolumn
.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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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 botsThe 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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):
- 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"
returnsfoo-bar
util_text_to_url -existing_urls {foo-bar some-other-item} -text "Foo Bar"
returnsfoo-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):
- 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):
- 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):
- 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):
- 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):
- 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):
- Testcases:
- xml_get_child_node_content_by_path