README.global-renaming

This file documents the generic scripts that have been used to implement
the recent type renamings, e.g. the "great integral type renaming" and the
"text/char type renaming".  More information about these changes can be
found in the Internals manual.

A sample script to do such renaming is this (used in the great integral
type renaming):

----------------------------------- cut ------------------------------------
files="*.[ch] s/*.h m/*.h config.h.in ../configure.in Makefile.in.in ../lib-src/*.[ch] ../lwlib/*.[ch]"
gr Memory_Count Bytecount $files
gr Lstream_Data_Count Bytecount $files
gr Element_Count Elemcount $files
gr Hash_Code Hashcode $files
gr extcount bytecount $files
gr bufpos charbpos $files
gr bytind bytebpos $files
gr memind membpos $files
gr bufbyte intbyte $files
gr Extcount Bytecount $files
gr Bufpos Charbpos $files
gr Bytind Bytebpos $files
gr Memind Membpos $files
gr Bufbyte Intbyte $files
gr EXTCOUNT BYTECOUNT $files
gr BUFPOS CHARBPOS $files
gr BYTIND BYTEBPOS $files
gr MEMIND MEMBPOS $files
gr BUFBYTE INTBYTE $files
gr MEMORY_COUNT BYTECOUNT $files
gr LSTREAM_DATA_COUNT BYTECOUNT $files
gr ELEMENT_COUNT ELEMCOUNT $files
gr HASH_CODE HASHCODE $files
----------------------------------- cut ------------------------------------


`fixtypes.sh' is a Bourne-shell script; it uses 'gr':


----------------------------------- cut ------------------------------------
#!/bin/sh

# Usage is like this:

# gr FROM TO FILES ...

# globally replace FROM with TO in FILES.  FROM and TO are regular expressions.
# backup files are stored in the `backup' directory.
from="$1"
to="$2"
shift 2
echo ${1+"$@"} | xargs global-replace "s/$from/$to/g"
----------------------------------- cut ------------------------------------


`gr' in turn uses a Perl script to do its real work, `global-replace',
which follows:


----------------------------------- cut ------------------------------------
: #-*- Perl -*-

### global-replace --- modify the contents of a file by a Perl expression

## Copyright (C) 1999 Martin Buchholz.
## Copyright (C) 2001, 2002 Ben Wing.

## Authors: Martin Buchholz <martin@xemacs.org>, Ben Wing <ben@xemacs.org>
## Maintainer: Ben Wing <ben@xemacs.org>
## Current Version: 1.2, March 12, 2002

# This program is free software: you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the
# Free Software Foundation, either version 3 of the License, or (at your
# option) any later version.
# 
# 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 the GNU General Public License
# for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

eval 'exec perl -w -S $0 ${1+"$@"}'
    if 0;

use strict;
use FileHandle;
use Carp;
use Getopt::Long;
use File::Basename;

(my $myName = $0) =~ s@.*/@@; my $usage="
Usage: $myName [--help] [--backup-dir=DIR] [--line-mode] [--hunk-mode]
       PERLEXPR FILE ...

Globally modify a file, either line by line or in one big hunk.

Typical usage is like this:

[with GNU print, GNU xargs: guaranteed to handle spaces, quotes, etc.
 in file names]

find . -name '*.[ch]' -print0 | xargs -0 $0 's/\bCONST\b/const/g'\n

[with non-GNU print, xargs]

find . -name '*.[ch]' -print | xargs $0 's/\bCONST\b/const/g'\n


The file is read in, either line by line (with --line-mode specified)
or in one big hunk (with --hunk-mode specified; it's the default), and
the Perl expression is then evalled with \$_ set to the line or hunk of
text, including the terminating newline if there is one.  It should
destructively modify the value there, storing the changed result in \$_.

Files in which any modifications are made are backed up to the directory
specified using --backup-dir, or to `backup.orig' by default.  To disable
this, use --backup-dir= with no argument.

Hunk mode is the default because it is MUCH MUCH faster than line-by-line.
Use line-by-line only when it matters, e.g. you want to do a replacement
only once per line (the default without the `g' argument).  Conversely,
when using hunk mode, *ALWAYS* use `g'; otherwise, you will only make one
replacement in the entire file!
";

my %options = ();
$Getopt::Long::ignorecase = 0;
&GetOptions (
	     \%options,
	     'help', 'backup-dir=s', 'line-mode', 'hunk-mode',
);


die $usage if $options{"help"} or @ARGV <= 1;
my $code = shift;

die $usage if grep (-d || ! -w, @ARGV);

sub SafeOpen {
  open ((my $fh = new FileHandle), $_[0]);
  confess "Can't open $_[0]: $!" if ! defined $fh;
  return $fh;
}

sub SafeClose {
  close $_[0] or confess "Can't close $_[0]: $!";
}

sub FileContents {
  my $fh = SafeOpen ("< $_[0]");
  my $olddollarslash = $/;
  local $/ = undef;
  my $contents = <$fh>;
  $/ = $olddollarslash;
  return $contents;
}

sub WriteStringToFile {
  my $fh = SafeOpen ("> $_[0]");
  binmode $fh;
  print $fh $_[1] or confess "$_[0]: $!\n";
  SafeClose $fh;
}

foreach my $file (@ARGV) {
  my $changed_p = 0;
  my $new_contents = "";
  if ($options{"line-mode"}) {
    my $fh = SafeOpen $file;
    while (<$fh>) {
      my $save_line = $_;
      eval $code;
      $changed_p = 1 if $save_line ne $_;
      $new_contents .= $_;
    }
  } else {
    my $orig_contents = $_ = FileContents $file;
    eval $code;
    if ($_ ne $orig_contents) {
      $changed_p = 1;
      $new_contents = $_;
    }
  }

  if ($changed_p) {
    my $backdir = $options{"backup-dir"};
    $backdir = "backup.orig" if !defined ($backdir);
    if ($backdir) {
      my ($name, $path, $suffix) = fileparse ($file, "");
      my $backfulldir = $path . $backdir;
      my $backfile = "$backfulldir/$name";
      mkdir $backfulldir, 0755 unless -d $backfulldir;
      print "modifying $file (original saved in $backfile)\n";
      rename $file, $backfile;
    }
    WriteStringToFile ($file, $new_contents);
  }
}
----------------------------------- cut ------------------------------------
