\input texinfo @c -*-texinfo-*-
@c This file uses the @command command introduced in Texinfo 4.0.
@c %**start of header
@setfilename rrep.info
@include version.texi
@settitle rrep @value{VERSION}
@finalout
@setchapternewpage odd
@c %**end of header

@copying
This file documents the @command{rrep} utility which replaces patterns in files.

Copyright @copyright{} 2011, 2013, 2019, 2022 Arno Onken

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end quotation
@end copying

@dircategory Text creation and manipulation
@direntry
* rrep: (rrep).                 Replace patterns in files.
@end direntry

@titlepage
@title rrep: Replace patterns in files
@subtitle version @value{VERSION}
@author Arno Onken

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@contents


@ifnottex
@c All the nodes can be updated using the EMACS command
@c texinfo-every-node-update, which is normally bound to C-c C-u C-e.
@node Top
@top rrep

The @command{rrep} utility replaces patterns in files.

This manual is for version @value{VERSION} of rrep.

@insertcopying
@end ifnottex

@c All the menus can be updated with the EMACS command
@c texinfo-all-menus-update, which is normally bound to C-c C-u C-a.
@menu
* Introduction::                
* Invoking::                    
* Usage::                       
* Reporting Bugs::              
* Copying::                     
* Index::                       
@end menu

@node Introduction
@chapter Introduction

@cindex replacing a pattern in multiple files

The @command{rrep} utility searches input files for matches to a given pattern
and replaces those matches by a given replacement string.
The pattern is, by default, a basic regular expression.
The replacement string may contain special characters to refer to portions of
the matched pattern.

Binary files are, by default, ignored.
A file is regarded as binary if it contains the null character.

@node Invoking
@chapter Invoking @command{rrep}

The synopsis of @command{rrep} is

@example
rrep @var{options} @var{pattern} @var{replacement} @var{input_file_names}
@end example

@noindent
There can be zero or more @var{options}.
@var{pattern} is, by default, a basic regular expression (BRE) that is searched
in the @var{input_file_names} and replaced by @var{replacement}.
@var{replacement} may contain the special character @samp{&} to refer to that
portion of the pattern space which matched, and the special escapes @samp{\1}
through @samp{\9} to refer to the corresponding matching sub-expressions in
@var{pattern}.
@var{pattern} and @var{replacement} can also be set by the options
@samp{-e @var{pattern}} and @samp{-p @var{replacement}}.
In that case all the arguments following the options are seen as input files.
If no @var{input_file_names} are specified, then the standard input is read.

@menu
* Command-line Options::        Short and long names, grouped by category.
* Exit Status::                 Exit status returned by @command{rrep}.
@end menu

@node Command-line Options
@section Command-line Options

@table @samp

@item -E
@itemx --extended-regexp
@cindex extended regular expression
@var{pattern} is interpreted as an extended regular expression (ERE).

@item -F
@itemx --fixed-strings
@cindex fixed strings
@var{pattern} and @var{replacement} are interpreted as fixed strings, not as
regular expressions or escape sequences.

@item -R
@itemx -r
@itemx --recursive
@cindex recursive replacement
Each directory that is given on the command line is processed recursively.
Files and sub-directories starting with the @samp{.} character are, by default,
ignored.

@item --include=@var{FILE_PATTERN}
@cindex include files
Only files are processed that match the pattern @var{FILE_PATTERN}, except for
files that are specifically given on the command line.
@samp{*}, @samp{?}, and @samp{[}...@samp{]} can be used as wildcards in
@var{FILE_PATTERN}.
Wildcards and backslash characters can be quoted with @code{\}.

@item --exclude=@var{FILE_PATTERN}
@cindex exclude files
Files that match the pattern @var{FILE_PATTERN} will be skipped, except for
files that are specifically given on the command line (using wildcard matching
as described under @samp{--include}).

@item --exclude-dir=@var{PATTERN}
@cindex exclude directories
Directories that match @var{PATTERN} will be skipped, except for files that are
specifically given on the command line (using wildcard matching as described
under @samp{--include}).

@item -S
@itemx --suffix=@var{SUFFIX}
@cindex suffix
Override default backup suffix.
This option implicitly activates backups.

@item -V
@itemx --version
@cindex version
Print the version number of @command{rrep}.

@item -a
@itemx --all
@cindex all regular files
Files and sub-directories starting with the @samp{.} character in recursively
processed directories (see @samp{--recursive}) are processed as well.

@item -b
@cindex backup
Backup before overwriting files.
The backup files are written into the directory of the original file.
Equivalent to using @samp{--backup=existing}.

@item --backup
@cindex long backup
Like @samp{-b} but accepts a version control argument.
The file name of the backup file is appended by a @samp{~} character.
The backup suffix is @samp{~}, unless set with @samp{--suffix} or
@var{SIMPLE_BACKUP_SUFFIX}.
The version control method may be selected via the @samp{--backup} option or
through the @var{VERSION_CONTROL} environment variable.
Here are the values:
@itemize @bullet
@item @samp{none}, @samp{off}: never make backups (even if @samp{--backup} is
given)
@item @samp{numbered}, @samp{t}: make numbered backups
@item @samp{existing}, @samp{nil}: numbered if numbered backups exist, simple
otherwise
@item @samp{simple}, @samp{never}: always make simple backups
@end itemize

@item --binary
@cindex binary files
Do not ignore binary files.
A file is regarded as binary if it contains the null character @samp{\0}.

@item --dry-run
@cindex simulation
The replacement is just simulated.
No file is actually modified.

@item -e
@itemx --regex=@var{PATTERN}
@cindex pattern list
Use @var{PATTERN} for matching.
This option can be used to specify a pattern beginning with @samp{-}.

@item -h
@itemx --help
@cindex help
Display a help message that describes the command line options and exit
afterwards.

@item -i
@itemx --ignore-case
@cindex ignore case
Case distinctions in @var{pattern} are ignored.

@item --keep-times
@cindex keep times
The original access and modification times of files and directories are
restored after processing.

@item -p
@itemx --replace-with=@var{REPLACEMENT}
@cindex replacement string
Use @var{REPLACEMENT} for substitution.

@item --interactive
@cindex interactive
Each time before a file is modified the user is prompted and can cancel the
modification.

@item -q
@itemx --quiet
@itemx --silent
@cindex quiet
All normal output messages are suppressed.

@item -s
@itemx --no-messages
@cindex no messages
All error messages are suppressed.

@item -w
@itemx --word-regexp
@cindex whole words
Only those matches of @var{pattern} are replaced that match whole words.

@item -x
@itemx --line-regexp
@cindex whole lines
Only those matches of @var{pattern} are replaced that match whole lines.

@end table


@node Exit Status
@section Exit Status
@cindex exit status
@cindex return status

Exit status is 1 if any error occurs, 0 otherwise.


@node Usage
@chapter Usage
@cindex usage, examples

@example
rrep 'hello world' 'Hello, World!' menu.h main.c
@end example

@noindent
This command replaces all occurences of the string @samp{hello world} by the
string @samp{Hello, World!} in the files @samp{menu.h} and @samp{main.c}.

@example
rrep -i 'hello.*world!*' 'Hello, world!' menu.h main.c
@end example

@noindent
All occurences of the pattern @samp{hello.*world!*'} like @samp{hello world},
@samp{hello, world}, or @samp{hello,, world!!} (see regular expressions) are
replaced by the string @samp{Hello, world!} in the files @samp{menu.h} and
@samp{main.c}.
The @samp{-i} option causes @command{rrep} to ignore cases, so, for instance,
@samp{HeLLo WoRlD} will be replaced as well.

@example
rrep -i --backup '\(hello\).*\(world\)!*' '\1, \2!' menu.h main.c
@end example

@noindent
This command replaces all occurences of the pattern
@samp{\(hello\).*\(world\)!*} by @samp{\1, \2!}, where @samp{\1} and @samp{\2}
are the corresponding sub-expressions @samp{hello} and @samp{world} in the
files @samp{menu.h} and @samp{main.c}.
For instance, @samp{hEllO wOrLd} will be replaced by @samp{hEllO, wOrLd!}.
Backups will be made.

@example
rrep -F -r --binary --interactive '*hello\1' '*hello\2' /home/user/hello
@end example

@noindent
All occurences of the string @samp{*hello\1} are replaced by the string
@samp{*hello\2} in @samp{/home/user/hello}.
Due to the @samp{-F} option, the strings are not interpreted as regular
expressions or escape sequenses.
If @samp{/home/user/hello} is a directory, then the @samp{-r} option causes
@command{rrep} to process all files and sub-directories in
@samp{/home/user/hello} as well.
However, files and directories starting with the @samp{.} character are ignored.
The @samp{--binary} option causes @command{rrep} to the replace the string in
binary files as well.
The @samp{--interactive} option causes @command{rrep} to prompt the user before
modifying any file.

@example
rrep -r -a 'hello' 'Hello' /home/user/.hello
@end example

@noindent
This command replaces all occurences of @samp{hello} by @samp{Hello} in
@samp{/home/user/hello}.
If @samp{/home/user/hello} is a directory, then the @samp{-r} option causes
@command{rrep} to process all files and sub-directories in
@samp{/home/user/hello} as well.
The @samp{-a} option causes @command{rrep} to process files and directories
starting with the @samp{.} character as well.
However, binary files (files that contain the null character) are ignored.

@example
rrep -e '-hello' --dry-run 'Hello' menu.h main.c
@end example

@noindent
This command simulates the replacement of @samp{-hello} by @samp{Hello} in the
files @samp{menu.h} and @samp{main.c}.
The files are not actually modified due to the @samp{--dry-run} option.

@example
rrep -r --include=*.c 'hello world' 'Hello, world!' /home/user/hello
@end example

@noindent
All occurences of @samp{hello world} are replaced by @samp{Hello, world!} in
@samp{/home/user/hello}.
If @samp{/home/user/hello} is a directory, then the @samp{-r} option causes
@command{rrep} to process all files and sub-directories in
@samp{/home/user/hello} as well.
However, files and directories starting with the @samp{.} character and binary
files are ignored.
Moreover, the @samp{--include=*.c} option causes @command{rrep} to process only
files with file names that end with @samp{.c}.


@node Reporting Bugs
@chapter Reporting Bugs
@cindex bugs
@cindex problems

If you find a bug in @command{rrep}, please send electronic mail to
@email{asnelt@@asnelt.org}.
Include the version number, which you can find by running
@w{@samp{rrep --version}}.
Also include in your message the output that the program produced and the output
you expected.@refill

If you have other questions, comments or suggestions about @command{rrep},
contact the author via electronic mail to @email{asnelt@@asnelt.org}.
The author will try to help you out, although he may not have time to fix your
problems.


@node Copying
@chapter Copying
@cindex copying

rrep is licensed under the GNU GPL, which makes it @dfn{free software}.

The ``free'' in ``free software'' refers to liberty, not price.
As some GNU project advocates like to point out, think of ``free speech''
rather than ``free beer''.
In short, you have the right (freedom) to run and change rrep and distribute it
to other people, and---if you want---charge money for doing either.
The important restriction is that you have to grant your recipients the same
rights and impose the same restrictions.

This general method of licensing software is sometimes called @dfn{open source}.
The GNU project prefers the term ``free software'' for reasons outlined at
@url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}.

This manual is free documentation in the same sense.
The documentation license is included below.
The license for the program is available with the source code, or at
@url{http://www.gnu.org/licenses/gpl.html}.

@menu
* GNU Free Documentation License::  
@end menu

@node GNU Free Documentation License
@section GNU Free Documentation License

@include fdl.texi


@node Index
@unnumbered Index

@printindex cp

@bye