Index: openacs-4/packages/acs-templating/tcl/util-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/util-procs.tcl,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-templating/tcl/util-procs.tcl 13 Aug 2002 16:45:49 -0000 1.6
+++ openacs-4/packages/acs-templating/tcl/util-procs.tcl 1 Sep 2002 02:24:57 -0000 1.7
@@ -13,17 +13,15 @@
namespace eval template::util {}
namespace eval template::query {}
-# @public get_opts
-
-# Builds an array named "opts" in the calling frame, containing all
-# switches passed at the end of a proc. The array values are either
-# switch parameters or 1 if no parameter was specified.
-
-# Problem: there is currently no way to specify an option parameter that
-# begins with a dash. This particularly problematic for negative numbers.
-
ad_proc -public template::util::get_opts { argv } {
+ Builds an array named "opts" in the calling frame, containing all
+ switches passed at the end of a proc. The array values are either
+ switch parameters or 1 if no parameter was specified.
+ Problem: there is currently no way to specify an option parameter that
+ begins with a dash. This particularly problematic for negative numbers.
+} {
+
upvar opts opts
set size [llength $argv]
@@ -59,17 +57,15 @@
# * Utility procedures for manipulating lists, arrays and ns_sets *
# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-# @public list_opts
+ad_proc -public template::util::list_opts { {array_ref opts} } {
+ Converts an array to an option list
-# Converts an array to an option list
+ @param array_ref The name of the array in the calling frame containing
+ option-value pairs. Defaults to "opts".
-# @param array_ref The name of the array in the calling frame containing
-# option-value pairs. Defaults to "opts".
+ @return A list of option-value pairs suitable for appending to a command.
+} {
-# @return A list of option-value pairs suitable for appending to a command.
-
-ad_proc -public template::util::list_opts { {array_ref opts} } {
-
upvar $array_ref arr
set ret [list]
@@ -80,17 +76,15 @@
return $ret
}
-# @public is_nil
+ad_proc -public template::util::is_nil { ref } {
+ Determines whether a variable both exists and is not an empty string.
-# Determines whether a variable both exists and is not an empty string.
+ @param ref The name of a variable to test in the calling frame.
-# @param ref The name of a variable to test in the calling frame.
+ @return 1 if the variable either not exist or is an empty string. 0 if
+ the variable is either an array reference or a non-empty scalar.
+} {
-# @return 1 if the variable either not exist or is an empty string. 0 if
-# the variable is either an array reference or a non-empty scalar.
-
-ad_proc -public template::util::is_nil { ref } {
-
upvar $ref var
# check for an array as well
@@ -104,20 +98,18 @@
return $result
}
-# @public is_unique
+ad_proc -public template::util::is_unique { table columns values } {
+ Queries a database table for the existence of a particular row.
+ Useful for validating form input to reduce the possibility of
+ unique constraint violations.
-# Queries a database table for the existence of a particular row.
-# Useful for validating form input to reduce the possibility of
-# unique constraint violations.
+ @param table The name of a database table.
+ @param columns A list of columns on which to select the row.
+ @param values A list of values for each specified column.
-# @param table The name of a database table.
-# @param columns A list of columns on which to select the row.
-# @param values A list of values for each specified column.
+ @return 1 if the row exists, 0 if not
+} {
-# @return 1 if the row exists, 0 if not
-
-ad_proc -public template::util::is_unique { table columns values } {
-
set query "select count(*) from $table where "
for { set i 0 } { $i < [llength $columns] } { incr i } {
@@ -133,44 +125,43 @@
return [expr $count == 0]
}
+ad_proc -public template::util::is_true { x } {
+ interprets its argument as a boolean.
-# @public is_true
+ @param x the value to test
-# interprets its argument as a boolean.
-
-# @param x the value to test
-
-# @return 0 if the variable can be interpreted as false; 1 for true if it can't.
-
-ad_proc -public template::util::is_true { x } {
+ @return 0 if the variable can be interpreted as false;
+ 1 for true if it can't.
+} {
expr [lsearch -exact {0 f false n no off ""} [string tolower $x]] == -1
}
# @public lpop
-# Removes the last item from a list. The operation is performed
-# in-place, rather than returning the new list.
-# @param ref The name of a list in the calling frame on which to operate.
-
ad_proc -public template::util::lpop { ref } {
+ Removes the last item from a list. The operation is performed
+ in-place, rather than returning the new list.
+ @param ref The name of a list in the calling frame on which to operate.
+} {
+
upvar $ref the_list
set the_list [lrange $the_list 0 [expr [llength $the_list] - 2]]
}
-# Recursive procedure for building a hierarchical or multidimensional
-# data structure in a list.
-
-# @param value Either a list or scalar value to store in the list.
-# @param next A key value that determines the next node to
-# traverse outward in the data structure.
-# @param args Subsequent nodes to traverse.
-
ad_proc -public template::util::lnest { listref value next args } {
+ Recursive procedure for building a hierarchical or multidimensional
+ data structure in a list.
+ @param value Either a list or scalar value to store in the list.
+ @param next A key value that determines the next node to
+ traverse outward in the data structure.
+ @param args Subsequent nodes to traverse.
+} {
+
upvar $listref inlist
if { ! [info exists inlist] } {
set inlist [list]
@@ -225,19 +216,17 @@
set inlist [array get values]
}
-# @public set_to_list
+ad_proc -public template::util::set_to_list { set args } {
+ Turns an ns_set into a key-value list, excluding any number of
+ specified keys. Useful for turning the contents on an ns_set into
+ a form that may be cached or manipulated as a native Tcl data structure.
-# Turns an ns_set into a key-value list, excluding any number of
-# specified keys. Useful for turning the contents on an ns_set into
-# a form that may be cached or manipulated as a native Tcl data structure.
+ @param set A reference to an ns_set.
+ @param args Any number of key names to exclude from the list.
-# @param set A reference to an ns_set.
-# @param args Any number of key names to exclude from the list.
+ @return A list in the form { key value key value key value ... }
+} {
-# @return A list in the form { key value key value key value ... }
-
-ad_proc -public template::util::set_to_list { set args } {
-
set result [list]
for { set i 0 } { $i < [ns_set size $set] } { incr i } {
@@ -251,15 +240,13 @@
return $result
}
-# @public set_to_vars
-
-# Declare local variables for set values
-
-# @param set A reference to an ns_set.
-# @param args Any number of keys to declare as local variables.
-
ad_proc -public template::util::set_to_vars { set args } {
+ Declare local variables for set values
+ @param set A reference to an ns_set.
+ @param args Any number of keys to declare as local variables.
+} {
+
if { [llength $args] == 0 } {
for { set i 0 } { $i < [ns_set size $set] } { incr i } {
@@ -277,30 +264,25 @@
}
}
-# @public array_to_vars
-
-# Declare local variables for every key in an array.
-
-# @param arrayname The name of an array in the calling frame.
-
ad_proc -public template::util::array_to_vars { arrayname } {
+ Declare local variables for every key in an array.
+ @param arrayname The name of an array in the calling frame.
+} {
+
upvar $arrayname arr
foreach { key value } [array get arr] {
uplevel "set \{${key}\} \{$value\}"
}
}
-# @public vars_to_array
-
-# Place local variables into an array
-
-# @param arrayname The name of an array in the calling frame.
-# @param args Any number of local variables to include in the array
-
ad_proc -public template::util::vars_to_array { arrayname args } {
+ Place local variables into an array
+ @param arrayname The name of an array in the calling frame.
+ @param args Any number of local variables to include in the array
+} {
upvar $arrayname arr
foreach var $args {
@@ -309,19 +291,17 @@
}
}
-# @public list_to_array
-
-# Converts a list of values into an array, using a list of
-# corresponding column names for the array keys.
-
-# @param values A list of values
-# @param array_ref The name of the array to create in the calling frame.
-# @param columns A list of column names to use for the array keys.
-# The length of this list should be the same as the values
-# list.
-
ad_proc -public template::util::list_to_array { values array_ref columns } {
+ Converts a list of values into an array, using a list of
+ corresponding column names for the array keys.
+ @param values A list of values
+ @param array_ref The name of the array to create in the calling frame.
+ @param columns A list of column names to use for the array keys.
+ The length of this list should be the same as the values
+ list.
+} {
+
upvar $array_ref array
for { set i 0 } { $i < [llength $values] } { incr i } {
@@ -333,12 +313,10 @@
}
}
-# @public list_of_lists_to_array
-
-# Converts a list of lists in the form { { key value } { key value } ... }
-# to an array.
-
ad_proc -public template::util::list_of_lists_to_array { lists array_ref } {
+ Converts a list of lists in the form { { key value } { key value } ... }
+ to an array.
+} {
upvar $array_ref array
@@ -351,17 +329,14 @@
}
}
-# @public list_to_lookup
-
-# Turn a list into an array where each key corresponds to an element
-# of the list... Sort of like a sparse bitmap. Each value corresponds
-# to the key's position in the input list.
-
-# @param values A list of values
-# @param array_ref The name of the array to create in the calling frame.
-
ad_proc -public template::util::list_to_lookup { values array_ref } {
-
+ Turn a list into an array where each key corresponds to an element
+ of the list... Sort of like a sparse bitmap. Each value corresponds
+ to the key's position in the input list.
+
+ @param values A list of values
+ @param array_ref The name of the array to create in the calling frame.
+} {
upvar $array_ref array
set i 1
@@ -372,11 +347,18 @@
}
}
-# Return a representation of a multirow data source as a list,
-# suitable for passing by value in the form { { row } { row } { row } ... }
ad_proc -public template::util::multirow_to_list { name } {
+ generate a list structure representitive of a multirow data source
+ @param name the name of an existing multirow data source
+
+ @return a representation of a multirow data source as a list,
+ suitable for passing by value in the form { { row } { row } { row } ... }
+
+ @see proc template::util::list_to_multirow
+} {
+
upvar $name:rowcount rowcount
set rows [list]
@@ -391,7 +373,16 @@
}
ad_proc -public template::util::list_to_multirow { name rows { level 1 } } {
+ populate a multirow data source from a list string gotten from
+ a call to template::util::multirow_to_list
+ @param name the name of a multirow data source
+ @param rows a representation of a multirow data source as a list,
+ suitable for passing by value in the form { { row } { row } { row } ... }
+
+ @see proc template::util::multirow_to_list
+} {
+
upvar $level $name:rowcount rowcount
set rowcount [llength $rows]
set rownum 1
@@ -434,32 +425,28 @@
# * Utility procedures for interacting with the file system *
# * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-# @public read_file
+ad_proc -public template::util::read_file { path } {
+ Reads a text file.
-# Reads a text file.
+ @param path The absolute path to the file
-# @param path The absolute path to the file
+ @return A string with the contents of the file.
+} {
-# @return A string with the contents of the file.
-
-ad_proc -public template::util::read_file { path } {
-
set fd [open $path]
set text [read $fd]
close $fd
return $text
}
-# @public write_file
-
-# Writes a text file
-
-# @param path The absolute path to the file
-# @param text A string containing the text to write to the file.
-
ad_proc -public template::util::write_file { path text } {
+ Writes a text file
+ @param path The absolute path to the file
+ @param text A string containing the text to write to the file.
+} {
+
file mkdir [file dirname $path]
set fd [open $path w]
@@ -469,9 +456,10 @@
# @public url_to_file
-# Resolve a URL into an absolute file path.
ad_proc -public template::util::url_to_file { url {reference_url ""} } {
+ Resolve a URL into an absolute file path.
+} {
if { [string index $url 0] != "/" } {
@@ -485,12 +473,9 @@
return [ns_normalizepath $path]
}
-# @public resolve_directory_url
-
-# Resolve the file name for a directory URL
-
ad_proc -public template::util::resolve_directory_url { url } {
-
+ Resolve the file name for a directory URL
+} {
set path [ns_info pageroot]$url
if { [file isdirectory $path] && [file exists ${path}index.adp] } {
@@ -500,13 +485,10 @@
return $url
}
-# @public get_url_directory
-
-# Get the directory portion of a URL. If the URL has a trailing
-# slash, then return the entire URL.
-
ad_proc -public template::util::get_url_directory { url } {
-
+ Get the directory portion of a URL. If the URL has a trailing
+ slash, then return the entire URL.
+} {
set directory $url
set lastchar [string range $url [expr [string length $url]-1] end]
@@ -524,13 +506,10 @@
return $directory
}
-# @public get_cookie
-
-# Retrieve the value of a cookie and return it
-# Return the default if no such cookie exists
-
ad_proc -public template::util::get_cookie { name {default_value ""} } {
-
+ Retrieve the value of a cookie and return it
+ Return the default if no such cookie exists
+} {
set headers [ns_conn headers]
set cookie [ns_set iget $headers Cookie]
@@ -542,13 +521,11 @@
return $default_value
}
-# @public set_cookie
-
-# Create a cookie with specified parameters. The expiration state
-# may be persistent, session, or a number of minutes from the current
-# time.
-
ad_proc -public template::util::set_cookie { expire_state name value { domain "" } } {
+ Create a cookie with specified parameters. The expiration state
+ may be persistent, session, or a number of minutes from the current
+ time.
+} {
if { [string match $domain {}] } {
set path "ns/server/[ns_info server]/module/nssock"
@@ -577,12 +554,9 @@
ns_set put [ns_conn outputheaders] "Set-Cookie" $cookie
}
-# @public clear_cookie
-
-# Expires an existing cookie.
-
ad_proc -public template::util::clear_cookie { name { domain "" } } {
-
+ Expires an existing cookie.
+} {
if { [string match $domain {}] } {
set path "ns/server/[ns_info server]/module/nssock"
set domain [ns_config $path Hostname]
@@ -601,16 +575,15 @@
return $html
}
+ad_proc -public template::util::multirow_quote_html {multirow_ref column_ref} {
+ implements template::util::quote_html on the designated column of a multirow
-# @public multirow_quote_html
-# implements template::util::quote_html on the designated column of a multirow
+ @param multirow_ref name of the multirow
+ @param column_ref name of the column to be
-# @param multirow_ref name of the multirow
-# @param column_ref name of the column to be
+ @author simon
+} {
-# @author simon
-
-ad_proc -public template::util::multirow_quote_html {multirow_ref column_ref} {
upvar $multirow_ref:rowcount rowcount
for { set i 1 } { $i <= $rowcount } { incr i} {
@@ -621,21 +594,27 @@
}
-# @public multirow_foreach
-# runs a block of code foreach row in a multirow
+ad_proc -public template::util::multirow_foreach { name code_text } {
+ runs a block of code foreach row in a multirow
-# @param name the name of the multirow over which the block of code is iterated
-# @param code_text the block of code in the for loop; this block can reference
-# any of the columns belonging to the multirow specified; with the multirow
-# named "fake_multirow" containing columns named "spanky" and "foobar",to set the column
-# spanky to the value of column foobar use:
-# set fake_multirow.spanky @fake_multirow.foobar@
-# note: this block of code is evaluated in the same scope as the .tcl page that uses
-# this procedure
+ @param name the name of the multirow over which the block of
+ code is iterated
-# @author simon
+ @param code_text the block of code in the for loop; this block can
+ reference any of the columns belonging to the
+ multirow specified; with the multirow named
+ "fake_multirow" containing columns named "spanky"
+ and "foobar",to set the column spanky to the value
+ of column foobar use:
+ set fake_multirow.spanky
+ @fake_multirow.foobar@
+
+ note: this block of code is evaluated in the same
+ scope as the .tcl page that uses this procedure
-ad_proc -public template::util::multirow_foreach { name code_text } {
+ @author simon
+} {
+
upvar $name:rowcount rowcount $name:columns columns i i
upvar running_code running_code
@@ -660,15 +639,11 @@
}
-
-
-# @public get_param
-
-# Retreive a stored parameter, or "" if no such parameter
-# If section/key are present, read the parameter from the specified
-# section.key in the INI file, and cache them under the given name
-
ad_proc -public template::util::get_param { name {section {}} {key {}} } {
+ Retreive a stored parameter, or "" if no such parameter
+ If section/key are present, read the parameter from the specified
+ section.key in the INI file, and cache them under the given name
+} {
if { ![nsv_exists __template_config $name] } {
@@ -698,45 +673,39 @@
}
}
-# @public set_param
-
-# Set a stored parameter
-
ad_proc -public template::util::set_param { name value } {
+ Set a stored parameter
+} {
nsv_set __template_config $name $value
}
-# @public nvl
-
-# Analogous to SQL NVL
-
ad_proc -public template::util::nvl { value value_if_null } {
+ Analogous to SQL NVL
+} {
+
if { [template::util::is_nil value] } {
return $value_if_null
} else {
return $value
}
}
-# @public number_list
-
-# Return a list of numbers, {1 2 3 ... n}
-
ad_proc -public template::util::number_list { last_number {start_at 0} } {
+ Return a list of numbers, {1 2 3 ... n}
+} {
+
set ret [list]
for {set i $start_at} { $i <= $ret } {incr i} {
lappend ret $i
}
return $ret
}
-
-# @public tcl_to_sql_list
-
-# Convert a TCL list to a SQL list, for use with the "in" statement
-# why doesn't this use ns_dbquotevalue?
-
ad_proc -public template::util::tcl_to_sql_list { lst } {
+ Convert a TCL list to a SQL list, for use with the "in" statement
+ why doesn't this use ns_dbquotevalue?
+} {
+
if { [llength $lst] > 0 } {
set sql "'"
append sql [join $lst "', '"]
@@ -749,16 +718,19 @@
-# Get the template directory
-# The body is doublequoted, so it is interpreted when this file is read
-ad_proc -public template::get_resource_path {} "
+ad_proc -public template::get_resource_path {} {
+ Get the template directory
+ The body is doublequoted, so it is interpreted when this file is read
+} "
return \"[file dir [file dir [info script]]]/resources\"
"
-# return the variables and arrays of one frame as HTML
ad_proc -public stack_frame_values {level} {
+ return the variables and arrays of one frame as HTML
+} {
+
set varlist ""
foreach i [if $level {
uplevel \#$level {info locals}
@@ -788,8 +760,9 @@
-# return the whole call stack as HTML
ad_proc -public stack_dump {} {
+ return the whole call stack as HTML
+} {
append page "
Tcl Call Trace