STASH v2.02 - Roll Your Own Database Copyright 2000/2006 Michael S. Sanders Email: mjs@nts-online.

net SYNOPSIS: STASH is a minimal, console only, utility for managing small fragments of text like your book or CDROM collection, URLs, etc, from the command line. STASH considers 1 line equal to 1 cell. With that design philosophy in mind the goal here is to: Get in > Get your data > Get out. STASH is not a big time database. Hey - if you use wanna use STASH for much more than cataloging your books, it probably isn't the right choice. REQUIREMENTS: In order to use STASH you'll need: Win9x/NT/ME/XP or greater Pentium class processor or better 16MB of RAM, 64MB recommended A working knowledge of the command line

SETUP: Understand well, STASH is 100% command line driven. This means, in order to use STASH, you must be familiar with the command prompt. When upgrading to a new version of STASH - always - backup your index first elsewise, newer versions of STASH may inform you your index is invalid. To create a plain text backup of all cells (zapped or not), just issue the command: 'STASH D' then delete the index file 'STASH.NDX' and lastly, import your plain text backup: 'STASH I DUMP.TXT' Righty then, assuming you've already unpacked the STASH archive into a folder like 'C:\STASH', then follow these steps: At the Taskbar click: 'Start' and then 'Run' Type 'CMD' (Win9x users type 'COMMAND') Type 'C:' then 'CD STASH' Once in the STASH folder type: 'STASH' for usage information

Note: First time users should run the provided batch file 'EXAMPLE.BAT' to help get you started. SYNTAX: To manipulate data steams, STASH employs single character operators and mnemonics that endeavor to convey the intent of a given expression. For instance: The plus symbol +, directs the program to 'ADD' a cell. While the minus symbol -, is interpreted as 'REMOVE' all matching cells. Here is a canonical list of switches along with their definitions:

STASH [operator|mnemonic] string ? ! + % / @ ~ Z U I P C L R D X string string string string string x y x y string string string file Display matching cells Display non-matching cells Add cell containing string to index Remove string from matching cells Enumerate instances of string Display matching cells containing x or y Replace all instances of x with y in index Execute alias Zap cells matching string Unzap cells matching string Import plain text file into index Pack index deleting all zapped cells Toggle clipboard support ON/OFF Toggle index lock ON/OFF Display report Dump all cells to Dump.txt Example expressions

STASHING YOUR DATA: Chances are that when you catalog something, you do so in associated groups. Let's use a collection of books to further illustrate this train of thought. Books Fiction - The Great Gatsby, F. Scott Fitzgerald ISBN: 0684801523 Books Biography - Theodore Roosevelt A Life, Nathan Miller ISBN: 0688067840 Books History - The Histories, Herodotus ISBN: 0375400613 You'll notice a prefix of 'BOOKS', this gives you a handle of sorts that easily refers to the collection, so: To list all cells containing books: 'STASH ? BOOKS' To filter only biography's: 'STASH ? BIOGRAPHY' You can use any qualifiers you wish like: hardcover, paperback, etc... Here are some typical examples: Display all cells containing 'BOOKS' To save all cells containing 'BOOKS' to file Display all cells containing 'NEW' or 'USED' Display all cells not containing 'BOOKS' Add a new book to the index Remove all instances of 'GENRE' Replace all instances of 'USED' with 'NEW' Enumerate all instances of 'PAPERBACK' Zap all cells containing the phrase 'WESTERN' Unzap all cells containing the phrase 'SCIFI' ALIASES: You can execute commands in STASH by way of easy to remember labels. This is a very handy feature for small, quick commands while in a DOSBOX. The construction of an alias is: ~LABEL~cmd.exe~arg1 arg2 etc... STASH parses up to 3 (and no less than 2) tokens per alias. Recognized tokens are: 'STASH 'STASH 'STASH 'STASH 'STASH 'STASH 'STASH 'STASH 'STASH 'STASH ? ? / ! + @ % Z U BOOKS' BOOKS >>BOOKS.TXT' NEW USED' BOOKS' BOOKS TITLE' GENRE' USED NEW' PAPERBACK' WESTERN' SCIFI'

The label token - ~LABEL The command token - ~cmd.exe The argument(s) token - ~arg1 arg2 You'll notice that each token begins with a '~' this acts as a delimiter telling STASH where it should split each portion of a given alias. While the argument token must begin with a '~', succeeding arguments need not include the delimiter. To create an alias follow these steps: - Add your alias to the index: 'STASH + ~log~notepad.exe~c:\log.txt' - To use it invoke: 'STASH ~ LOG' Here are some more alias examples: ~TXT~command~/k dir /p *.txt ~ROOT~explorer.exe~c:\ ~PRNLOG~notepad~/p c:\log.txt ~URL~http://www.google.com ~EMAIL~mailto:wendy@hotmail.com COLOR: Beginning with version 2.01 you can set your own fore and background colors. When STASH is launched it looks for the existence to two environment variables named: 'STASH.FG', and 'STASH.BG' if you don't want to bother with this, simply do nothing and STASH will use your existing color palette. To customize the colors create an example batch file like the one below: @echo off :: foreground lightcyan set stash.fg=11 :: background blue set stash.bg=1 %comspec% /k stash.exe Any value 0 to 15 will work for either color. If STASH sees that you've set both colors to the same value, your existing colors will be used instead. Here's a table of valid colors: 0 1 2 3 4 BLACK BLUE GREEN CYAN RED 5 7 8 9 10 MAGENTA LIGHTGRAY DARKGRAY LIGHTBLUE LIGHTGREEN 11 12 13 14 15 LIGHTCYAN LIGHTRED LIGHTMAGENTA YELLOW WHITE

MISCELLANEOUS: It's worth remembering that when adding an alias, items containing shell meta characters (<,>,|) can't be entered on the command line since the shell has reserved their use. In order to add aliases containing these meta characters, simply create a plain text file containing your aliases, and issue the import directive: 'STASH I FILE.TXT'

The '@' and '/' directives used by STASH only support a single word per each argument. The example below better explains this condition: Correct - 'STASH @ peas carrots' Incorrect - 'STASH @ apples oranges bananas' You may find that a application or immediately after running an alias you'll need to redefine your alias processor not to exit '/K' or '/C' ~LABEL~command~/k app.exe arg1 arg2 A single cell can contain a maximum of 78 characters (formatted thusly to display one cell per row in text mode). Data streams in excess of this amount will be truncated... Don't be tempted to edit the index with any other editor as the data is not stored in a sequential (line by line) manner. Several bits of info are located in the header of the index that STASH relies on. If you remove or replace a phrase within a given set of cells and the result leaves the cell empty, then the cell will automatically be zapped so the index will not contain any active cells of zero length. When the index is locked, you can view and enumerate cells but not modify them in any way. Be judicious with the pack 'P' directive. Once you repack the index, all zapped cells are gone forever. If the index lock is toggled off, you will not be asked for confirmation... Some STASH directives will operate with little guidance: 'STASH 'STASH 'STASH 'STASH ?' %' Z' ~' will will will will display all non zapped cells. enumerate all non zapped cells. enumerate all zapped cells. display all aliases. intrinsic shell command exits when you'd rather it not. Likely, to explicitly direct your command after shelling out like so:

Clipboard support is limited to 64KB of data to accommodate all versions of Windows. This should be non issue for the bulk of STASH users. Only a single instance of STASH will run at anytime, this prevents file locking errors and insures the integrity of your data. LEGALESE: Command line junkies can use and redistribute STASH without charge upon acceptance of the following provisos: - No warranties, so if you break anything you get to keep both pieces. - The original archive and it's contents are left intact. - Kindly remember that STASH is copyrighted software. And finally, STASH will not make your car payment, stay crunchy in milk or bring back Elvis. It's just a small tool built for the sake of convenience because that's all it has to be. Besides, it really is a nice day outside...

HISTORY: 2.02 - Redefined the alias operator from '^' to '~' to avoid a conflict under WinXp Pro (special thanks to Srdjan Markovic for pointing this out). 2.01 - User definable colors ooh, aaw! Added dump 'D' directive which will dump all cells (zapped or not) to Dump.txt. A subtle change in the manner a cell is validated results in more efficient processing, a bug squashed: previously, if removing or replacing a phrase within a cell resulted in a zero length string, the cell was still active, now the cell is zapped. 2.00 - This is where the rubber meets the road... added binary indexing, new directives: zap, unzap, pack, report, import, lock, clipboard, etc... 1.07 - First release sans company names 'Mike's Software', 'Vega-Tek'. Documentation is now embedded and automagically recreated if missing. 1.06 - A leaner, meaner stash, ported to 32 bit environments. 1.05 - Added aliases '~', various bug fixes. 1.04 - Total re-write, improved error handling. 1.03 - Added search and replace '@', added inverse match '!', rearranged operators for clearer logic, cleaned up help screen. 1.02 - Optimized file I/O, documentation updates. 1.01 - Refined several parsing routines. 1.00 - Initial compilation