Added section on Conditional Processing Statements.
1 parent 042cbb4 commit cfde9654cd15e5039d78041d351afcb82f05f098
@tundra tundra authored on 9 Mar 2003
Showing 1 changed file
View
158
twander.1
Key Binding Statements
Directory Shortcut Statements
Wildcard Statements
Variables And Command Definitions
Conditional Processing Statements
.fi
 
(See the ".twander" file provided with the program distribution
for examples of valid configuration statements.)
 
.IP \(bu 4
Unlike previous versions of \*(TW, Variable Names may be redefined.
This makes it more convenient to exploit the ability for \*(TW
to process the contents of a \*(CF conditionally (see the section
below entitled, "Conditional Processing").
to process the contents of a \*(CF conditionally (see the
.B Conditional Processing Statements
section below).
 
For example, you can set a variable to some default
value, and then override it if a condition is satisfied:
 
Menu), they will be presented with two prompts, one after the other,
and then the command will run.
 
 
.SS Conditional Processing Statements
 
Most of \*(TWs power lies in its ability to be customized to each
different user and operating system via its \*(CF. To make this a bit
easier to manage, the \*(TW configuration language recognizes
so-called "Conditional Processing Statements". These statements give
you the ability to write a single \*(CF which automatically tailors
itself to run \*(TW properly wherever you are running.
 
The general idea is to define a "Condition Block" which begins by
doing a logical test. If that test evaluates to True, all statements
in the block are included in the current configuration. If the test
evaluates to False, all statements to the end of the block are
ignored.
 
A Conditional Block always begins with a "Condition Test Statement"
and ends with the ".endif" statement. Conditional Processing
Statements may be nested without limit. \*(TW keeps track of which
\&'.endif' matches which Condition Test Statement. Like all \*(CF
entries, whitespace is ignored when processing Conditional Statements
and you are free to indent (or not) as you see fit.
 
Condition Test Statements are one of three types:
 
.nf
#####
# Existential: True if FOO or $FOO are defined
#####
 
\&.if [FOO]
...
\&.endif
 
.if [$FOO]
...
\&.endif
 
#####
# Equality: True if FOO or $FOO are literally
# the same as the test-string
#####
 
\&.if [FOO] == test-string
...
\&.endif
 
\&.if [$FOO] == test-string
...
\&.endif
 
#####
# Inequality: True if FOO or $FOO are literally
# not the same as the test-string
#####
 
\&.if [FOO] != test-string
...
\&.endif
 
\&.if [$FOO] != test-string
...
\&.endif
.fi
To make it easy to create conditional blocks based on the type of
system you're running, \*(TW automatically pre-defines two
variables which provide information about your system:
 
.nf
Variable Name Typical Values
--------------------------------
 
\& .OS nt, posix
\& .PLATFORM freebsd4, linux-i386, win32
.fi
 
These predefined variables show up as "User Defined Variables" in the
various \*(TW Help and Debug outputs, but they begin with a period to
remind you of their intended role. They will thus also sort first in
the User-Defined Variables section of the Help Menu.
 
Several things about Conditional Processing Statements are worth
noting:
 
.IP \(bu 4
Whitespace is mandatory after the ".if" statement - \&.if[FOO] is
syntactically incorrect. However, you need no whitespace on either
side of a "==" or "!=" test.
 
.IP \(bu 4
All these tests involve either a User-Defined Variable or
an Environment Variable, never a Program Option or Built In Variable.
 
.IP \(bu 4
A Condition Test Statement always involves a variable
.B reference
("[FOO]", never just "FOO") because we want the
.B contents,
not the name, of the variable for the test.
 
.IP \(bu 4
The Right Hand Side of an (in)equality test is just a string
comparsion - no variable expansion is done:
 
.nf
\&.if [FOO] == string[BAR]
.fi
 
This will not work as you might expect because the contents of
variable FOO are literally compared to the string, "string[BAR]".
Note too that this comparison is case-sensitive.
 
.IP \(bu 4
The ".endif" statement must appear on the line by itself. Nothing
other than whitespace may precede it, and nothing (other than a
comment) may follow it.
 
.P
See the example ".twander" file provided in the distribution for some
extended examples of using conditinals in your Configuration File.
Also see the
.B GOTCHAS
section below for further discussion.
 
 
.SH ADVANCED WIN32 FEATURES
 
As shipped from the factory, \*(TW runs pretty much identically
on various Unix variants (FreeBSD, Linux) and Win32. However,
\*(TW is written to take advantage of Mark Hammond's
\*(W3 Python extensions if they are present on the system.
These extensions add many Windows-specific features to Python
and allow \*(TW to provide quite a bit more Windows-centric
information about files, directories, and drives. You do
As shipped from the factory, \*(TW runs pretty much identically on
various Unix variants (FreeBSD, Linux) and Win32. However, \*(TW is
written to take advantage of Mark Hammond's \*(W3 Python extensions if
they are present on the system. These extensions add many
Windows-specific features to Python and allow \*(TW to provide quite a
bit more Windows-centric information about files, directories, and
drives. You do
.B not
have to install \*(W3 for \*(TW to operate properly
on your Win32 system. Installing this package just means you'll
get even more \*(TW features on Win32 than you would otherwise.
L lshome xterm -l -e bash -c 'ls / | [$PAGER]'
.fi
 
In fact, this idiom is so common, you will see variables
defined in the example \'.twander\' file to simplify
defined in the example ".twander" file to simplify
such definitions (comments removed):
 
.nf
SHELL = bash -c
.B until they appear in a Command Definition.
 
.IP \(bu 4
The Right Hand Side of Option Statements, Key Binding Statements, Directory Shortcut
Statements, and Wildcard Statements
Statements, Wildcard Statements, and Condition Test Statements
.B are treated literally -
No variable substitution is ever done there.
 
.IP \(bu 4
A Conditional Statement always involves a variable
A Condition Test Statement always involves a variable
.B reference,
never just a variable name.
 
.IP \(bu 4
For a Conditional Statement to be true, the referenced variable
For a Condition Test Statement to be true, the referenced variable
.B must be defined
and any equality test must be satisfied.
 
.IP \(bu 4
 
If you've installed \*(TW using the FreeBSD port, all you have
to do is copy the example \*(CF, ".twander" found in
/usr/local/share/doc/twander to your home directory and edit it to
taste.
taste. (You'll also find documentation for \*(TW in various formats in
this directory as well.)
 
Make sure that /usr/local/bin is in your path. To start the program,
just type "twander.py" from the shell prompt.