Initial revision

1 files changed, 162 insertions, 0 deletions

diff --git a/doc/ObjSetVar.3 b/doc/ObjSetVar.3
new file mode 100644
index 0000000..49dd82d
--- /dev/null
+++ b/doc/ObjSetVar.3
@@ -0,0 +1,162 @@
+'\"
+'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" SCCS: @(#) ObjSetVar.3 1.6 97/05/19 17:35:44
+'\" 
+.so man.macros
+.TH Tcl_ObjSetVar2 3 8.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_ObjSetVar2, Tcl_ObjGetVar2 \- manipulate Tcl variables
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
+.sp
+Tcl_Obj *
+\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *newValuePtr
+.AP Tcl_Interp *interp in
+Interpreter containing variable.
+.AP Tcl_Obj *part1Ptr in
+Points to a Tcl object containing the variable's name.
+The name may include a series of \fB::\fR namespace qualifiers
+to specify a variable in a particular namespace.
+May refer to a scalar variable or an element of an array variable.
+.AP Tcl_Obj *part2Ptr in
+If non-NULL, points to an object containing the name of an element
+within an array and \fIpart1Ptr\fR must refer to an array variable.
+.AP Tcl_Obj *newValuePtr in
+Points to a Tcl object containing the new value for the variable.
+.AP int flags in
+OR-ed combination of bits providing additional information for
+operation. See below for valid values.
+.BE
+
+.SH DESCRIPTION
+.PP
+These two procedures may be used to read and modify
+Tcl variables from C code.
+\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one.
+It sets the specified variable to
+the object referenced by \fInewValuePtr\fR
+and returns a pointer to the object which is the variable's new value.
+The returned object may not be the same one
+referenced by \fInewValuePtr\fR;
+this might happen because variable traces may modify the variable's value.
+The reference count for the variable's old value is decremented
+and the reference count for its new value is incremented.
+If the new value for the variable
+is not the same one referenced by \fInewValuePtr\fR
+(perhaps as a result of a variable trace),
+then \fInewValuePtr\fR's reference count is left unchanged.
+The reference count for the returned object is not incremented
+to reflect the returned reference.
+If the caller needs to keep a reference to the object,
+say in a data structure,
+it must increment its reference count using \fBTcl_IncrRefCount\fR.
+If an error occurs in setting the variable
+(e.g. an array variable is referenced
+without giving an index into the array),
+then NULL is returned.
+.PP
+The variable name specified to \fBTcl_ObjSetVar2\fR consists of two parts.
+\fIpart1Ptr\fR contains the name of a scalar or array variable.
+If \fIpart2Ptr\fR is NULL, the variable must be a scalar.
+If \fIpart2Ptr\fR is not NULL,
+it contains the name of an element in the array named by \fIpart2Ptr\fR.
+As a special case, if the flag TCL_PARSE_PART1 is specified,
+\fIpart1Ptr\fR may contain both an array and an element name:
+if the name contains an open parenthesis and ends with a
+close parenthesis, then the value between the parentheses is
+treated as an element name (which can have any string value) and
+the characters before the first open
+parenthesis are treated as the name of an array variable.
+If the flag TCL_PARSE_PART1 is given,
+\fIpart2Ptr\fR should be NULL since the array and element names
+are taken from \fIpart2Ptr\fR.
+.PP
+The \fIflags\fR argument may be used to specify any of several
+options to the procedures.
+It consists of an OR-ed combination of any of the following
+bits:
+.TP
+\fBTCL_GLOBAL_ONLY\fR
+Under normal circumstances the procedures look up variables as follows:
+If a procedure call is active in \fIinterp\fR,
+a variable is looked up at the current level of procedure call.
+Otherwise, a variable is looked up first in the current namespace,
+then in the global namespace.
+However, if this bit is set in \fIflags\fR then the variable
+is looked up only in the global namespace
+even if there is a procedure call active.
+If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
+\fBTCL_GLOBAL_ONLY\fR is ignored.
+.TP
+\fBTCL_NAMESPACE_ONLY\fR
+Under normal circumstances the procedures look up variables as follows:
+If a procedure call is active in \fIinterp\fR,
+a variable is looked up at the current level of procedure call.
+Otherwise, a variable is looked up first in the current namespace,
+then in the global namespace.
+However, if this bit is set in \fIflags\fR then the variable
+is looked up only in the current namespace
+even if there is a procedure call active.
+.TP
+\fBTCL_LEAVE_ERR_MSG\fR
+If an error is returned and this bit is set in \fIflags\fR, then
+an error message will be left in the interpreter's result,
+where it can be retrieved with \fBTcl_GetObjResult\fR
+or \fBTcl_GetStringResult\fR.
+If this flag bit isn't set then no error message is left
+and the interpreter's result will not be modified.
+.TP
+\fBTCL_APPEND_VALUE\fR
+If this bit is set then \fInewValuePtr\fR is appended to the current
+value, instead of replacing it.
+If the variable is currently undefined, then this bit is ignored.
+.TP
+\fBTCL_LIST_ELEMENT\fR
+If this bit is set, then \fInewValuePtr\fR is converted to a valid
+Tcl list element before setting (or appending to) the variable.
+A separator space is appended before the new list element unless
+the list element is going to be the first element in a list or
+sublist (i.e. the variable's current value is empty, or contains
+the single character ``{'', or ends in `` }'').
+.TP
+\fBTCL_PARSE_PART1\fR
+If this bit is set,
+then \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR
+will parse \fIpart1Ptr\fR
+to obtain both an array name and an element name.
+If the name in \fIpart1Ptr\fR contains an open parenthesis
+and ends with a close parenthesis,
+the name is treated as the name of an element of an array;
+otherwise, the name in \fIpart1Ptr\fR
+is interpreted as the name of a scalar variable.
+When this bit is set,
+\fIpart2Ptr\fR is ignored.
+.PP
+\fBTcl_ObjGetVar2\fR returns the value of the specified variable.
+Its arguments are treated the same way as those for \fBTcl_ObjSetVar2\fR.
+It returns a pointer to the object which is the variable's value.
+The reference count for the returned object is not incremented.
+If the caller needs to keep a reference to the object,
+say in a data structure,
+it must increment the reference count using \fBTcl_IncrRefCount\fR.
+If an error occurs in setting the variable
+(e.g. an array variable is referenced
+without giving an index into the array),
+then NULL is returned.
+
+.SH "SEE ALSO"
+Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar, Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar, Tcl_UnsetVar, Tcl_UnsetVar2
+
+.SH KEYWORDS
+array, interpreter, object, scalar, set, unset, variable