bionic (1) subst.1.gz

NAME

       subst - substitute definitions into file(s)

SYNOPSIS

       subst [ -e editor ] -f substitutions victim ...

DESCRIPTION

       Subst  makes  substitutions  into  files,  in  a  way  that is suitable for customizing software to local
       conditions.  Each victim file is altered according to the contents of the substitutions file.

       The substitutions file contains one line per substitution.  A line consists of two  fields  separated  by
       one  or  more  tabs.   The first field is the name of the substitution, the second is the value.  Neither
       should contain the character `#', and use of text-editor metacharacters like `&' and `\' is also  unwise;
       the  name in particular is best restricted to be alphanumeric.  A line starting with `#' is a comment and
       is ignored.

       In the victims, each line on which a substitution is to be made (a target line) must  be  preceded  by  a
       prototype  line.  The prototype line should be delimited in such a way that it will be taken as a comment
       by whatever program processes the file later.  The prototype line must contain  a  ``prototype''  of  the
       target  line  bracketed  by  `=()<'  and `>()='; everything else on the prototype line is ignored.  Subst
       extracts the prototype, changes all instances of substitution names bracketed by `@<' and `>@'  to  their
       values, and then replaces the target line with the result.

OPTIONS

       -e     Substitutions are done using the sed(1) editor, which must be found in either the /bin or /usr/bin
              directories.  To specify a different executable, use the ``-e'' flag.

EXAMPLE

       If the substitutions file is

              FIRST     111
              SECOND    222

       and the victim file is

              x = 2;
              /* =()<y = @<FIRST>@ + @<SECOND>@;>()= */
              y = 88 + 99;
              z = 5;

       then ``subst -f substitutions victim'' changes victim to:

              x = 2;
              /* =()<y = @<FIRST>@ + @<SECOND>@;>()= */
              y = 111 + 222;
              z = 5;

FILES

       victimdir/substtmp.new    new version being built
       victimdir/substtmp.old    old version during renaming

SEE ALSO

       sed(1)

DIAGNOSTICS

       Complains and halts if it is unable to create its temporary files or if they already exist.

HISTORY

       Written at U of Toronto by Henry Spencer.

       Rich $alz added the ``-e'' flag July, 1991.

BUGS

       When creating a file to be substed, it's easy to forget to insert a dummy target line after  a  prototype
       line; if you forget, subst ends up deleting whichever line did in fact follow the prototype line.

                                                   25 Feb 1990                                          SUBST(1)