Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tcl_SubstObj(3)		    Tcl	Library	Procedures	       Tcl_SubstObj(3)

______________________________________________________________________________

NAME
       Tcl_SubstObj - perform substitutions on Tcl values

SYNOPSIS
       #include	<tcl.h>

       Tcl_Obj *
       Tcl_SubstObj(interp, objPtr, flags)

ARGUMENTS
       Tcl_Interp *interp (in)		  Interpreter  in which	to execute Tcl
					  scripts and lookup variables.	 If an
					  error	occurs,	the interpreter's  re-
					  sult	is  modified  to hold an error
					  message.

       Tcl_Obj *objPtr (in)		  A Tcl	value containing the string to
					  perform substitutions	on.

       int flags (in)			  OR'ed	combination of flag bits  that
					  specify  which substitutions to per-
					  form.	 The flags TCL_SUBST_COMMANDS,
					  TCL_SUBST_VARIABLES		   and
					  TCL_SUBST_BACKSLASHES	 are currently
					  supported, and TCL_SUBST_ALL is pro-
					  vided	as a convenience for the  com-
					  mon case where all substitutions are
					  desired.
______________________________________________________________________________

DESCRIPTION
       The  Tcl_SubstObj  function is used to perform substitutions on strings
       in the fashion of the subst command.  It	gets the value of  the	string
       contained in objPtr and scans it, copying characters and	performing the
       chosen substitutions as it goes to an output value which	is returned as
       the  result of the function.  In	the event of an	error occurring	during
       the execution of	a command or variable substitution, the	 function  re-
       turns NULL and an error message is left in interp's result.

       Three  kinds  of	substitutions are supported.  When the TCL_SUBST_BACK-
       SLASHES bit is set in flags, sequences that look	like backslash substi-
       tutions for Tcl commands	are replaced by	their corresponding character.

       When the	TCL_SUBST_VARIABLES bit	is set in flags, sequences  that  look
       like  variable  substitutions for Tcl commands are replaced by the con-
       tents of	the named variable.

       When the	TCL_SUBST_COMMANDS bit is set in flags,	 sequences  that  look
       like  command substitutions for Tcl commands are	replaced by the	result
       of evaluating that script.  Where an uncaught "continue exception"  oc-
       curs  during  the evaluation of a command substitution, an empty	string
       is substituted for the command.	Where an  uncaught  "break  exception"
       occurs  during  the evaluation of a command substitution, the result of
       the whole substitution on objPtr	will be	truncated at the point immedi-
       ately before the	start of the command substitution, and	no  characters
       will  be	 added	to  the	 result	 or substitutions performed after that
       point.

REFERENCE COUNT	MANAGEMENT
       The objPtr argument to Tcl_SubstObj must	not have a reference count  of
       zero.  This  function  modifies the interpreter result, both on success
       and on failure; the result of this function on success is  exactly  the
       current interpreter result. Successful results should have their	refer-
       ence count incremented if they are to be	retained.

SEE ALSO
       subst(n)

KEYWORDS
       backslash substitution, command substitution, variable substitution

Tcl				      8.4		       Tcl_SubstObj(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_SubstObj.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help