STASH.TXT

7/27/2019 STASH.TXT

http://slidepdf.com/reader/full/stashtxt 1/5

STASH v2.02 - Roll Your Own Database Copyright 2000/2006 Michael S. Sanders Email: [email protected]

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:

7/27/2019 STASH.TXT


STASH [operator|mnemonic] string

? string - Display matching cells ! string - Display non-matching cells + string - Add cell containing string to index - string - Remove string from matching cells % string - Enumerate instances of string / x y - Display matching cells containing x or y @ x y - Replace all instances of x with y in index ~ string - Execute alias Z string - Zap cells matching string U string - Unzap cells matching string I file - Import plain text file into index P - Pack index deleting all zapped cells C - Toggle clipboard support ON/OFF L - Toggle index lock ON/OFF R - Display report D - Dump all cells to Dump.txt X - 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' - 'STASH ? BOOKS' To save all cells containing 'BOOKS' to file - 'STASH ? BOOKS >>BOOKS.TXT' Display all cells containing 'NEW' or 'USED' - 'STASH / NEW USED' Display all cells not containing 'BOOKS' - 'STASH ! BOOKS' Add a new book to the index - 'STASH + BOOKS TITLE' Remove all instances of 'GENRE' - 'STASH - GENRE' Replace all instances of 'USED' with 'NEW' - 'STASH @ USED NEW' Enumerate all instances of 'PAPERBACK' - 'STASH % PAPERBACK' Zap all cells containing the phrase 'WESTERN' - 'STASH Z WESTERN' Unzap all cells containing the phrase 'SCIFI' - 'STASH U 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:

7/27/2019 STASH.TXT


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:[email protected]

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 BLACK 5 MAGENTA 11 LIGHTCYAN 1 BLUE 7 LIGHTGRAY 12 LIGHTRED 2 GREEN 8 DARKGRAY 13 LIGHTMAGENTA 3 CYAN 9 LIGHTBLUE 14 YELLOW

4 RED 10 LIGHTGREEN 15 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'

7/27/2019 STASH.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 intrinsic shell command exits immediately after running an alias when you'd rather it not. Likely, you'll need to redefine your alias to explicitly direct your command processor not to exit '/K' or '/C' after shelling out like so:

~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 ?' will display all non zapped cells. 'STASH %' will enumerate all non zapped cells.

'STASH Z' will enumerate all zapped cells. 'STASH ~' will display all aliases.

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

7/27/2019 STASH.TXT


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

Documents

STASH.TXT