Documentation Index Download
Command Line File Handling and ASCII Tools


The filter command maps characters, converts to upper/lower case, trims blanks etc. It can also remove all occurrences of certain characters, and collapse multiple blanks into a single one.

filter can handle multiple input files in a single command, just like the cop command. The default is to read from standard input, which makes it suitable for use with pipes.

> filter 'new/***/*.html' -output='publish/***' -trim
Text Files With Windows Or Linux Line Endings
Text files on Windows are normally encoded so that the lines of text are separated by a carriage-return/newline character pair ('\r\n'). Under Linux, lines are normally separated by a newline character only ('\n').

filter will read either kind of text file under both Windows and Linux, and convert it to the native encoding. The output files will always be on the native format for the platform.

This makes filter useful for converting imported text files that have the non-native encoding on either platform.

Example (Windows and Linux)
> filter -output '*.txt'
Converts all files with the extension .txt to the native end-of-line encoding ('\r\n' on Windows and '\n' on Linux).

Control Options

-map = filename
Maps characters according to specification in a parameter file.
Converts to lower, UPPER, or Title Case.
-collapse Collapses multiple whitespace characters into a single space, and trims away leading and trailing whitespaces.
-noindents Removes leading whitespace characters from each line.
-trim Trims away trailing whitespace characters.


> filter a.txt -output -map=ebcdic_in.charmap
Specifies a file containing a character map. The default filename extension for the file with the character map is .charmap .

When a character map is given, the characters in the input file(s) will be mapped accordingly. The charmap can also specify that certain characters should be removed completely.

See charmap Character Maps for a description of the syntax.

The installation directory ...\glindra\par\ contains some examples of charmap files.


> filter a.txt -output -lower

The option -lower converts all letters to lower case, and -upper converts them to upper case.

Both the English letters A-Z and national letters in the 8-bit Latin 1 (ISO-8859-1) alphabet are converted. For example, the -lower option corresponds to the following charmap:

"ABCDEFGHIJKLMNOPQRSTUVWXYZ" -> "abcdefghijklmnopqrstuvwxyz"
"" -> ""

The option -title converts to "Title Case", which means that the first letter in each word is in upper case, and all other letters are in lower case.

The definition of what constitutes a "word" is very straight-forward: a word may consist of letters (including the national ones) and digits. All other characters count as delimiters. Although this definition is sufficient to cover the most basic cases, you may well find it too simplistic to handle more complicated cases involving natural languages.


> filter a.txt -output -collapse
Removes all leading and trailing whitespace characters in each line, and collapses all occurrences of multiple adjacent whitespace characters into a single space character.

The whitespace characters are space, tab, vertical tab, form feed, and line feed. Note that non-breaking space '\240' is not a whitespace character.

Although technically a whitespace character, the newline character '\n' is not affected. As filter reads the input file line by line, and collapses each line individually, the newline characters '\n' will remain as they are in the output file.


> filter a.txt -output -noindents
To remove leading whitespace characters from each line, specify -noindents.

The default setting is -indents, which leaves the leading whitespaces as they were.


> filter a.txt -output -trim
Removes trailing whitespace characters from the end of each line.


Input File Specification

> filter somefile.dat -output -lower -trim

The first parameter is an input file specification.

filter accepts the same wildcards and file selection options as the cop copy command. You can specify more than one filename, and the filenames may contain wildcards. filter will create a separate output file for each input file, just like cop.

> filter '*.html' x.css -trim -output='publish/'

If no input filename is given, the default is that the program will read from standard input. This makes it convenient to pipe the result from another program directly to filter.

The default output file is standard output, which can of course be piped on to a third program.

This works the same under both Windows and Linux.

> someprog somefile.dat | filter -lower | sort

Standard Options


> filter -trim

-output [= filename]
-o [= filename]
Specifies an output file. If the option is not present, output will be sent to standard output (con:). This makes it convenient to pipe the output from filter to another program.

If the -output option is given without a filename, the default filename is *.* in the current working directory.

See Output File Specifications for more information.

Version Numbers Are Your Friends

Like all the Glindra programs, filter supports version numbers, so if an output file already exists, it is renamed with a version number before the new file is written out.

This makes it much safer to modify files in place. If you give a command and realize afterwards that you have made a mistake, or if the computer goes down while executing the command, the original file original file is still there, so that you can make another attempt.

See File Version Numbers: Output Files for a full description of how the version numbers work for output files.

> filter '***/*.html' -output='***' -trim
Trims trailiing blanks from all .html files in all subdirectories. Each output file gets the same name as the corresponding input file, and the input files are renamed with a version number.

File Selection Options

> filter '***/*.html' -since=today -hidden=also -output='***'
-since [= datetime] Select files that were created on or after a certain date/time.
-before [= datetime] Select file that were created before a certain date/time.
-min_size [= size] Specify a minimum file size in bytes, Mb, or some other unit
-max_size [= size] Specify a maximum file size .
-directories [= only/also/not]
List directory files (only/also/not) . Default is also.
-hidden [= only/also/not] List hidden files (only/also/not). Default is not.
-nodefault Do not add any default wildcards or other filename parts to the filename.
For the filter command, option is used to suppress wildcards in the output file specification. (The input file specifications has no default wildcards to suppress.)
-exclude [= filespec] Exclude files that match the file specification given as option value. If the option value is enclosed in parenthesis, it can contain a full file specification, including recursive file selection options.

These options control which files are selected. See File Selection Options for more information.

Help and Information Options

> filter '*.dat' -output=senddir -lower -noverbose
-help   -h   -?
Print out a brief help text with a summary of each of the different options, and exit from the program.
-version Show the name and version number of the program, and exit. This option must be written out in full, and cannot be abbreviated.
-verbose   -v
Specify the amount of informational messages.
Specify the level of error reporting.

See Help and Information Options.