Johan Vromans > srep > srep

Download:
srep-1.09.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

srep -- Perform bulk replacements on files

SUMMARY ^

    srep --data=... [ options ] [ files|directories ... ]

DESCRIPTION ^

srep performs bulk replacements on the contents of series of files.

It is driven by a data file with replacement instructions.

When processing the files, each file is rewritten when one or more of the replacement instructions succeed. If no replacement instructions succeed, the file is left unmodified.

OPTIONS ^

--recursive

Recurses through directories. Without this option, directories are ignored.

--data=XXX

Specifies the file with replacement instructions. This is a mandatory option.

-Dxxx=yyy

Defines variable xxx to have the value yyy. See the description of replacement files how to use these variables.

--define=xxx=yyy

Same as -Dxxx=yyy.

--filter=glob

Processes only files with names that obey the shell pattern glob. This option may occur more than once, the patterns will be combined.

--filter_pat=pat

Processes only files with names that obey the Perl pattern pat. This option may occur more than once, the patterns will be combined.

--exclude=glob

Excludes files with names that obey the shell pattern glob. This option may occur more than once, the patterns will be combined.

--exclude_pat=pat

Excludes files with names that obey the Perl pattern glob. This option may occur more than once, the patterns will be combined.

--dry-run

Runs, but do not change any files. This is useful to test the instructions in the replacement file.

--help

Provides a help message. Does not execute anything.

--ident

Shows identification and version of the program.

--verbose

Produces verbose information.

--debug

Produces debugging information.

REPLACEMENT FILES ^

The replacement file specifies what changes are to be made to the files.

The replacement file is interpreted on a line by line basis. Empty lines, and lines that start with a #, are ignored.

Generally, each line contains an operation in the form

    operation  argument  replacement

The words are whitespace separated, which implies that argument cannot contain whitespace. replacement can contain whitespace. replacement may be omitted, in which case it defaults to the empty string.

In replacement all Perl escapes (e.g., \n), and pattern match variables (e.g., $1, $&) can be used.

These are the basic operations:

p pattern replacement

The Perl pattern pattern is replaced by replacement. The operation is case-insensitive.

Example:

    p creat[\040\t]?( create(

Note the use of \040 to indicate a literal space.

P pattern replacement

Identical to p, but case-sensitive.

s string replacement

Replaces each substring string by replacement. The operation is case-insensitive.

S string replacement

Identical to s, but case-sensitive.

w word replacement

Replaces each occurrence of the word (according to Perl's defintion of words) by replacement. The operation is case-insensitive.

Note: Perl considers as words anything bounded by \w\W and \W\w transitions.

W word replacement

Identical to w, but case-sensitive.

e pattern replacement

Like p, but allows Perl expressions in the replacement text.

Variables that have been defined on the command line (with --define=xxx=yyy) are stored in a special hash named %VARS and can be referenced in the replacement text with $VARS{xxx}.

ee pattern replacement

Like e, but evaluates replacement twice for increased power.

E pattern replacement

Identical to e, but case-sensitive.

EE pattern replacement

Identical to ee, but case-sensitive.

x value

Terminates any further replacements on the current file. If value is zero, the file is considered to be unmodified and will not be rewritten.

This is most useful with an operator condition, see below.

<< text

Prepends the text to the file data.

>> text

Appends the text to the file data.

<< file name

Prepends the contents of the named file.

>> file name

Appends the contents of the named file.

Operator conditions

All of the operators described in the previous section may be preceded with ? or ! to have this operation applied conditionally.

With ?, the operation is only applied if any modifications have been made to the current file so far.

With !, the operation is only applied unless modifications have been made to the current file so far.

For example:

    s  foo  bar
    !x
    ...other operations...

This will apply the ...other operations... only if the first substitution succeeded.

Matching balanced strings

Special pattern elements are available to deal with balanced brackets. Recognized brackets are parentheses (), braces {}, straight brackets [] and angular (broken) brackets <>. In the description below, braces are used but the description applies to all recognized brackets.

\{...\}

This matches a bracketed string that is itself balanced with respect to these brackets.

Note that ... indicates three literal dots in a row.

\{(...)}

Like \{...\}, except that the matched string is assigned to the corresponding $n variable without the outer brackets. For example, \{(...)\} will match {x{xx}} but assign x{xx} to $1.

Note that ... indicates three literal dots in a row.

Special instructions

The following special instructions may be contained in the replacement control file. All special instructions double the functionality of some of the command line options.

!filter glob

Same as command line argument --filter=glob.

!filter_pat pat

Same as command line argument --filter_pat=pat.

!exclude glob

Same as command line argument --exclude=glob.

!exclude_pat pat

Same as command line argument --exclude_pat=pat.

The choice of the leading exclamation mark is unfortunate.

BUGS ^

Doesn't currently make backups of the files.

The contents of each of the files must fit in memory, together with the contents of any append/prepend files.

Literal NUL characters are not allowed in patterns and replacement texts. Use \0 (backslash-zero) instead.

AUTHOR ^

Johan Vromans <jvromans@squirrel.nl>

COPYRIGHT AND DISCLAIMER ^

This program is Copyright 2000,2005,2006 by Squirrel Consultancy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

syntax highlighting: