If you're new to and want to know why this program is better and different than whatever you're using at the moment, take a moment to read the section called DESIGN PHILOSOPHY toward the end of this document first.
Similarly, if this is the first time you've worked with , there is a section near the end of this document entitled INSTALLING which describes how the program should be installed.
You can get the latest version of the program and documentation from the homepage:
http://www.tundraware.com/Software/twander/
You should check this site periodically for program updates, bug fixes, and enhacements.
Also, you are strongly encouraged to join the mailing list where you'll find help and answers to questions you have about this program. Details of how to do this can be found toward the end of this document in the section entitled, GETTING HELP: THE MAILING LIST.
If this directory does not exist or cannot be opened, will display an error message and abort.
If this file does not exist or cannot be opened, will display a warning to that effect but continue to run. This is reasonable behavior because provides a command to reload the without exiting the program (which you would presumably do after fixing the problem).
is able to selectively dump debugging information to stdout. 'debuglevel' is understood to be a bitfield in which each bit specifies some kind of debugging information or behavior. 'debuglevel' can be specified in either decimal or hex (using the form 0x#) formats. The bits in the bitfield are defined as follows:
Bit Hex Value Meaning --- --------- ------- 0 0x001 Dump Internal Options & User-Settable Options 1 0x002 Dump User-Defined Variables 2 0x004 Dump Command Definitions 3 0x008 Dump Key Bindings 4 0x010 Display, Do Not Execute, Commands When Invoked 5 0x020 Dump Directory Stack As It Changes 6 0x040 Dump Command History Stack After Command Executes 7 0x080 Dump Contents Of Program Memories As They Change 8 0x100 Dump Contents Of Wildcard Stack As It Changes 9 0x200 Reserved/Unused 10 0x400 Reserved/Unused 11 0x800 Dump Requested Debug Information And Exit Immediately
These bits can be combined to provided very specific debugging information. For example, '-d 0x80f' will dump (to stdout) all the Internal Options, User-Settable Options, User-Defined Options, Command Definitions, and Key Bindings and then terminate the program.
Normally re-reads and displays the current directory every few seconds to reflect any changes that might have occurred to that directory's contents. This option is useful on slow machines (or slow X connections) and/or when working with very large directories. In this situation, the frequent updating of the display can make the program unacceptably slow and unresponsive. In this case you can still force an update manually with the REFRESH function (default assignment is to the Control-l key).
Anytime encounters a reference to one of the built-in variables which do string replacement (DIR, DSELECTION, DSELECTIONS, MEM1-12, PROMPT:, SELECTION, SELECTIONS) in a command, it will replace them with double quoted strings. This is necessary because any of these can return values which have embedded spaces in them. By quoting them, they can be passed to a command or script as a single item. The -t option disables this behavior and replaces the built-in variable with unquoted literals.
In addition to these command line options, there are two other ways you can set program features. If you prefer, you can set the command line options via the environment variable, TWANDER. That way you don't have to type them in each time you start the program. Say you set the environment variable this way on Unix:
export TWANDER=-qt
From then on, every time you run the program, the -q and -t options would be invoked (No Quoting, No Warnings) just as if you had typed them in on the command line.
The second way to set these (and MANY more) Program Options is by setting the appropriate entries in the . This is covered later in this document.
evaluates options in the following order (from first to last:
command line
This means, for example, that the environment variable overrides a corresponding setting in the , but the command line overrides the environment variable. Furthermore, there are many Program Options which can only be set/changed the and are not available in either the environment variable or on the command line.
This also means that options set on the command line are not read until after the has been processed. So, the -q argument on the command line will not inhibit warnings generated during the reading of the . This is best done by adding the statement, WARN=False, at the top of the Configuration File.
If the is reloaded while the program is running (see the READCONF key below), any options set in the file will have the last word. This allows you to edit the and have your changes reflected in a running instance of , but it also means that the environment variable/command line arguments are ignored after initial program startup.
By design, allows you to do almost everything of interest using only the keyboard. Various features are thus associated with particular keystrokes which are described below. It is also very simple to change the default key assignments with entries in the , also described below.
Generally, the arrow and keypad keys should do what you would expect on the system in question. On Win32 systems, particularly, there ought to be no odd arrow/keypad behavior.
X-Windows is somewhat more problematic in this area. Just what an arrow key is "supposed" to do depends on how it's been mapped in your X server software. Testing on various X servers showed quite a bit of variability in how they handled the arrows and keypad. So ... if you're running in an X Windows universe and arrows or keypad do nothing, or do strange things, look into your key maps, don't blame .
There are several features of that will present the user a text entry dialog. These include the CHANGEDIR and RUNCMD features as well as the [PROMPT:...] Built-In Variable (all described below).
Any time you are entering text in such a dialog, be aware that the text can be edited several ways - You can edit it using the arrow/keypad editing assignments which are enabled/normal for your operating system, OR you can use emacs-style commands to edit the text. For instance, Control-a, Control-k will erase the text currently entered in the dialog.
Here, ordered by category, are the default keyboard and mouse bindings for . The general format is:
The "Program Function Name" is the internal variable uses to associate a particular feature with a particular keystroke or mouse action. You can ignore it unless you intend to override the default key assignments. This use is described below in the section entitled, Key Binding Statements.
It is important to realize that key-bindings are case-sensitive. This means that 'Control-b' and 'Control-B' are different. This was a conscious design decision because it effectively doubles the number of Control/Alt key combinations available for the addition of future features.
The default bindings chosen for features are all currently lower-case. If your program suddenly stops responding to keyboard commands, check to make sure you don't have CapsLock turned on.
NOTE: Some features are doubled on the mouse. These mouse button assignments are documented below for the sake of completeness. However, mouse button assignments cannot be changed by the user, even in the .
This family of commands controls the operation of itself.
Clears out various program histories including the All Visited Directories list, the Directory Stack, the Command History, and the last manually-entered values for CHANGEDIR and RUNCMD. The 12 Program Memories are not cleared - they have specially dedicated key bindings for this purpose.
Decrease font size.
Increase font size.
These two features allow you to change the display font sizes while is running. But, you may not immediately get the results you expect. internally keeps track of separate font sizes for the main display, the main menu text, and the help menu text. When you use the two font sizing commands above, subtracts or adds 1 to each of these three values respectively. On systems like Win32 using TrueType fonts, this works as you would expect, because every font is effectively available in every size. However, in systems like X-Windows or Win32 using fixed-size fonts, you may have to press these keys repeatedly until finds a font matching the requested size.
This can also cause some parts of the display to change but not others. Suppose you are running on X-Windows and have specified that the main display is to use a 12 point font, and that menus and help should use 10 point font. Let's also suppose that the next font available larger than 12 point is 16 point. If you press FONTINCR twice, both the menu text and help text will jump to 12 point, but the main display text will remain unchanged. Why? Because pressing FONTINCR twice tells to set the main display to 14 point (12+1+1) which does not exist, and the menu and help text to 12 point (10+1+1) which does exist, so that change is visible.
The "User-Settable Options" Help Menu displays the font metrics (name, size, weight) you've currently specified. Pressing FONTDECR/FONTINCR changes the size specification and this will be reflected in that menu. However, most systems do some form of "best match" font substitution - if you ask for a font that does not exist, the system will use the "closest matching" font as a substitute. This means the font you see specified in the Help Menu is not necessarily the font you're actually using. You're more likely to run into this when running on a Unix/X-Windows system (where not all the fonts are available in all sizes/weights like they are on Win32 TrueType) as you change the font size with FONTDECR/FONTINCR.
Reloading the (READCONF) will reset the fonts to either their default values or any font sizes specified in the .
Displays a list of all available commands in a pop-up menu near the mouse pointer. If no commands are defined, this feature does nothing at all. This means commands can be invoked one of three ways: Directly via the Command Key defined in the , via selection in the Command Menu at the top of the GUI, or via selection from the Command Menu.
Win32 users should note that, unlike Windows Explorer, the Command Menu does not change the set of currently selected items. It merely provides a list of available commands. This allows the command chosen via the Command Menu to operate on a previously selected set of items.
Displays a list of all the directories visited so far in a pop-up menu near the mouse. This means that you can navigate to a previously visited directory in one of two ways: Via a selection in the Directory Menu at the top of the GUI or via a selection from this pop-up menu.
Displays a list of all commands executed so far (including those entered manually) in a pop-up menu near the mouse pointer. If the Command History is empty, this command does nothing. This means you can repeat a previously entered command via the History Menu or this mouse command. (You can also repeat the last manually entered command by pressing RUNCMD - it will preload its text entry area with the last command you entered by hand.)
Exit the program.
Re-read the . This allows you to edit the while is running and then read your changes in without having to exit the program. This is handy when editing or changing Command Definitions.
Program Options are set back to their default each time a is about to be read (initially or on reload) just before the is parsed. This means commenting out or removing a Program Option Statement (see relevant section below) in the and then pressing READCONF causes that option to be reset to its default value. STARTDIR defaults to either its internal default ($HOME or ./) or to the value given in the Environment Variable/Command line.
Re-read the current directory's contents and display it. This is most useful if you have turned off automatic directory refreshing with either the -r command line flag or setting the AUTOREFRESH Program Option to False.
Control-t
Toggle between detailed and filename-only views of the directory.
As described later in this document, provides enhanced features for Win32 users who also install Mark Hammond's extensions for Python on Win32. This key binding will toggle those advanced features on- and off. This is useful if you happen to be examining a very large directory. The features, while handy, can be computationally expensive and make updates of a directory with many entries somewhat slow. This toggle is provided as a means to temporarily disable the advanced features when viewing such a directory.
This family of commands controls movement between directories. If you attempt to navigate into a directory that does not exist or which does not have appropriate permissions, will display a warning message and remain in the current directory. This is unlike the case of a non-existent or unreadable directory specified when the program is first started. In that case, reports the error and aborts.
This is a shortcut that allows you to directly move to a new directory/path - i.e., Without having to navigate to it.
Unless you have set the MAXMENU option to 0, CHANGEDIR keeps track of your last manually entered directory and presents it as a default when you press CHANGEDIR again. You can then move to that directory, edit the string to specify another directory, or delete it and enter an entirely new directory. Directories can be edited with either the arrow and keypad keys defined on your system or by emacs editing commands like Control-a, Control-k, Control-e, and so forth.
If the "HOME" environment variable is defined on your system, this will move you to that directory. If the "HOME" environment variable is not defined, this command will move to the original starting directory.
keeps track of every directory visited and the order in which they are visited. This command allows you to move back successively until you get to the directory in which you started. This feature is implemented as a stack - each "backing up" removes the directory name from the visited list. The "Directory" menu (see MENU OPTIONS below) implements a similar feature in a different way and keeps track of all directories visited regardless of order.
Go to the root directory.
Go back to the original directory in which was started.
Move to the parent of the current directory ("..").
This is a Win32-only feature which displays a list of all available disk drives. Details about each drive are also displayed if you have details enabled. In order for this feature to work, you must be running on Win32 AND have the package installed, AND the USEWIN32ALL Program Option must be True (default condition,) AND you must not have toggled these features off with the TOGWIN32ALL key described above. For more details about Drive List View, see the section below entitled, ADVANCED WIN32 FEATURES.
This family of commands controls the selection of one or more (or no) items in the current directory.
Select every item in the current directory. The ".." entry at the top of the directory listing is not included. (We almost never want to include the parent directory when issuing a command on "everything in this directory". If you do wish to include the "..", do the SELALL command first, then click on ".." while holding down the Control key.)
Control-i
Unselects everything which was selected and selects everything which was not. As with SELALL, and for the same reason, the ".." entry is never selected on an inversion.
Unselect everything in the current directory.
Control-n
Select next item down in the directory.
Select previous item up in the directory.
Select last item in the directory.
Select first item in the directory. This will always be the ".." entry, but it is a quick way to get to the first part of a very long directory listing which does not all fit on-screen.
Although provides a very rich set of keyboard and mouse selection commands, selecting a group of files out of list of hundreds or thousands in a large directory can be tedious. If the files/directories you want to select have some lexical commonality in their names OR details you can have select them for you using so-called "Regular Expressions". The idea here is that you press SELWILD and enter a "matching" string or regular expression, and will select all entries which match this criteria for you. For example, if you just enter the text,
tar
would select every file or directory in the current display where the string "tar" appeared anywhere on the line for that file/directory. This is very important: Wildcard matching takes place anywhere on the visible line. So, if you have details turned on, the match can occur anywhere on the permissions, links, group, owner, and so on. Obviously, if you have details turned off, the match can only occur on the name of the file or directory since that's all that is visible.
This is a purposeful design decision because it allows you to make selections on more than just the name. Say you enter the following in the SELWILD dialog:
drwx------
will select all directories with no permissions enabled for group or world users.
The matching string above could also select other entries (not having the permissions just described), if say, this string appeared in their name ... a rather unlikely scenario, but not impossible. If we want to get real specific about which entries we want selected, we need to enter a "regular expression" in the SELWILD dialog. Regular expressions are a far more powerful pattern-matching tool than simple text strings and will allow you to do some fairly amazing selections. For example, this regular expression selects all entries which contain a string beginning with "Ju" followed by any other character, a single space, and ending in "0":
Ju. 0
So, for instance, this would select files with date details (or names, or anything else on the line...) like "Jun 01", "Jul 03", and "Jul 09".
No matter what you specify, a literal matching string or a regular expression, the ".." entry of the currently viewed directory is never selected by SELWILD.
Notice that these regular expressions are not the same thing as the filename "globbing" wildcards commonly used with Unix and Win32 shells. If you enter constructs like "*.txt" or "*.tar.gz", you will not get the results you expect. In fact, these specific examples will cause to grumble and present a warning message.
For an excellent tutorial on Python-compliant regular expressions, see:
http://www.amk.ca/python/howto/regex/
By default, SELWILD will select an entry when your regular expression matches anything on the displayed line. This allows you to make selections based on any visible column of information. This "match anywhere on the line" semantic is possible because SELWILD automatically massages the regular expression you provide to make "any match on the line" true. There may be times when you want to provide very specific regular expression definitions which seek a match at specific locations. In that case, you can prevent SELWILD from fiddling with your regular expression, by beginning it with the double-quote (") character. SELWILD understands this to mean that your regular expression is to be treated literally without modification. (It only throws away this leading escape character.)
Suppose we changed our example above slightly and used this regular expression:
"^drwx------
Now would select only the directories without any group and world access because:
The carat (^) at the beginning of the actual regular expression "anchors" the match to the start of the line. For a match to be declared (and for to select an item) the regular expression must be satisfied at the beginning-of-line.
There is also provision for pre-defining frequently used selection wildcards in your (see below) so you don't have to type them in manually each time you start the program - you can just select them from the Wildcard Menu.
The mouse can also be used to select one or more items. A single-click of the left mouse button selects a particular item. Clicking and dragging selects an adjacent group of items. Clicking an item and then clicking a second item while holding down the "Shift" key also selects an adjacent group of items. Finally, a group of non-adjacent items can also be selected. The first item is selected with a single left mouse button click as usual. Each subsequent (non-adjacent) item is then selected by holding down the "Control" key when clicking on the item.
If a given directory's contents cannot be displayed on a single screen, supports both vertical and horizontal scrolling via scrollbars. This capability is doubled on the keyboard with:
Scroll down one page in the directory listing.
Scroll up one page in the directory listing.
Scroll to the right one page width.
Scroll to the left one page width.
This family of commands causes to actually attempt to execute some command you've chosen:
This is a shortcut that allows you to run any command you'd like without having to define it ahead of time in the . It is more-or-less like having a miniature command line environment at your disposal.
You may enter a number of different things in the RUNCMD dialog. You may type literal text or refer to any of the variable types (User-Defined, Environment, or Built-In) supported by just as you do in writing Command Definitions (see below). This makes it easy to enter complex commands without having to type everything literally. For example, if you would like to copy all the currently selected files to a new directory, press RUNCMD and enter (on Unix):
cp [SELECTIONS] newdir
understands the variable reference syntax here just as it does in a Command Definition. This also gives you a single way of referring to environment variables, regardless of OS platform. Recall that in Unix-like shells, an environment variable is in the form "$NAME", but on Win32 it is in the form "%NAME%". Instead if having to keep track of this difference, you can just use a Environment Variable reference. For instance, assuming the EDITOR environment variable is set, this command works the same on both systems:
[$EDITOR] [SELECTIONS]
Unless you have set the MAXMENU option to 0, RUNCMD keeps track of your last manually entered command and presents it as a default when you press RUNCMD again. You can then run the command again exactly as you last entered it, you can modify it before running the command again, or you can delete it and enter an entirely new command. Commands can be edited with either the arrow and keypad keys defined on your system or by emacs editing commands like Control-a, Control-k, Control-e, and so forth.
Also see the section below entitled, Program Option Statements, to understand the CMDSHELL option. This option greatly simplifies running command-line programs from RUNCMD so their output can been seen in a GUI window. This is particularly handy on Unix.
If the selected item is a Directory, will move into that directory when this command is issued. If the selected item is a file, will attempt to execute it. Whether or not the file is actually executed depends on how the underlying operating system views that file.
In the case of Unix-like operating systems, the execute permission must be set for the user running (or their group) for the file to be executed.
On Win32, the file will be executed if the user has permission to do so and that file is either executable or there is a Windows association defined for that file type. For example, double-clicking on a file ending with ".txt" will cause the file to be opened with the 'notepad' program (unless the association for ".txt" has been changed).
If determines that it is running on neither a Unix-like or Win32 system, double-clicking on a file does nothing.
Key
Each command defined in the has a Command Key associated with it. Pressing that key will cause the associated command to be run. If no command is associated with a given keystroke, nothing will happen when it is pressed.
provides a way to directly navigate into a frequently-used directory using a single keystroke. You can define up to 12 such "Directory Shortcuts" in the . Each of the definitions is associated with one of the following 12 keys:
Pressing one of these keys changes to the directory associated with it in the . For more information on this topic, see the discussion of the below entitled, Directory Shortcut Statements.
If you've used GUIs before, you're probably familiar with the idea of a program "Clipboard" - a temporary holding area which is used when cutting, copying, and pasting files. This is a good idea, but has several limitations. First, most systems only have a single clipboard. It would be mighty handy to have muliple Clipboard-like storage areas for keeping track of several different operations at once. Secondly, when you copy or paste something to a conventional Clipboard, its old contents get overwritten. There is no way to keep appending items to the Clipboard. Finally, items usually can only be cut or copied to the Clipboard from the current directory. It would be nice if we could not only keep adding things to the Clipboard, but be able to do so as we navigate around the filesystem.
addresses these concerns by means of 12 separate "Program Memories". As you use , you can add (append) the names of any directories or files in the currently viewed directory by selecting them and then using the appropriate MEMSETx key (see below). To take advantage of this feature, you write Command Definitions (or manually issue a command via the RUNCMD key) which reference the contents of a Program Memory using one of the [MEMx] Built-In Variables. (See the section below on entitled, Program Memory Built-Ins for more details in how to apply Program Memories).
provides key combinations for selectively setting and clearing particular Program Memories as well as a key combination for clearing all Program Memories in a single keystroke:
Clear (empty) the selected Program Memory.
Clear (empty) all 12 Program Memories at once.
Append the the full path names of the currently selected files and directories to the Program Memory desired.
provides a variety of ways to sort the display. These can be selected with either a keystroke or from the Sorting Menu (see below). The meaning of the sort depends on whether or not you are in Drive List View (see ADVANCED WIN32 FEATURES below). The table below summarizes the keys associated with sorting and their meaning in the two possible views:
Program
Function Sort Order In Sort Order In
Key Name Normal View Drive List View
--- -------- ------------ ---------------
Shift-F10 SORTBYNONE No Sort No Sort
Shift-F1 SORTBYPERMS Permissions Label/Share String
Shift-F2 SORTBYLINKS Links Drive Type
Shift-F3 SORTBYOWNER Owner Free Space
Shift-F4 SORTBYGROUP Group Total Space
Shift-F5 SORTBYLENGTH Length Drive Letter
Shift-F6 SORTBYTIME Time Ignored
Shift-F7 SORTBYNAME Name Ignored
Shift-F11 SORTREV Reverse Order Reverse Order
Shift-F12 SORTSEP Separate Dirs Ignored
An easy way to remember these is that the function key number for the primary sort keys corresponds to the column position of the key in a detailed display. For instance, Shift-F1 sorts by column 1, Shift-F2 by column 2, and so forth.
These sorting options are available whether or not details are currently available. For example, you can toggle details off, but still sort by one of the now invisible details such as Owner, Length, and so on.
SORTREV reverses the order of the sort.
SORTSEP toggles whether or not directories and files should be grouped separately or displayed in absolute sort order. If enabled, directories will be displayed first, then files. If the sort is reversed via SORTREV, and SORTSEP is enabled, the directories will appear after the files, sorted by whatever sort key has been chosen. SORTSEP is not meaningful in Drive List View and is ignored.
You'll find the currently selected sorting options displayed in the program titlebar.
Although is primarily keyboard-oriented, several menu-based features are also implemented to make the program more convenient to use. These menus appear at the top of the display window, above the directory listing.
A menu can be invoked in one of several ways. You can click on it, you can press its associated "Accelerator Key" combination, or you can use the "Mouse Shortcut" to cause a copy of the menu to pop-up near the mouse pointer. The Accelerator Keys are shown in parenthesis next to the menu names below and the Mouse Shortcuts are similarly shown below in square brackets. All menus have Accelerator Keys defined, but only some menus have associated Mouse Shortcuts.
The first item in each menu is a dashed line ("----") which indicates that it is a "tearoff" menu. Clicking on the dashed line will detach the menu from allowing it to be placed anywhere on screen. Even when detatched, these menus remain current and in-sync with as it continues to run. You can also tear off multiple instances of these menus if you'd like copies of them at several locations on the screen simultaneously.
A number of these menus have "dynamic" content - their content changes as the program runs. For example, the Directory, History, and Wildcard menus all keep some sort of "history" of what the program has done. Their content thus grows longer as the program is used.
On Win32 systems, if such menus grow too long to physically fit on screen, up- and down- scrolling arrows automatically appear at the top- and bottom of the menu respectively. This is not a feature of the Unix Tk implementation, so menus which grow too large are simply truncated to fit the screen on Unix-like systems.
There are two User-Settable Options options available to help you manage the maximum size of dynamic menus (see the section below on the which explains how such options are actually set. The MAXMENU option specifies the maximum number entries that will be displayed in any dynamic menu. ( internally tracks MAXMENUBUF number of items for each dynamic menu.) This defaults to 32 as is intended to keep the menu size reasonable.
If you set MAXMENU=0, it means you are disabling all dynamic menus. It also means that no interactive dialog will "remember" your last manual entry. For example, with MAXMENU set to 0, will not keep track of your last manual entries for the CHANGEDIR, SELWILD, and RUNCMD dialogs.
MAXMENUBUF specifies the size of the internal storage buffer for each dynamic menu regardless of how many entries are actually displayed. i.e. MAXMENUBUF determines how many dynamic events each menu tracks internally regardless of how many are actually visible in the menu at any moment in time. It defaults to 250 and probably never needs to be changed. If you set MAXMENUBUF to be less than MAXMENU, then this smaller value will determine the maximum size of the displayed menu. Setting MAXMENUBUF to 0 is equivalent to setting MAXMENU to 0.
Every command defined in the is listed in this menu by its Command Name. The association Command Key is also shown in parenthesis. Clicking on an item in this menu is the same as invoking it from the keyboard by its Command Key. This is a convenient way to invoke an infrequently used command whose Command Key you've forgotten. It is also handy to confirm which commands are defined after you've edited and reloaded the . The commands are listed in the order in which they are defined in the configuration file. This allows most frequently used commands to appear at the top of the menu by defining them first in the . If no commands are defined, either because the contains no Command Definitions or because the cannot be opened for some reason, the Commands Menu will be disabled (grayed out).
keeps track of every directory visited. The previously described command to move "Back" one directory allows directory navigation in reverse traversal order - you can back up to where you started. However, this feature "throws away" directories as it backs up, sort of like an "undo" function.
The "Directories" menu provides a slightly different approach to the same task. It keeps permanent track of every directory visited and displays that list in sorted order. This provides another way to move directly to a previously visited directory without having to manually navigate to it again, back up to it, or name it explictly using the Change Directory command.
Unless MAXMENU is set to 0, the Directory Menu shows the last MAXMENU directories visited in alphabetically sorted order (unless you change MAXMENUBUF to be smaller than MAXMENU). "Visited", in this case, is stretching things a bit. All Directory Shortcut locations are also preloaded into the Directory Menu when the program starts even though they have not yet actually been visited.
The Directory Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y)
keeps track of every command you attempt to execute, whether it is an invocation of a Command Definition found in the or a manually entered command via the RUNCMD key. (default: Control-z) This is done whether or not the command is successfully executed.
This feature provides a quick way to re-execute a command you've previously run. When you select a command to run this way, a dialog box is opened, giving you an opportunity to edit the command before running it again.
One important point of clarification is in order here. If you run one of the commands defined in your , it is stored in the History after all variable substitutions have been made. But, manually entered commands are stored in the History literally as typed - i.e., Without variable substitution. This allows you easily reuse a manually entered command in another directory or context. (Presumably, Command Definitions in the are written in such a way so as to be useful across many different directories and contexts. Running such a command again is simply a matter of pressing its associated letter key once more. By storing the resolved version of the command in the History, you can see what the command actually did.)
The History Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y)
This menu provides a way to select any of the available sorting options. It is context-sensitive and will show entries appropriate to what kind of "view" the program is currently displaying. That is, it will show options which make sense for both "normal" view as well as "Drive List View" (see the ADVANCED WIN32 FEATURES section below).
You'll find the currently selected sorting options displayed in the program titlebar.
(Note that on Win32 you must press Alt then Control then Right-Mouse-Button for this to work. Win32 appears to care deeply about keystroke order.)
This menu provides a list of all previously used selection "wildcard" regular expressions. Any regular expressions defined in the (see below) using the "WILDCARD = " statement will also appear in this menu. This saves you the tedium of constantly having to enter complex regular expression syntax every time you wish to do wildcard-based selections.
Selecting something from this menu brings up a dialog box which allows you to edit the selected wildcard before using it.
Bear in mind that the size of the displayed menu is governed by the MAXMENU and MAXMENUBUF options (see below). i.e., Only the last MAXMENU number of wildcards are actually displayed on the menu.
The Wildcard Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y) This history is not cleared if the is reloaded.
This menu provides information about various internal settings of including User-Defined Variables, Command Definitions, Internal Program Variables, User-Settable Options, Keyboard Assignments, and Directory Shortcuts. It also has an About feature which provides version and copyright information about the program.
For the most part, this help information should fit on screen easily. However, very long Command Definitions will probably not fit on-screen once User-Defined and Environment Variables have been substituted. In this case, if you are curious about just how is interpreting your Command Definitions, invoke the program with the relevant debug bit turned on and watch the output on stdout as runs.
Much of s flexibility comes from the fact that it is a macro-programmable user interface. The program itself does little more than provide a way to navigate around a filesystem. It must be configured (programmed) to actually do something with the files you specify. This is done via a "". This file is also used to set Program Options and change keyboard assignments. Although the program will run without a present, it will warn you that it is doing so with no commands defined.
By default, the program expects to find configuration information in $HOME/.twander (%HOME%\\.twander on Win32) but you can override this with the -c command line option. (Recommended for Win32 systems - see the section below entitled, INSTALLING )
Actually, can look in a number of places to find its . It does this using the following scheme (in priority order):
s consist of freeform lines of text. Each line is considered independently - no configuration line may cross into the next line. Whitespace is ignored within a line as are blank lines.
There are several possible legal lines in a Configuration File:
Comments Program Option Statements Key Binding Statements Directory Shortcut Statements Wildcard Statements Variables And Command Definitions Conditional Processing Statements The Include Directive
(See the ".twander" file provided with the program distribution for examples of valid configuration statements.)
Everything else is considered invalid. will respond with errors or warnings as is appropriate anytime it encounters a problem in a . An error will cause the program to terminate, but the program continues to run after a warning. For the most part, tries to be forgiving and merely ignores invalid configuration statements (after an appropriate warning). It only declares an error when it cannot continue. This is true both when the program initially loads as well as during any subsequent reloads initiated from the keyboard while running .
The following sections describe each of the valid Configuration File entires in more detail.
A comment is begun with the "#" character which may be placed anywhere on a line. Comments may appear freely within a . strictly ignores everything from the "#" to the end of the line on which it appears without exception. This means that "#" cannot occur anywhere within a User-Defined Variable Definition, Key Binding Statement, or Command Definition (these are described below). Comments can be placed on the same line to the right of such statements.
It is conceivable that the "#" character might be needed in the Command String portion of a Command Definition. provides a Built-In Variable, [HASH], for exactly this purpose. See the section below entitled, Variables And Command Definitions, for a more complete description.
Many of s internal program defaults can be overriden in the using Program Option statements. These statements look just like the User-Defined variables described later in this document except recognizes the variable name as a Program Option rather than an arbitrary variable. Program Option Statements thus take the form:
Option Name = Option Value
The Option Name is case-sensitive and must be entered exactly as described below. For instance, understands "AUTOREFRESH" as a Program Option, but will treat "AutoRefresh" as a User-Defined Variable.
The Option Value is checked to make sure it conforms to the proper type for this variable. The Type can be Boolean, Numeric, or String.
A Boolean Option must be assigned a value of True or False. These logical values can be in any case, so TRUE, TRue, and tRue all work. Note that when you view these variables in the Help menu entitled, User-Settable Options, they are displayed as 0 (False) and 1 (True).
A Numeric Option must be a number 0 or greater. Numbers can also be entered in hexadecimal format: 0xNNN, where NNN is the numeric expression in hex.
A String Option can be any string of characters. Quotation marks are treated as part of the string! Do not include any quotation marks unless you really want them to be assigned to the option in question (almost never the case).
Furthermore, as described above, you cannot use the '#' symbol as part of the string assignment because always treats this character as the beginning of a comment no matter where it appears.
For consistency with other entries, Program Option Statements may have a blank Right Hand Side. Such statements are simply ignored. This is convenient when you want to leave a placeholder in your but don't actually want to activate it at the moment. However, be careful - depending on what precedes the statement, you'll get different settings for the option in question. For example:
# This effectively sets BCOLOR to its default value when # the is reloaded BCOLOR = # But this means the value of BCOLOR is set to red BCOLOR = red BCOLOR = In other words, you should think of Program Option Statements with a blank Right Hand Side as comments - present but ignored. Other than this basic type-checking, does no further validation of the Right Hand Side of a Program Option Statement. It is perfectly possible to provide a RHS which passes s type validation but which makes no sense whatsoever to the program. Entries like this cause everything from a mild warning to a spectacular program failure and Python traceback on stdout: # A Nice Way To Clobber BCOLOR = goo
The following sections document each available Program Option using this general format:
Option-Name [Type] (Default Value)
By default, regularly re-reads the current directory to refresh the display with any changes. If you are running on a very slow machine or slow connection between the X-Windows server and client, set this option to False. You can manually force an update at any time using the REFRESH key. (default: Control-l)
Selects the main display Background Color.
This option is primarily intended for people running on Unix-like operating systems like FreeBSD and Linux. As described in the GOTCHAS section below, running a command line program or script requires some extra effort if you want to see the results presented in a GUI window. Typically, you need to run these commands in some kind of 'xterm' context so that the results will be visible, possibly using a shell as well. So, it's common to see Command Definitions like:
x MyCommand xterm -l -e bash -c 'stuff-for-my-command'
In fact, on Unix, the need for this idiom is so common, it's best to define some variables for this. If you look in the example '.twander' provided in the program distribution, you'll see something like (comments removed):
SHELL = bash -c VSHELL = [XTERM] [SHELL] XTERM = xterm -fn 9x15 -l -e
Now the Command Definition above becomes:
x MyCommand [VSHELL] 'stuff-for-my-command'
That's all well and good for Command Definitions, but what happens when you want to manually enter a command via the RUNCMD key? (default: Control-z) You have to manually enter the gobbledy-gook above, or at least start your command with [VSHELL] (since RUNCMD understands variable references).
The CMDSHELL option is a way to automate this. You can assign it to any literal text. That text will be automatically prepended to any command you enter manually. In this case you could do either of the following in the :
CMDSHELL = xterm -l -e bash -c
- or -
CMDSHELL = [VSHELL] # Assuming VSHELL is defined previously
Now every time you enter a command, this will be placed in front of your text before command execution commences.
To disable CMDSHELL operation permanently, just remove the statement above from your . If you want to leave it in as a placeholder, but deactivate CMDSHELL, use the following statement:
CMDSHELL =
You also may want to occasionally use RUNCMD to do something without CMDSHELL processing, even though that feature has been defined in the . You can disable CMDSHELL operation on a per-RUNCMD basis. Just begin your entering your command with the double-quote (") character. understands this to "escape" CMDSHELL processing.
As a general matter, CMDSHELL allows you to prepend anything you like before a manually entered command - literal text, references to variables, or even the name of a script the system will use to execute your command. Whatever value you use for CMDSHELL will appear in the Command Menu history for each manually initiated command which used this feature - i.e., All the manual commands that did not escape the feature.
This is another way to set the debugging level you desire (the other way being the -d command line argument). For example, say you want to always dump the current Command Definitions to stdout when the program starts - perhaps you want to redirect this output to a file or printer. Just add this line to your :
DEBUGLEVEL = 0x004
Selects the main display Foreground (Text) Color.
Selects the main display Font Name.
Selects the main display Font Size.
Selects the main display Font Weight. This can be assigned to: normal, bold, italic, or underlined. Depending on your system, other values may also be possible.
Selects the help menu Background Color.
Initial vertical size of the window in pixels.
Selects the help menu Foreground (Text) Color.
Selects the help menu Font Name.
Selects the help menu Font Size.
This selects the help menu Font Weight.
Maximum number of entries to display in any dynamic menu. This keeps the menu size reasonable. Internally, keeps track of way more than this number of dynamic entiries (see the MAXMENUBUF option below).
Number of times a Command Definition is processed to dereference all variables. For example, suppose you have this:
FOO = bax BAM = x[FOO] x mycmd [BAM] [SELECTION]
When you press the x key, the command interpreter has to process the line repeatedly until all variables are resolved:
[BAM] [SELECTION] -> x[FOO] [SELECTION] x[FOO] [SELECTION] -> xbax [SELECTION] xbax [SELECTION] -> xbax selected-item
So, in this case, it took 3 iterations to do this. MAXNESTING merely sets the maximum number of times this is permitted. We have to do this to stop runaway definitions like this:
FOO = x[FOO]
This kind of construct will cause to iterate MAXNESTING number of times and then give up with a warning about exeeding the nesting (dereferencing) limit.
A 32 iteration limit should be plenty for any reasonable Command Definitions. If you set MAXNESTING to 0, will not allow any variable dereferencing, including the Built-In Variables. This is probably not what you want.
Selects the Menu Bar color.
Selects the menu Background Color.
Selects the menu Foreground (text) Color.
Selects the menu Font Name.
Selects the menu Font Size.
Selects the menu Font Weight.
Prevents details from ever being displayed.
Prevents the user from navigating out of the starting directory. Command Definitions and commands initiated manually via RUNCMD (default: Control-z) can still "see" other directories, the user just cannot move elsewhere with any of the navigation commands.
The NODETAILS and NONAVIGATE commands are not security features. They can easily be defeated by editing the . They exist to make it easy for you to create 'twander' configurations for technically unsophisticated users.
Say you want to define a few simple commands for your boss to use which won't challenge his or her feeble managerial mind ;) By defining these commands and setting both NODETAILS and NONAVIGATE to TRUE, you really limit what can be done with . They can't wander off into other directories and get lost, or worse yet, clobber files they don't understand. There are no details to confuse them. Your instructions for using the program thus become, "Select the files you're interested in and press P to print them, M to mail them to Headquarters.." and so on.
Again, these are NOT security features. Anyone with even very modest technical skills can thwart these limitations. But, it is suprising just how effective these can be in simplifying life for technically challenged users.
As described below, ordinarily quotes most Built-In Variables as it replaces them during command processing. This is useful because modern operating systems allow file and directory names to have spaces in them. Such names must be quoted for most programs to understand them as a single entity on a command line.
By default, the double-quote char is used for this purpose. You can suppress quote processing by using the -t command line argument. This does nothing more than set QUOTECHAR to an empty string. Unfortunately, since the RHS of a Program Option Statement cannot be blank, you cannot disable quoting with this option. However, you can set the quotation character to be anything else you like, such as a single-quote. In fact, you can set QUOTECHAR to any string of characters you like and they will faithfully be used on either side of a Built-In Variable replacement.
Nominal time in milliseconds between automatic directory refreshes (if AUTOREFRESH is True). This time is really nominal and should not be used with any accurate timing in mind. REFRESHINT=8000 says that the refresh interval will be nominally 8 seconds (and certainly more than the default of 5 seconds), but it can be off this nominal value by quite a bit.
If you run on a slow system (or have a slow link between X-Client and X-Server) you might want to increase this value substantially. You can get into the situtation where just as one refresh completes, its time to do the next one, and the will seem really sluggish and unresponsive. By lengthening the time between automatic updates, the amount of unresponsive behavior is reduced. Of course, this also means that any changes in the currently viewed directory will also take longer to appear in the display.
Specifies which field is to be used as the sort key. May be one of the fields below under "Sort Key" (case-insensitive). The equivalent field name for Drive List View (see ADVANCED WIN32 FEATURES section below) is shown in the second column, however these may not be used as arguments for SORTBYFIELD. For example, if you plan to start the program in Drive List View and want to sort by Drive Type, use: SORTBYFIELD=Links.
Equivalent Sort Key Drive List View Field -------- --------------------- No Sort No Sort Permissions Label/Share String Links Drive Type Owner Free Space Group Total Space Length Drive Letter Time Drive Letter Name Drive Letter
Specifies whether to reverse the sort order or not. If True and SORTSEPARATE is also True, then the directory list will appear at the end of the display in addition to being reverse ordered.
Determines whether directories and files should be separated or mingled in absolute sort order in the display. By default, they are separated with directories sorted according to SORTBYFIELD order but appearing before any files in the display.
This option is ignored in Drive List View.
This allows you to force a starting directory of your choice no matter where the program actually is launched. This is useful for day-to-day operation - perhaps you always want to start in your home directory. STARTDIR is also handy in tandem with the NODETAILS and NONAVIGATE options to force a user to the only directory which they should be using.
Initial horizontal offset of the window in pixels.
Initial vertical offset of the window in pixels.
defaults to using normal "heavy weight" processes for running commands on Unix. Many Unix implementations also support a "threaded" process model. Setting USETHREADS to True on such systems will cause to use threads, rather than processes to launch user-defined commands. There are some known issues with thread-based operations (hence the reason this option defaults to False). These are discussed in the GOTCHAS section below.
This option applies only to Unix-like operating systems. Win32 commands are always run as a thread - this is the only process model Win32 supports..
Win32 only. If is installed, determines whether its features should be used (see section below entitled, ADVANCED WIN32 FEATURES for details).
Normally, this option should be left alone. However, if you have installed on your system for some other reason, but don't want it used by , set this option to False.
The main reason to do this would be on a slow machine with very large directories. The advanced features of come at a computational price. This is especially noticeable when it is computing the attributes, ownership, and size in a directory with hundreds (or more) of entries. Typically, you would just use the TOGWIN32ALL key (default: Control-w) to temporarily disable these features before entering such a directory. However, if your starting directory is in this category, setting USEWIN32ALL=False might not be a bad idea.
Determines whether interactive warnings should be displayed as encounters them (while parsing a Configuration File or just in normal execution).
Setting this option to False is the same thing as using the -q command line option with one important difference: The is parsed before the command line is parsed. Even if you have -q on the command line (or in the TWANDER environment variable), if there is an error in your , you will see warning messages at program startup time. Putting WARN=False at the top of your will suppress this.
It is not recommended that you operate normally with the -q flag or with WARN=False. is pretty forgiving in most cases and when it does warn you about something, there is a good reason for it - you probably want to know what the problem is.
Initial horizontal size of the window in pixels.
A few general notes about Program Options are worth mentioning here:
Most systems attempt some kind of "best fit" font matching. If you specify a font size/weight/name that does not exist, the system will try to find what it thinks is the closest match. This is usually ugly, so try to specify font information for things that actually exist on your system.
If your setting in the seems not to work, take a look at the command window in which you started (or start it from one manually, if you're using a GUI shortcut to start it). Attempts to use unavailable colors and weights will cause Python/Tkinter to dump traceback information on stdout.
Say MAXMENU is set to 4, but you've actually visited 20 different directories and issued 30 commands. You'll only see 4 of each on the associated menus. But, if you edit MAXMENU to now be 32 and reload the , you will see all 20 directories and 30 commands on their respective menus.
x mycmd MyPythonScript [DSELECTIONS] other stuff
When MyPythonScript runs, it can immediately tell which arguments came from (the ones that are in the form +++dir+++ or +++file+++) and which arguments are just other stuff.
You probably won't need this often, but its nice to have.
No program that runs in many operating environments can satisfy everyone's (anyone's!) idea of what the "correct" key bindings should be. An emacs user, vi user, BSD user, and Windows user are going to differ considerably on what keys should be bound to what feature. ships from the factory with a set of default key bindings, but it also provides a mechanism for changing these bindings via entries in the .
This feature is available only for Keyboard Assignments. Mouse Button Assignments may not be changed by the user. An attempt to do so in the will cause to display a warning and ignore the offending line.
It is not difficult to override the default keyboard bindings by adding entries in the . Doing so requires some familiarity with how Tkinter names keystrokes. Good resources for learning this exist abundantly on the Internet, among them:
http://www.pythonware.com/library/tkinter/introduction/index.htm http://www.nmt.edu/tcc/help/pubs/lang.html http://www.cs.mcgill.ca/~hv/classes/MS/TkinterPres/
(As an aside - Tkinter is nothing more than a Python interface to the Tcl/Tk windowing system. The "real" naming conventions for keystokes can be found in the many sources of Tk documentation, both in print and on the Internet.)
Keyboard binding assignments look just like variable definitions in the . (The parser automatically distinguishes between Key Binding Statements and Variable Definitions or other legitimate statements. This means you can never use one of the program function names as one of your own variable names.) Key Binding Statements thus take the form:
Program Function Name = Tkinter Keystroke Name
Changing the default bindings is therefore nothing more than a matter of assigning the appropriate Program Function Name (found in parenthesis next to the description in the default descriptions above) to the desired keystroke.
Examples of all the default key bindings are shown as comments in the ".twander" example supplied in the program distribution. The easiest way to rebind a particular function is to copy the relevant line, uncomment the copy, and change the right side of the assignment to the new key you'd like to use.
It is important to observe several rules when rebinding keys:
# Incorrect QUITPROG = '<F3>' # Correct QUITPROG = <F3>
QUITPROG = something-or-other
Because you want to be able to reference [QUITPROG] in a subsequent Command Definition. will actually interpret this as just another key binding command, in this case binding the program function QUITPROG to "something-or-other" - probably not what you intended. Moreover, if you have a Command String somewhere with [QUITPROG] in it, will declare and error and abort because it has no User-Defined variable of that name in its symbol table.
provides a mechanism for directly navigating into one of 12 frequently used directories. 12 keys, KDIRSC1 ... KDIRSC12 (default: F1 ... F12) have been set aside for this purpose. Directory Shortcut Statements are entries in the which associate one of these keys with a particular directory path. These statements are in the form:
DIRSCxx = path where, xx is a number from 1-12
So, for example, if you want to enter "C:\Documents And Settings" when you press the F5 key, you would add this to your Configuration File:
DIRSC5 = c:\Documents And Settings
There are several subtleties to Directory Shortcuts you should understand:
# This "undefines" shortcut #5 DIRSC5 =
As discussed above, provides powerful regular expression-based "wildcard" selection capabilities via the SELWILD command. (default: Control-\) These regular expressions can be complex and tedious to enter by hand each time you need them. You can pre-define frequently needed wildcard strings in your Configuration File using the following statement:
WILDCARD = regular-expression-string
This regular expression will then be pre-loaded into the Wildcard Menu (making it easy to invoke by just clicking on it) when starts. You may place as many of these as you like in your . (Though the menu will be limited to displaying MAXMENU number of items - see the section above on Program Option Statements.)
Most programs "ship from the factory" with a pre-defined set of features or commands. comes with no built-in commands! Instead, it comes with a mechanism which allows you to specify your own Command Definitions. By means of a simple and very powerful macro lanuage, you "program" and equip it with commands of your own choosing. For example, you might define commands to copy, delete, edit, and move the files or directories you choose. Perhaps you have a specialized shell script for doing backups. It's a simple matter to write a Command Definition that will pass the names of the files and directories you've selected to that backup script. You might combine this with 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 once you've programmed to suit your needs, actually using 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.
User-Defined Variables are defined using the syntax:
Variable Name = Replacement String
Environment Variables are referenced using the syntax:
[$VARIABLE]
Say we have a configuration line like this,
EDITOR = emacs blah blah blah blah
Later on, when defining a command, instead of typing in "emacs blah blah blah blah", you can just refer to the variable [EDITOR] - the brackets indicate you are referring to a previously defined variable.
Similarly, suppose you have an environment variable called "EDITOR" which indicates your preferred editing program. Our definition could thus become:
EDITOR = [$EDITOR] blah blah blah blah
Why bother with this? Because it makes maintaining complex s easier. If you look in the example ".twander" provided in the program distribution, you will see this is mighty handy when setting up complex "xterm" sessions, for example.
Here are several other subtleties regarding User-Defined Variables:
NewVar = somestring [OldVar]
It is important to realize that this only means: "If you encounter the string '[NewVar]' 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 defined. Evaluation of a variable only takes place when the variable is 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).
Var1 = Foo Var2 = Bar FB = [Var1][Var2]
Later on (when defining some command) when runs into the variable reference [FB], it will keep substituting variables until all [...] references have been resolved or it hits the nesting limit (The default is 32, but you can change it with the MAXNESTING option). This limit has to be imposed to catch silly things like this:
Var = a[Var]
This recursive definition is a no-no and will be cause to generate an error while parsing the and then terminate.
Your variable definitions can also nest other kinds of variables (Environment and Built-Ins). So, constructs like this are perfectly OK:
Var1 = [$PAGER] Var2 = command-arguments V = [Var1] [Var2] [DSELECTION]
Var1 = foo Var2 = [Var3] # This is just a string substitution, 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]
$MYVAR = some-string
You will never be able to subsequently reference it because, [$MYVAR] tells to look in the current environment, not its own symbol table to resolve the reference. However, note that "$" symbol may appear anywhere else but the first character of a variable name. So, for example, MY$VAR is fine.
For example, you can set a variable to some default value, and then override it if a condition is satisfied:
# Assume we're running on a Unix-like system
MyEditor = [$EDITOR]
# Override this if we're on Win32
.if [.OS] == nt
MyEditor = write
.endif
Command Definitions The heart of the configuration process is creating
of one or more Command Definitions. These definitions are the way user-defined
commands are added to a given instance of . A Command Definition consists
of three fields separated by whitespace:
Command-Key Command-Name Command-String
The Command Key is any single character which can be typed on the keyboard. This is the key that will be used to invoke the command from the keyboard. Command Keys are case-sensitive. If "m" is used as a Command Key, "M" will not invoke that command. Command Keys must be unique within a given . If finds multiple Command Definitions assigned to the same Command Key, it will associate the last definition it finds with that Command Key. 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 the command from the Command Menu. Command Names are case-sensitive ("command" and "Command" are different names), but they are not required to be unique within a given . That is, two different Command Definitions may have identical Command Names associated with them, though this is not ordinarily recommended.
The Command String is any arbitrary string which is what actually tries to execute when the command is invoked.
In its simplest form, a Command Definition looks like this:
# A simple Command Definition m MyMore more somefile
This command can be invoked pressing the "m" key on the keyboard or selecting the "MyMore" entry from the Command Menu - either directly from the menu or from the Command Menu Pop-Up. No matter how it is invoked, will then execute the command, "more somefile".
The problem is that this command as written actually will not give you the result you'd like (...well, on X-Windows - is does work on Win32 as written). (For more details on why, see the GOTCHAS section below.) It turns out that starting a non-GUI program like 'more' in a new window needs some extra work. What we want to do is run 'more' inside a copy of 'xterm'. Now our command looks like this:
# Our command setup to run as a GUI window m MyMore xterm -l -e more somefile
The last example works quite nicely. But, we're probably going to end up using the string "xterm -l -e" over and over again for any shell commands we'd like to see run in a new window. Why not create a User-Defined Variable for this string so we can simplify its use throughout the whole ? Now, our command looks like this:
# 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
This is all very nice, but we'd really like a command to be generic 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:
# 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
It would also be really nice if the command applied to more than just a single file called "somefile". The whole point of is to allow you to use the GUI to select one or more directories and/or files and have your Command Definitions make use of those selections. uses a set of Built-In Variables to communicate the current directory and user selections to the any commands you've defined. Built-In Variables are referenced just like User-Defined Variables and Environment Variables and may be inserted any appropriate place in the Command String. In our example, we probably want the command to pickup whatever item the user has selected via the GUI and examine that item with our paging program. Now our command becomes:
# Our command in its most generic form using # User-Defined, Environment, and Built-In Variables XTERM = xterm -l -e m MyMore [XTERM] [$PAGER] [DSELECTION]
The "DSELECTION" built-in is what communicates the currently selected item from the GUI to your command when the command actually gets run.
has a rich set of Built-In Variables for use in your Command Definitions. The first group of these is used to convey your current directory and items which you've selected to a Command Definition:
[DIR] is replaced with the current directory is viewing.
[DSELECTION] is replaced with the full path name of the item currently selected in the GUI. If more than one item is selected, [DSELECTION] refers to the last item in the group (the bottom-most, not the most recent item you selected).
[DSELECTIONS] is replaced with the full path name of all items currently selected in the GUI.
[SELECTION] is replaced with the name of the currently selected item in the GUI. The path to that file is not included. As with [DSELECTION], if more than one item is selected in the GUI, the name of the last item in the group is returned for this variable.
[SELECTIONS] is replaced with the names of all items currently selected in the GUI. The path to those names is not included.
There are also several special-purpose Built-In Variables which are used for creating more powerful Command Definitions:
Because always recognizes the "#" as the beginning of a comment, there is no direct way to include this character in a Command String. It is conceivable that some commands (such as 'sed') need to make use of this character. The [HASH] built-in is provided for this purpose. Anywhere it appears in the Command String, it will be replaced with the "#" at command execution time. Unlike all the other Built-In Variables, [HASH] is never quoted when it is replaced in a Command String (regardless of whether the -t command argument is used or how the QUOTECHAR Program Option is defined).
[PROMPT:...] allows you to insert an interactive prompt for the user anywhere you'd like in a Command String. The user is prompted with the "Prompt String" and this variable is replaced with their response. If they respond with nothing, it is interpreted as an abort, and the command execution is terminated. This makes commands extremely powerful. For instance, say you want to create a group copy command:
# Copy a group of items to a location set by # the user at runtime UnixCopy = cp -R Win32Copy = copy # Unix Version c UnixCP [UnixCopy] [DSELECTIONS] [PROMPT:Enter Destination] # Win32 Version C Win32CP [Win32Copy] [DSELECTIONS] [PROMPT:Enter Destination]
[YESNO:...] allows you to prompt the user with a dialog containing a Yes/No question and buttons for their response. If the user presses "Yes", command interpretation/execution continues. If the user presses "No", the command is aborted. This is handy when you want to make sure the user really wants to run the command before continuing. For instance, suppose you define a recursive file/directory deletion command. Before running it, it's good to prompt the user to confirm their intentions:
D BigDelete [YESNO:Are You Absolutely Sure About This?] rm -rf [SELECTIONS]
As described previously, implements an advanced notion of a Clipboard called "Program Memories". There is a corresponding group of Built-In Variables which allows the contents of these memories to be used in a Command Definition:
Return the file/directory names currently stored in the indicated memory. For example, to move all the files/directories currently named in the first Program Memory to the current directory we could define a move command like this:
m move mv [MEM1] ./
For
example, another way to express the full path of the currently
selected item is:
# Unix Path Separator
UPSEP = /
#Win32 Path Separator
WPSEP = \
[DIR][UPSEP][SELECTION]
- or -
[DIR][WPSEP][SELECTION]
Be aware that, because of quoting rules, such constructs will result in strings like:
"/mydir"/"myfile"
- or -
C:\mydir\"myfile"This should not generally be a problem with the various Unix shells, and may work for some Win32 commands. However, some Win32 programs (noted in 'notepad') reject this kind of file name when passed on the command line. The workaround (and a generally easier way to do this sort of thing), is to use the [DSELECTION] built-in which returns the full path name of an item as a single quoted string.
g gencopy cp -R [PROMPT:Enter Source] [PROMPT:Enter Destination]
When the user presses "g" (or clicks on "gencopy" on the Command Menu), they will be presented with two prompts, one after the other, and then the command will run.
Most of s power lies in its ability to be customized to each different user and operating system via its . To make this a bit easier to manage, the configuration language recognizes so-called "Conditional Processing Statements". These statements give you the ability to write a single which automatically tailors itself to run 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. keeps track of which '.endif' matches which Condition Test Statement. Like all 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:
#####
# 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
These predefined variables show up as "User Defined Variables" in the various 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:
.if [FOO] == string[BAR]
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.
See the example ".twander" file provided in the distribution for some extended examples of using conditionals in your Configuration File. Also see the GOTCHAS section below for further discussion.
You may include other files in your with the following directive:
.include path-to-file
You may place as many of these statements in your as you wish. The only syntactic requirement is that there must be whitespace between the directive and the file path. makes no attempt to validate that path, and you will see an warning message if the file you specify cannot be opened.
The most common reason to do this is to maintain a "standard" configuration in a separate file which is controlled by the system administrator. This is especially handy on larger systems with multiple users. The system administrator provides a read-only copy of the standard configuration in a place anyone can read it. Everyone is free to use (but not modify) that standard configuration. You are then free to add to, or even override the standard configuration content with statements of your own following the ".include". Suppose you have the following "standard" configuration file available on your system:
# Contents of /usr/local/etc/.twander.global SHELL = bash -c XTERM = xterm -fn 9x15 -l VSHELL = [XTERM] -e [SHELL] DIRSC1 = /usr/local DIRSC2 = /usr/sbin t terminal [XTERM]
Now, you can create your own personal which takes advantage of this standard file, but augments it with additional configuration information of your choosing:
# Contents of $HOME/.twander .include /usr/local/etc/.twander.global DIRSC2 = /etc l ls [VSHELL] 'ls -al | [$PAGER]'
Keep in mind that reads the contents of its in order. In this case, it means that all of "/usr/local/etc/.twander.global" is read and then the rest of "$HOME/.twander" is read. If something is defined more than once, the last definition is what is used. In this case, DIRSC2 is overriden in the local and is ultimately assigned to "/etc". Similarly, you can override previous definitions for User-Defined Variables and even Command Definitions.
As shipped from the factory, runs pretty much identically on various Unix variants (FreeBSD, Linux) and Win32. However, is written to take advantage of Mark Hammond's Python extensions if they are present on the system. These extensions add many Windows-specific features to Python and allow to provide quite a bit more Windows-centric information about files, directories, and drives. You do not have to install for to operate properly on your Win32 system. Installing this package just means you'll get even more features on Win32 than you would otherwise. If you've installed , you can toggle these features on- and off with the TOGWIN32ALL key described above.
You can get the extensions one of two ways. If you've installed the Active State version of Python for Win32, (http://www.activestate.com/Products/ActivePython/) is already installed on your system. If you installed the standard Python release for Win32 (http://www.python.org/download/download_windows.html), you must add to your installation. You'll find the extensions and painless installation instructions at: http://starship.python.net/crew/mhammond/
One important note is in order here: The features enabled by are only available on "true" Win32 systems like Windows 2000 and Windows XP. Earlier versions of Windows like Win98 and WinME emulate portions of the Win32 API and do not implement the advanced security features found in the NTFS file system. Therefore, as noted below, some of these features will not work on any of the older 16-bit Windows operating systems. handles this gracefully without blowing-up so you can safely have installed on one of these older systems to take advantage of the features that do work.
Once you have these extensions installed, will automatically enable three new features otherwise unavailable.
d - Directory A - Archive C - Compressed H - Hidden N - Normal R - Read-Only S - System
You can enter the Drive List View in a number of ways:
1) Select the ".." from the root directory of any drive.
2) Enter the string "\\" from the CHANGDIR dialog.
3) Press the DRIVELIST key. (default: Control-k)
4) Start using "\\" as the starting directory
argument, either on the command line or using the
STARTDIR option.
The "Drive List View" is available on all Win32 variants, however the free/total space values will be incorrect on older systems like Win98.
The Drive List View is a little different than the usual file/directory view. Program behavior (semantics) is thus also slightly different than usual in several ways:
There are several tricky corners of which need further explanation:
attempts to determine the name of the host on which it is running at program startup. This is used in the titlebar display. It first looks to see if the environment variable HOSTNAME is set, and uses that value if it is. If this variable is not set, does a socket call to see if it can determine the hostname that way.
Either of these methods works fine, but the socket call can be very slow if the network is misconfigured or malfunctioning. If is starting very slowly, try setting HOSTNAME explicitly in your environment - this will prevent the socket call from ever taking place. A simple way to do this with 'ksh' or 'bash' is:
export HOSTNAME=`hostname`
(Note the backticks used to execute the 'hostname' program and assign its results to HOSTNAME.)
Be aware that 'bash' claims to automatically set this variable when it starts. However, it does not appear to export it properly on some systems (noted on FreeBSD 4.7 with 'bash' 2.05b). In this case, you have to do this manually as just described even when using 'bash'
On Win32, environment variables are set via the System Properties menu.
is a fairly large Python program and can take a few seconds to load and initialize, especially on older, slower systems. You can speed this up a bit by creating an optimized byte-code version of the program as follows (make sure you have appropriate administrative permission to do this):
1) Go to the directory where the twander.py file is located. 2) Type the following command: python -O 3) Once Python is loaded type: import twander 4) Exit . 5) Exit Python by pressing Control-d on Unix or Control-z on Win32. 6) You will now see a new file in this directory: twander.pyo This file should be significantly smaller than twander.py. 7) Now you can run the program by entering: python twander.pyo on Unix/Win32 or pythonw twander.pyo on Win32. 8) You have to repeat this procedure each time you install a new version of twander.py
Win32 allows file/directory names to contain non-ASCII characters. Python, as shipped, defaults to ASCII only and grumbles mightily when it is asked to deal with a string containing characters with ordinal values greater than 127 (i.e., 8-Bit "extended" ASCII). The solution to this problem is to enable Python to handle non-ASCII strings. This is done by editing a file called "site.py". This file is normally found in:
C:\Program Files\PythonXX\Lib
Where "XX" is the actual version of Python you're running.
Open this file with an editor and look for the following text:
encoding = "ascii" # Default value set by _PyUnicode_Init()
if 0:
# Enable to support locale aware default string encodings.
import locale
Change the if 0: statement to if 1: and the problem will disappear.
When you invoke a command via (whether via a command definition in the or the keyboard shortcut), you generally want it to run in a new window. This turns out to be tricky on Unix-like systems. If the program you are running is GUI-aware, this should not be a problem. However, if you are using to run a command line program or script, you have to take extra care in the formulation of the Command String. In the case of Unix-like systems you have to invoke the command so that it runs in some GUI context. Say you want to use a pager like 'less' to view files. You would expect that this entry might do it:
V view less [DSELECTIONS]
Sadly, this will not work, at least not the way you expect. If you started from a terminal session and use the command above, it will work, but the results will appear in the invoking terminal window, not in a new window as you might expect. If you started from a GUI or disconnected it from the initiating terminal with a 'nohup' ... & invocation, you will get no output. This is not a problem, it is innate to how command line programs run under Unix shell control.
To achieve the desired results, you have to create a new GUI window in which your command can run and display results. The easiest way to do this is to run your command in a new 'xterm' window like this:
V view xterm -l -e less [DSELECTIONS]
Some program further require you to provide a shell so they can execute correctly. For instance, running 'ls' in a command definition requires something like this:
L lshome xterm -l -e bash -c 'ls / | [$PAGER]'
In fact, this idiom is so common, you will see variables defined in the example ".twander" file to simplify such definitions (comments removed):
SHELL = bash -c VSHELL = [XTERM] [SHELL] XTERM = xterm -fn 9x15 -l -e
Now you can write the command above like this:
L lshome [VSHELL] 'ls / | [$PAGER]'
This causes your command line program to execute in an 'xterm' context and under a shell interpreter.
This is not as much an issue on Win32 systems where the first form of the command above works fine. Win32 appears to have no problem invoking a new window whether the command is GUI-aware or not.
However, which terminal window is used for output can be confusing. If you start from a terminal session, all terminal output will be sent to the terminal session you used to invoke the program. The way to work around this is to start from a Win32 shortcut, using 'pythonw.exe' rather than 'python.exe'. Now each time you run a command that needs a terminal session for output, Win32 will automatically create that session for you.
The [PROMPT:...] Built-In Variable is provided to make it possible to write general-purpose commands which interact with the user. For example, you might want to define a directory listing command for Win32 like this:
L DirList dir [PROMPT:Directory Of What?] | more
When the user presses the "L", they are presented with a dialog box into which they enter their directory name or wildcard pattern such as "\*.bat" and everything works as expected.
On Unix-like systems, however, this does not work as expected. Suppose we define the command for these systems to be:
L DirList [VSHELL] 'ls -l [PROMPT:Directory Of What?] | [$PAGER]'
This works fine so long as the user does not enter a wildcard pattern in response to the prompt. Why? Recall that quotes all Built-In Variable substitutions by default. If the user enters this at the prompt:
/kern*
The command tries to execute is:
VSHELL Stuff ... 'ls -l "/kern*" | ... pager stuff
The argument to 'ls' is double-quoted. The Unix shells understands this kind of quoting to mean no expansion of wildcard characters is to be done, which is the exact opposite of what we want.
You might think that the easy way to solve this problem is to turn off argument quoting with the -t command line flag. However, this is not really practical. Quoting is on or off globally in the program. Turning it off means no Built-In Variable substitutions will be quoted. That's fine so long as no directory/file you select via the user interface has a space in the name. However, you are almost certain to run into such files sooner or later. (Recall that the only way to deal a directory/file name with spaces in it as a single argument is to quote that name.)
So, we need a way to leave quoting on but also properly deal with wildcard string entries from the user. Fortunately, because of the richness of Unix shells, there is a simple way to do this: we'll use a "shell variable" to hold the user's response and the shell's ability to handle multiple commands on one line separated by semi-colons:
L DirList [VSHELL] 'UsrResp=[PROMPT:Directory Of What?] ; ls -l $UsrResp | [$PAGER]'
Why does this work? Because the shell interprets (and drops) the double-quotes, when the results of the [PROMPT:...] are assigned to "UsrResp". The later reference to "$UsrResp" returns just the string the user entered without the quotes and the command works as expected.
Interestingly, this problem does not occur when entering text via the RUNCMD dialog. (default: Control-z) Here the text you enter is not part of a Built-In Variable substitution, so it is not quoted. (The exception, of course, would be if you entered a [PROMPT:...] reference in the RUNCMD dialog. In this case, the same problem we've just described could occur.)
Notice our example commands above do not end with "&". These should not be needed on either Unix-like or Win32 operating systems. When a command is executed, starts a process which runs concurrently with itself. This means you should be able to continue using while the new command executes.
If you enable the use of threads by setting USETHREADS to True, you may see locked out while the new command runs - so-called "modal" operation. If this happens, it means your system does not completely or correctly implement threading and you must use conventional "heavy weight" processes (the default) rather than threads.
It appears that some X Windows implementations (noted on XFree86 / FreeBSD) do not correctly destroy an 'xterm' window after a command initiated with -e terminates. This is not a problem - it is an artifact of thread behavior on such systems and only happens if you set USETHREADS=True. The workaround is to use the default USETHREADS=False setting.
Certain Unix programs such as 'less' appear to not work correctly when the window in which they are running is resized. The program seems to not be properly informed that the window size has changed. This seems to be an interaction caused by running such programs as threads rather than processes. Once again, the workaround here is to not change the USETHREADS=False default setting.
You may occasionally see really slow response times when you change to a new directory. This occurs when you enter a huge directory with thousands of file or subdirectory entries. has to to compute the detail information for each of these entries and this can take a lot of time. On a fast machine with modern hard drives and controllers, is able to process several thousand entries in just a second or two. However, a number of factors can significantly slow down this process:
When you combine these factors, it is possible to get really long processing times. One test situation we observed was reading a directory with over 4000 entries on a Win32 CDROM. With processing enabled this took over a minute. By disabling these features, the time came down to under 30 seconds.
It's easy to fall into the trap of treating the configuration capabilities as a real "programming language". It is not, it is a fairly simple macro language that does very little more than string substitutions. Keep the following rules in mind as you edit your configuration:
CondVar = .if [CondVar] .... .endif
FOO = bar x cmd1 command [FOO] FOO = baz y cmd2 command [FOO]
In this example, the first command will be defined as "command bar", but the second will be defined as "command baz".
Watch for this, especially, when using the ".include" directive and then overriding a variable defined in that file.
Common mistakes include:
#####
# Trying to embed a variable where it will never be resolved
#####
DIRSC03 = [$SystemDrive]\Program Files
MYCOLOR = blue
FCOLOR = [MYCOLOR]
#####
# Expecting a conditional variable to be resolved before the test
# Suppose $EDITOR is set to "/usr/local/bin/emacs" ...
#
# The following will be False because [EDT] equals
# the string "[$EDITOR]". It is not replaced
# with "/usr/local/bin/emacs" until [EDT] appears
# in a Command Definition
#####
EDT = [$EDITOR]
.if [EDT] == /usr/local/bin/emacs
...
.endif
# Note, however, that *this* would work because
# Environment Variables are permitted in conditionals ...
.if [$EDITOR] == /usr/local/bin/emacs
...
.endif
#####
# A badly formed condition is ignored (after a warning)
# which means *all the lines following will be processed*
# (until a valid condition statement which is False is
# encountered).
#####
PROCESS = no
SUBPART = no
# We meant not to process the following but all the
# lines up to the next .if statement *are* processed
# because the bad syntax on the next line means it's ignored
.if PROCESS != no
... # Processed!
.if [SUBPART] == yes # *Now* we'll stop
...
.endif
.endif
File/Directory name sorting is done without-case sensitivity on Win32 systems because the underlying operating system does not observe case.
Because this program has not been tested on anything other than Unix-like and Win32 systems, command execution by double-click or pressing Enter is inhibited on all other operating systems by default.
You must have Python 2.2 or later installed as well as Tkinter support installed for that release. In the case of Win32, Tkinter is bundled with the standard Windows Python distribution. In the case of Unix-like systems, you may have to first install Python and then the appropriate release of Tkinter. This is the case, for example, with FreeBSD.
You must install the extensions if you want to use the advanced Win32 features.
You'll find the latest version, and occasionally, Release Candidates of the next version of at:
http://www.tundraware.com/Software/twander
You should check this site regularly for updates and bug-fixes. The 'WHATSNEW.txt' file describes changes since the last public release of the program.
Installation of is fairly simple and takes only a few moments. The most important thing before installing the program is to make sure you have Python 2.2 (or later) with Tkinter support installed on your system.
One other note: However you install the program, it is probably easiest to get started by editing the example ".twander" file to taste. Be aware that this file is shipped with everything commented out. You have to uncomment/edit the section relevant to your operating system: Unix-like or Win32.
If you've installed using the FreeBSD port, all you have to do is copy the example , ".twander" found in /usr/local/share/doc/twander to your home directory and edit it to taste. (You'll also find documentation for 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.
Copy the "twander.py" file to a directory somewhere on your path. (/usr/local/bin is a good candidate). Make sure this file has permissions 755 and owner/group appropriate for your system (root/wheel, root/root, or bin/bin). Copy the ".twander" file to your home directory and edit to taste.
To run the program, just type "twander.py" from a shell prompt.
Red Hat Linux Users Please Note: RH Linux (and possibly other Linux systems) installs two versions of Python. Version 1.52 is called 'python', and Version 2.2 is called 'python2'. requires the latter and will not run on the former. As shipped, invokes Python with the Unix shell "#!" mechanism using the name 'python' - which in this case is the wrong version. You can work around this problem one of several ways:
#!/bin/sh python2 twander.py $*
Red Hat users who have upgraded from earlier Linux versions should also note that you may have files in your home directories owned by owners and groups which are no longer defined in the system! shows the owner and group fields for such files as numbers rather than names. As best as we can determine, this is caused when an RH installation is updated from an older version.
Copy the "twander.py" file to a directory somewhere on your path, or create a new directory to hold this file and add that directory path to the PATH environment variable.
IMPORTANT NOTE TO WIN32 USERS: Windows has the old MS-DOS legacy of assuming that a "." begins a file "extension". Although you can create and read files in the form ".something", it is not recommended because many Win32 programs get confused when they see this. It is also difficult to remove files named this way with the standard Windows programs and utilities. This is especially the case for older Win32 operating systems like Win98. For this reason, it is recommended that you rename the ".twander" default provided in the program distribution to something else like "twander.conf" and use the -c command line option to point to this .
On Win32, where to put the raises an interesting question. Microsoft operating systems normally do not set the "HOME" environment variable, because they have no notion of a "home" directory - Well, they do, but it is called "USERPROFILE" not "HOME". So, you can either create a new user-specific environment variable called HOME yourself (which points to your desired home directory) or you can invoke with the -c argument to explictly declare where it can find its .
You can run the program several ways on Win32 systems:
"C:\Program Files\Python22\pythonw.exe" C:\twander.py \
This runs the program starting at the root directory of the current drive (assuming "twander.py" is located in C:\.
TundraWare Inc. maintains an email list for users to get help and exchange ideas. To subscribe, send mail to:
majordomo@tundraware.com
In the body (not the subject line) of the email, enter the following text, substituting your own email address as indicated:
subscribe twander-users your-email-address
Nowhere is this more apparent than in filesystem browsers. In one corner we have the GUI variants like 'Konqueror' and 'Microsoft Windows Explorer'. These are very easy to use but you pretty much need the mouse in your hand to do anything useful. In the other corner are the text-based file browsers like 'List', 'Norton Commander', and 'Midnight Commander'. These are really efficient to use, but have limited functionality and generally do not operate very well on groups of things.
Both of these approaches also suffer from the well-known interface problem of "What You See Is All You Get" - Each program has a predefined set of commands and the user cannot easily extend these with their own, new commands.
is another approach to the filesystem navigation problem which embraces the best of both the GUI-based approach and the text-based approach. It also provides a rich mechanism whereby each user can easily define their own command set and thereby customize the program as they see fit. This is done with a number of key features:
The consequence of all this is that is an extremely powerful and highly customizable filesystem navigator. Once learned, both navigation and command execution are lightning-fast (or at least, as fast as your machine can go ;) while minimizing dependency on the mouse.
Tim Daneliuk twander@tundraware.com