diff --git a/tconfpy.3 b/tconfpy.3 index 860c2e2..ba908aa 100644 --- a/tconfpy.3 +++ b/tconfpy.3 @@ -825,6 +825,11 @@ .B PROGRAMMING USING THE \*(TC API for all the gory details.) +The programmer can also arrange for the configuration file to only +have access to variables predefined by the program ahead of time. In +that case, if you try to create a new variable, \*(TC will produce an +appropriate error and the new variable will not be created. + .SS Variable Names @@ -979,9 +984,10 @@ i.e., The value \'Dad\' is assigned to a (new) variable called \'HouseCleaning\'. In other words, putting a variable reference on the left-hand-side of an assignment like this allows you -to access another variable which is named "indirectly". You have -to be careful when doing this, though. Consider a similar, but -slightly different example: +to access another variable which is named "indirectly". + +You have to be careful when doing this, though. Consider a similar, +but slightly different example: .nf CurrentTask = House Cleaning # This is fine @@ -1002,6 +1008,36 @@ contain whitespace, begin with \'$\', contain \'#\', \'[\', or \']\' and so on. +Another example of how indirection can "bite" you is when the +value of the variable begins with a period. As you'll see in the +following section on Lexical Namespaces, a variable name beginning +with a period is understood to be an "absolute" variable name +reference (relative to the root namespace). This can cause unexpected +(though correct) behavior when doing indirect variable access: + +.nf + NAMESPACE = NS1 + foo = .bar # Creates variable NS1.foo with value \'.bar\' + [foo] = baz # Means \'[NS1.foo] = baz\' +.fi + + +The second assignment statement in this example does not do what you +might initially think. Remember, \*(TC always does variable +dereferencing before anything else, so the second statement becomes: + +.nf + .bar = baz +.fi + +As you'll see in the section on Lexical Namespaces below, this actually +means, "Set the variable \'bar\' in the root namespace to the value +\'baz\'." In other words, if you do indirect variable assignment, and +the content of that variable begins with a period, you will be creating/setting +a variable in +.B the root namespace. +Be sure this is what you intended to do. + Get into the habit of reading \'[something]\' as, "The current value of \'something\'". See if you understand what the following does (if you don't, try it out with \'test-tc.py\'):