RelocateTree(3)

NAME
ActiveState::RelocateTree - copy tree substituting paths at the same time

SYNOPSIS
   use ActiveState::RelocateTree qw(relocate);
   relocate(from => 'C:\Perl', to => 'D:\lang\perl');

DESCRIPTION
When a perl installation is copied into a new location, some of its files need to be modified accordingly. The "ActiveState::RelocateTree" module provide functions that helps you do this.

The following functions are provided. None of them are exported by default.

relocate( %options )
    This is the main entry point that applications will use. The following options are recognized:

    "to"
        The tree which must be transformed. Unless the "inplace" option is true, it will copy the tree at "from" to "to" before transforming it. This option is the only one required. The other options have reasonable defaults, so in most cases this is the only option you need to provide.

    "from"
        The path from which to copy the perl tree. Defaults to $Config{prefix}, the home of the currently executing perl interpreter.

    "search"
        This is the path which will be searched for and replaced in "to". This defaults to the value of "from".

    "replace"
        The replacement value for "search". This defaults to the value of "to".

    "inplace"
        If the tree at "to" already exists and you just want to transform it in-situ, use this option. It skips the copying step and just transforms the tree. If "from" equals "to", it is set to true and cannot be unset. Otherwise it defaults to false.

    "killorig"
        If you're really moving the tree, this option will remove "from" after copying and transforming "to". Use with care! Defaults to false.

    "bak"
        While relocating the tree, relocate() creates a backup file for each file being edited. This option allows you to specify the extension of backup files. Defaults to ".~1~".

    "savebaks"
        Normally relocate() deletes the backup files before returning. "savebaks" skips that step, leaving the backup files alone. Defaults to false (backups are deleted).

    "textonly"
        Normally relocate() edits both text and binary files. Text files are replaced using a normal search-and-replace algorithm, but binary files are NULL-padded so that all offsets remain the same. By default, "textonly" is false, i.e. relocate() operates on both text and binary files.

    "ranlib"
        If "ranlib" is true, relocate() will call "ranlib" on binary files which look like library files (have the $Config{_a} extension). Defaults to true.

    "verbose"
        If "verbose" is true, relocate() emits warning messages as it performs certain operations. This may be useful for debugging, or for command-line tools, where user feedback is a good thing.

    "quiet"
        Normally, relocate() prints out some status messages even with "verbose" disabled. If "quiet" is true, all messages (except error messages) are temporarily silenced. This option overrides "verbose", so there isn't much point calling relocate() with both "quiet" and "verbose" set. By default, "quiet" is false.

    "filelist"
        If specified, relocate() will write a list of the files modified to "filelist", one filename per line. The lines are prefixed with "B " for binary files and "T " for text files.

move_tree( $from, $to )
move_tree( $from, $to, $delete_after, $verbose )
    This function will copy the directory tree at $from to the location $to.

    If $delete_after is TRUE, then tree at $from will be removed after the copy completes. If $verbose is TRUE, then print a message when deleting the $from tree.

check( $file, $regexp, $is_binary )
    Returns TRUE if there are occurrences of $regexp in $file. It is used by relocate() to search for files which should be edited. If $is_binary is TRUE, then read the file in binmode.

edit( $regexp, $from, $dest, $bak, $are_binary, @files )
    edit() is designed to rip though a set of files, efficiently replacing $from with $dest. It operates on the whole set of files, which all need to be of the same type (binary or text). It accepts the following parameters:

    $regexp
        The regular expression to search for. Matching text will be replaced with $dest.

    $from
        The path to search for and replace. If $are_binary is true, this is used to calculate the amount of NUL-padding required to preserve the length of strings. It is not used otherwise.

    $dest
        The replacement string. If $are_binary is true and $dest is shorter than $from, then it inserts a NULL-pad to preserve the original length of the strings.

    $bak
        The extension to use when storing backup files.

    $are_binary
        A boolean: if true, the files are edited with binary semantics: the filehandles are set to binmode, and strings are NULL-padded. Otherwise a plain-old substitution occurs.

    @files
        A list of files to edit.

spongedir( $name )
    Returns the spongedir associated with a particular product. The $name is the spongedir you're interested in. It's case-insensitive. The following spongedirs are known:

    ppm The sponge directory to be used in PPM packages.

    thisperl
        The original directory in which this copy of Perl was built. This allows relocate() to detect when a replacement path will not fit into the binary.

SEE ALSO
reloc_perl

COPYRIGHT
Copyright 2002 ActiveState Software Inc. All Rights Reserved.