fgres string replace utility for binary and text files/pipes

Copyright (c) 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:
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
     16384    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)