| |
---|
| | 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. |
---|
| | |
---|
| |
---|
| | |