Top

SpecTcl Home  General Information User Guide Programmer's Guide Obtaining and Installing

	treevariable - Manipulate and query tree variables

treevariable -list [pattern]
treevariable -set name value units
treevariable -check name
treevariable -setchanged name
treevariable -firetraces [pattern]    ;# New in 3.0

Synopsis

Sets and examines the properties of treevariables.

Description

The Tree parameter package provides for a binding between a set of Tcl variables and elements of a structured data type. Such bound variables are called treevariables Associated with a tree variable is a units specificatino that can be used to document to the user what is expected for the parameter.

Note in the discussion below, that the ordinary Tcl set command can be used to modify the value of a treevariable, as Tcl's core sees them as ordinary variables.

The first command parameter after the treevariable command is a switch that defines the desired operation, the number and the meaning of the remaining parameters on the command line. The following sections describe each valid switch, its parameters and what it does.

treevariable -list [pattern]

Lists the properties of all or some of the treevariables. The optional pattern parameter allows you to select which variables are listed (if omitted all are listed). The pattern is a glob pattern, which means that all of the wildcard specifications you can use to select Unix filenames are accepted.

The output of this command is a list. Each element of the list describes a single variable. Each parameter is described as a sublist containing the following elements

• name the name of the variable. This is a period separated path to a single variable.
• value the current value of the variable.
• units Units of measure of the variable. This only documents the expected units of measure of the values given to this parameter.

Example - listing all variables

(treeparam) 10 % treevariable -list
{vars.unused.00 0 furl/fort} 
{vars.unused.01 0 furl/fort} 
{vars.unused.02 0 furl/fort} 
{vars.unused.03 0 furl/fort} 
{vars.unused.04 0 furl/fort} 
{vars.unused.05 0 furl/fort} 
{vars.unused.06 0 furl/fort} 
{vars.unused.07 0 furl/fort} 
{vars.unused.08 0 furl/fort} 
{vars.unused.09 0 furl/fort} 
{vars.w1 1 arb/chan} 
{vars.w2 1 arb/chan}

Example - listing all variables beginning with vars.w

(treeparam) 12 % treevariable -list vars.w*
{vars.w1 1 arb/chan} 
{vars.w2 1 arb/chan}

treevariable -set name value units

Modifies both the value and units of a tree variable. Note that the set command can be used to modify only the units. The new value of the parameter will be value and the new units units. The examples below show how to modify only the units of a parameter

Modifying value and units

(treeparam) 15 % treevariable -list vars.w1
{vars.w1 1 arb/chan}
(treeparam) 16 % treevariable -set vars.w1 0.5 MeV/channel
(treeparam) 17 % treevariable -list vars.w1
{vars.w1 0.5 MeV/channel}

Modifying the value only

The best way to do this is with the set Tcl built in command:

(treeparam) 17 % treevariable -list vars.w1
{vars.w1 0.5 MeV/channel}
(treeparam) 18 % set vars.w1 1.3
1.3
(treeparam) 19 % treevariable -list vars.w1
{vars.w1 1.3 MeV/channel}

Modifying the units only

Use the treevariable -set command but substitute the current value of the variable you are modifying for the value parameter.

(treeparam) 19 % treevariable -list vars.w1
{vars.w1 1.3 MeV/channel}
(treeparam) 23 % treevariable -set vars.w1 ${vars.w1} KeV/channel
(treeparam) 24 % treevariable -list vars.w1
{vars.w1 1.3 KeV/channel}

Note the use of curly brackets to quote the treevariable name. This is required because otherwise the substitution will think it is being asked to substitute for vars since the period will end the variable name.

treevariable -check name

This subcommand returns 0 if the variable's changed flag is false and 1 if it is true. Each tree variable has a changed flag that reflects whether or not the variable's properties have changed. In the case of a treevariable, the properties of a variable are considered to be its value and units. Being able to determine if treevariable properties have changed allows scripts to know if it is necessary to save these changes.

treevariable -setchanged name

This subcommand allows you to set the variable changed flag. See treevarible -check for more information about what this means.

treevariable -firetraces [pattern]

If there are traces established on the variable and its value has changed since the last attempt to fire its traces, the variables that match pattern will have Tcl_UpdateLinkedVar called on their behalf.