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
arglist

See Also:

• {*}

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

Testcases:

No testcase defined.

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
persistent (defaults to "f")
excluded_vars (optional)

Author:

Brad Duell <bduell@ncacasi.org>

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

Testcases:

No testcase defined.

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 - input value

Returns:

matched value or default

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

Testcases:

ad_decode, datamodel__named_constraints

Generates a random string made of numbers and letters

Parameters:

length (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

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 (defaults to "-2") - The level to start from, relative to this proc. Defaults to -2, meaning 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:

• ad_print_stack_trace

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

Testcases:

No testcase defined.

Convenience wrapper for simple usages of ns_job provided by AOLServer and 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

(defaults to "jobs") (optional)

Name of job queue

-timeout

(optional)

timeout for job, might be 1:0 for 1 sec

Returns:

result of the specified command

Author:

Gustaf Neumann

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

Testcases:

ad_job

Output ns_log message with detailed context. This function is intended to be used typically with "error" to ease debugging.

Parameters:

level - 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

Wrapper for Tcl's "file tempdir ...", but respects the server's tmpdir settings.

Parameters:

prefix (defaults to "oacs") - 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

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

(defaults to "overwrite") (optional)

This optional switch argument defines what happens if the Tcl var 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

(defaults to "1") (optional)

The level to upvar to.

Parameters:

set_id

Author:

Lars Pind <lars@pinds.com>

See Also:

• upvar
• for
• ns_set

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

Testcases:

No testcase defined.

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
template (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

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

Parameters:

first_part_of_page
content_type (defaults to "text/html")

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

Testcases:

No testcase defined.

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

(boolean) (optional)

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

(boolean) (optional)

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

See Also:

• util_user_message
• ad_script_abort

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

Testcases:

No testcase defined.

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

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

(boolean) (optional)

-existing_names

(optional)

-collapse_spaces

(boolean) (optional)

-replace_with

(defaults to "-") (optional)

-tolower

(boolean) (optional)

Parameters:

str

Author:

Gustaf Neumann

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

Testcases:

ad__sanitize_filename, fs_add_file_to_folder

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

(defaults to "t") (optional)

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

(defaults to "f") (optional)

t/f. If true only run the scheduled proc once

-debug

(defaults to "f") (optional)

t/f If true log debugging information

-all_servers

(defaults to "f") (optional)

If true run on all servers in a cluster

-schedule_proc

(optional)

ns_schedule_daily, ns_schedule_weekly or blank

Parameters:

interval - 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 - The proc to schedule

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

Testcases:

ad_schedule_proc

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

(boolean) (optional)

If this boolean switch is specified, it'll use ns_set put instead of ns_set update (update is default)

Parameters:

kv_pairs - 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.

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

(boolean) (optional)

If this boolean switch is specified, it'll use ns_set put instead of ns_set update (update is default)

Parameters:

vars_list - 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.

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

(boolean) (optional)

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):

Testcases:

No testcase defined.

Convenience function to return the tmp directory

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

Testcases:

csv_foreach, process_objects_csv

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.

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

Parameters:

string

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

Testcases:

No testcase defined.

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

Parameters:

url

See Also:

• ad_urlencode_folder_path

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

Testcases:

export_vars

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
sql

Author:

yon [yon@arsdigita.com]

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

Testcases:

No testcase defined.

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

(defaults to "0") (optional)

-option_index

(defaults to "1") (optional)

Parameters:

stmt_name
sql

Author:

yon [yon@arsdigita.com]

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

Testcases:

No testcase defined.

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:

• export_vars

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

Testcases:

No testcase defined.

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:

• export_vars

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

Testcases:

No testcase defined.

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 (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:

• export_vars

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

Testcases:

No testcase defined.

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

Example usage: 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]}}

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.

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

(boolean) (optional)

Sign all variables.

-form

(boolean) (optional)

Export in form format. You can't specify both URL and form format.

-url

(boolean) (optional)

Export in URL format. This is the default.

-quotehtml

(boolean) (optional)

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

(boolean) (optional)

Export the entire form from the GET query string or the POST.

-no_empty

(boolean) (optional)

-base

(optional)

-no_base_encode

(boolean) (optional)

-anchor

(optional)

-exclude

(optional)

-override

(optional)

-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)

Options:

-no_empty

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

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

Decides whether argument passed as base option will be encoded by ad_urlencode_url proc

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

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

Switches:

-file

(required)

the CSV file to read.

-header_line

(defaults to "1") (optional)

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

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

Testcases:

csv_foreach

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

(defaults to "1") (optional)

-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

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.

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

(defaults to "12") (optional)

The upper limit, in hours, for mode 1.

-days_limit

(defaults to "3") (optional)

The upper limit, in days, for mode 2.

-mode_2_fmt

(defaults to "%X, %A") (optional)

A formatting string, as per lc_time_fmt, for mode 2

-mode_3_fmt

(defaults to "%X, %d %b %Y") (optional)

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

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

Parameters:

list
indent (defaults to "0")

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

Testcases:

No testcase defined.

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

(defaults to ".bak") (optional)

The suffix to add to the backup file.

Author:

Peter Marklund

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

Testcases:

No testcase defined.

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 - A list of arguments to pass to exec
result_var - 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.

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

(boolean) (optional)

Returns:

the configured location in the form "proto://hostname?:port?"

See Also:

• ad_url
• util_current_location

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

Testcases:

No testcase defined.

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

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

Testcases:

ad_page_contract_filters

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

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

(defaults to "0") (optional)

Should directories be included in the list of files.

-max_depth

(defaults to "1") (optional)

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.

Switches:

-relative

(boolean) (optional)

return the refer without protocol and host

-trusted

(boolean) (optional)

Returns:

referrer from the request headers.

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

Testcases:

No testcase defined.

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 - grapviz dot code

Author:

Gustaf Neumann

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

Testcases:

No testcase defined.

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

Switches:

-seconds

(defaults to "0") (optional)

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

Testcases:

util__interval_pretty

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

Switches:

-proto

(optional)

-hostname

(optional)

-port

(optional)

Returns:

location consisting of hostname and optionally port

Author:

Gustaf Neumann

See Also:

• util::split_location

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

Testcases:

util__split_and_join_location

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

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

Transforms a pretty name to a reasonable pathname.

Switches:

-name

(required)

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

Testcases:

name_to_path

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

Parameters:

set_id

Returns:

text string conisting of multiple lines of the form "key: value"

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

Testcases:

No testcase defined.

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 - 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.

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

(boolean) (optional)

Parameters:

string

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

Testcases:

No testcase defined.

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:

• util::random_init

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

Testcases:

acs_mail_lite_inbound_procs_check, parameter__check_procs

Seed the random number generator.

Parameters:

seed

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

Testcases:

No testcase defined.

Returns a random element from the list.

Parameters:

list

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

Testcases:

acs_mail_lite_inbound_procs_check

Returns a pseudo-random number between 0 and range.

Parameters:

range

Returns:

integer

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

Testcases:

set_get_timezone, acs_mail_lite_inbound_procs_check, util__randomize_list

Returns a random permutation of the list.

Parameters:

list

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

Testcases:

acs_mail_lite_inbound_procs_check, util__randomize_list

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

Switches:

-with_headers

(boolean) (defaults to "false") (optional)

Include request headers

Author:

Gustaf Neumann

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

Testcases:

No testcase defined.

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_dir

(optional)

an optional directory, under the resource directory

Author:

Gustaf Neumann

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

Testcases:

No testcase defined.

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_dir

(optional)

an optional directory, under the resource directory

Author:

Gustaf Neumann

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

Testcases:

No testcase defined.

Check, if the required resource files are installed locally. When the version_dir is specified, it is possible to have different versions locally installed.

Switches:

-resource_info

(required)

a dict containing resourceDir, cssFiles, jsFiles, and extraFiles

-version_dir

(optional)

an optional directory, under the resource directory

Author:

Gustaf Neumann

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

Testcases:

No testcase defined.

Obtain the version_dir either form the provided string or from the resource_info dict.

Switches:

-resource_info

(required)

-version_dir

(optional)

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

Testcases:

No testcase defined.

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.

Split host potentially into a hostname and a port

Parameters:

hostspec
hostnameVar
portVar

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

Testcases:

No testcase defined.

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
protoVar
hostnameVar
portVar

Returns:

boolean value indicating success

Author:

Gustaf Neumann

See Also:

• util::join_location

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

Testcases:

util__split_and_join_location

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

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

Testcases:

No testcase defined.

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

Parameters:

s1
s2

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

Testcases:

string_length_compare

Make string safe for subst'ing.

Parameters:

string

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

Testcases:

No testcase defined.

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

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

Testcases:

util__trim_leading_zeros

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

(boolean) (optional)

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

Testcases:

zip_and_unzip

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

(defaults to "1") (optional)

Where we should uplevel to when doing the subst's. Defaults to '1', meaning the caller's scope.

Parameters:

string

Author:

Gustaf Neumann

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

Testcases:

No testcase defined.

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 - 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, file_storage_exec_dependencies

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

(defaults to "ns_quotehtml") (optional)

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

(defaults to "<strike><i><font color="blue">") (optional)

HTML fragment to place before text that has been removed.

-end_old

(defaults to "</font></i></strike>") (optional)

HTML fragment to place after text that has been removed.

-start_new

(defaults to "<u><b><font color="red">") (optional)

HTML fragment to place before new text.

-end_new

(defaults to "</font></b></u>") (optional)

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

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

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

See Also:

• lc_time_fmt

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

Testcases:

No testcase defined.

Check whether the path begins with a slash

Parameters:

path

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

Testcases:

util__absolute_path_p

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 - The chunk you want executed

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

Testcases:

No testcase defined.

Gets the result of a completed background thread execution.

Switches:

-name

(required)

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

Testcases:

No testcase defined.

Gets the result of a completed background thread execution.

Switches:

-name

(required)

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

Testcases:

No testcase defined.

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.

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

See Also:

• lc_numeric

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

Testcases:

No testcase defined.

Determine whether string is a complete URL, i.e. whether it begins with protocol: where protocol consists of letters only.

Parameters:

string

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

Testcases:

subsite_api, ad_page_contract_filters, util__complete_url_p

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.

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:

• util::configured_location
• ad_url
• ad_conn

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

Testcases:

sync_http_get_document, get_insecure_location

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:

• security::configured_driver_info

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

Testcases:

No testcase defined.

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

Parameters:

email

Author:

yon <yon@openforce.net>

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

Testcases:

No testcase defined.

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

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

Returns its argument with double quote replaced by backslash double quote

Parameters:

string

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

Testcases:

util__escape_quotes_for_csv

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:

• ad_return_url

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

Testcases:

No testcase defined.

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

Parameters:

list1
list2

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

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

Switches:

-keep

(boolean) (optional)

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:

• util_user_message

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

Testcases:

util_user_messages

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.

Creates and returns a new ns_set without any null value fields

Parameters:

old_set_id

Returns:

new ns_set

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

Testcases:

No testcase defined.

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.

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.

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 (defaults to "text/html")
content_length (optional)

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

Testcases:

No testcase defined.

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

Parameters:

list1
list2

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

Tests whether list1 is a subset of list2.

Parameters:

list1
list2

Returns:

1 if list1 is a subset of list2.

Author:

Peter Marklund

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

Testcases:

util_subset_p

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

(boolean) (optional)

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

(defaults to "-") (optional)

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

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

(boolean) (optional)

Boolean. If true, Accept also relative URLs.

Parameters:

query_url - 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

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

Switches:

-replace

(boolean) (optional)

Set this if you want to replace existing messages. Default behavior is to append to a list of messages.

-html

(boolean) (optional)

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:

• util_get_user_messages

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

Testcases:

util_user_messages

Wraps text to a particular line length.

Switches:

-eol

(defaults to " \") (optional)

the string to be used at the end of each line.

-indent

(defaults to "4") (optional)

the number of spaces to use to indent all lines after the first.

-length

(defaults to "70") (optional)

the maximum line length.

Parameters:

items - 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