fgres string replace utility for binary and text files/pipes
Copyright © 1994, W. Stumvoll, Germany
Download
source file fgres-1.5.tar.gz Download
Readme
fgres' ( Fast GREp and Substitute ) primary function is to substitute or delete character patterns. It can operate on binary and text files or in a pipe.
It is ideally suited for quick and dirty replacements in multiple files. Especially for this purpose, fgres supports in situ replacements, which do not need any temporary files.
For example:<br />
If you want to replace all variables `foo' by `foobar' in all your program sources, a mere:
=fgres foo foobar *.[ch]=
will do.
The more demanding user can create fgres command files. They can contain any number of substitution patterns which will be simultaneously searched for and can be collected in named groups. These groups can be used to generate finite automatons.
man page
NAME
fgres - search and replace character patterns (v1.5)
SYNOPSIS
fgres <options> search [replace [file ...]]
fgres <options> [-r in] [-w out] search [replace]
fgres <options> <program> [file ...]
fgres <options> <program> [-r in] [-w out]
where:
<options>=[-bghipsv] [n number] [-F delimiter]
<program>=(-f command-file | -e command) ...
DESCRIPTION
General Description
fgres (Fast GREp and Substitute) primary function is to sub-
stitute or delete character patterns. It can operate on
binary and text files or in a pipe.
The command language consists of very straightforward sub-
stitution patterns. These commands can be collected in
named groups, which can be dynamically enabled and disabled.
In addition to the fgres command language, you can also use
simple command line arguments for search and replace pat-
terns.
Search and Replace Patterns on Command Line
This can be used in the follwoing two ways:
fgres <options> search replace file ...
Replace search with replace (default: empty word) in
all files file ... . The replacement is done in the
files, without copying them.
fgres <options> [-r in] [-w out] search [replace]
Replace search with replace (default: empty word).
Read all files given with -r in (default: standard
input) and write to the file, given with - w out
(default: standard output).
search and replace are taken literally.
Program with -e or -f:
This can be used in the following two ways:
fgres <options> <program> file ...
Execute the command given in <program> and the
corresponding actions in all files file ... . The
replacement is done in the files, without copying them.
fgres <options> <program> [-r in] [-w out]
Execute the command given in <program> and the
corresponding actions. Read all files given with -r in
(default: standard input) and write to the file, given
with -w out (default: standard output).
The basic elements of the fgres program <program> are
search-and-replace commands. While these commands can be
grouped and those groups can be switched on and off, you can
build up a kind of a finite state machine. In detail, a
fgres program is a sequence of the following statements
(field separator is set to the default space or tab):
\## this is a comment
No comment :-)
search [replace [ (+|-)switch ...]]
Replace the search string with replace and execute the
optional switches. A switch turns on/off the
corresponding named group of commands. If switches
have to be used with the empty replace string, use \#
for replace.
\#start[-len] [replace [ (+|-)switch ...]]
Replace the len characters, starting at byte number
start (0 is the first), with replace and execute the
optional switches. len defaults to zero. start and
len can be decimal, octal (starting with 0) or hex
(starting with 0x). If switches have to be used with
the empty replace string, use \# for replace.
\# name
command-1
:
command-n
\#
All commands belong to the group name. They are con-
trolled by corresponding (+| -)name switches. Named
groups are switched off at startup. Nested groups are
not allowed.
There are three reserved group names:
default
This group contains all commands, which are
declared outside of groups.
write
These switches do not belong to a set of commands,
but switch on/off writing to the output file. If
+write and -write are both used for a command
line, the replace pattern is printed and output is
disabled afterwards.
position
These switches do not belong to a set of commands,
but print the current match position in hex. If
+(-) is used, the position will be printed in
front (behind) of the replace pattern. If + and -
are used together, only the last one will be
activated. Like in adress patterns, counting
starts with 0.
In strings, you can use \\ to get a \, \n to get a newline
and \t to get a tab. You can also use \ followed by a
decimal, octal (starting with 0) or hex (starting with 0x)
number to get any character (non-printables!) of your char-
acter set.
Group identifiers can consist of a-zA-Z_0-9.
OPTIONS
-e command
Add expression command to the command list. command
may contain one line of a fgres program.
-f cmd-file
Read commands from file cmd-file.
-F delimiter
Any character in the string delimiter will be used as
field separator on fgres program lines. The default is
space or tab.
-i Pattern matching is done case insensitive.
-b Allow only replace commands, which do not change the
filesize (typically used on binary files).
-g If -b was used, this option enables commands, which
let the file grow. If option -b is used after -g, this
will overwrite -g!
-s If -b was used, this option enables commands, which
let the file shrink. If option -b is used after -s,
this will overwrite -s!
-p Activate padding. If -b was used, pad substitute pat-
terns with trailing null characters or cut them off, in
order to match the length of the search pattern. Using
-s or -g disables padding respectively cutting.
-v Switch on verbose mode. fgres prints information
about read and written bytes and meybe some warning
messages, if -p is used.
-r in
Read from file in. If in is -, standard input is used.
Multiple usage of -r is allowed.
-w out
Write to file out. If out is -, standard output is
used.
-n number
If fgres is not used in a pipe, fgres stores blocks of
- characters in memory, while extending files.
This option overwrites the default value of 64 blocks
by number blocks.
-h Print a long usage as help.
RETURN VALUE and ERRORS
fgres uses standard output only, if fgres was used in a pipe
( -r or -w or no filter files on command line). The follow-
ing exit values are used by fgres:
tab(@); l r | l. Exit Status@@Used for _
EX_OK@(0)@everything goes as planed
EX_USAGE@(64)@command line arguments are incorrect
EX_DATAERR@(65)@fgres program is incorrect or missing
EX_NOINPUT@(66)@error on reading the filter source
EX_SOFTWARE@(70)@should never appear EX_OSERR@(71)@error on
malloc(3), lseek(2),.. EX_CANTCREAT@(73)@error on writing
the filter output EX_IOERR@(74)@error on reading/writing _
@(*)@T{ These are the standard UNIX values for the given
symbolic constants. T}
EXAMPLES
Simple Replacement
Substitue all occurrences of foo with bar in file name:
fgres foo bar name
or
fgres -e "foo bar" name
Tagged Replacement
Substitute the string foo with bar in the string part of an
assembler listing list. The string part begins with a line
BEGIN_STRING_DATA and ends at a line END_STRING_DATA:
Use fgres script file foobar.script:
\## start foo-bar replace if matching:
BEGIN_STRING_DATA BEGIN_STRING_DATA +foobar
\# foobar
\## this is the replace line
foo bar
\#
\## end foo-bar replace if matching:
END_STRING_DATA END_STRING_DATA -foobar
and call:
fgres -f foobar.script list
or simulate foobar.script with -e options and call:
fgres \
-e "BEGIN_STRING_DATA BEGIN_STRING_DATA +foobar" \
-e "\# foobar" \
-e " foo bar" \
-e "\#" \
-e "END_STRING_DATA END_STRING_DATA -foobar" \
list
Show Positions
Get all positions of string pattern in a file source (which
can be a binary file, so that grep(1) and similar commands
cannot be used):
Use fgres with options:
fgres -r source \
-e '\#0 \# -write' \
-e 'pattern \n +write -write +position'
Count Occurrences
Count the number of occurrences of string pattern in a file
source (which can be a binary file, so that grep(1) and
similar commands cannot be used):
Use example Show Positions, piped through wc(1):
fgres -r source \
-e '\#0 \# -write' \
-e 'pattern \n +write -write +position' \
| wc -l
FILES
fgres uses tmpnam(3) for temporary files.
NOTES
Obviously sequences of -e and -f options are allowed. In
this case, the options are handled left-to-right. The dif-
ferent program parts are joined together and handled as a
single unit.
Multiple usage of option -r is handled left-to-right, all
given files will be read one after the other. Only one out-
put file is generated.
DIAGNOSTICS
Warning messages:
cut long replace (program-position)
padding short replace (program-position)
If -v, -b and -p are active and a replace pattern
is longer than the corresponding search pattern,
this messages shows the position of the -b viola-
tion.
(using temporary file file-name)
The extension of an filtered file cannot be hold
in memory and is stored in a temporary file (temp-
nam(3)). Option -n can be used to increase the
number of bytes, hold in memory.
Error messages:
empty search (program-position) no program given
Empty fgres programs or invalid search patterns
are not allowed.
group active (program-position)
no group active (program-position)
group open at end of program
Nested groups for fgres commands are not allowed.
The start- and close-group statements do not fit.
invalid group id (program-position)
Invalid group action on replace line or invalid
group name on definition of a group. Group names
write, position and default are not allowed on
start-group command lines.
growing command (program-position)
shrinking command (program-position)
-b disables position output (program-position)
-b disables stop writing (program-position)
Option -b used. The corresponding fgres program
lines violates this restriction!
-n: invalid value
-F: invalid string, using default
option r/w and file argument conflict
Command line parameters are used in an invalid
combination or their parameters are invalid.
cannot open file-type file file-name (system-error)
write failed (system-error)
seek failed (system-error)
truncate file failes, padded with number-bytes 0
cannot close file-name (system-error)
remove temporary file failed (system-error)
System errors occur, the corresponding action
couldt not be performed. fgres tries to tell you
the reason in the fences.
RESTRICTIONS
If there are overlapping patterns/adresses, it is undefined,
which of these patterns/adresses triggers its actions.
Different fgres program lines for the same pattern/adress
are allowed. This situation is handled in the same way,
overlapping patterns/adresses are handled.
If -r in is used more than once, patterns are only handled
inside of the files. Patterns on the border of two files
are not recognized!
The output file, given with -w or standard output may not be
an inputfile!
AUTHOR
Wolfgang Stumvoll at RWTH-Aachen, Germany
(stumvoll@pool.informatik.rwth-aachen.de)
SEE ALSO
awk(1), dd(1), sed(1), tr(1)