Difference between revisions of "Ns adp parse"

From AOLserver Wiki
Jump to navigation Jump to search
 
(2 intermediate revisions by the same user not shown)
Line 9: Line 9:
 
'''SYNOPSIS'''
 
'''SYNOPSIS'''
  
: '''ns_adp_parse''' ''?-file|-string? ?-safe? arg ?arg ...?''
+
: '''ns_adp_parse''' ''?-file|-string? ?-safe? ?-savedresult varName? ?-cwd path? arg ?arg ...?''
  
 
'''DESCRIPTION'''
 
'''DESCRIPTION'''
Line 15: Line 15:
 
: This command processes an ADP from either a file or a string, returning the output.  The first ''arg'' specifies the filename or contains the string to parse, depending on ''-file'' or ''-string''.
 
: This command processes an ADP from either a file or a string, returning the output.  The first ''arg'' specifies the filename or contains the string to parse, depending on ''-file'' or ''-string''.
  
: If you need to process a second ADP from inside an ADP, it is usually better to use [[ns_adp_include]], because that command resolves relative pathnames passed to it.  Also note that '''ns_adp_parse''' will ignore any directives to turn on streaming.  Tcl_Eval() is used to evaluate the Tcl commands in the ADP.  
+
: Note that '''ns_adp_parse''' will ignore any directives to turn on streaming.  Tcl_Eval() is used to evaluate the Tcl commands in the ADP.  
  
 
: If you use the ''-string'' syntax, then ''arg'' is a string containing ADP syntax to be parsed.  Note that when you call this command with the ''-string'' syntax from inside an ADP, the string cannot contain the "<% ... %>" syntax in versions of AOLserver prior to 4.5.  The ''-string'' syntax is the default.
 
: If you use the ''-string'' syntax, then ''arg'' is a string containing ADP syntax to be parsed.  Note that when you call this command with the ''-string'' syntax from inside an ADP, the string cannot contain the "<% ... %>" syntax in versions of AOLserver prior to 4.5.  The ''-string'' syntax is the default.
  
: If you use the ''-file'' syntax, then ''arg'' is the absolute path to the file containing the ADP to be parsed.
+
: If you use the ''-file'' syntax, then ''arg'' can either be an absolute path to the file containing the ADP to be parsed or, starting with AOLserver 4.0, a path relative to the current adp directory (as returned by [[ns_adp_dir]], which in AOLserver 4.5+ returns the pageroot when executed outside of an adp page). You can also temporarily override the current adp directory for the duration of the ns_adp_parse execution by using the -cwd ''path'' switch.
  
 
: If you specify the ''-safe'' flag, then only registered tags are executed; inline scripts using "<% ... %>" or "<%= ... %>" are ignored.   
 
: If you specify the ''-safe'' flag, then only registered tags are executed; inline scripts using "<% ... %>" or "<%= ... %>" are ignored.   
Line 40: Line 40:
 
'''NOTES'''
 
'''NOTES'''
 
: Using the -file option is preferrable to opening and reading the file yourself (even from an in-memory cache) and then parsing with -string because, with -file, it takes advantage of the adp page byte-compiled cache the same way ns_adp_include does.
 
: Using the -file option is preferrable to opening and reading the file yourself (even from an in-memory cache) and then parsing with -string because, with -file, it takes advantage of the adp page byte-compiled cache the same way ns_adp_include does.
 +
: ns_adp_parse -file differs from ns_adp_include in three key ways:
 +
:# ns_adp_include will throw an error if executed outside of an adp, though it will work when the calling adp block is itself being ns_adp_parsed.
 +
:# ns_adp_parse evaluates the adp in the current stack frame (with access to the same local variables), whereas ns_adp_include evaluates in one stack level below the caller.
 +
:# ns_adp_include writes to the adp buffer and returns the ''adp return value'' (i.e. the value from return, ns_adp_return or the last tcl command), whereas ns_adp_parse does not write to the adp buffer and instead returns what would have been normally written to the buffer.  The ''adp return value'' is placed into a variable specified with -savedresult.
 +
 +
: Contrary to older documentation, ns_adp_parse -file goes through the same relative path resolution as [[ns_adp_include]].
  
 
'''SEE ALSO'''
 
'''SEE ALSO'''

Latest revision as of 04:07, 14 June 2010

Man page: http://aolserver.com/docs/tcl/ns_adp_parse.html


NAME

ns_adp_parse - Parse an ADP file or string and return its output

SYNOPSIS

ns_adp_parse ?-file|-string? ?-safe? ?-savedresult varName? ?-cwd path? arg ?arg ...?

DESCRIPTION

This command processes an ADP from either a file or a string, returning the output. The first arg specifies the filename or contains the string to parse, depending on -file or -string.
Note that ns_adp_parse will ignore any directives to turn on streaming. Tcl_Eval() is used to evaluate the Tcl commands in the ADP.
If you use the -string syntax, then arg is a string containing ADP syntax to be parsed. Note that when you call this command with the -string syntax from inside an ADP, the string cannot contain the "<% ... %>" syntax in versions of AOLserver prior to 4.5. The -string syntax is the default.
If you use the -file syntax, then arg can either be an absolute path to the file containing the ADP to be parsed or, starting with AOLserver 4.0, a path relative to the current adp directory (as returned by ns_adp_dir, which in AOLserver 4.5+ returns the pageroot when executed outside of an adp page). You can also temporarily override the current adp directory for the duration of the ns_adp_parse execution by using the -cwd path switch.
If you specify the -safe flag, then only registered tags are executed; inline scripts using "<% ... %>" or "<%= ... %>" are ignored.
You can pass optional arguments to the ADP. The arguments can be accessed within the ADP using the ns_adp_argc, ns_adp_argv and ns_adp_bind_args commands.
If this call is a nested ADP evaluation (where one ADP calls another), an error will be thrown if the depth exceeds 256, the maximum number of nested ADP evaluations.

EXAMPLES

   % ns_adp_parse -string {<% return expr 2 + 2 %>}
   4
   % ns_adp_parse -file ns_info pageroot/index.adp
   ... output of index.adp ...

WARNING

In AOLserver versions prior to 4.5, -safe flag had no effect when used in combination with -file. In addition, -safe restriction could be bypassed in either a string or file by using this syntax: <script runat=server>...</script>

NOTES

Using the -file option is preferrable to opening and reading the file yourself (even from an in-memory cache) and then parsing with -string because, with -file, it takes advantage of the adp page byte-compiled cache the same way ns_adp_include does.
ns_adp_parse -file differs from ns_adp_include in three key ways:
  1. ns_adp_include will throw an error if executed outside of an adp, though it will work when the calling adp block is itself being ns_adp_parsed.
  2. ns_adp_parse evaluates the adp in the current stack frame (with access to the same local variables), whereas ns_adp_include evaluates in one stack level below the caller.
  3. ns_adp_include writes to the adp buffer and returns the adp return value (i.e. the value from return, ns_adp_return or the last tcl command), whereas ns_adp_parse does not write to the adp buffer and instead returns what would have been normally written to the buffer. The adp return value is placed into a variable specified with -savedresult.
Contrary to older documentation, ns_adp_parse -file goes through the same relative path resolution as ns_adp_include.

SEE ALSO

ns_adp_abort, ns_adp_append, ns_adp_argc, ns_adp_argv, ns_adp_bind_args, ns_adp_break, ns_adp_debug, ns_adp_debuginit, ns_adp_dir, ns_adp_dump, ns_adp_eval, ns_adp_exception, ns_adp_include, ns_adp_mime, ns_adp_mimetype, ns_adp_puts, ns_adp_registeradp, ns_adp_registerproc, ns_adp_registertag, ns_adp_return, ns_adp_safeeval, ns_adp_stats, ns_adp_stream, ns_adp_tell, ns_adp_trunc

Category Documentation - Category Core Tcl API