• Publicity: Public Only All

tcl-documentation-procs.tcl

Routines to support documenting pages and processing query arguments.

Location:
packages/acs-tcl/tcl/tcl-documentation-procs.tcl
Created:
16 June 2000
Authors:
Lars Pind <lars@pinds.com>
Jon Salz <jsalz@mit.edu>
Yonatan Feldman <yon@arsdigita.com>
Bryan Quinn <bquinn@arsdigita.com>
CVS Identification:
$Id: tcl-documentation-procs.tcl,v 1.61.2.33 2022/08/29 10:34:19 gustafn Exp $

Procedures in this file

Detailed information

ad_complain (public)

 ad_complain [ -key key ] [ message ]

Used to report a problem while validating user input. This proc does not in itself make your code terminate, you must call return if you do not want control to return to the caller.

Switches:
-key
(optional)
Parameters:
message (optional)
Author:
Lars Pind <lars@pinds.com>
Created:
24 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_aa_page_contract_filters aa_page_contract_filters (test acs-automated-testing) ad_complain ad_complain test_aa_page_contract_filters->ad_complain test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) test_ad_page_contract_filters->ad_complain _ _ (public) ad_complain->_

Testcases:
aa_page_contract_filters, ad_page_contract_filters

ad_complaints_get_list (public)

 ad_complaints_get_list

Returns the list of complaints encountered so far.

Author:
Lars Pind <lars@pinds.com>
Created:
24 July 2000

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

Testcases:
No testcase defined.

ad_include_contract (public)

 ad_include_contract docstring [ args... ]

Define an interface between a page and an ADP <include> similar to the page_contract. This is a light-weight implementation based on the ad_page_contract. It allows one to check the passed arguments (types, optionality) and can be used for setting defaults the usual way. Using ad_include_contracts helps to improve documentation of included content.

Parameters:
docstring - documentation of the include
Author:
gustaf neumann <neumann@wu-wien.ac.at>
Created:
Sept 2015
See Also:

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

Testcases:
No testcase defined.

ad_page_contract (public)

 ad_page_contract [ -form form ] [ -level level ] [ -context context ] \
    [ -warn ] [ -properties properties ] docstring [ args... ]

Specifies the contract between programmer and graphic designer for a page. When called with the magic "documentation-gathering" flag set (to be defined), the proc will record the information about this page, so it can be displayed as documentation. When called during normal page execution, it will validate the query string and set corresponding variables in the caller's environment.

Example:

ad_page_contract  {
        Some documentation.
        @author me (my@email)
        @cvs-id $Id: tcl-documentation-procs.tcl,v 1.61.2.33 2022/08/29 10:34:19 gustafn Exp $
    } {
        foo
        bar:integer,notnull,multiple,trim
        {greble:integer {[expr {[lindex $bar 0] + 1}]}}
    } -validate {
        greble_is_in_range -requires {greble:integer} {
            if { $greble < 1 || $greble > 100 } {
                ad_complain
            }
        }
        greble_exists -requires { greble_is_in_range } {
            if { ![info exists ::greble_values($greble)] } {
                ad_complain [_ acs-tcl.lt_Theres_no_greble_with]
            }
        }
    } -errors {
        foo {error message goes here}
        bar:integer,notnull {another error message}
        greble_is_in_range {Greble must be between 1 and 100}
    }
An argspec takes one of two forms, depending on whether there's a default value or not:
  1. {name[:flag,flag,flag] default}
  2. name[:flag,flag,flag]

If no default value is specified, the argument is considered required, but the empty string is permissible unless you specify :notnull. For all arguments, the filter :nohtml is applied by default. If the arg is named *.tmpfile, the tmpfile filter is applied.

Possible flags are:

trim
The value will be string trimmed.
notnull
When set, will barf if the value is the empty string. Checked after processing the trim flag. If not set, the empty string is always considered valid input, and no other filters are processed for that particular value. If it's an array or multiple variable, the filters will still be applied for other values, though.
optional
If there's a default value present, it's considered optional even without the flag. If a default is given, and the argument is present but blank, the default value will be used. Optional and no default value means the variable will not be set, if the argument is not present in the query string.
multiple
If multiple is specified, the var will be set as a list of all the argument values (e.g. arg=val1&arg=val2 will turn into arg=[list val1 val2]). The defaults are filled in from left to right, so it can depend on values of arguments to its left.
array
This syntax maps query variables into Tcl arrays. If you specify customfield:array, then query var customfield.foo will translate into the Tcl array entry $customfield(foo). In other words: whatever comes after the dot is used as the key into the array, or, more mathematically: x.y=z => set x(y) z. If you use dot or comma is part of your key (i.e., y above contains comma or dot), then you can easily split on it in your Tcl code. Remember that you can use any other flag or filter with array.
verify
Will invoke ad_verify_signature to verify the value of the variable, to make sure it's the value that was output by us, and haven't been tampered with. If you use export_vars -form -sign or export_vars -sign to export the variable, use this flag to verify it. To verify a variable named foo, the verify flag looks for a form variable named foo:sig. For a :multiple, it only expects one single signature for the whole list. For :array it also expects one signature only, taken on the [array get] form of the array.
cached
This syntax will check to see if a value is being passed in for this variable. If it is not, it will then look in cache for this variable in the package that this page is located, and get this value if it exists.
date
Pluggable filter, installed by default, that makes sure the array validates as a date. Use this filter with :array to do automatic date filtering. To use it, set up in your HTML form a call to [ad_dateentrywidget varname]. Then on the receiving page, specify the filter using varname:array,date. If the date validates, there will be a variable set in your environment varname with four keys: day, month, year, and date. You can safely pass $varname(date) to Oracle.
time
Pluggable filter, installed by default, that makes sure the array validates as a time in am/pm format. That is that it has two fields: time and ampm that have valid values. Use this filter with :array to do automatic time filtering. To use it, set up in you HTML form using [ec_timeentrywidget varname] or equivalent. Then on the processing page specify the filter using varname:array,time. If the time validates, there will be a variable set in your environment varname with five keys: time, ampm, hours, minutes, and seconds.
time24
Pluggable filter, installed by default, that makes sure the array validates as a time in 24hr format. That is that it has one field: time that has valid values. Use this filter with :array to do automatic time filtering. To use it, set up in you HTML form using <input type="text" name="varname".time>. Then on the processing page specify the filter using varname:array,time24. If the time validates, there will be a variable set in your environment varname with four keys: time, hours, minutes, and seconds.
integer
Pluggable filter, installed by default, that makes sure the value is integer, and removed any leading zeros.
naturalnum
Pluggable filter, installed by default, that makes sure the value is a natural number, i.e. non-decimal numbers >= 0.
oneof
Pluggable filter, installed by default, that makes sure the value X contained in the set of the provided values. Usage example: color:oneof(red|blue|green)
range
Pluggable filter, installed by default, that makes sure the value X is in range [Y, Z]. Usage example: foo:range(1|100)
nohtml
Pluggable filter, installed by default, that disallows any and all html.
html
Pluggable filter, installed by default, that only allows certain, safe allowed tags to pass (see ad_html_security_check). The purpose of screening naughty html is to prevent users from uploading HTML with tags that hijack page formatting or execute malicious code on the users's computer.
allhtml
Pluggable filter, installed by default, that allows any and all html. Use of this filter is not recommended, except for cases when the HTML will not be presented to the user or there is some other reason for overriding the site-wide control over naughty html.
tmpfile
Checks to see if the path and file specified by tmpfile are allowed on this system.
sql_identifier
Pluggable filter, installed by default, that makes sure the value is a valid SQL identifier.
path
Pluggable filter, installed by default, that makes sure that argument contains only Tcl word characters or a few additional safe characters used in paths ("/", ".", "-")
token
Pluggable filter, installed by default, that makes sure that argument contains only Tcl word characters or a few additional safe characters (",", ":", "-").
word
Pluggable filter, installed by default, that makes sure that argument contains only Tcl word characters (as defined by \w in Tcl regular expressions, i.e. characters, digits and underscore).
localurl
Pluggable filter, installed by default, that makes sure that argument contains a non-external url, which can be used in ad_returnredirect without throwing an error.
clock
Pluggable filter, installed by default, that makes sure that argument is a time string formatted according to the format specified in the flag. The format uses the syntax from the clock Tcl command. Usage example time:clock(%H:%M:%S).
more filters...

Note that there can be no spaces between name, colon, flags, commas, etc. The first space encountered denotes the beginning of the default value. Also, variable names can't contain commas, colons or anything Tcl accepts as list element separators (space, tab, newline, possibly others) If more than one value is specified for something that's not a multiple, a complaint will be thrown ("you supplied more than one value for foo").

There's an interface for enhancing ad_page_contract with pluggable filters, whose names can be used in place of flags (see ad_page_contract_filter). There's also an interface for pluggable filter rules, which determine what filters are applied to arguments (see ad_page_contract_filter_rule).

Note on QQ-variables: Unlike the old ad_page_variables, ad_page_contract does not set QQ-versions of variables. The QQ-versions (had each single-quote replaced by two single-quotes) were only necessary for building up SQL statements directly in a Tcl string. Now that we're using bind variables, the QQ-variables aren't necessary anymore, and thus, ad_page_contract doesn't waste time setting them.

Default Values

Default values are filled in from left to right (or top to bottom), so it can depend on the values or variables that comes before it, like in the example above. Default values are only used when the argument is not supplied, thus you can't use default values to override the empty string. (This behavior has been questioned and may have to be changed at a later point.) Also, default values are not checked, even if you've specified flags and filters. If the argument has the multiple flag specified, the default value is treated as a list. If the array flag is specified, we expect it to be in array get format, i.e. a list of { name value name value ... } pairs. If both multiple and array are set, the value elements of the before-mentioned array get format are treated as lists themselves.

Errors Argument

The -errors block defines custom error messages. The format is a list in array get format with alternating error-names and error texts. The error names can be foo, which means it's thrown when the variable is not supplied. Or foo:flag,flag,..., which means it'll get thrown whenever one of the flags fail. If you want the same error to be thrown for both not supplying a var, and for a flag, you can say foo:,flag,... (a comma immediately after the colon).

Validation Blocks

The -validate is used to fully customized user input validation. The format is a list of named chunks of code, for example:
-validate {
        name {
            code block
        }
        another_name -requires { argname[:filter-or-validation-block-name,...] ... } {
            code block
        }
    }
The name is for use with the -errors block, and for use within the -requires argument of another validation block. The validation blocks will get executed after all flags and filters have been evaluated. The code chunk should perform some validation, and if it's unhappy it should call ad_complain, optionally with an error message. If no error message is specified, the error should be declared in the -errors section.

Each validation block can also have a -requires switch, which takes a list of validations that must already have been successfully passed, for the validation to get executed. The intent is that you want to provide as much feedback as possible at once, but you don't want redundant feedback, like "foo must be an integer" and "foo must be in range 10 to 20". So a check for foo in range 10 to 20 would have a -requires { foo:integer } switch, to ensure that the check only gets executed if foo was successfully validated as an integer.

In the -requires argument, you can specify a list of (1) the name of an argument, which means that the argument must be supplied. Or (2) you can specify argname:filter or argname:validation_block to say that a given filter, flag or valdiation block must have been executed and satisfied for this validation block to get executed. You can have as many requirements as you like.

Switches:
-form
(optional)
Optionally supply the parameters directly here instead of fetching them from the page's form (ns_getform). This should be a reference to an ns_set.
-level
(defaults to "1") (optional)
-context
(optional)
-warn
(boolean) (optional)
-properties
(optional)
What properties the resulting document will contain.
Parameters:
docstring - The documentation for your page; will be parsed like ad_proc and ad_library.
Authors:
Lars Pind <lars@pinds.com>
Yonatan Feldman <yon@arsdigita.com>
Bryan Quinn <bquinn@arsdigita.com>
Created:
16 June 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_arg_parser ad_arg_parser (public) ad_complain ad_complain (public) ad_complaints_count ad_complaints_count (private) ad_complaints_get_list ad_complaints_get_list (public) ad_page_contract ad_page_contract ad_page_contract->_ ad_page_contract->ad_arg_parser ad_page_contract->ad_complain ad_page_contract->ad_complaints_count ad_page_contract->ad_complaints_get_list

Testcases:
No testcase defined.

ad_page_contract_eval (public)

 ad_page_contract_eval [ args... ]

This just uplevels its args. We need this proc, so that the return -code statements get processed correctly inside a catch block. This processing is namely done by the proc invocation.

Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

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

Testcases:
No testcase defined.

ad_page_contract_filter (public)

 ad_page_contract_filter [ -type type ] [ -priority priority ] name \
    proc_args doc_string body

Declare a filter to be available for use in ad_page_contract.

Here's an example of how to declare a filter:

    ad_page_contract_filter integer { name value } {
        Checks whether the value is a valid integer, and removes any leading zeros so as
        not to confuse Tcl into thinking it's octal
    } {
        if { ![regexp {^[0-9]+$} $value] } {
            ad_complain [_ acs-tcl.lt_Value_is_not_an_integ]
            return 0
        }
        set value [util::trim_leading_zeros $value]
        return 1
    }
    
After the filter has been declared, it can be used as a flag in ad_page_contract, e.g.
    ad_page_contract {
        foo:integer
    } {}
    
Note that there's only one global namespace for names. At some point, we might add package-local filters, but we don't have it yet.

The filter proc must return either 1 if it accepts the value or 0 if it rejects it. Any problem with the value is reported using ad_complain (see documentation for this). Note: Any modifications you make to value from inside your code block will modify the actual value being set in the page.

There are two types of filters. They differ in scope for variables that are multiple or array. The standard type of filter (filter classic) is invoked on each individual value before it's being put into the list or the array. A post filter is invoked after all values have been collected, and is invoked on the list or array as a whole.

Switches:
-type
(defaults to "filter") (optional)
The type of filter; i.e. filter or post. Default is filter.
-priority
(defaults to "1000") (optional)
Parameters:
name - The name of the flag as used in ad_page_contract
proc_args - the arguments to your filter. The filter must take three arguments, name, value, and parameters, although you can name them any way you want. The first will be set to the name of the variable, the second will be upvar'd to the value, so that any change you make to the value will be reflected in the value ultimately being set in the page's environment, and the third is a list of arguments to the filter. This third argument can have multiple parameters split by | with no spaces or any other characters. Something like foo:range(3|5)
doc_string - Standard documentation-string. Tell other programmers what your filter does.
body - The body is a procedure body that performs the filtering. It'll automatically have one argument named value set, and it must either return the possibly transformed value, or throw an error. The error message will be displayed to the user.
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_page_contract_filter_script ad_page_contract_filter_script (public) ad_page_contract_filter_type ad_page_contract_filter_type (public) ad_page_contract_filter ad_page_contract_filter ad_page_contract_filter->_ ad_page_contract_filter->ad_page_contract_filter_script ad_page_contract_filter->ad_page_contract_filter_type

Testcases:
No testcase defined.

ad_page_contract_filter_invoke (public)

 ad_page_contract_filter_invoke filter name value_varname \
    [ parameters ]

Invokes a filter on the argument and returns the result (1 or 0). The value may be modified during the invocation of the filter.

Parameters:
filter - the name of the filter to invoke
name - the logical name of the variable to filter
value_varname - the name of the variable holding the value to be filtered.
parameters (optional) - any arguments to pass to the filter
Authors:
Lars Pind <lars@pinds.com>
Yonatan Feldman <yon@arsdigita.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_invoke ad_page_contract_filter_invoke test_ad_page_contract_filters->ad_page_contract_filter_invoke ad_page_contract_filter_proc ad_page_contract_filter_proc (public) ad_page_contract_filter_invoke->ad_page_contract_filter_proc ad_page_contract_set_validation_passed ad_page_contract_set_validation_passed (private) ad_page_contract_filter_invoke->ad_page_contract_set_validation_passed

Testcases:
ad_page_contract_filters

ad_page_contract_filter_priority (public)

 ad_page_contract_filter_priority filter

Returns the type of proc that executes the given ad_page_contract filter, or the empty string if the filter is not defined.

Parameters:
filter
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

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

Testcases:
No testcase defined.

ad_page_contract_filter_proc (public)

 ad_page_contract_filter_proc filter

Returns the proc that executes the given ad_page_contract filter.

Parameters:
filter
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_aa_page_contract_filters aa_page_contract_filters (test acs-automated-testing) ad_page_contract_filter_proc ad_page_contract_filter_proc test_aa_page_contract_filters->ad_page_contract_filter_proc test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) test_ad_page_contract_filters->ad_page_contract_filter_proc

Testcases:
aa_page_contract_filters, ad_page_contract_filters

ad_page_contract_filter_proc_allhtml (public)

 ad_page_contract_filter_proc_allhtml name value_varname

Allows any html tags (a no-op filter)

Parameters:
name
value_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

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

Testcases:
No testcase defined.

ad_page_contract_filter_proc_boolean (public)

 ad_page_contract_filter_proc_boolean name value_varname

Checks whether the value is boolean (1 or 0) or predicate (t or f) or otherwise a 2 state value (true or false, y or n, yes or no)

Parameters:
name
value_varname
Author:
Randy Beggs <randyb@arsdigita.com>
Created:
23 August 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_boolean ad_page_contract_filter_proc_boolean test_ad_page_contract_filters->ad_page_contract_filter_proc_boolean _ _ (public) ad_page_contract_filter_proc_boolean->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_boolean->ad_complain

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_clock (public)

 ad_page_contract_filter_proc_clock name value_varname [ formats ]

Ensures the supplied date string is in one of the specified clock formats.

Parameters:
name
value_varname
formats (defaults to "%Y-%m-%d")
Author:
Antonio Pisano
See Also:
  • clock

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_clock ad_page_contract_filter_proc_clock ad_page_contract_filter_proc_clock->_ ad_page_contract_filter_proc_clock->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_date (public)

 ad_page_contract_filter_proc_date name date_varname

Validates date type variables

Parameters:
name
date_varname
Author:
Yonatan Feldman <yon@arsdigita.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_date ad_page_contract_filter_proc_date ad_page_contract_filter_proc_date->_ ad_page_contract_filter_proc_date->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_email (public)

 ad_page_contract_filter_proc_email name value_varname

Checks whether the value is a valid email address (stolen from philg_email_valid_p)

Parameters:
name
value_varname
Authors:
Philip Greenspun <philip@mit.edu>
Randy Beggs <randyb@arsdigita.com>
Created:
22 August 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_email ad_page_contract_filter_proc_email test_ad_page_contract_filters->ad_page_contract_filter_proc_email _ _ (public) ad_page_contract_filter_proc_email->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_email->ad_complain util_email_valid_p util_email_valid_p (public) ad_page_contract_filter_proc_email->util_email_valid_p

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_float (public)

 ad_page_contract_filter_proc_float name value_varname

Checks to make sure that the value in question is a valid number, possibly with a decimal point - randyb took this from the ACS dev bboard

Parameters:
name
value_varname
Author:
Steven Pulito <stevenp@seas.upenn.edu>
Created:
22 August 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_float ad_page_contract_filter_proc_float test_ad_page_contract_filters->ad_page_contract_filter_proc_float _ _ (public) ad_page_contract_filter_proc_float->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_float->ad_complain util::trim_leading_zeros util::trim_leading_zeros (public) ad_page_contract_filter_proc_float->util::trim_leading_zeros

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_html (public)

 ad_page_contract_filter_proc_html name value_varname

Checks whether the value contains naughty HTML

Parameters:
name
value_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_html ad_page_contract_filter_proc_html test_ad_page_contract_filters->ad_page_contract_filter_proc_html ad_complain ad_complain (public) ad_page_contract_filter_proc_html->ad_complain ad_html_security_check ad_html_security_check (public) ad_page_contract_filter_proc_html->ad_html_security_check

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_integer (public)

 ad_page_contract_filter_proc_integer name value_varname

Checks whether the value is a valid integer, and removes any leading zeros so as not to confuse Tcl into thinking it's octal. Allows negative numbers.

Parameters:
name
value_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_integer ad_page_contract_filter_proc_integer test_ad_page_contract_filters->ad_page_contract_filter_proc_integer _ _ (public) ad_page_contract_filter_proc_integer->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_integer->ad_complain util::trim_leading_zeros util::trim_leading_zeros (public) ad_page_contract_filter_proc_integer->util::trim_leading_zeros

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_localurl (public)

 ad_page_contract_filter_proc_localurl name value_varname

Checks whether the value is an acceptable (non-external) url, which can be used in ad_returnredirect without throwing an error.

Parameters:
name
value_varname
Author:
Gustaf Neumann
Created:
19 Mai 2016

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_localurl ad_page_contract_filter_proc_localurl test_ad_page_contract_filters->ad_page_contract_filter_proc_localurl _ _ (public) ad_page_contract_filter_proc_localurl->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_localurl->ad_complain util::external_url_p util::external_url_p (public) ad_page_contract_filter_proc_localurl->util::external_url_p

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_naturalnum (public)

 ad_page_contract_filter_proc_naturalnum name value_varname

Checks whether the value is a valid integer >= 0, and removes any leading zeros so as not to confuse Tcl into thinking it's octal.

Parameters:
name
value_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_naturalnum ad_page_contract_filter_proc_naturalnum test_ad_page_contract_filters->ad_page_contract_filter_proc_naturalnum _ _ (public) ad_page_contract_filter_proc_naturalnum->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_naturalnum->ad_complain

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_negative_float (public)

 ad_page_contract_filter_proc_negative_float name value_varname

Same as float but allows negative numbers too GN: this is deprecated, since "float" allows as well negative numbers

Parameters:
name
value_varname
Author:
Brian Fenton
Created:
1 December 2004

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_negative_float ad_page_contract_filter_proc_negative_float test_ad_page_contract_filters->ad_page_contract_filter_proc_negative_float _ _ (public) ad_page_contract_filter_proc_negative_float->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_negative_float->ad_complain util::trim_leading_zeros util::trim_leading_zeros (public) ad_page_contract_filter_proc_negative_float->util::trim_leading_zeros

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_nohtml (public)

 ad_page_contract_filter_proc_nohtml name value_varname

Doesn't allow any HTML to pass through.

Parameters:
name
value_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_nohtml ad_page_contract_filter_proc_nohtml test_ad_page_contract_filters->ad_page_contract_filter_proc_nohtml _ _ (public) ad_page_contract_filter_proc_nohtml->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_nohtml->ad_complain

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_object_id (public)

 ad_page_contract_filter_proc_object_id name value_varname

Checks whether the value is a valid object_id, i.e. in the range defined for the SQL datatype "integer", which is the same for Oracle and PostgreSQL. In case, object_types are altered in future versions of OpenACS to e.g. "longinteger", this function has to be adjusted as well. The function is essentially the same as ad_page_contract_filter "integer", but with the additional value range check.

Parameters:
name
value_varname
Author:
Gustaf Neumann
Created:
May 23, 2021

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_object_id ad_page_contract_filter_proc_object_id test_ad_page_contract_filters->ad_page_contract_filter_proc_object_id _ _ (public) ad_page_contract_filter_proc_object_id->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_object_id->ad_complain util::trim_leading_zeros util::trim_leading_zeros (public) ad_page_contract_filter_proc_object_id->util::trim_leading_zeros

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_object_type (public)

 ad_page_contract_filter_proc_object_type name object_id_varname types

Checks whether the supplied object_id is an acs_object of one of the types specified in the flag parameters. The check will take the object_type hierarchy into account e.g. will always succeed if one of the types is "acs_object". In this case the filter will just behave as an existence check.

Parameters:
name
object_id_varname
types

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) acs_object::is_type_p acs_object::is_type_p (private) ad_complain ad_complain (public) ad_page_contract_filter_proc_object_id ad_page_contract_filter_proc_object_id (public) ad_page_contract_filter_proc_object_type ad_page_contract_filter_proc_object_type ad_page_contract_filter_proc_object_type->_ ad_page_contract_filter_proc_object_type->acs_object::is_type_p ad_page_contract_filter_proc_object_type->ad_complain ad_page_contract_filter_proc_object_type->ad_page_contract_filter_proc_object_id

Testcases:
No testcase defined.

ad_page_contract_filter_proc_oneof (public)

 ad_page_contract_filter_proc_oneof name value_varname set

Checks whether the value is contained in the set of provided values. Example spec: w:oneof(red|green)

Parameters:
name
value_varname
set
Author:
Gustaf Neumann
Created:
Feb, 2018

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_oneof ad_page_contract_filter_proc_oneof ad_page_contract_filter_proc_oneof->_ ad_page_contract_filter_proc_oneof->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_path (public)

 ad_page_contract_filter_proc_path name value_varname

Checks whether the value is a Tcl word, or contains a few rather safe other characters ("-", "/", ".") used in (file-system) paths

Parameters:
name
value_varname
Author:
Gustaf Neumann
Created:
24 June 2015

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_path ad_page_contract_filter_proc_path ad_page_contract_filter_proc_path->_ ad_page_contract_filter_proc_path->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_phone (public)

 ad_page_contract_filter_proc_phone name value_varname

Checks whether the value is more or less a valid phone number with the area code. Specifically, area code excluding leading "1", optionally enclosed in parentheses; followed by phone number in the format xxx xxx xxxx (either spaces, periods or dashes separating the number). This filter matches the beginning of the value being checked, and considers any user input following the match as valid (to allow for extensions, etc.). Add a $ at the end of the regexp to disallow extensions. Examples:

  • (800) 888-8888 will pass
  • 800-888-8888 will pass
  • 800.888.8888 will pass
  • 8008888888 will pass
  • (800) 888-8888 extension 405 will pass
  • (800) 888-8888abcd will pass
  • "" (the empty string) will pass
  • 1-800-888-8888 will fail
  • 10-10-220 800.888.8888 will fail
  • abcd(800) 888-8888 will fail

Parameters:
name
value_varname
Author:
Randy Beggs <randyb@arsdigita.com>
Created:
August 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_phone ad_page_contract_filter_proc_phone ad_page_contract_filter_proc_phone->_ ad_page_contract_filter_proc_phone->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_printable (public)

 ad_page_contract_filter_proc_printable name value_varname

Checks whether the value contains only characters with a printable representation. This represents character class of the Tcl character class "print", which consists of the characters with a visible representation and space. This filter is useful for e.g. avoiding invalid byte sequences for the database.

Parameters:
name
value_varname
Author:
Gustaf Neumann
Created:
22 April 2021

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_printable ad_page_contract_filter_proc_printable test_ad_page_contract_filters->ad_page_contract_filter_proc_printable _ _ (public) ad_page_contract_filter_proc_printable->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_printable->ad_complain

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_range (public)

 ad_page_contract_filter_proc_range name value_varname range

Checks whether the value falls between the specified range. Range must be a list of two elements: min and max. Example spec: w:range(3|7)

Parameters:
name
value_varname
range
Author:
Yonatan Feldman <yon@arsdigita.com>
Created:
August 18, 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_script_abort ad_script_abort (public) util::trim_leading_zeros util::trim_leading_zeros (public) ad_page_contract_filter_proc_range ad_page_contract_filter_proc_range ad_page_contract_filter_proc_range->_ ad_page_contract_filter_proc_range->ad_complain ad_page_contract_filter_proc_range->ad_script_abort ad_page_contract_filter_proc_range->util::trim_leading_zeros

Testcases:
No testcase defined.

ad_page_contract_filter_proc_sql_identifier (public)

 ad_page_contract_filter_proc_sql_identifier name value_varname

Checks whether the value is a valid SQL identifier

Parameters:
name
value_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_sql_identifier ad_page_contract_filter_proc_sql_identifier test_ad_page_contract_filters->ad_page_contract_filter_proc_sql_identifier _ _ (public) ad_page_contract_filter_proc_sql_identifier->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_sql_identifier->ad_complain

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_string_length (public)

 ad_page_contract_filter_proc_string_length name value_varname length

Checks whether the string is less or greater than the minimum or maximum length specified, inclusive e.g.address_1:notnull,string_length(max|100) will test address_1 for maximum length of 100.

Parameters:
name
value_varname
length
Author:
Randy Beggs <randyb@arsdigita.com>
Created:
August 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_string_length ad_page_contract_filter_proc_string_length ad_page_contract_filter_proc_string_length->_ ad_page_contract_filter_proc_string_length->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_string_length_range (public)

 ad_page_contract_filter_proc_string_length_range name value_varname \
    range

Checks whether the string is within the specified range, inclusive

Parameters:
name
value_varname
range
Author:
Randy Beggs <randyb@arsdigita.com>
Created:
August 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_string_length_range ad_page_contract_filter_proc_string_length_range ad_page_contract_filter_proc_string_length_range->_ ad_page_contract_filter_proc_string_length_range->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_time (public)

 ad_page_contract_filter_proc_time name time_varname

Validates time type variables of the regular variety (that is 8:12:21 PM)

Parameters:
name
time_varname
Author:
Yonatan Feldman <yon@arsdigita.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_time ad_page_contract_filter_proc_time ad_page_contract_filter_proc_time->_ ad_page_contract_filter_proc_time->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_time24 (public)

 ad_page_contract_filter_proc_time24 name time_varname

Validates time type variables of the 24HR variety (that is 20:12:21)

Parameters:
name
time_varname
Author:
Yonatan Feldman <yon@arsdigita.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_time24 ad_page_contract_filter_proc_time24 ad_page_contract_filter_proc_time24->_ ad_page_contract_filter_proc_time24->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_tmpfile (public)

 ad_page_contract_filter_proc_tmpfile name value_varname

Validate a tmpfile path. This must exist, be a direct child of the configured tmpfolder in the server-wide parameter and be readable and writable by the current user. Example usage: uploaded_file.tmpfile:tmpfile,optional

Parameters:
name
value_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_log ad_log (public) security::safe_tmpfile_p security::safe_tmpfile_p (public) ad_page_contract_filter_proc_tmpfile ad_page_contract_filter_proc_tmpfile ad_page_contract_filter_proc_tmpfile->_ ad_page_contract_filter_proc_tmpfile->ad_complain ad_page_contract_filter_proc_tmpfile->ad_log ad_page_contract_filter_proc_tmpfile->security::safe_tmpfile_p

Testcases:
No testcase defined.

ad_page_contract_filter_proc_token (public)

 ad_page_contract_filter_proc_token name value_varname

Checks whether the value is a Tcl word, or contains a few rather safe other characters (".", ",", "-") used e.g. in orderby.

Parameters:
name
value_varname
Author:
Gustaf Neumann
Created:
24 June 2015

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_token ad_page_contract_filter_proc_token test_ad_page_contract_filters->ad_page_contract_filter_proc_token _ _ (public) ad_page_contract_filter_proc_token->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_token->ad_complain

Testcases:
ad_page_contract_filters

ad_page_contract_filter_proc_usphone (public)

 ad_page_contract_filter_proc_usphone name value_varname

Checks whether the value is more or less a valid US phone number with the area code. Exact filter is XXX-XXX-XXXX

Parameters:
name
value_varname
Author:
Randy Beggs <randyb@arsdigita.com>
Created:
22 August 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_complain ad_complain (public) ad_page_contract_filter_proc_usphone ad_page_contract_filter_proc_usphone ad_page_contract_filter_proc_usphone->_ ad_page_contract_filter_proc_usphone->ad_complain

Testcases:
No testcase defined.

ad_page_contract_filter_proc_word (public)

 ad_page_contract_filter_proc_word name value_varname

Checks whether the value is a Tcl word, i.e. it consists of just characters, digits and underscore.

Parameters:
name
value_varname
Author:
Gustaf Neumann
Created:
24 June 2015

Partial Call Graph (max 5 caller/called nodes):
%3 test_ad_page_contract_filters ad_page_contract_filters (test acs-tcl) ad_page_contract_filter_proc_word ad_page_contract_filter_proc_word test_ad_page_contract_filters->ad_page_contract_filter_proc_word _ _ (public) ad_page_contract_filter_proc_word->_ ad_complain ad_complain (public) ad_page_contract_filter_proc_word->ad_complain

Testcases:
ad_page_contract_filters

ad_page_contract_filter_rule (public)

 ad_page_contract_filter_rule name proc_args doc_string body

A filter rule determines what filters are applied to a given value. The code is passed the name of the formal argument and the list of filters currently being applied, and should on that basis modify the list of filters to suit its needs. Usually, a filter rule will add a certain filter, unless some list of filters are already present.

Unlike the filters themselves (registered with ad_page_contract_filter), all rules are always applied to all formal arguments of all pages.

Parameters:
name - filter rules must be named. The name isn't referred to anywhere.
proc_args - the filter rule proc must take two arguments, name and filters, although you can name them as you like. The first will be set to the name of the formal argument, the second will be upvar'd to the list of filters, so that any modifications you make to this list are reflected in the actual list of filters being applied.
doc_string - let other programmers know what your filter rule does.
body - the code to manipulate the filter list.
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

Partial Call Graph (max 5 caller/called nodes):
%3 _ _ (public) ad_page_contract_filter_rule_script ad_page_contract_filter_rule_script (public) ad_page_contract_filter_rule ad_page_contract_filter_rule ad_page_contract_filter_rule->_ ad_page_contract_filter_rule->ad_page_contract_filter_rule_script

Testcases:
No testcase defined.

ad_page_contract_filter_rule_proc (public)

 ad_page_contract_filter_rule_proc filter

Returns the proc that executes the given ad_page_contract default-filter.

Parameters:
filter

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

Testcases:
No testcase defined.

ad_page_contract_filter_rule_proc_html (public)

 ad_page_contract_filter_rule_proc_html name filters_varname

Makes sure the filter nohtml gets applied, unless some other html filter (html or allhtml) is already specified.

Parameters:
name
filters_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

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

Testcases:
No testcase defined.

ad_page_contract_filter_rule_proc_tmpfile (public)

 ad_page_contract_filter_rule_proc_tmpfile name filters_varname

Makes sure the tmpfile filter gets applied for all vars named *.tmpfile.

Parameters:
name
filters_varname
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

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

Testcases:
No testcase defined.

ad_page_contract_filter_rule_script (public)

 ad_page_contract_filter_rule_script filter

Returns the proc that executes the given ad_page_contract default-filter.

Parameters:
filter

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

Testcases:
No testcase defined.

ad_page_contract_filter_script (public)

 ad_page_contract_filter_script filter

Returns the type of proc that executes the given ad_page_contract filter, or the empty string if the filter is not defined.

Parameters:
filter
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

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

Testcases:
No testcase defined.

ad_page_contract_filter_type (public)

 ad_page_contract_filter_type filter

Returns the type of proc that executes the given ad_page_contract filter, or the empty string if the filter is not defined.

Parameters:
filter
Author:
Lars Pind <lars@pinds.com>
Created:
25 July 2000

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

Testcases:
No testcase defined.

ad_page_contract_get_variables (public)

 ad_page_contract_get_variables

Returns a list of all the formal variables specified in ad_page_contract. If no variables have been specified, returns an empty list.

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

Testcases:
No testcase defined.

ad_page_contract_handle_datasource_error (public)

 ad_page_contract_handle_datasource_error error

Output a diagnostic page. Treats both special and generic error messages.

Parameters:
error
Author:
Christian Brechbuehler
Created:
13 Aug 2000

Partial Call Graph (max 5 caller/called nodes):
%3 ad_parse_template ad_parse_template (public) parameter::get_from_package_key parameter::get_from_package_key (public) util::get_referrer util::get_referrer (public) ad_page_contract_handle_datasource_error ad_page_contract_handle_datasource_error ad_page_contract_handle_datasource_error->ad_parse_template ad_page_contract_handle_datasource_error->parameter::get_from_package_key ad_page_contract_handle_datasource_error->util::get_referrer

Testcases:
No testcase defined.

ad_page_contract_verify_datasources (public)

 ad_page_contract_verify_datasources

Check if all the datasources (properties) promised in the page contract have actually been set.

Author:
Christian Brechbuehler
Created:
13 Aug 2000

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

Testcases:
No testcase defined.

api_page_documentation_mode_p (public)

 api_page_documentation_mode_p

Determines whether the thread is in "gathering documentation" or "executing the page" mode.

Returns:
true if the thread is in "gathering documentation" mode, or false otherwise.
See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 test_link_tests link_tests (test xowiki) api_page_documentation_mode_p api_page_documentation_mode_p test_link_tests->api_page_documentation_mode_p test_package_normalize_path package_normalize_path (test xowiki) test_package_normalize_path->api_page_documentation_mode_p test_path_resolve path_resolve (test xowiki) test_path_resolve->api_page_documentation_mode_p test_slot_interactions slot_interactions (test xowiki) test_slot_interactions->api_page_documentation_mode_p test_xowiki_test_cases xowiki_test_cases (test xowiki) test_xowiki_test_cases->api_page_documentation_mode_p

Testcases:
package_normalize_path, xowiki_test_cases, link_tests, slot_interactions, path_resolve

doc_set_page_documentation_mode (public)

 doc_set_page_documentation_mode page_documentation_mode_p

Set a flag in the environment determining whether the thread is in "gathering documentation" or "executing the page" mode.

Parameters:
page_documentation_mode_p - true to set the "gathering documentation" flag, or false to clear it.
See Also:

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

Testcases:
No testcase defined.

template::csrf::validate (public)

 template::csrf::validate [ -package_id package_id ]

validate a csrf token

Switches:
-package_id
(optional)
Author:
Gustaf Neumann
Created:
Feb 2, 2017

Partial Call Graph (max 5 caller/called nodes):
%3 ad_conn ad_conn (public) parameter::get parameter::get (public) security::csrf::validate security::csrf::validate (public) template::csrf::validate template::csrf::validate template::csrf::validate->ad_conn template::csrf::validate->parameter::get template::csrf::validate->security::csrf::validate

Testcases:
No testcase defined.
[ show source ]