OS/2 Shareware BBS: 6 File

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 6 File / 06-File.zip / WIZ114.ZIP / WIZ.DOC < prev next >

Wrap

Text File | 1993-04-02 | 25KB | 734 lines

The Wizard Directory Changing Utility Version 1.14 Reference Manual Copyright 1993 Christopher R. S. Schanck April 2, 1993 Table of Contents ----------------- Welcome to Wiz . . . . . . . . . . . . . . . . . . . . . . . . . 3 The Author & Support . . . . . . . . . . . . . . . . . . . . . . 3 Included Files . . . . . . . . . . . . . . . . . . . . . . . . . 4 Example directory structure . . . . . . . . . . . . . . . . . . . 5 Basic directory traversal Using Wiz . . . . . . . . . . . . . . . 6 Using The Stack to Traverse Directories . . . . . . . . . . . . . 8 How the Stack gets Updated . . . . . . . . . . . . . . . . . 8 Viewing the Stack Contents . . . . . . . . . . . . . . . . . 8 Manipulating the Stack: Clearing Entries . . . . . . . . . . 9 Manipulating the Stack: Popping Entries . . . . . . . . . . 9 Manipulating the Stack: Going to Specific Entries . . . . . 10 Defining, Using, and Deleting directory Nicknames . . . . . . . . 11 Defining Nicknames . . . . . . . . . . . . . . . . . . . . . 11 Deleting Nicknames . . . . . . . . . . . . . . . . . . . . . 11 Viewing Nicknames . . . . . . . . . . . . . . . . . . . . . 12 Using Nicknames . . . . . . . . . . . . . . . . . . . . . . 12 Traveling First Class: Partial Directory Matching . . . . . . . . 13 Partial Matching the First Specification . . . . . . . . . . 13 Partial Matching the Rest of the Input . . . . . . . . . . 13 WIZARD.BAT (WIZARD.CMD for OS/2, WIZARD.COM for VMS) . . . . . . 15 Miscellaneous Features and Notes . . . . . . . . . . . . . . . . 16 The WIZARD.DAT Datafile . . . . . . . . . . . . . . . . . . 16 '-i': the Info switch . . . . . . . . . . . . . . . . . . . 16 '-t': the Tree Display switch . . . . . . . . . . . . . . . 16 '-safe' switch . . . . . . . . . . . . . . . . . . . . . . 16 '-nonick': the No Nickname switch . . . . . . . . . . . . . 16 '-quiet': the Quiet switch . . . . . . . . . . . . . . . . . 16 Implementation Specific Notes . . . . . . . . . . . . . . . . . . 17 Welcome to Wiz -------------- Welcome to the Wizard Directory Changing Utility. I wrote Wiz over the past year in order to relieve some of my frustrations in using MS-DOS's CD command. Later I ported Wiz to Digital Equipment Corp.'s VMS as a replacement for SET DEF; a port to Unix would be pretty easy as well, but I don't have access to a Unix system, so.... More recently, I ported Wiz to OS/2. (Note: Wiz *will* work with HPFS long filenames). Wiz can be described as a 'lazy' directory changing tool. It uses ideas culled from a number of sources -- other tools I have written in the past, other public domain and shareware utilities I have seen or used over the years, and various users comments. Wiz will let you: - retain and manipulate a stack of directory locations - define nicknames for common directory locations - traverse trees using shorthand 'partial' path specifications - automatically execute a command when entering a directory - display a visual representation of a directory structure Wiz is distributed as "freeware". You may freely copy and distribute Wiz, subject to the following conditions: 1) You distribute the executables and documentation file together. 2) You do not alter either the executables or documentation. You are free to distribute Wiz as long as you follow these two conditions. You may charge a nominal fee for this distribution, such as enough to cover disk costs and such. The Author & Support -------------------- Wiz is distributed pretty much on an as-is basis. Bugs will be fixed when they get fixed, and new version released when they get released. Wiz is not a product of mine and I ask for no money for it. You are welcome to contact me if you have questions or suggestions or if you want a differetn version than the one yu have. My address is: Christopher R.S. Schanck PO Box 279 Hanover MD 21076 Phone # (410)379-9019 On Compuserve: 70541,3614 On the Internet: 70541.3614@compuserve.com Included Files -------------- The distribution archive for Wiz includes the following files: wiz.doc : Doc file for all versions of The Wizard read.me : Extra notes and introductory material OS/2 Version: w.cmd : REXX command file wrapper for the OS/2 version of The Wizard wizcore1.exe : Core Wiz OS/2 executable file, called by W.CMD DOS Version: wizdos.com : MS-DOS executable of The Wizard Vax/VMS Version: wizvms.exe : Vax/VMS executable of The Wizard Feel free to rename the executables (for VMS and MS-DOS) and/or the command file (OS/2) to whatever you wish. The OS/2 core executable must be named WIZCORE1.EXE. Example directory structure --------------------------- MS-DOS & OS/2 VMS Drive: c: disk$user01: ---> \ \ [000000] ---> bin \bin [bin] ---> temp \bin\temp [bin.temp] ---> src \src [src] ---> foobar \src\foobar [src.foobar] ---> app1 \src\app1 [src.app1] ---> testapp \src\testapp [src.testapp] ---> help \help [help] ---> hello \hello [hello] ---> apps \apps [apps] ---> swapapp \apps\swapapp [apps.swapapp] ---> games \apps\games [apps.games] ---> tictac \apps\games\tictac [apps.games.tictac] ---> chess \apps\games\chess [apps.games.chess] ---> testapp \apps\testapp [apps.testapp] ---> temp1 \temp1 [temp1] Drive: d: disk$user02: ---> \ \ [000000] ---> test \test [test] Basic directory traversal Using Wiz ----------------------------------- This section will show you how to use WIZ as a drop-in replacement for CD (MS-DOS and OS/2) or SET DEF (VMS). The following examples are in MS-DOS (OS/2) terms, except where noted. These examples assume you have renamed the executable (DOS/VMS) or the .CMD (OS/2) file to be W.(COM/EXE/CMD). Suppose we start at the root directory of drive C:. The current directory is c:\. To change to c:\bin, type: w bin OR w \bin OR w c:\bin Note: For VMS usage, 'bin' == '[bin' == 'bin]' == '[bin]' to make your typing life easier. In MS-DOS, you can use the forward slash '/' in place of the backslash '\' as you wish. You are now at c:\bin. To further change to c:\bin\temp, use: w temp OR w .\temp To return to the root, use: w \ OR w ..\.. To now get directly to the c:\apps\games directory, use: w \apps\games OR w apps\games To go to the root of the D: drive (D:\), use: w d:\ In summary, 'w <path specification>' will work just like CD/SET DEF would, with a couple of noteworthy exceptions: a) MS-DOS (OS/2) - forward slashes '/' equate to backslashes '\', i.e., 'w \' == 'w /' - Wiz will change drives as well as paths, unlike CD. The command 'CD d:\' when you are currently logged will simply change the currently logged subdirectory ****on D:**** to be the root. CD will not log you on the D: drive directly. Wiz on the other hand will move you to the D: drive as well as changing the logged subdirectory of D:. b) VMS - logicals will be handled just as SET DEF would, i.e. no problems. - Wiz will not let you move to a nonexistent directory, though it will let you move to a directory you do not have read access to. - Wiz will let you use shorthand for directory specifications. I.e., these are equivalent: [bin] == bin] == [bin == bin and [.bin] == .bin] == [.bin == .bin Using The Stack to Traverse Directories --------------------------------------- How the Stack gets Updated -------------------------- Every time you move using the method outlined in Section 2 (above) or using the methods covered in sections 4 and 5, Wiz adds the current directory (prior to the move) to the top of the stack. For example, assume we start with the stack empty and the logged directory c:\. Command Stack Contents Move ------- -------------- ---- w bin 1. c:\ from 'c:\' to 'c:\bin' w temp 1. c:\bin from 'c:\bin' to 'c:\bin\temp' 2. c:\ w \ 1. c:\bin\temp from 'c:\bin\temp' to 'c:\' 2. c:\bin 3. c:\ As you can see, prior to Wiz actually change your location, the current location is 'pushed' onto the top of the stack. Wiz will keep at most 20 stack items on the stack; if there are currently 20 items on the stack and Wiz 'pushes' a new item on, the (now) 21st item is lost. Notice also that the drive letter is maintained as well as the path, in keeping with Wiz's methodology as outlined in the previous section. Viewing the Stack Contents -------------------------- It will be useful for you to view the contents of the stack from time to time. To do so, use the '-s' switch. The command: 'w -s' will list the number of items on the stack and each item: 3 entries on stack: 1: c:\bin\temp 2: c:\bin 3: c:\ The '-i' switch will also display stack information in the same format, but it will also display Nickname information. You will see more about nicknames in section 4. Manipulating the Stack: Clearing Entries ---------------------------------------- Occasionally you will need to delete or 'clear' certain entries from the stack. Use the '-c' switch to accomplish this. The '-c' switch does not change the currently logged directory. There are three forms of the '-c' switch. 'w -c' clears the first or top entry from the stack: Before After 1: c:\bin\temp --> 'w -c' --> 1: c:\bin 2: c:\bin 2: c:\ 3: c:\ 'w -c#' where # is an integer from 1-20 will clear entry # from the stack: Before After 1: c:\bin\temp --> 'w -c2' --> 1: c:\bin\temp 2: c:\bin 2: c:\ 3: c:\ 'w -call' will empty the entire stack: Before After 1: c:\bin\temp --> 'w -call' --> <empty> 2: c:\bin 3: c:\ Manipulating the Stack: Popping Entries --------------------------------------- Wiz takes care of automatically 'pushing' entries onto the stack for you, but you can 'pop' entries off of the stack with ease. Use the '-p' switch to accomplish this. Roughly, the '-p' switch 'pops' an entry off of the stack and changes to it. '-p' operations do not add entries to the stack. There are two forms of the '-p' switch: 'w -p' 'pops' the first or top entry from the stack and changes the currently logged subdirectory to it (c:\bin\temp in this case): Before After 1: c:\bin\temp --> 'w -p' --> 1: c:\bin 2: c:\bin 2: c:\ 3: c:\ 'w -p#' where # is an integer from 1-20 will 'pop' entry # from the stack and changes the currently logged subdirectory to it (c:\bin in this case): Before After 1: c:\bin\temp --> 'w -p2' --> 1: c:\bin\temp 2: c:\bin 2: c:\ 3: c:\ Manipulating the Stack: Going to Specific Entries ------------------------------------------------- Popping entries off of the stack is useful, but by its nature it unravels the "history" of subdirectory locations the stack provides. The '-g' switch is similar to the '-p' switch, but it does NOT remove the entry from the stack, it merely changes to it. Further, it DOES 'push' the current location onto the stack before moving, unlike the '-p' switch. There are two forms of the '-g' switch: 'w -g' 'goes' to the first or top entry on the stack (c:\bin\temp in this case), adding the current location to the stack: Starting location: c:\ Before After 1: c:\bin\temp --> 'w -g' --> 1: c:\ 2: c:\bin 2: c:\bin\temp 3: c:\ 3: c:\bin 4: c:\ Ending location: c:\bin\temp 'w -g#' where # is an integer from 1-20 will 'go' to entry # from the stack (c:\bin\temp in this case), adding the current location to the stack: Starting location: c:\ Before After 1: c:\bin\temp --> 'w -g2' --> 1: c:\ 2: c:\bin 2: c:\bin\temp 3: c:\ 3: c:\bin 4: c:\ Ending location: c:\bin Notice that you could use repeated 'w -g' commands to "flip" between two directory locations. Defining, Using, and Deleting directory Nicknames ------------------------------------------------- Nicknames are shorthand names for disk/directory locations. For example, if you repeatedly have to change to c:\apps\games\tictac (because you love to play tic-tac-toe, for example ;-), you will soon tire of typing 'w c:\apps\games\tictac' Suppose you define a 'nickname' for this location? Wiz allows you to define as many as you wish. The following sections will show how to define, use, delete, and view nicknames. Defining Nicknames ------------------ To define a nickname for Wiz to use, use the '-d' switch. The syntax is: 'w -d <nickname> <dir_location>' where <nickname> is the nickname you are defining and <dir_location> is the specification you want <nickname> to stand for. For example: 'w -d home \' defines 'home' as a nickname for the root directory '/' of the current drive. 'w -d ttac c:\apps\games\tictac' defines 'ttac' as the drive and path of the tic-tac-toe game we discussed earlier. 'w -d fbar c:\src\foobar' defines 'fbar' as the specification 'c:\src\foobar' Deleting Nicknames ------------------ Deleting an existing nickname is very simple. The syntax is: 'w -d <nickname>' where <nickname> is the nickname you want deleted. For example: 'w -d fbar' deletes the definition of 'fbar' we defined previously. Viewing Nicknames ----------------- In order to view the list of currently defined nicknames, use the '-n' switch. The command: 'w -n' will list the currently defined nicknames. 3 entries in nickname pool: 1: 'home' == \ 2: 'ttac' == c:\apps\games\tictac 3: 'fbar' == c:\src\foobar The '-i' switch will also display nickname information in the same format, but will also display stack information. Using Nicknames --------------- You do not have to do anything special to use nicknames. In section 2 we showed how Wiz interprets the directory specification just as CD (or SET DEF) does. I.e., 'w \bin' changes to the '\bin' directory. However, before Wiz attempts to change directly to '\bin', it matches it against the nickname pool. For example: 'w home' would be translated to ' w \' changing you to the root directory of the current drive. Furthermore, the input need only match the leading characters of the nickname. For example: 'w ho' 'ho' would match 'home' and be translated to ' w \' changing you to the root directory of the current drive. If you have multiple matches, wiz will notify you and abort the operation. So you want to choose your nicknames with care. Normal stack actions take place, i.e. the current directory is pushed onto the stack before a change is made. Traveling First Class: Partial Directory Matching ------------------------------------------------- We have shown how for the command line 'w <nickname/pathname>' Wiz will try <nickname/pathname> first as a nickname, then directly as a subdirectory specification. If both of these cases fail, a third option is tried. The <nickname/pathname> is tried as a *partial* directory specification, starting from the top of the tree. Partial Matching the First Specification ---------------------------------------- To explain, let us examine the sample tree we started with. The topmost subdirectories are: bin src help hello apps temp1 So, if we use the command line: 'w sr' and there is no 'sr' nickname and 'sr' is not a normal, valid directory specification, the top directories are now checked. A single match is found, 'src'. Wiz will then change to '\src' on the current drive. Suppose we use: 'w hel' and there are no matching nicknames and 'hel' is not a valid directory specification. Now we have a problem, because there are 2 matching directories. Wiz will NOT change to either of them, but it will list all of the matching ones, in this case '\help' and '\hello'. Partial Matching the Rest of the Input -------------------------------------- This is all well and good, but how useful is it to quickly change to your toplevel subdirectories? Not very, if this was the end of Wiz's abilities. But this is just the start. Consider the command line: 'w ap ga ti' Based on what we just learned. Wiz will try 'ap' as a nickname and as a valid directory. It then fails. So it tries 'ap' as a partial, and matches: '\apps' It then processes the rest of the command line as partials also, tacking onto the end of the first match: 'ga' matches '\apps\games' 'ti' matches '\apps\games\tictac' This is much more useful. How about: 'w b te' --> c:\bin\temp' 'w app sw' --> c:\apps\swapapp' Furthermore, remember that the first entry can be a nickname or a specification. This means: 'w . swap' will attempt to match 'swap' below the current directory, since '.' is a legal shorthand for the current directory. 'w ho sr' will translate 'ho' to 'home' to '\' (as a nickname), then match 'sr' as 'src'. This gives you a very powerful, shorthand way to jump around your directory structure. Again, normal stack actions take place, i.e. the current directory is pushed onto the stack before a change is made. WIZARD.BAT (WIZARD.CMD for OS/2, WIZARD.COM for VMS) ---------------------------------------------------- Everytime you change to a directory, Wiz checks for the existence of a file called WIZARD.BAT (WIZARD.COM for VMS). If it finds the file, Wiz automatically executes it as its last and fatal act. This is a nice shortcut for directories where the only reason you change there is to run one specific program. Miscellaneous Features and Notes -------------------------------- The WIZARD.DAT Datafile ----------------------- The Wiz uses a file called WIZARD.DAT to stroe the stack and the nicknames. On MS-DOS systems, this file is stored in the same directory that W.COM/W.EXE itself is. For VMS systems, this file is kept in SYS$LOGIN. There are several other minor command switches which are useful. '-i': the Info switch --------------------- The '-i' switch will cause Wiz to list both the contents of the stack and the contents of the nickname pool. '-t': the Tree Display switch ----------------------------- This will list a hierarchical display of the subdirectory structure starting with the current directory on down, recursively. '-safe' switch -------------- This tells Wiz to ignore WIZARD.BAT (WIZARD.CMD for OS/2, WIZARD.COM for VMS) if found. '-nonick': the No Nickname switch --------------------------------- This tells Wiz not to use the nickname pool '-quiet': the Quiet switch -------------------------- This tells Wiz to display no messages except errors when changing directories. This suppresses Wiz's natural tendency to display 'to' --> 'from' messages when changing directories. Implementation Specific Notes ----------------------------- MS-DOS ------ None. VMS --- None. OS/2 ---- The OS/2 implementation has a hitch to it, in that there is no way for a program to "permanently" change the directory for an instance of CMD.EXE. Therefore, the W.CMD Rexx command file is used as "wrapper" for Wiz itself. You can rename this file to be anything you want; just keep the .CMD file and WIZCORE1.EXE file in the same directory.