FILTER(1)

NAME

filter - apply a filter to a set of files, in-place

SYNOPSIS

filter [ -bpsv ] command files

DESCRIPTION

filter applies command to each of the listed files, replacing each file with the output of command when run with that file as input. The command must, therefore, (and as this program's name suggests) be a filter, reading standard input and writing some usefully modified rendition of it to standard output. Typical commands are sed and tr.

filter pays attention to the exit status of command and does not replace an original file if command exits with an error status. filter also attempts to preserve the original file's permissions, ownership, and hard links, although its ability to do so is somewhat dependent on ancillary utilities which may not be universally available.

filter's interpretation of its command line is rather blunt: the first argument is the command to be invoked; the remaining argument(s) are the file(s) to be filtered.

This syntax presents an obvious difficulty: what if the command to be invoked itself takes some option flags or arguments, or is otherwise multi-word? The solution is simple: enclose the command string in quotes. But this solution presents a further difficulty: what if one of the command's arguments needs to be quoted? The solution to that is either to quote some of the quotes, or use two different kinds of quotes.

For example, suppose that filter is to be used to invoke sed on a series of files, where the sed command to be invoked must be quoted (as it of course usually must be). The complete invocation might look like this:

	filter "sed 's/cannot/can not/g'" file1 file2 file3

(In extreme cases, it may be easier to encapsulate a complicated filtering command as a shell script which can then be invoked as a single word, although this is admittedly a nuisance.)

filter invokes the specified command within an extra shell eval layer, meaning that an exotic invocation such as

	filter "rev | sort | rev" file1 file2 file3

will work as expected (that is, each file will be filtered through the pipeline ``rev | sort | rev'').

OPTIONS

filter accepts a few options of its own:

-b: Save a backup copy of each original input file, before modification, as filename.bak.
-i: Ignore any errors returned by command; always replace the input file with the output.
-p: Preserve the original modification times of the files being filtered. (This option may not be available in all versions of the program, as it depends on ancillary utilities which may not be universally available.)
-s: Do not replace an input file if the output of command is no different from the input.
-v: Verbose: print messages about all files filtered.
-?, -h: Print a brief help/usage message.

AUTHOR

Steve Summit, scs@eskimo.com

See http://www.eskimo.com/~scs/src/#filter for possible updates.