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)			  ORed 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.

SEE ALSO
       subst(n)

KEYWORDS
       backslash substitution, command substitution, variable substitution

Tcl				      8.4		       Tcl_SubstObj(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_SubstObj.tcl86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help