usr.bin/qsubst/qsubst.1

   1 .\"     $NetBSD: qsubst.1,v 1.2 1999/09/04 17:07:23 perry Exp $
   2 .\"
   3 .\" This file is in the public domain.
   4 .Dd September 4, 1999
   5 .Dt QSUBST 1
   6 .Os
   7 .Sh NAME
   8 .Nm qsubst
   9 .Nd query-replace strings in files
  10 .Sh SYNOPSIS
  11 .Nm
  12 .Ar str1
  13 .Ar str2
  14 .Op Ar flags
  15 .Ar file
  16 .Op Ar file Op Ar ...
  17 .Sh DESCRIPTION
  18 .Nm
  19 reads its options (see below) to get a list of files.
  20 For each file on this list, it then replaces
  21 .Ar str1
  22 with
  23 .Ar str2
  24 wherever possible in that file, depending on user input (see below).
  25 The result is written back onto the original file.
  26 .Pp
  27 For each potential substitution found, the user is prompted with a few
  28 lines before and after the line containing the string to be
  29 substituted.
  30 The string itself is displayed using the terminal's standout mode, if any.
  31 Then one character is read from the terminal.
  32 This is then interpreted as follows (this is designed to be like Emacs'
  33 query-replace-string):
  34 .Bl -tag -width "space" -compact -offset indent
  35 .It space
  36 Replace this occurrence and go on to the next one.
  37 .It \&.
  38 Replace this occurrence and don't change any more in this file (i.e., go
  39 on to the next file).
  40 .It \&,
  41 Tentatively replace this occurrence.
  42 The lines as they would look if the substitution were made are printed out.
  43 Then another character is read and it is used to decide the result as if
  44 the tentative replacement had not happened.
  45 .It n
  46 Don't change this one; just go on to the next one.
  47 .It \&^G
  48 Don't change this one or any others in this file, but instead simply go
  49 on to the next file.
  50 .It \&!
  51 Change the rest in this file without asking, then go on to the next
  52 file (at which point qsubst will start asking again).
  53 .It \&?
  54 Print out the current filename and ask again.
  55 .El
  56 .Pp
  57 The first two arguments to qsubst are always the string to replace and
  58 the string to replace it with.
  59 The options are as follows:
  60 .Bl -tag -width "-F filename" -compact -offset indent
  61 .It Fl w
  62 The search string is considered as a C symbol; it must be bounded by
  63 non-symbol characters.
  64 This option toggles.
  65 .Pf ( Sq w
  66 for
  67 .Sq word . )
  68 .It Fl \&!
  69 .It Fl go
  70 .It Fl noask
  71 Enter \&! mode automatically at the beginning of each file.
  72 .It Fl nogo
  73 .It Fl ask
  74 Negate
  75 .Fl go ,
  76 that is, ask as usual.
  77 .It Fl c Ns Ar N
  78 (Where
  79 .Ar N
  80 is a number.)
  81 Give
  82 .Ar N
  83 lines of context above and below the
  84 line with the match when prompting the user.
  85 .It Fl CA Ns Ar N
  86 (Where
  87 .Ar N
  88 is a number.)
  89 Give
  90 .Ar N
  91 lines of context above the line with the match when prompting the user.
  92 .It Fl CB Ns Ar N
  93 (Where
  94 .Ar N
  95 is a number.)
  96 Give
  97 .Ar N
  98 lines of context below the line with the match when prompting the user.
  99 .It Fl f Ar filename
 100 The
 101 .Ar filename
 102 argument is one of the files qsubst should perform substitutions in.
 103 .It Fl F Ar filename
 104 .Nm
 105 reads
 106 .Ar filename
 107 to get the names of files to perform substitutions in.
 108 The names should appear one to a line.
 109 .El
 110 .Pp
 111 The default amount of context is
 112 .Fl c2 ,
 113 that is, two lines above and two lines below the line with the match.
 114 .Pp
 115 Arguments not beginning with a
 116 .Fl \&
 117 sign in the options field are implicitly preceded by
 118 .Fl f .
 119 Thus,
 120 .Fl f
 121 is really needed only when the file name begins with a
 122 .Fl \&
 123 sign.
 124 .Pp
 125 .Nm
 126 reads its options in order and processes files as it gets them.
 127 This means, for example, that a
 128 .Fl go
 129 will affect only files named after the
 130 .Fl go .
 131 .Pp
 132 The most context you can get is ten lines each, above and below.
 133 .Pp
 134 .Ar str1
 135 is limited to 512 characters; there is no limit on the size of
 136 .Ar str2 .
 137 Neither one may contain a NUL.
 138 .Pp
 139 NULs in the file may cause qsubst to make various mistakes.
 140 .Pp
 141 If any other program modifies the file while qsubst is running, all
 142 bets are off.
 143 .Sh AUTHORS
 144 .An der Mouse Aq mouse@rodents.montreal.qc.ca