diff --git a/twander.1 b/twander.1 index 7a75fcf..a7c7d9e 100644 --- a/twander.1 +++ b/twander.1 @@ -2583,7 +2583,7 @@ script for doing backups. It's a simple matter to write a \fCtwander\fP Command Definition that will pass the names of the files and directories you've selected to that backup script. You might combine -this with \fCtwander\fPs Program Memory feature to keep a running list +this with \fCtwander\fP's Program Memory feature to keep a running list of the files and directories you want to backup and then finally issue the backup command when you're ready. Best of all, commands you define this way are always a single keystroke. This means that @@ -2591,8 +2591,39 @@ it is very fast and convenient. Command Definitions are built out of literal text and may also have -any combination of three variable types: User-Defined Variables, -Environment Variables, and Built-In Variables. +any combination of several variable types: User-Defined Variables, +Environment Variables, Execution Variables, and Built-In Variables. + +User-Defined Variables are variables you define in the configuration +file. They can hold any string of text you desire. + +Environment Variables are set in the shell you use to invoke +\fCtwander\fP. This makes it easy to write a generic command +definition that acts based on something set uniquely for each user in +that user's environment. You can only read, not change, Environment +Variables in \fCtwander\fP. + +Execution Variables are set by running a program - pretty much any +program will do. (Unix users will be familiar with this if they've +ever used shell "backtick" quoting.) This makes it easy to +construct a \fCtwander\fP command that is defined in whole or in part +by some external program. + +Built-In Variables are a set of variables defined by \fCtwander\fP +itself. There are two general kinds of Built-Ins. The first +kind are used to let your command know (at runtime) which file or files +you have currently selected in the \fCtwander\fP interface. The other +kind of Built-Ins are used to prompt you during command execution. +There are also a few other Built-Ins described below. + +.SS Just When Does A Variable Get Evaluated? + +Before getting into the mechanics of variables and command definitions, it's +important to emphasize one point: Variables get "evaluated" (read) +.B when a command is actually run. +Older versions of \fCtwander\fP evaluated variables at the time a configuration +file was read. However, as we'll see below, by waiting until the command +is actually run to evaluate its variable references, we can do some nifty things. .SS User-Defined Variables And Environment Variables @@ -2666,10 +2697,10 @@ .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). +(in the Command String portion of a Command Definition) at the time +the command is run. 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 @@ -2721,6 +2752,32 @@ [Var1][Var2][DSELECTION] we would get one long string back instead of a command with arguments and a list of selected items. + +.IP \(bu 4 +Variable references are only significant on the right hand side of +an assignment statement: + +.ft C \" courier +.nf + Var1 = Foo + My[Var1] = bar +.fi +.ft \" revert + +This does +.B not +create a variable called "MyFoo". It creates a variable called "My[Var1]" and sets +its value to "bar". This is both confusing and useless because you can never +dereference this variable, because ... + +.IP \(bu 4 +Variable references cannot be nested. Using our example above, suppose we +later want to get the value ("bar") of variable "My[Var1]". That variable +reference would look like this: \fC[My[Var1]]\fP and this is +.B not +permitted. A variable reference may only contain a text string, not references +to other variables. + .IP \(bu 4 Variables must be .B defined before they are referenced @@ -2806,6 +2863,52 @@ .fi .ft \" revert + +.SS Execution Variables + +Execution Variables are a special case of User-Defined Variables. +However, instead of setting a variable to some string of text, +you tell \fCtwander\fP to +.B run a program +and set it's results to the variable: + +.ft C \" courier +.nf + TODAY = [`date`] +.fi +.ft \" revert + +Now, suppose you define a command with \fC[TODAY]\fP in it somewhere. +When you later run that command, \fC[TODAY]\fP will be replaced +by the output of the "date" command. In other words, Execution Variables +allow you to run any external program you like, and have that program's +output substituted into the definition of a command. Several futher +points are worth noting here. + +.IP \(bu 4 +Notice that Execution Variables are delimited by backticks, not single-quotes. + +.IP \(bu 4 +If you have something like \fC[`program`]\fP in a Command Definition, +it will be replaced with any text that "program" produces as it runs. +That text will have any trailing newline stripped. + +.IP \(bu 4 +Suppose you want to populate an Execution Variable with a program that +returns multiple lines of text. You'll need to strip all the newlines +out of the output in that case. To do this, you can use a second form +of an Execution Variable: \fC[`-program`]\fP. The leading minus sign +tells \fCtwander\fP to strip all newlines when doing the replacement. +For example, let's define a command that lists all the files in the +current directory: + +.ft C \" courier +.nf + a mycommand echo "[`-ls`]" +.fi +.ft \" revert + + .SS Command Definitions The heart of the \fCtwander\fP configuration process is creating of one or more @@ -4477,4 +4580,4 @@ .ft \" revert .SH DOCUMENT REVISION INFORMATION -$Id: twander.1,v 1.119 2005/02/04 09:20:23 tundra Exp $ \ No newline at end of file +$Id: twander.1,v 1.120 2005/02/04 10:19:14 tundra Exp $ \ No newline at end of file