OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tcl/] [doc/] [ObjSetVar.3] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom 
'\"
2 
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
3 
'\"
4 
'\" See the file "license.terms" for information on usage and redistribution
5 
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
6 
'\"
7 
'\" RCS: @(#) $Id: ObjSetVar.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
8 
'\"
9 
.so man.macros
10 
.TH Tcl_ObjSetVar2 3 8.0 Tcl "Tcl Library Procedures"
11 
.BS
12 
.SH NAME
13 
Tcl_ObjSetVar2, Tcl_ObjGetVar2 \- manipulate Tcl variables
14 
.SH SYNOPSIS
15 
.nf
16 
\fB#include \fR
17 
.sp
18 
Tcl_Obj *
19 
\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
20 
.sp
21 
Tcl_Obj *
22 
\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR)
23 
.SH ARGUMENTS
24 
.AS Tcl_Interp *newValuePtr
25 
.AP Tcl_Interp *interp in
26 
Interpreter containing variable.
27 
.AP Tcl_Obj *part1Ptr in
28 
Points to a Tcl object containing the variable's name.
29 
The name may include a series of \fB::\fR namespace qualifiers
30 
to specify a variable in a particular namespace.
31 
May refer to a scalar variable or an element of an array variable.
32 
.AP Tcl_Obj *part2Ptr in
33 
If non-NULL, points to an object containing the name of an element
34 
within an array and \fIpart1Ptr\fR must refer to an array variable.
35 
.AP Tcl_Obj *newValuePtr in
36 
Points to a Tcl object containing the new value for the variable.
37 
.AP int flags in
38 
OR-ed combination of bits providing additional information for
39 
operation. See below for valid values.
40 
.BE
41 
 
42 
.SH DESCRIPTION
43 
.PP
44 
These two procedures may be used to read and modify
45 
Tcl variables from C code.
46 
\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one.
47 
It sets the specified variable to
48 
the object referenced by \fInewValuePtr\fR
49 
and returns a pointer to the object which is the variable's new value.
50 
The returned object may not be the same one
51 
referenced by \fInewValuePtr\fR;
52 
this might happen because variable traces may modify the variable's value.
53 
The reference count for the variable's old value is decremented
54 
and the reference count for its new value is incremented.
55 
If the new value for the variable
56 
is not the same one referenced by \fInewValuePtr\fR
57 
(perhaps as a result of a variable trace),
58 
then \fInewValuePtr\fR's reference count is left unchanged.
59 
The reference count for the returned object is not incremented
60 
to reflect the returned reference.
61 
If the caller needs to keep a reference to the object,
62 
say in a data structure,
63 
it must increment its reference count using \fBTcl_IncrRefCount\fR.
64 
If an error occurs in setting the variable
65 
(e.g. an array variable is referenced
66 
without giving an index into the array),
67 
then NULL is returned.
68 
.PP
69 
The variable name specified to \fBTcl_ObjSetVar2\fR consists of two parts.
70 
\fIpart1Ptr\fR contains the name of a scalar or array variable.
71 
If \fIpart2Ptr\fR is NULL, the variable must be a scalar.
72 
If \fIpart2Ptr\fR is not NULL,
73 
it contains the name of an element in the array named by \fIpart2Ptr\fR.
74 
As a special case, if the flag TCL_PARSE_PART1 is specified,
75 
\fIpart1Ptr\fR may contain both an array and an element name:
76 
if the name contains an open parenthesis and ends with a
77 
close parenthesis, then the value between the parentheses is
78 
treated as an element name (which can have any string value) and
79 
the characters before the first open
80 
parenthesis are treated as the name of an array variable.
81 
If the flag TCL_PARSE_PART1 is given,
82 
\fIpart2Ptr\fR should be NULL since the array and element names
83 
are taken from \fIpart2Ptr\fR.
84 
.PP
85 
The \fIflags\fR argument may be used to specify any of several
86 
options to the procedures.
87 
It consists of an OR-ed combination of any of the following
88 
bits:
89 
.TP
90 
\fBTCL_GLOBAL_ONLY\fR
91 
Under normal circumstances the procedures look up variables as follows:
92 
If a procedure call is active in \fIinterp\fR,
93 
a variable is looked up at the current level of procedure call.
94 
Otherwise, a variable is looked up first in the current namespace,
95 
then in the global namespace.
96 
However, if this bit is set in \fIflags\fR then the variable
97 
is looked up only in the global namespace
98 
even if there is a procedure call active.
99 
If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
100 
\fBTCL_GLOBAL_ONLY\fR is ignored.
101 
.TP
102 
\fBTCL_NAMESPACE_ONLY\fR
103 
Under normal circumstances the procedures look up variables as follows:
104 
If a procedure call is active in \fIinterp\fR,
105 
a variable is looked up at the current level of procedure call.
106 
Otherwise, a variable is looked up first in the current namespace,
107 
then in the global namespace.
108 
However, if this bit is set in \fIflags\fR then the variable
109 
is looked up only in the current namespace
110 
even if there is a procedure call active.
111 
.TP
112 
\fBTCL_LEAVE_ERR_MSG\fR
113 
If an error is returned and this bit is set in \fIflags\fR, then
114 
an error message will be left in the interpreter's result,
115 
where it can be retrieved with \fBTcl_GetObjResult\fR
116 
or \fBTcl_GetStringResult\fR.
117 
If this flag bit isn't set then no error message is left
118 
and the interpreter's result will not be modified.
119 
.TP
120 
\fBTCL_APPEND_VALUE\fR
121 
If this bit is set then \fInewValuePtr\fR is appended to the current
122 
value, instead of replacing it.
123 
If the variable is currently undefined, then this bit is ignored.
124 
.TP
125 
\fBTCL_LIST_ELEMENT\fR
126 
If this bit is set, then \fInewValuePtr\fR is converted to a valid
127 
Tcl list element before setting (or appending to) the variable.
128 
A separator space is appended before the new list element unless
129 
the list element is going to be the first element in a list or
130 
sublist (i.e. the variable's current value is empty, or contains
131 
the single character ``{'', or ends in `` }'').
132 
.TP
133 
\fBTCL_PARSE_PART1\fR
134 
If this bit is set,
135 
then \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR
136 
will parse \fIpart1Ptr\fR
137 
to obtain both an array name and an element name.
138 
If the name in \fIpart1Ptr\fR contains an open parenthesis
139 
and ends with a close parenthesis,
140 
the name is treated as the name of an element of an array;
141 
otherwise, the name in \fIpart1Ptr\fR
142 
is interpreted as the name of a scalar variable.
143 
When this bit is set,
144 
\fIpart2Ptr\fR is ignored.
145 
.PP
146 
\fBTcl_ObjGetVar2\fR returns the value of the specified variable.
147 
Its arguments are treated the same way as those for \fBTcl_ObjSetVar2\fR.
148 
It returns a pointer to the object which is the variable's value.
149 
The reference count for the returned object is not incremented.
150 
If the caller needs to keep a reference to the object,
151 
say in a data structure,
152 
it must increment the reference count using \fBTcl_IncrRefCount\fR.
153 
If an error occurs in setting the variable
154 
(e.g. an array variable is referenced
155 
without giving an index into the array),
156 
then NULL is returned.
157 
 
158 
.SH "SEE ALSO"
159 
Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar, Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar, Tcl_UnsetVar, Tcl_UnsetVar2
160 
 
161 
.SH KEYWORDS
162 
array, interpreter, object, scalar, set, unset, variable

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.