- Publicity: Public Only All
parse-procs.tcl
ADP to Tcl Compiler for the ArsDigita Templating System,
- Location:
- packages/acs-templating/tcl/parse-procs.tcl
- Authors:
- Karl Goldstein
- Stanislav Freidin
- Jon Salz
- CVS Identification:
$Id: parse-procs.tcl,v 1.67 2024/09/11 06:15:48 gustafn Exp $
Procedures in this file
- template::adp_abort (public)
- template::adp_append_code (public)
- template::adp_array_variable_regexp (public)
- template::adp_array_variable_regexp_literal (public)
- template::adp_array_variable_regexp_noi18n (public)
- template::adp_array_variable_regexp_noquote (public)
- template::adp_compile (public)
- template::adp_compile_chunk (public)
- template::adp_eval (public)
- template::adp_include (public)
- template::adp_init (public)
- template::adp_level (public)
- template::adp_levels (public, deprecated)
- template::adp_parse (public)
- template::adp_parse_tags (public)
- template::adp_variable_regexp (public)
- template::adp_variable_regexp_literal (public)
- template::adp_variable_regexp_noi18n (public)
- template::adp_variable_regexp_noquote (public)
- template::expand_percentage_signs (public)
- template::get_attribute (public)
- template::set_file (public)
Detailed information
template::adp_abort (public)
template::adp_abort
Terminates processing of a template and throws away all output.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::adp_append_code (public)
template::adp_append_code code [ nobreak ]
Adds a line of code to the Tcl output from the compiler. Called by basically any adp custom tag implementation and also from developer support.
- Parameters:
- Options:
- code (required)
- A line of Tcl code
- nobreak (optional)
- -nobreak
- Flag indicating that code should be appended to the current last line rather than adding a new line, for cases where code must continue on the same line, such as the "else" tag.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_widget_file, adp_parse_tags
template::adp_array_variable_regexp (public)
template::adp_array_variable_regexp
The regexp pattern used to find adp array variables in a piece of text (i.e. @array_name.variable_name@). Captures the character preceding the first @ in \1, the array_name in \2, and variable_name in \3
- Author:
- Peter Marklund <peter@collaboraid.biz>
- Created:
- 25 October 2002
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::adp_array_variable_regexp_literal (public)
template::adp_array_variable_regexp_literal
adp_array_variable_regexp's pattern augmented by "literal"
- Author:
- Gustaf Neumann
- Created:
- December 2012
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::adp_array_variable_regexp_noi18n (public)
template::adp_array_variable_regexp_noi18n
adp_array_variable_regexp's pattern augmented by "noi18n"
- Author:
- Gustaf Neumann
- Created:
- June 2015
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::adp_array_variable_regexp_noquote (public)
template::adp_array_variable_regexp_noquote
adp_array_variable_regexp's pattern augmented by "noquote"
- Author:
- Dirk Gomez <openacs@dirkgomez.de>
- Created:
- 12 February 2003
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::adp_compile (public)
template::adp_compile [ -file file ] [ -string string ]
Converts an ADP template into a chunk of Tcl code. Caching this code avoids the need to reparse the ADP template with each request.
- Switches:
- -file (optional)
- The filename of the source
- -string (optional)
- string to be compiled
- Returns:
- The compiled code. Valid options are either -string or -file
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_dimensional, template_widget_file, xowiki_test_cases
template::adp_compile_chunk (public)
template::adp_compile_chunk chunk
Parses a single chunk of a template. A chunk is either the entire template or the portion of a template contained within a balanced tag. This procedure does not return the compiled chunk; compiled code is assembled in the template::parse_list variable.
- Parameters:
- chunk (required)
- A string containing markup, potentially with embedded ADP tags.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- adp_parse_tags
template::adp_eval (public)
template::adp_eval coderef
Evaluates a chunk of compiled template code in the calling stack frame. The resulting output is placed in __adp_output in the calling frame, and also returned for convenience.
- Parameters:
- coderef (required)
- Returns:
- The output produced by the compiled template code.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_dimensional, template_widget_file, xowiki_test_cases
template::adp_include (public)
template::adp_include [ -uplevel uplevel ] src varlist
return the output of a Tcl/ADP pair as a string. adp_level is set to the calling procedure so that pass by reference works. and example of using this is in the search indexer for various content types:
bookshelf::book::get -book_id $book_id -array bookdata set body [template::adp_include /packages/bookshelf/lib/one-book [list &book "bookdata" base $base style feed]]The [list &book "bookdata" ...] tells adp_include to pass the book array by reference to the adp include, where it is referred to via @book.field@.
- Switches:
- -uplevel (optional, defaults to
"1"
)- how far up the stack should the adp_level be set to (default is the calling procedures level)
- Parameters:
- src (required)
- should be the path to the Tcl/ADP pair relative to the server root, as with the src attribute to the include tag.
- varlist (required)
- a list of {key value key value ... } varlist can also be &var foo for things passed by reference (arrays and multirows)
- Returns:
- the string generated by the Tcl/ADP pair.
- Author:
- Jeff Davis davis@xarg.net
- Created:
- 2004-06-02
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- page_contracts, templates_and_scripts
template::adp_init (public)
template::adp_init type file_stub
Ensures that both data source Tcl files and compiled ADP templates are wrapped in procedures in the current interpreter. Procedures are cached in byte code form in the interpreter, so this is more efficient than sourcing a Tcl file or parsing the template every time. Also checks the modification time on the source file to ensure that the procedure is up-to-date.
- Parameters:
- type (required)
- Either ADP (template) or Tcl (code)
- file_stub (required)
- The root (sans file extension) of the absolute path to the .adp or .tcl file to source.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- callgraph__bad_page_calls
template::adp_level (public)
template::adp_level [ up ]
Get the stack frame level at which the template is being evaluated. This is used extensively for obtaining references to data sources, as well template objects such as forms and wizards
- Parameters:
- up (optional)
- A relative reference to the "parse level" of interest. Useful in the context of an included template to reach into the stack frame in which the container template is being parsed, for accessing data sources or other objects. The default is the highest parse level.
- Returns:
- A number, as returned by [info level], representing the stack frame in which a template is being parsed.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- adp_level
template::adp_levels (public, deprecated)
template::adp_levels
Deprecated. Invoking this procedure generates a warning.
- Returns:
- all stack frame levels
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::adp_parse (public)
template::adp_parse __adp_stub __args
Execute procedures to prepare data sources and then to output template. Assumes adp_level is set on entry. in general the public version template::adp_include should be used for generating strings from adp files.
- Parameters:
- __adp_stub (required)
- The root (without the file extension) of the absolute path to the template and associated code.
- __args (required)
- One list containing any number of key-value pairs passed to an included template from its container. All data sources may be passed by reference.
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- xowiki_test_cases
template::adp_parse_tags (public)
template::adp_parse_tags HTML
Parse the tags of the provided HTML text. This function is similar to
template::adp_compile -string $HTMLbut it just performs tag substitution, but not ADP variable substitution, since this is done differently in some contextes on the provided HTML chunk. An example for specialized handling is the handling of instance attributes in xowiki.
- Parameters:
- HTML (required)
- text containing potentially ADP tags
- Returns:
- HTML text with substituted ADP tags
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- adp_parse_tags
template::adp_variable_regexp (public)
template::adp_variable_regexp
The regexp pattern used to find adp variables in a piece of text, i.e. occurrences of @variable_name@. Captures the character preceding the first @ in \1 and the variable_name in \2.
- Author:
- Peter Marklund <peter@collaboraid.biz>
- Created:
- 25 October 2002
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::adp_variable_regexp_literal (public)
template::adp_variable_regexp_literal
adp_variable_regexp augmented by "literal"
- Author:
- Gustaf Neumann
- Created:
- December 2012
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::adp_variable_regexp_noi18n (public)
template::adp_variable_regexp_noi18n
adp_variable_regexp augmented by "noi18n"
- Author:
- Gustaf Neumann
- Created:
- June 2015
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::adp_variable_regexp_noquote (public)
template::adp_variable_regexp_noquote
adp_variable_regexp augmented by "noquote"
- Author:
- Dirk Gomez <openacs@dirkgomez.de>
- Created:
- 12 February 2003
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- template_variable
template::expand_percentage_signs (public)
template::expand_percentage_signs message
Expand variables marked with percentage signs in caller's scope. Some examples - if example and array(variable) has the values Erik and Oluf in the caller's scope - the following expansion will occur: Here is an %example% variable. -> Here is an Erik variable. Here is an %array.variable% for you -> Here is an Oluf for you
- Parameters:
- message (required)
- Author:
- Christian Hvid
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- expand_percentage_signs
template::get_attribute (public)
template::get_attribute tag params name [ default ]
Retrieves a named attribute value from the parameter set passed to a tag handler. If a default is not specified, assumes the attribute is required and throws an error.
- Parameters:
- tag (required)
- The name of the tag.
- params (required)
- The ns_set passed to the tag handler.
- name (required)
- The name of the attribute.
- default (optional, defaults to
"ERROR"
)- A default value to return if the attribute is not specified in the template. A default value of "ERROR" will cause the proc to throw an error if the attribute wasn't supplied.
- Returns:
- The value of the attribute.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
template::set_file (public)
template::set_file path
Set the path of the template to render. This is typically used to implement multiple "skins" on a common set of data sources. The initial code (which may be in a .tcl file not associated with a .adp file) sets up any number of data sources, and then calls set_file to specify the template to actually render. Any code associated with the specified template is executed in the same stack frame as the initial code, so that each "skin" may reference additional specific data or logic as necessary.
- Parameters:
- path (required)
- The root (sans file extension) of the absolute path to the next template to parse.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.