######################################################################
    Config::Patch 0.02
######################################################################

NAME
    Config::Patch - Patch configuration files and unpatch them later

SYNOPSIS
        use Config::Patch;

        my $patcher = Config::Patch->new( 
            file => "/etc/syslog.conf",
            key  => "mypatch", 
        );

            # Append a patch:
        $patcher->append(q{
            # Log my stuff
            my.*         /var/log/my
        });

            # Appends the following to /etc/syslog.conf:
            *-------------------------------------------
            | ...
            | #(Config::Patch-mypatch-append)
            | # Log my stuff
            | my.*         /var/log/my
            | #(Config::Patch-mypatch-append)
            *-------------------------------------------

        # later on, to remove the patch:
        $patcher->remove();

DESCRIPTION
    "Config::Patch" helps changing configuration files, remembering the
    changes, and undoing them if necessary.

    Every change (patch) is marked by a *key*, which must be unique for the
    change, in order allow undoing it later on.

    To facilitate its usage, "Config::Patch" comes with a command line
    script that performs all functions:

            # Append a patch
        echo "my patch text" | config-patch -a -k key -f textfile

            # Remove a patch
        config-patch -r -k key -f textfile

    Note that 'patch' doesn't refer to a patch in the format used by the
    *patch* program, but to an arbitrary section of text inserted into a
    file.

    "Config::Patch" is format-agnostic. The only requirement is that lines
    starting with a # character are comment lines. If you need to pay
    attention to the syntax of the configuration file to be patched, use a
    subclass of "Config::Patch".

METHODS
    "$patcher = Config::Patch->new(file => $file, key => $key)"
        Creates a new patcher object.

    "$patcher->append($textstring)"
        Appends a text string to the config file.

    "$patcher->remove()"
        Remove a previously applied patch. The patch key has either been
        provided with the constructor call previously or can be supplied as
        "key => $key".

    "$patcher->patched()"
        Checks if a patch with the given key was applied to the file
        already. The patch key has either been provided with the constructor
        call previously or can be supplied as "key => $key".

    "$patcher->replace($search, $replace)"
        Patches by searching for a given pattern $search (regexp) and
        replacing it by the text string $replace. Example:

                # Remove the all: target and all its production 
                # commands from a Makefile
            $patcher->replace(qr(^all:.*?\n\n)sm,
                              "all:\n\n");

        Note that the replace command will replace *the entire line* if it
        finds that the regular expression is matching.

        CAUTION: Make sure that $search doesn't match a section that
        contains another patch already. "Config::Patch" can't handle this
        case yet.

    "$patcher->comment_out($search)"
        Patches by commenting out config lines matching the regular
        expression $search. Example:

                # Remove the function 'somefunction'
                # commands from a Makefile
            $patcher->replace(qr(^all:.*?\n\n)sm,
                              "all:\n\n");

        Note that the replace command will replace *the entire line* if it
        finds that the regular expression is matching.

    "($arrayref, $hashref) = $patcher->patches()"
        Examines the file and locates all patches.

        It returns two results: $arrayref, a reference to an array, mapping
        patch keys to the text of the patched sections:

            $arrayref = [ ['key1', 'patchtext1'], ['key2', 'patchtext2'],
                          ['key2', 'patchtext3'] ];

        Note that there can be several patched sections appearing under the
        same patch key (like the two non-consecutive sections under "key2"
        above).

        The second result is a reference $hashref to a hash, holding all
        patch keys as keys. Its values are the number of patch sections
        appearing under a given key.

LIMITATIONS
    "Config::Patch" assumes that a hashmark (#) at the beginning of a line
    in the configuration file marks a comment.

COPYRIGHT AND LICENSE
    Copyright 2005 by Mike Schilli. This library is free software; you can
    redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR
    2005, Mike Schilli <cpan@perlmeister.com>