Documentation for the WIN9X/NT filters

Basename | gets basename from filename.
Decho    | echoes standard input to screen (great for debugging).
Dict     | puts each word of a file onto a separate line.
Lcase    | translate all uppercase characters to lowercase.
Numbey   | number all the lines in a file.
Onespace | removes extra blank lines from a file.
Pad      | pad each line in a file to a fixed length.
Strip    | create comments file from a c source code file.
Sub      | replace one string with another throughout a file.
Sum      | add columns of numbers from a redirected file.
Trim     | trim trailing blanks from each line in a file.
Truncate | truncates a line at first matching char (or space).
Ucase    | translate all lowercase characters to uppercase.
Uniq     | deletes multiple occurances from a sorted list.
Untab    | expand all tabs in a file to blanks.
Unws     | translate a wordstar document to plain text.
Xtodos   | translate Unix text or Apple Text to DOS text.

========================================================================

UNIX has a large number of very useful FILTERS available, which inspired
several of the FILTERS here.  What follows is a short description of
each filter and usage examples for the weirder ones.

------------------------------------------------------------------------

BASENAME

Gets basename from filename.

This filter could be used with a redirected list of filenames to strip
the directory names and extensions and create a stream of base names for
additional input for processing in another program or filter.

------------------------------------------------------------------------

DECHO

Filter to echo to stderr and to stdout at the same time. Use with other
filters when redirecting to show activity or to debug output.

This filter is VERY handy when you are designing a filter string of your
own.  Placing it in your command allows you to see what is going on
without disrupting the command itself. Specificaly, it reads standard
input and sends the data to both standard output AND error output (the
screen.)

        Example:

                DIR *.BAS |TRUNCATE|DECHO|SORT|DECHO|UNIQ >SRTED.LST

This line contains two DECHO commands, one after the TRUNCATE and the
other after the SORT.  This shows you the results of the TRUNCATE
command before SORT sees it, and again afterwards.

------------------------------------------------------------------------

DICT

This filter reads a file of text and sends it out one word to a line.
Non-alphabetic characters are deleted.  If you were to send this file
through DICT what you would see would start with:

                Documentation
                for
                the
                WIN
                NT
                filters

Filter to list individual words, one word per line. Only alphabetic
characters are retained - no case changes are performed. Words must be
longer than 1 character.

Output can be piped through sort to group duplicates, then through uniq
to remove duplicates, to build unique word lists.

------------------------------------------------------------------------

LCASE & UCASE

These two filters work very much alike - they read from standard input
and translate every character to either uppercase (UCASE) or lowercase
(LCASE).  Non-alphabetic characters are not affected.

Both of these filters will also accept a filename on the command line,
which means you don't have to use the redirection symbol "<" to supply
the input data. Note that output data must still be redirected.

        Examples:

                UCASE <BOOK.TXT >BOOKUP.TXT
                LCASE BOOK.TXT >BOOKLOW.TXT
                UCASE TRASH.TXT
                etc...

------------------------------------------------------------------------

LCASE

Uppercase to Lowercase filter.

This program is a filter that translates all uppercase characters to
lowercase.  It will optionally accept a filename to read input from.
All output goes to the standard output device unless redirected.

                Examples:
                  Lcase abc.txt
                      read input from abc.txt,
                      output goes to screen.
                  Lcase abc.txt >abcnew.txt
                      read input from abc.txt,
                      output goes to abcnew.txt.
                  Lcase <abc.txt >abcnew.txt
                      same as previous example
                  Lcase abc.txt | find "abc"
                      translates abc.txt to lowercase
                      and then searches the result
                      for the string "abc".
                      Output goes to screen.
                  find "ABC" abc.txt | Lcase | sort
                      Search abc.txt for all lines that
                      contain "ABC".  Translate all lines
                      selected and sort them, sending output
                      to the screen.

------------------------------------------------------------------------

NUMBEY

Line Numbering Filter.

A filter which will number all the lines in a file. Options are
user-defined increment rate, and formatting style for line numbers
(using long integer).

Originally developed to re-number GWBASIC programs in order to run in
the old interpreter.

     - allows command line override on incrementing.
     - allows command line override on formatting.

------------------------------------------------------------------------

ONESPACE

Convert doublespace to singlespace. This program is a filter that reads
from standard input and removes blank lines. (Blank lines are defined as
more than one cr/lf together.)

         Examples:
           onespace abc.txt
             read input from abc.txt,
           onespace abc.txt >abcnew.txt
           onespace <abc.txt >abcnew.txt
           onespace abc.txt | find "ABC"
           find "abc" abc.txt | onespace | sort

------------------------------------------------------------------------

PAD

A filter that pads whitespace to create a fixed width record for each
line in a stream.

Useful for padding-out a flatfile with trailing blanks. Also truncates
if record is too long... pads to 80 characters by default.

------------------------------------------------------------------------

STRIP

A filter that creates a comments only file from c source code in a file
or a stream. (This documentation was built partially from STRIP filtered
output.)

Useful for stripping multiple files when used in a stream created with
the ffeed (filter feed) program.

    Errata - Does not handle nested comments.
    Errata - Does not handle comments in quotes.

------------------------------------------------------------------------

SUB

A filter that replaces one string with another.

Usage is sub [find] [replace] -i (filename - optional)

------------------------------------------------------------------------

SUM

A filter that adds columns from the console or from redirected input and
writes the total to standard output.

------------------------------------------------------------------------

TRIM

A filter that trims whitespace from the end of each line in a stream.

Useful for trimming a flatfile with trailing blanks or for trimming
trailing blanks from text files before re-formatting and word-wrapping
etc.

------------------------------------------------------------------------

TRUNCATE

This is a filter to truncate each line at the character specified on the
command line or the eol char. If no command line then each line will be
truncated at the first space (which includes leading spaces as well.) If
the character is not found in the line the entire line is passed intact.

Useful to strip trailing comments from a shell-script, or to create a
fixed length line with trailing white spaces for flat file creation by
stripping a "pound sign" or some other eol token.

        Example:

                DIR *.C|TRUNCATE|SORT >C.LST

This line will give you a sorted list of C programs that does not
include extensions.

                FFEED *.PL | TRUNCATE # > PERL.LST

This line will truncate all comments from all Perl scripts. Since it has
been said that 1 line of Perl is worth 20 lines of C and is 20 times as
hard to understand 1 week later, this is unfortunately not a good idea
unless you want to make your code harder to read.

------------------------------------------------------------------------

UCASE

Lowercase to Uppercase filter. This program is a filter that translates
all lowercase characters to uppercase.  It will optionally accept a
filename to read input from. All output goes to the standard output
device unless redirected.

                Examples:
                  Ucase abc.txt
                      read input from abc.txt,
                      output goes to screen.
                  Ucase abc.txt >abcnew.txt
                      read input from abc.txt,
                      output goes to abcnew.txt.
                  Ucase <abc.txt >abcnew.txt
                      same as previous example
                  Ucase abc.txt | find "ABC"
                      translates abc.txt to uppercase and then searches
                      the result for the string "ABC". Output goes to
                      screen.
                  find "abc" abc.txt | Ucase | sort
                      Search abc.txt for all lines that contain "abc".
                      Translate all lines selected and sort them,
                      sending output to the screen.

------------------------------------------------------------------------

UNIQ

This filter reads a SORTED list and removes multiple occurances of
IDENTICAL lines. (A filter that deletes duplicate adjacent lines from a
file or stream. Useful after sorting to remove duplicate lines.)

        Example:

                LCASE BOOK.TXT | DICT | SORT | UNIQ >WORDS.TXT

WORDS.TXT new contains a sorted list of all the different words
contained in BOOK.TXT.

------------------------------------------------------------------------

UNTAB.C

A tabstop filter which takes a command line argument of the number of
spaces per tabstop. Default is 8. Use this to pipe tabfree output to
stdout or a file.

------------------------------------------------------------------------

UNWS.C

WordStar to Plain Text Filter.

A filter which strips the 8 bit ascii formatting used in files created
in the old WordStar WordProcesser.

Output is in the form of plain text with formatting removed. Tested with
WordStar 3 and 4. Avoids wordstar's cludgy blocking, and skips lower
order characters except for line feeds and tabs

------------------------------------------------------------------------

XTODOS.C

Unix to Dos text filter. Translates lf -> cr, lf. Should also work with
Apple text. Transalates cr -> cr, lf. This is handy for processing files
that come-in from the Internet but that have not been translated form
their native mode to MS-DOS style text.

------------------------------------------------------------------------

Licence Agreement
-----------------

You have a royalty-free right to use, modify, reproduce and distribute
these programs and their source code and associated files in any
non-competitive way you find useful, provided that you agree that Bill
Buckels and the other respective authors have no warranty obligations or
liability resulting from said use or distribution in any way whatsoever.
If you don't agree, remove all associated files from your computer now.

Bill Buckels
589 Oxford Street
Winnipeg, Manitoba, Canada R3M 3J2

Email: bbuckels@escape.ca
WebSite: http://www.escape.ca/~bbuckels

March 31, 2000

End of Document
