diff --git a/twander.1 b/twander.1 index 3195fcf..2166d25 100644 --- a/twander.1 +++ b/twander.1 @@ -505,7 +505,7 @@ .SS Comments -A comment is begun with the "#" string which may begin anywhere on a +A comment is begun with the "#" string which may be placed anywhere on a line. Comments may appear freely within a configuration file. \'twander\' strictly ignores everything from the "#" to the end of the line on which it appears without exception. This means that "#" @@ -545,7 +545,95 @@ Here are several other subtleties regarding User-Defined Variables: .IP \(bu 4 -The Variable Name is case-sensitive - [EDITOR], [Editor], +\'twander\' variable definitions are nothing more than a +string substitution mechanism. Suppose you have a variable +definition that refers to another variable: + +.nf +NewVar = somestring [OldVar] +.fi + +It is important to realize that this only means: "If you encounter +the string \'[NewVar]\' +.B in a subsequent Command Definition, +replace it with the string \'somestring [OldVar]\'. + +In other words, +no evaluation of the right side of the expression takes +place when a variable is +.B defined. +Evaluation of a variable only takes place when the variable is +.B referenced +(in the Command String portion of a Command Definition). The Command +Definition parser will continue to dereference variable names until +they are all resolved or it has reached the maximum nesting level (see +next bullet). + + +.IP \(bu 4 +User-Defined Variables may be +.B nested +up to 32 levels deep. You can have constructs like: + +.nf +Var1 = Foo +Var2 = Bar +FB = [Var1][Var2] +.fi + +Later on (when defining some command) when \'twander\' runs into the +variable reference [FB], it will keep substituting variables until all +[...] references have been resolved or it hits the nesting limit (32). +This limit has to be imposed to catch silly things like this: + +.nf +Var = a[Var] +.fi + +This recursive definition is a no-no and will be cause \'twander\' +to generate an error while parsing the configuration file and then +terminate. + +Your variable definitions can also nest other kinds of variables +(Environment and Builtins). So, constructs like this are perfectly +OK: + +.nf +Var1 = [$PAGER] +Var2 = command-arguments +V = [Var1] [Var2] [DSELECTIONS] +.fi + +Notice that since the right-hand side of User-Defined Variables +is literally replaced, we have to make sure there is +space between the various variable references. If we +used "[Var1][Var2][DSELECTIONS]" we would get one long string +back instead of a command with arguments and a list of selected +items. + + +.IP \(bu 4 +Variables must be +.B defined before thye are referenced (in a Command Definition). +The following is OK because all variables are defined by the +time they actually get used in the Command Definition: + +.nf +Var1 = foo +Var2 = [Var3] # This is just a string substition, not a reference +Var3 = bar +MyVar = [Var1][Var2] + +# Now comes the command definition +# If we put this before the Variable Definitions above, +# it would be an error. + +x mycommand [MyVar] +.fi + + +.IP \(bu 4 +Variable Names are case-sensitive - [EDITOR], [Editor], and [editor] all refer to different variables. .IP \(bu 4 @@ -592,98 +680,6 @@ Definitions) or one of the Program Function Names (used for key bindings). -.IP \(bu 4 -User-Defined Variables are replaced with simple string substitution -logic. Say you have: - -.n -VAR = something or other ... -.fi - -Anytime \'twander\' finds a reference later to [VAR] it replaces -it with everthing from "something..." to the end of the line including -spaces within the string. Only the leading and trailing spaces of -the right side of the variable are dropped. - -.IP \(bu 4 -User-Defined Variables may be -.B nested -up to 32 levels deep. You can have constructs like: - -.nf -Var1 = Foo -Var2 = Bar -FB = [Var1][Var2] -.fi - -Just make sure the variable -.B definitions -precede variable -.B references. -Later on (when defining some command) when \'twander\' runs into the -variable reference [FB], it will keep substituting variables until all -[...] references have been resolved or it hits the nesting limit (32). -This limit has to be imposed to catch silly things like this: - -.nf -Var = a[Var] -.fi - -This recursive definition is a no-no and will be cause \'twander\' -to generate an error while parsing the configuration file and then -terminate. - -Your variable definitions can also nest other kinds of variables -(Environment and Builtins). So, constructs like this are perfectly -OK: - -.nf -Var1 = [$PAGER] -Var2 = command-arguments -V = [Var1] [Var2] [DSELECTIONS] -.fi - -Notice that since the right-hand side of User-Defined Variables -is literally replaced later, we have to make sure there is -space between the various variable references. If we -used "[Var1][Var2][DSELECTIONS]" we would get one long string -back instead of a command with arguments and a list of selected -items. - -.IP \(bu 4 -While it is true that variables must be defined before they -are referenced, \'twander\' only checks this when -.B commands -are defined, not when variables are defined. This is because a -variable "definition" does nothing more than associate a symbol name -(the left side) with a replacement string (the right side) in the -symbol table. It is not until that string is actually referenced in a -Command String definition that \'twander\' does the variable -dereferencing that checks for validity. This creates an interesting -situation if you define an illegal variable, but never -actually use it. You edit your configuration file and add: - -.nf -foo = [BAD-VBL] # Illegal! BAD-VBL is not defined anywhere -bar = x[foo] -.fi - - -\'twander\' will run fine! Why? Because we are merely declaring -sting substitutions, we are not actually dereferencing any variables -that appear on the right-hand side of a definition. - -Now we add this to configuration file: - -.nf -c mycommand blah blah blah [bar] -.fi - -Now we -.B do -get an error. Why? Because a [...] variable reference in a Command -Definition is actually dereferenced, detecting the fact that no -definition for BAD-VBL exits. .P .SS Key Binding Statements @@ -713,8 +709,8 @@ that command. Command Keys must be unique within a given configuration file. \'twander\' will declare an error and refuse to run if it sees two Command Definitions with the same Command Key in a -given configuration file. A described previously, the Command Key can -never be "#". +given configuration file. A Command Key can never be "#" which is +always understood to be the beginning of a comment. The "Command Name" is a string of any length containing any characters. This is the name of the command which is used to invoke @@ -727,10 +723,13 @@ The "Command String" is any arbitarary string which is what \'twander\' actually tries to execute when the command is invoked. +.SS A Simple Command Definition + In its simplest form, a Command Definition looks like this: .nf # A simple Command Definition + m MyMore more somefile .fi @@ -748,6 +747,7 @@ .nf # Our command setup to run as a GUI window + m MyMore xterm -l -e more somefile .fi @@ -765,24 +765,26 @@ # Our command enhanced with a User-Defined Variable. # Remember that the variable has to be defined *before* # it is referenced. -XTERM = xterm -l -e # This defines the variable -m MyMore [XTERM] more somefile # And the command then uses it + +XTERM = xterm -l -e # This defines the variable +m MyMore [XTERM] more somefile # And the command then uses it .fi .SS Environment Variables In A Command String This is all very nice, but we'd really like a command to be generic -and be easily used by a variety of users. First of all, not everyone -likes the "more" program as a pager. In fact, on Unix-like systems, -especially, there is an environment variable ($PAGER) set by each user -which names the paging program that user prefers. We can refer to -environment variables just like any other variable as explained -previously. Now our command looks like this: +and be easily used by a variety of users. Not everyone likes the +"more" program as a pager. In fact, on Unix-like systems there is an +environment variable ($PAGER) set by each user which names the paging +program that user prefers. We can refer to environment variables just +like any other variable as explained previously. Now our command +looks like this: .nf # Our command using both a User-Defined Variable and # an Environment Variable to make it more general + XTERM = xterm -l -e m MyMore [XTERM] [$PAGER] somefile .fi @@ -807,6 +809,7 @@ .nf # Our command in its most generic form using # User-Defined, Environment, and Builtin Variables + XTERM = xterm -l -e m MyMore [XTERM] [$PAGER] [DSELECTION] .fi @@ -911,7 +914,8 @@ .B once at load time. -Builtin Variables are resolved +.IP \(bu 4 +By contrast, Builtin Variables are resolved .B on each command invocation, i.e - at runtime.