twander - File Browser
Overview
Synopsis
Options
OTHER WAYS TO SET twander OPTIONS
The Title Bar
Keyboard Use
Notes On Keyboard Arrow/keypad Behavior And Text Dialog Edits
Default Keyboard And Mouse Bindings
General Program Commands
Directory Navigation
Selection Keys
Scrolling Commands
Command Execution Options
Directory Shortcuts
Program Memories
Sorting Options
Wildcard Features
Hiding Dotfiles
Menu Options
Invoking A Menu
Detaching A Menu
Managing The Size Of Dynamic Menus
Commands Menu (Alt-c) [Right-Mouse-Button]
History Menu (Alt-h) [Shift-Control-Right-Mouse-Button]
Directories Menu (Alt-d) [Shift-Right-Mouse-Button]
Shortcut Menu (Alt-u) [Alt-Control-Left-Mouse-Button]
Filter Menu (Alt-f) [Alt-Control-Middle-Mouse-Button]
Select Menu (Alt-l) [Alt-Control-Right-Mouse-Button]
Sorting Menu (Alt-s) [Alt-Shift-Right-Mouse-Button]
Help Menu (Alt-l) [No Mouse Shortcut]
THE twander CONFIGURATION FILE
Location Of Configuration File
Configuration File Format
Comments
Program Option Statements
Key Binding Statements
Directory Shortcut Statements
Wildcard Statements
Variables And Command Definitions
Just When Does A Variable Get Evaluated?
User-Defined Variables And Environment Variables
Execution Variables
Command Definitions
A Simple Command Definition
Forcing Display Updates In Command Definitions
User-Defined Variables In A Command String
Environment Variables In A Command String
Execution Variables In A Command String
Built-In Variables In A Command String
Selection-Related Built-Ins
Prompting And Special-Purpose Built-Ins
Using Variable References Within Prompting Built-Ins
Program Memory Built-Ins
Notes On Built-In Variable Use
Associations
Association Wildcards
A Few Association Subtleties
Associations Differences Across Platforms
Conditional Processing Statements
The Include Directive
Advanced Windows Features
Getting 'win32all'
New Features Supported With 'win32all'
Notes On Drive List View
Disabling 'win32all' Features
Gotchas
Program Starts Very Slowly
Program Loads Slowly
Cannot Enter Certain Directories On Windows
Getting Command Results Displayed In A New Window
Using Shell Wildcards In Command Definitions
Modal Operation Of New Windows
Windows Don’t Disappear On Command Completion
Program Behavior Incorrect When A Window Is Resized
Really Slow Response Times When Changing To A New Directory
Your Configuration File Does Not Produce The Desired Results
Other
Bugs And Misfeatures
INSTALLING twander
Installing Using The FreeBSD Port
Installing Manually On A Unix-like System
Installing Manually On A Windows System
GETTING HELP: THE twander MAILING LIST
Design Philosophy
Copyright And Licensing
Author
Document Revision Information
Wander around a filesystem executing commands of your choice on selected files and directories. The general idea here is that twander provides GUI facilities for navigating around your filesystem, but you define the commands you want available via "Command Definitions" (in the Configuration File). In other words, twander can’t do anything useful until you’ve defined some commands. This document describes how to install and start twander as well as it’s various startup options.This document also describes the format and content of a twander Configuration File. You will find an example Configuration File called .twander in the distribution tarball. All the entries in that file are commented out, so you’ll need to uncomment and edit the ones you want to work with.
If you’re new to twander 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 twander, there is a section near the end of this document entitled INSTALLING twander which describes how the program should be installed.
You can get the latest version of the program and documentation from the twander homepage:
http://www.tundraware.com/Software/twander/
You should check this site periodically for program updates, bug fixes, and enhancements.
Also, you are strongly encouraged to join the twander 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 twander MAILING LIST.
twander [-cdhqrtv] [startdir]
startdir Directory in which to begin. (default: directory in which program was started) If this directory does not exist or cannot be opened, twander will display an error message and abort.
-c path/name of Configuration File Specify the location and name of the configuration file. (default is ~/.twander) If this file does not exist or cannot be opened, twander will display a warning to that effect but continue to run. This is reasonable behavior because twander provides a command to reload the Configuration File without exiting the program (which you would presumably do after fixing the Configuration File problem).
-d debuglevel Start in debug mode dumping the items specified in the debuglevel. (default: debuglevel=0/debug off) twander 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 Filter/Selection Wildcard Lists As They Change (0x100) 9 0x200 Dump Associations Table 10 0x400 Reserved/Unused 11 0x800 Dump Requested Debug Information And Exit ImmediatelyThese 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.
-h Print help information on stdout.
-q Quiet mode - suppresses warnings. (default: warnings on)
-r Turn off automatic refreshing of directory display. (default: refresh on) Normally twander 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 twander 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).
-t Turn off quoting when substituting built-in variables. (default: quoting on) Anytime twander 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.
-v Print detailed version information.
In addition to these command line options, there are two other ways you can set twander 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=-qtFrom 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 Configuration File. This is covered later in this document.
twander evaluates options in the following order (from first to last):
This means, for example, that the environment variable overrides a corresponding setting in the Configuration File, but the command line overrides the environment variable. Furthermore, there are many Program Options which can only be set/changed the Configuration File and are not available in either the environment variable or on the command line.
o Internally set default value of options
o Options set in the Configuration File
o Options set in the TWANDER environment variable
o Options set on the command line
This also means that options set on the command line are not read until after the Configuration File has been processed. So, the -q argument on the command line will not inhibit warnings generated during the reading of the Configuration File. This is best done by adding the statement, WARN=False, at the top of the Configuration File.
If the Configuration File 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 Configuration File and have your changes reflected in a running instance of twander, but it also means that the environment variable/command line arguments are ignored after initial program startup.
twander displays a lot of information about the state of the running program in the main window title bar. From left to right you will see:
o Program name and version number.
o Login name and machine/domain of current user.
o The path of the directory you are currently viewing. If this path length is greater than 60 characters, twander will show the last 60 characters of the path length, prepended with "..." to show that it is truncated. Directories relative to your home directory will have the home directory string replaced with "~" (a common Unix shorthand for "home directory" in order to save title bar space.
o The status of various symbolic link processing options. See the program options, SYMDIR, SYMEXPAND, and SYMRESOLV for a more complete explanation.
o Any "filter" that is limiting which files you see. If you’ve toggled the filter, you will see the word "NOT" before the filter string.
o An indication of whether or not "dotfiles" are currently hidden.
o The total number of files in this directory. The ".." entry is not included in this count.
o The total size of all the files in this directory. The size of the ".." directory is not included in this total.
o They key used to sort the display. If a reverse sort is selected, you will see "-" appended to the end of the key to indicated this. "Sort By: NAME-" means you are doing a reverse sort by name.
o An indication of whether or not directories and ordinary files are being separated in the display.
o An indication of whether or not automatic refreshing is enabled. Anytime refreshing is actually underway, whether automatic, manual, because you are executing a command that forces a refresh, or just because you changed directories, you will see the ’*’ character appended to this field. Ordinarily, this happens so quickly you will not see it. However, on really large directories and/or very slow disks like CDROMs, you’ll see the asterisk stay on for some time. During refresh, the program is locked from user input. On very long refreshes, it can appear to be "hung". This indicator is there just to let you know the program is busy refreshing and all is well.
By design, twander allows you to do almost everything of interest using only the keyboard. Various twander 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 Configuration File, also described below.
Generally, the arrow and keypad keys should do what you would expect on the system in question. On Windows 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 twander 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 twander.
There are several features of twander 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 twander. The general format is:
Description (Program Function Name) Default Key Assignment Default Mouse Assignment (if any) The "Program Function Name" is the internal variable twander 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 twander 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 twander 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 twander 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 Configuration File.
This family of commands controls the operation of twander itself.
Clear History (CLRHIST) Control-y 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.
Decrement Font Size (FONTDECR) Control-[ Decrease font size.
Increment Font Size (FONTINCR) Control-] Increase font size.
These two features allow you to change the display font sizes while twander is running. But, you may not immediately get the results you expect. twander 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, twander subtracts or adds 1 to each of these three values respectively. On systems like Windows 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 Windows using fixed-size fonts, you may have to press these keys repeatedly until twander 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 twander 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 Windows TrueType) as you change the font size with FONTDECR/FONTINCR.
Reloading the Configuration File (READCONF) will reset the fonts to either their default values or any font sizes specified in the Configuration File.
Display Command Menu (MOUSECTX) Right-Mouse-Button 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 Configuration File, via selection in the Command Menu at the top of the GUI, or via selection from the Command Menu.
Windows users should note that, unlike Windows Explorer, the twander 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.
Display Directory Menu (MOUSEDIR) Shift-Right-Mouse-Button 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.
Display History Menu (MOUSEHIST) Control-Shift-Right-Mouse-Button 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.)
Display Shortcut Menu (MOUSESC) Alt-Control-Left-Mouse-Button Displays a list of all user-defined directory shortcuts in a pop-up menu near the mouse. The menu also has "canned" navigation shortcuts to go up a directory, back a directory, to the home directory, to the starting directory, and to the root directory. On Windows systems with the Win32All extensions, there is also a shortcut to the Drive List View.
Display Sorting Menu (MOUSESORT) Alt-Shift-Right-Mouse-Button (Note that on Windows you must press Alt then Shift then the Right-Mouse-Button for this to work. Windows appears to care deeply about keystroke order.)
Displays a list of all the sorting options in a pop-up menu near the mouse.
Quit Program (QUITPROG) Control-q Exit the program.
Re-Read Configuration File (READCONF) Control-r Re-read the Configuration File. This allows you to edit the Configuration File while twander 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 Configuration File is about to be read (initially or on reload) just before the Configuration File is parsed. This means commenting out or removing a Program Option Statement (see relevant section below) in the Configuration File 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.
Refresh Display (REFRESH) Control-l 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.
Toggle Autorefreshing (TOGAUTO) Control-o Toggle Autorefreshing on- and off. This is handy if you are about to enter a very large directory and/or a very slow disk (like a CDROM). With very large or slow directory reads, twander can end up spending all its time doing re-reads of the directory and never give you time to do anything there. If you find this is consistently the case, then you need to increase REFRESHINT. But for the occasional adventure into very large/slow directories, just toggling Autorefresh off is more convenient.
The state of the Autorefresh feature is displayed on the main window title bar.
Toggle Details (TOGDETAIL) Control-t Toggle between detailed and filename-only views of the directory.
Toggle Between Normalized And Actual File Length Display (TOGLENGTH) Control-0 By default, the program "normalizes" file sizes and expresses them in bytes, Kilobytes, Megabytes, or Gigabytes rather than showing their actual size. This is done everywhere a file size is displayed: on individual files, the total files size displayed on the title bar, and the drive sizes in Win32 Drive List View. This key binding invokes a feature that toggles these size displays between normalized and actual. See the ACTUALLENGTH configuration option below to set the default as you prefer it.
Toggle Sorting Of Symbolic Link Directories (TOGSYMDIR) Control-~ Toggles whether symbolic links pointing to directories should be sorted as directories or as files. This changes the state of the SYMDIR program option (default: True) and updates the title bar "Symlinks:" status field. This is only meaningful if you’ve selected "separated" sorting (SORTSEP) to cluster directories and then files together in the display.
Toggle The Display Of Symbolic Link Targets (TOGSYMEXPAND) Control-! Toggles whether or not to display the targets of symbolic links or to just display the link name by itself. This changes the state of the SYMEXPAND program option (default: True) and updates the title bar "Symlinks:" status field.
Toggle The Display Of Absolute Symbolic Link Targets(TOGSYMRESOLV) Control-@ Toggles whether the targets of symbolic links should be displayed as defined or in absolute path format. This changes the state of the SYMRESOLV program option (default: False) and updates the title bar "Symlinks:" status field. Pressing this key implies you want to see symbolic link targets (either as defined or as "resolved" absolute paths) so this keypress also forces SYMEXPAND to True.
Toggle 'win32all' Features (TOGWIN32ALL) Control-w As described later in this document, twander provides enhanced features for Windows users who also install Mark Hammond’s 'win32all' extensions for Python on Windows. 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 'win32all' 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, twander 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, twander reports the error and aborts.
Change Directory (CHANGEDIR) Control-x 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.
Go To Home Directory (DIRHOME) Control-h 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.
Go Back One Directory (DIRBACK and MOUSEBACK) Control-b Control-DoubleClick-Left-Mouse-Button twander 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 Root Directory (DIRROOT) Control-j Go to the root directory.
Go To Starting Directory (DIRSTART) Control-s Go back to the original directory in which twander was started.
Go Up To Parent Directory (DIRUP and MOUSEUP) Control-u Control-DoubleClick-Right-Mouse-Button Move to the parent of the current directory ("..").
Display Drive List View (DRIVELIST) Control-k This is a Windows-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 Windows AND have the 'win32all' 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 WINDOWS FEATURES.
This family of commands controls the selection of one or more (or no) items in the current directory.
Select All Items (SELALL) Control-Comma 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.)
Invert Current Selection (SELINV) 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 All Items (SELNONE) Control-Period Unselect everything in the current directory.
Select Next Item (SELNEXT) Control-n Select next item down in the directory.
Select Previous Item (SELPREV) Control-p Select previous item up in the directory.
Select Last Item (SELEND) Control-e Select last item in the directory.
Select First Item (SELTOP) Control-a 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.
Mouse-Based Selections 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, twander supports both vertical and horizontal scrolling via scrollbars. This capability is doubled on the keyboard with:
Scroll Page Down (PGDN) Control-v Scroll down one page in the directory listing.
Scroll Page Up (PGUP) Control-c Scroll up one page in the directory listing.
Scroll Page Right (PGRT) Control-g Scroll to the right one page width.
Scroll Page Left (PGLFT) Control-f Scroll to the left one page width.
This family of commands causes twander to actually attempt to execute some command you’ve chosen:
Run Arbitrary Command (RUNCMD) Control-z This is a shortcut that allows you to run any command you’d like without having to define it ahead of time in the Configuration File. 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 twander 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] newdirtwander 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 Windows it is in the form "%NAME%". Instead if having to keep track of this difference, you can just use a twander Environment Variable reference. For instance, assuming the EDITOR environment variable is set, this command works the same on both systems:
[$EDITOR] [SELECTIONS]
Built-in variables are most often used when manually entering commands So, RUNCMD also understands some "shortcut" references to many of the built-ins. You may use:
[D] for [DIR] [DN] for [DSELECTION] [DS] for [DSELECTIONS] [SN] for [SELECTION] [SS] for [SELECTIONS] [1] for [MEM1] [2] for [MEM2] [3] for [MEM3] [4] for [MEM4] [5] for [MEM5] [6] for [MEM6] [7] for [MEM7] [8] for [MEM8] [9] for [MEM9] [10] for [MEM10] [11] for [MEM11] [12] for [MEM12]Of course, the full form is also fine as well.
This shortcut feature is only supported in RUNCMD!!! Configuration File entries must use the full form of all built-in variables. This is a conscious design decision to help enforce some consistency and clarity in the Configuration Files.
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.
As with command definitions in a Configuration File, you can tell twander to force a display refresh after the command has been initiated. You do this by beginning the command with the '+' symbol. So, for example, if you enter,
+mycommandtwander will initiate the command, wait AFTERWAIT seconds (default: 1), and then update the display. See the discussion below entitled, Forcing Display Updates In Command Definitions for a more complete explanation.
This feature may be used in combination with CMDSHELL escaping (also described in the Program Option Statements section below) and the two characters may appear in any order at the beginning of the command line you enter.
Run Selected File / Move To Selected Directory (SELKEY and MOUSESEL) Return (Enter Key) DoubleClick-Left-Mouse-Button If the selected item is a Directory, twander will move into that directory when this command is issued. If the selected item is a file, twander 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 twander (or their group) for the file to be executed.
On Windows, 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 twander determines that it is running on neither a Unix-like or Windows system, double-clicking on a file does nothing.
Run User-Defined Command User-Defined (Single Letter) Key Each command defined in the Configuration File 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.
twander 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 Configuration File. Each of the definitions is associated with one of the following 12 keys:
Navigate Directly To A Directory (KDIRSC1 ... KDIRSC12) F1 ... F12 Pressing one of these keys changes to the directory associated with it in the Configuration File. For more information on this topic, see the discussion of the Configuration File below entitled, Directory Shortcut Statements
Assign Current Directory To One Of The Shortcut Keys (KDIRSCSET) Control-8 As discussed in Directory Shortcut Statements , the directory shortcut keys are associated with particular directories in the twander Configuration File. However, it is possible to temporarily assign them to something else while the program is running. This is handy if you need to temporarily "remember" one or more directories so you can jump back to them with a single keystroke. Think of it as a way to "override" the directory shortcut assignments defined in the Configuration File.
To do this, press the KDIRSCSET key (Default: Control-8). You will be presented with a dialog that asks you to specify which Directory Shortcut you want overwritten with the current directory. You may only enter a number from 1 to 12. You will see an error message if you try to enter anything else.
Any such reassociation of a directory shortcut is temporary. Directory shortcuts are set back to the values specified in the Configuration File if you restart the program or reload the Configuration File (Default: Control-r).
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.
twander addresses these concerns by means of 12 separate "Program Memories". As you use twander, you can add (append) the names of any directories or files in the currently viewed directory by selecting them and then using the appropriate twander 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).
twander 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 Selected Program Memory (MEMCLR1 - MEMCLR12) Control-F1 ... Control-F12 Clear (empty) the selected Program Memory.
Clear All Program Memories (MEMCLRALL) Control-m Clear (empty) all 12 Program Memories at once.
Set Selected Program Memory (MEMSET1 - MEMSET12) Alt-F1 ... Alt-F12 Append the the full path names of the currently selected files and directories to the Program Memory desired.
twander 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 WINDOWS 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 IgnoredAn 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 title bar.
Although twander 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 twander select them for you using so-called "Regular Expressions".
You can do this in one of two ways. A wildcard "filter" only displays files that match the specified regular expression. A wildcard "selection" selects (highlights) the matching entries from the currently displayed list. The general idea is to use filters to limit the number of files you’ll even see in the twander interface and then optionally choose from among them with a wildcard-based selection.
For example, suppose you initiate a wildcard-based selection (SELWILD) with the text, tar. This 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 FILTERWILD dialog:
drwx------twander would display only the entries that are directories with no permissions enabled for group or world users.
The matching string above could also filter/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 wildcard 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. 0So, 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 for wildcard processing. This is a "special" entry that is always present regardless of filtering and never selected with wildcard-based selections.
Notice that these regular expressions are not the same thing as the filename "globbing" wildcards commonly used with Unix and Windows 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 twander 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, these wildcarding tools 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 twander 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 the program from fiddling with your regular expression, by beginning it with the double-quote (") character. twander 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 twander would select only the directories without any group and world access because:
Because regular expressions can get complicated and tedious to type in, any such expression you use is saved in a history available via the Filter and Select Menus (see below). There is also provision for pre-defining frequently used wildcards in your Configuration File (see section below on WILDFILTER= and WILDSELECT= configuration statements) so you don’t have to type them in manually each time you start the program - you can just select them from the relevant menu.
o The leading double-quote (") forces literal interpretation of the regular expression - i.e. It turns off "match anywhere" semantics as just described.
o 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 twander to select an item) the regular expression must be satisfied at the beginning-of-line.
A few points to keep in mind when using wildcard features:
o By default, wildcard matching is case-insensitive on Win32 systems and case-sensitive everywhere else. This is because Windows systems allow case in filenames and attributes, but it is not significant - i.e., The case of a filename or attribute is ignored on Windows systems. You can control this explicitly with the WILDNOCASE configuration option. If you set WILDNOCASE=False, it will force all wildcard filters and selections to be case-sensistive. Setting it to True makes the wildcarding case-insensitive. This option is available for both Unix and Win32 systems so you can set the behavior you like anywhere.
o If you escape a wildcard to force twander to treat it exactly as you defined it, the case-sensitivity set by default or WILDNOCASE is ignored. Escaped wildcards are always treated exactly as you enter them and they are matched against the filename and/or details exactly as they appear.
o Wildcard-based filters are applied against the entire contents of the current directory to determine which files match and should be displayed. But, wildcard-based selections are done against the currently visible files. This is important if you do a filter and then a selection wildcard. The first will select which files to display. The second will select which ones to highlight from the displayed list.
Display Files Matching A Regular Expression (FILTERWILD) Control-equal This will present you with a dialog to enter your regular expression matching criteria described above. After you enter it, twander will only display the files that match. The filter is reset (to no filtering) when you manually referesh the directory - with REFRESH (default: Control-l - or change directories.
Toggle Active Filter (TOGFILT) Control-minus Pressing this once "inverts" any filter currently active. It means "show me the files that don’t match the filtering regular expression." Pressing it again returns the filter to its normal meaning. This is handy when you want to display everything except a group of files. You first filter for the files you don’t want and then press TOGFILT which will display everything except these files.
Select Files Matching A Regular Expression 'Wildcards' (SELWILD) Control-\ This will present you with a dialog to enter your regular expression matching criteria described above. After you enter it, twander will select (highlight) the files that match.
You can also "invert" your selections by using the SELINV key described previously. This is useful when you want to select everything except a group of files. Select the ones you don’t want with a selection wildcard andthen press the SELINV key.
Selections remain in effect until you make another manual selection, clear all selections, or run a command that forces a directory refresh after it runs - i.e., Commands defined with a leading "+".
Display Selection Wildcard Menu (MOUSEFILTERSEL) Alt-Control-Middle-Mouse-Button Display Selection Wildcard Menu (MOUSEWILDSEL) Alt-Control-Right-Mouse-Button (Note that on Windows you must press Alt then Control then the mouse button for this to work. Windows appears to care deeply about keystroke order.)
These keys popup a list near the current mouse cursor of any previously used filtering or selection wildcards respectively. Selecting one of the entries therein pops-up a dialog that allows you to edit the wildcard before actually doing another wildcard filter or selection. This allows use to modify previous wildcards for new use.
By convention on Unix and many other systems, files or directories whose names begin with a dot (’.’) are usually used as configuration files (directories). Unless you specifically want to edit a configuration, you typically do little or nothing with these files. Since there can be quite a few of them on a modern system, it’s helpful to be able to block them from view.
By default, dotfiles are not hidden, but this can be changed with the HIDEDOTFILES configuration option.
By default, files or directories whose names begin with a period (".") are considered dotfiles. You can change this dotfile "introducer" string with the DOTFILE configuration option.
Unlike Wildcard Filters (which test the entire displayed line), dotfile hiding is triggered only by the name of the file or directory.
Toggle Dotfile Hiding (TOGHIDEDOT) Control-9 This toggles dotfile hiding, on- and off. The program starts up with dotfiles visible or hidden as defined by the HIDEDOTFILES program option. Thereafter, TOGHIDEDOT can be used to make these files and directories visible or not.
If you change DOTFILE to some other string, be aware that the test to see if a file (or directory) name starts with this string is case-sensitive. If you set DOTFILE to "De", it will not hide files starting with "de", for example.
The current state of dotfile hiding is displayed in the window title bar, immediately after the Filter information.
Note that even though you cannot see the files with this option enabled, commands you write can still operate on these files. For example, if you define a command that does something like:
c cleandot rm .*~
This command will remove any backup (~) files, whether or not you can see them in the interface.
Although twander 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 twander 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 twander allowing it to be placed anywhere on screen. Even when detatched, these menus remain current and in-sync with twander 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, Filter and Select menus all keep some sort of "history" of what the program has done. Their content thus grows longer as the program is used.
On Windows 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 Configuration File which explains how such options are actually set. The MAXMENU option specifies the maximum number entries that will be displayed in any dynamic menu. (twander 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, twander will not keep track of your last manual entries for the CHANGEDIR, FILTERWILD, 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 Configuration File 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 Configuration File. 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 Configuration File. If no commands are defined, either because the Configuration File contains no Command Definitions or because the Configuration File cannot be opened for some reason, the Commands Menu will be disabled (grayed out).
twander keeps track of every command you attempt to execute, whether it is an invocation of a Command Definition found in the Configuration File 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 Configuration File, 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 Configuration File 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)
twander 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.
The Directory Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y)
This menu provides a way to access any of the Directory Shortcuts defined in the Configuration File. It also provides a number of "canned" navigation shortcuts to go up a directory, back a directory, to the home directory, to the starting directory, and to the root directory. On Windows systems using the Win32All extensions, there is also a shortcut to the Drive List View.
(Note that on Windows you must press Alt then Control then the Middle-Mouse-Button for this to work. Windows appears to care deeply about keystroke order.)
This menu provides a list of all previously used filtering "wildcard" regular expressions. Any regular expressions defined in the Configuration File (see below) using the "FILTERWILD = " 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 Configuration File options (see below). i.e., Only the last MAXMENU number of wildcards are actually displayed on the menu.
The Filter Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y) This history is not cleared if the Configuration File is reloaded.
(Note that on Windows you must press Alt then Control then the Right-Mouse-Button for this to work. Windows 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 Configuration File (see below) using the "SELECTWILD = " 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 Configuration File options (see below). i.e., Only the last MAXMENU number of wildcards are actually displayed on the menu.
The Select Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y) This history is not cleared if the Configuration File is reloaded.
(Note that on Windows you must press Alt then Shift then the Right-Mouse-Button for this to work. Windows appears to care deeply about keystroke order.)
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 WINDOWS FEATURES section below).
You’ll find the currently selected sorting options displayed in the program title bar.
This menu provides information about various internal settings of twander including Internal Program Variables, User-Settable Options, Keyboard Assignments, User-Defined Variables, Command Definitions, and Associations. 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. In this case, if you are curious about just how twander is interpreting your Command Definitions, invoke the program with the relevant debug bit turned on and watch the output on stdout as twander runs.
Much of twanders 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 "Configuration File". This file is also used to set Program Options and change keyboard assignments. Although the program will run without a Configuration File 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 Windows) but you can override this with the -c command line option. (Recommended for Windows systems - see the section below entitled, INSTALLING twander )
Actually, twander can look in a number of places to find its Configuration File. It does this using the following scheme (in priority order):
o If the -c argument was given on the command line, use this argument for a Configuration File.
o If -c was not given on the command line, but the HOME environment variable is set, look for the a Configuration File as $HOME/.twander.
o If the HOME environment variable is not set and a -c command line argument was not provided, look for a file called ".twander" in the directory from which twander was invoked.
twander Configuration Files 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 twander Configuration File:
Comments Program Option Statements Key Binding Statements Directory Shortcut Statements Wildcard Statements Variables And Command Definitions Associations 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. twander will respond with errors or warnings as is appropriate anytime it encounters a problem in a Configuration File. An error will cause the program to terminate, but the program continues to run after a warning. For the most part, twander 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 Configuration File reloads initiated from the keyboard while running twander.
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 Configuration File. twander 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. twander 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 twanders internal program defaults can be overriden in the Configuration File using Program Option statements. These statements look just like the User-Defined variables described later in this document except twander recognizes the variable name as a Program Option rather than an arbitrary variable. Program Option Statements thus take the form:
Option Name = Option ValueThe Option Name is case-sensitive and must be entered exactly as described below. For instance, twander 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.
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 twander always treats this character as the beginning of a comment no matter where it appears.
For consistency with other Configuration File 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 Configuration File 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 Configuration File 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, twander does no further validation of the Right Hand Side of a Program Option Statement. It is perfectly possible to provide a RHS which passes twanders type validation but which makes no sense whatsoever to the program. Entries like this cause everything from a mild twander warning to a spectacular program failure and Python traceback on stdout:
# A Nice Way To Clobbertwander BCOLOR = gooThe following sections document each available Program Option using this general format:
Option-Name [Type] (Default Value)
A few general notes about Program Options are worth mentioning here:
ACTUALLENGTH [Boolean] (False) By default, file sizes , total directory size (on the title bar), and drive sizes in Win32 Drive List view are "normalized". They are expressed in bytes, Kilobytes, Megabytes, or Gigabytes. This keeps the display from getting cluttered with the longer strings required to display the actual lengths in bytes. If you want the program to display the actual lengths for these items by default, set ACTUALLENGTH=True in your Configuration File. You can also "toggle" between normalized and actual size display with the TOGLENGTH key (default: Control-0).
ADAPTREFRESH [Boolean] (True) Whenever a directory is read, the time to do so is tracked. If that time is less than the current value of REFRESHINT - i.e., The directory read took less than REFRESHINT milliseconds to complete - nothing special happens. But, if the actual directory read time takes longer than REFRESHINT milliseconds, twander adjusts the value of REFRESHINT upwards. That way, you’re guaranteed to have time after the read completes to actually do something.
This dynamic adjustment takes place on every directory read. If you go to a slow directory and REFRESHINT gets dynamically adjusted to, say, 25 seconds, when you go back to a faster/smaller directory, REFRESHINT will be reset to its default value. The changing value of REFRESHINT is not shown in the program options help menu. The value there is the one set by default or set in the Configuration File. Think of this as the "base" value for REFRESHINT.
If ADAPTREFRESH is set to False, then adaptive refresh timing is disabled and a directory refresh will be attempted every REFRESHINT milliseconds.
AFTERCLEAR [Boolean] (True) Tells twander to clear any selections in the GUI if a command forces a display refresh after it completes. (See the AFTERWAIT and Forcing Display Updates In Command Definitions sections below). This is done because a command that forces a display update is probably changing the content of the current directory (otherwise, why bother with the update?), and the current selections may no longer be relevant.
Setting AFTERCLEAR to False, will leave the current selections alone after doing a command with a forced update.
AFTERWAIT [Numeric] (1) It is possible to define commands so that a display refresh is forced after a command is invoked (see the section below entitled, Forcing Display Updates In Command Definitions ). The AFTERWAIT option tells twander how long to wait after the command has been initiated before actually doing the refresh. The idea here is to give the command some time to complete before updating the display.
AUTOREFRESH [Boolean] (True) By default, twander 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)
BCOLOR [String] (Black) Selects the main display Background Color.
CMDMENUSORT [Boolean] (False) By default, twander populates the command menu on the menu bar (and the popup command menu) with commands in the order in which they are defined in the Configuration File. This was done so that you could define the most important or most frequently used commands first and they would thus conveniently appear at the top of the menu list. However, if you prefer your command list to be sorted, set the CMDMENUSORT option to True.
Note that the Command Definitions help menu ignores CMDMENUSORT and is always presented in sorted order.
CMDSHELL [String] () This option is primarily intended for people running twander 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' Configuration File provided in the program distribution, you’ll see something like (comments removed):
SHELL = bash -c VSHELL = [XTERM] [SHELL] XTERM = xterm -fn 9x15 -l -eNow 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 Configuration File:
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 Configuration File. 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 Configuration File. You can disable CMDSHELL operation on a per-RUNCMD basis. Just begin your entering your command with the double-quote (") character. twander 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.
DEBUGLEVEL [Numeric] (0) 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 Configuration File:
DEBUGLEVEL = 0x004
DEFAULTSEP [String] (==>) This is the string that separates the prompting text and the default response in {PROMPT: ...} and {YESNO: ...} Built-In Variables. You may change this to any string you like, though doing so is not recommended. Changing DEFAULTSEP will require you to edit any Configuration Files that use these Built-Ins with default responses. In no case should the delimiter string include any of the characters, [ ]{ } since these are used as delimiters in the twander configuration language.
DOTFILE [String] (.) It is a convention on Unix (and other systems) that files or directories whose names begin with a period are program configuration files (directories). twander has the ability to hide these so-called "dotfiles". (See the section above entitled Hiding Dotfiles for the details.) twander treats any file or directory whose name begins with the string defined by DOTFILE as a dotfile for this purpose.
For example, if you set DOTFILE=Xyz, all files or directories whose names begin with "Xyz", will be hidden when you tell twander to hide dotfiles. Notice that if you change this option from its default, you may use any string to be the dotfile "introducer", but it is always treated with case-sensitivity. For instance, in our example, files beginning with "XYZ" would not be hidden.
FCOLOR [String] (green) Selects the main display Foreground (Text) Color.
FNAME [String] (Courier) Selects the main display Font Name.
FSZ [Numeric] (12) Selects the main display Font Size.
FWT [String] (bold) 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.
FORCEUNIXPATH [Boolean] (False) Ordinarily, Built-In Variables and Program Memory References in a command definition are replaced with strings that list one or more files and/or directories. When this substitution is made at runtime, these strings contain the path separator character appropriate for the underlying operating system ("/" for Unix and "\" for Windows).
If you set FORCEUNIXPATH to True, twander will always use the Unix path separator character("/") in these substitutions.
This option is primarily useful when writing command definitions with Unix tools under Windows (such as cygwin) that are fussy about path separator conventions.
This option is only relevant on Windows systems. It is ignored on other operating systems.
HBCOLOR [String] (lightgreen) Selects the help menu Background Color.
HEIGHT [Numeric] (600) Initial vertical size of the twander window in pixels.
HFCOLOR [String] (black) Selects the help menu Foreground (Text) Color.
HFNAME [String] (Courier) Selects the help menu Font Name.
HFSZ [Numeric] (10) Selects the help menu Font Size.
HFWT [String] (italic) This selects the help menu Font Weight.
HIDEDOTFILES [Boolean] (False) Sets whether the program hides "dotfiles" by default. (See previous section entitled Hiding Dotfiles for the details of this feature.) This value can be toggled with the TOGHIDEDOT (default: Control-9) key binding.
INVERTFILTER [Boolean] (False) Invert wildcard filtering. That is, display the entries that do not match the wildcard filtering criteria. You can preset this in the Configuration File as you wish, but the more usual way to change it is via the TOGFILT (default: Control-minus) key binding.
ISODATE [Boolean] (False) Set this to True to display file/directory date and time in ISO 8601 format instead of the default US localized format.
MAXMENU [Numeric] (32) Maximum number of entries to display in any dynamic menu. This keeps the menu size reasonable. Internally, twander keeps track of way more than this number of dynamic entiries (see the MAXMENUBUF option below).
MAXMENUBUF [Numeric] (250) Maximum number of items twander tracks internally for each dynamic menu. This value need normally not be changed. It is present only to bound how much memory twander consumes for this task.
MAXNESTING [Numeric] (32) 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 twander 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-itemSo, 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 twander 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, twander will not allow any variable dereferencing, including the Built-In Variables. This is probably not what you want.
MBARCOL [String] (beige) Selects the Menu Bar color.
MBCOLOR [String] (beige) Selects the menu Background Color.
MFCOLOR [String] (black) Selects the menu Foreground (text) Color.
MFNAME [String] (Courier) Selects the menu Font Name.
MFSZ [Numeric] (12) Selects the menu Font Size.
MFWT [String] (bold) Selects the menu Font Weight.
NODETAILS [Boolean] (False) Prevents details from ever being displayed.
NONAVIGATE [Boolean] (False) 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 twander navigation commands.
The NODETAILS and NONAVIGATE commands are not security features. They can easily be defeated by editing the Configuration File. 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 twander. 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.
QUOTECHAR [String] (double-quote symbol) As described below, twander 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.
REFRESHINT [Numeric] (5000) 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 twander 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 twander 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 twander display.
SORTBYFIELD [String] (Name) 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 WINDOWS 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
SORTREVERSE [Boolean] (False) 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.
SORTSEPARATE [Boolean] (True) 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.
STARTDIR [String] (Directory In Which Program Started) 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.
STARTX [Numeric] (0) Initial horizontal offset of the twander window in pixels.
STARTY [Numeric] (0) Initial vertical offset of the twander window in pixels.
SYMDIR [Boolean] (True) This option causes symbolic links that point to directories to be treated as directories for purposes of sorting. This is relevant when "separated" sorting is selected - i.e., When the directories are sorted separately from files. If SYMDIR is set to False, then symbolic links will be sorted as files, regardless of what the link points to. This option can be set in the Configuration file or toggled from the keyboard with the TOGSYMDIR (default: Control-~) key binding. The status of this variable is displayed on the title bar in the "Symlinks:" field as either a "D" or "F" for directory and file sorting respectively.
SYMEXPAND [Boolean] (True) When displaying symbolic links, twander ordinarily shows both the link name and its target. If you set SYMEXPAND=False, only the name of the symbolic link, not its target will be shown. This effectively causes a symbolic link to be displayed like any other file or directory. This option can be set in the Configuration file or toggled from the keyboard with the TOGSYMEXPAND (default: Control-!) key binding. The title bar status field, "Symlinks:" will display an "E" if this option is True.
SYMRESOLV [Boolean] (False) twander ordinarily displays symbolic link targets as they were defined. That is, targets that were defined relative to the current (or some other) directory, or targets that point to other symbolic links will not be "resolved" to show their absolute path. Instead, the path as defined when the symbolic link was created will be shown. Setting SYMRESOLV=True will cause the absolute path of symbolic link targets to be displayed. This option can be set in the Configuration file or toggled from the keyboard with the TOGSYMRESOLV (default: Control-@) key binding. If you toggle this option with TOGSYMRESOLV, it implies you want to see symbolic link targets in some form (either in resolved or unresolved form), so this keyboard action will also force SYMEXPAND to be True. The title bar status field, "Symlinks:" will display an "R" if this option is True.
USETHREADS [Boolean] (False) twander 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 twander 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. Windows commands are always run as a thread - this is the only process model Windows supports..
USEWIN32ALL [Boolean] (True) Windows only. If 'win32all' is installed, determines whether its features should be used (see section below entitled, ADVANCED WINDOWS FEATURES for details).
Normally, this option should be left alone. However, if you have 'win32all' installed on your system for some other reason, but don’t want it used by twander, 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 'win32all' 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.
WARN [Boolean] (True) Determines whether interactive warnings should be displayed as twander 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 Configuration File 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 Configuration File, you will see warning messages at program startup time. Putting WARN=False at the top of your Configuration File will suppress this.
It is not recommended that you operate normally with the -q flag or with WARN=False. twander 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.
WIDTH [Numeric] (800) Initial horizontal size of the twander window in pixels.
WILDNOCASE [Boolean] (True On Win32 / False Elsewhere) Set’s whether or not case is significant in wildcard filtering and selection. If True, case is ignored, if False, case is significant in these wildcard operations.
o You can set the same option multiple times in a single Configuration File - twander pays no attention. However, only the last (the one nearest the end of the file) instance of that Program Option Statement actually takes effect. This is handy if you want to temporarily change something without modifying your existing configuration. Just add your temporary change at the end of the file. When you’re done with it, just remove it. No need to edit and re-edit your preferred configuration...
o The font colors, weights, and sizes available for your use will vary somewhat by system. For instance, Windows TrueType fonts are effectively available in every size and weight. On the other hand, most Unix-like systems have a more limited palette of fonts and colors with which to work. Most systems should support obvious color names like, red, white, blue, yellow, beige, and so on. Many also support colors like lightgreen, lightblue, etc. At a minimum, you should be able to use normal, bold, italic, and underline for font weights. 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 Configuration File seems not to work, take a look at the command window in which you started twander (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.
o Although you can use proportionally spaced fonts with twander, the result is pretty ugly. twander assumes a fixed width font when it calculates display formatting. Variable-width fonts will cause your display to be ragged and hard to read.
o If you set MAXMENU or MAXMENUBUF to 0, it disables both dynamic menu content and of the last manual entry in the dialogs associated with CHANGEDIR (default: Control-x), FI