lang::message::format (public)

 lang::message::format localized_message [ value_array_list ] \
    [ upvar_level ]

Defined in packages/acs-lang/tcl/lang-message-procs.tcl

Substitute all occurencies of %array_key% in the given localized message with the value from a lookup in the value_array_list with array_key (what's between the percentage sings). If value_array_list is not provided then attempt to fetch variable values the number of levels up given by upvar_level (defaults to 3 because this proc is typically invoked from the underscore lookup proc). Here is an example: set localized_message "The %animal% jumped across the %barrier%. About 50% of the time, he stumbled, or maybe it was %%20 %times%." set value_list { animal "frog" barrier "fence" } ns_log notice formatted=[format $localized_message $value_list] The output from the example is: The frog jumped across the fence. About 50% of the time, he stumbled, or maybe it was %20 %times%.

Parameters:

localized_message
value_array_list (optional)
upvar_level (defaults to "3")

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

Testcases:

message__format

Source code:

    if {[llength $value_array_list] % 2 != 0} {
        ad_log error "Invalid value_array_list passed in: <$value_array_list>"
    }

    array set value_array $value_array_list
    set value_array_keys [array names value_array]
    set remaining_message $localized_message
    set formatted_message ""
    while { [regexp [embedded_vars_regexp] $remaining_message match before_percent percent_match remaining_message] } {

        append formatted_message $before_percent

        if {$percent_match eq "%%"} {
            # A quoted percent sign
            append formatted_message "%"
        } else {
            set variable_string [string range $percent_match 1 end-1]

            if { [llength $value_array_list] > 0 } {
                # A substitution list is provided, the key should be in there

                if {$variable_string ni $value_array_keys} {
                    ns_log Warning "lang::message::format: The value_array_list"  "\"$value_array_list\" does not contain the variable name"  "$variable_string found in the message: $localized_message"

                    # There is no value available to do the substitution with
                    # so don't substitute at all
                    append formatted_message $percent_match
                } else {
                    # Do the substitution
                    append formatted_message $value_array($variable_string)
                }
            } else {
                regexp {^([^.]+)(?:\.([^.]+))?$} $variable_string match variable_name array_key

                # No substitution list provided - attempt to fetch variable value
                # from scope calling lang::message::lookup
                upvar $upvar_level $variable_name local_variable

                if { [info exists local_variable] } {
                    if { ![info exists array_key] || $array_key eq "" } {
                        # Normal Tcl variable
                        append formatted_message $local_variable
                    } else {
                        # Array variable
                        append formatted_message $local_variable($array_key)
                    }
                } else {
                    ns_log warning "Message contains a variable named '$variable_name' "  "which doesn't exist in the caller's environment: message $localized_message"
                    append formatted_message "MISSING: variable '$variable_name' is not available"
                }
            }
        }
    }

    # Append text after the last match
    append formatted_message $remaining_message

    return $formatted_message

Generic XQL file:

packages/acs-lang/tcl/lang-message-procs.xql

PostgreSQL XQL file:

packages/acs-lang/tcl/lang-message-procs-postgresql.xql

Oracle XQL file:

packages/acs-lang/tcl/lang-message-procs-oracle.xql