.TH pesubst 1 "2008-02-06" "hxtools" "hxtools"
.SH Name
.PP
pesubst \(em perl-regexp stream substitution
.SH Syntax
.PP
\fBpesubst\fP [\fB\-f\fP] [\fB\-s\fP \fIpattern\fP] [\fB\-d\fP \fIpattern\fP]
[\fB\-m\fP \fImodifiers\fP] \fIfile\fP...
.SH Description
.PP
pesubst can substitute strings in streams and files, and does so by using the
Perl engine. It obsoletes sed(1) for simple substitution tasks.
.SH Options
.TP
\fB\-f\fP
Fill the replacement string with NULs to bring it up to the size of the
original string.
.TP
\fB\-s\fP \fIpattern\fP
Source pattern to search for in files. This can be any valid Perl regular
expression. Files are slurped in as a whole, so matching across newlines should
be no problem (with the -ms flag).
.TP
\fB\-d\fP \fIpattern\fP
Destination (replacement) string. This can be any valid string Perl accepts.
For details see the \fBperlre\fP(1) manpage.
.TP
\fB\-m\fP \fImodifiers\fP
A string of modifiers to apply to the regex. See below.
.SH Modifiers
.TP
\fBe\fP
Evaluate the right side as an expression.
.TP
\fBg\fP
Replace globally, i.e., all occurrences. \fBThis is always enabled in
pesubst.\fP
.TP
\fBi\fP
Do case-insensitive pattern matching.
.TP
\fBm\fP
Treat string as multiple lines. That is, change "^" and "$" from matching the
start or end of the string to matching the start or end of any line anywhere
within the string.
.TP
\fBo\fP
Compile pattern only once.
.TP
\fBs\fP
Treat string as single line. That is, change "." to match any character
whatsoever, even a newline, which normally it would not match.
.TP
\fBx\fP
Extend your pattern's legibility by permitting whitespace and comments.
.SH Examples
.PP
Change all occurrences of foo (case-insensitive) to bar:
.PP
.nf
	pesubst \-s foo \-d bar \-ms myfile
.fi
.PP
Change all Shell-style comments into C++ ones:
.PP
.nf
	pesubst \-s '^#' \-d // \-mm myfile
.fi
.PP
Using both the "m" and "i" flags:
.PP
.nf
	pesubst \-s '^#INCLUDE\\s+' \-d '#include ' \-mmi myfile.c
.fi
.SH See also
.PP
\fBhxtools\fP(7), \fBpegrep\fP(1)