data/TWiki/TWikiMergeDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
---+ Package =TWiki::Merge=
colas@0
     2
colas@0
     3
Support for merging strings
colas@0
     4
colas@0
     5
colas@0
     6
%TOC%
colas@0
     7
colas@0
     8
---++ StaticMethod *merge2* <tt>($arev,$a,$brev,$b,$sep,$session,$info)</tt>
colas@0
     9
colas@0
    10
   * =$arev= - rev for $a (string)
colas@0
    11
   * =$a= - first ('original') string
colas@0
    12
   * =$brev= - rev for $b (string)
colas@0
    13
   * =$b= - second ('new') string
colas@0
    14
   * =$sep= = separator, string RE e.g. '.*?\n' for lines
colas@0
    15
   * =$session= - TWiki object
colas@0
    16
   * =$info= - data block passed to plugins merge handler. Conventionally this will identify the source of the text being merged (the source form field, or undef for the body text)
colas@0
    17
colas@0
    18
Perform a merge of two versions of the same text, using
colas@0
    19
HTML tags to mark conflicts.
colas@0
    20
colas@0
    21
The granularity of the merge depends on the setting of $sep.
colas@0
    22
For example, if it is ="\\n"=, a line-by-line merge will be done.
colas@0
    23
colas@0
    24
Where conflicts exist, they are marked using HTML &lt;del> and
colas@0
    25
&lt;ins> tags. &lt;del> marks content from $a while &lt;ins>
colas@0
    26
marks content from $b.
colas@0
    27
colas@0
    28
Non-conflicting content (insertions from either set) are not
colas@0
    29
marked.
colas@0
    30
colas@0
    31
The plugins =mergeHandler= is called for each merge.
colas@0
    32
colas@0
    33
Call it like this:
colas@0
    34
<verbatim>
colas@0
    35
$newText = TWiki::Merge::merge2(
colas@0
    36
   $oldrev, $old, $newrev, $new, '.*?\n', $session, $info );
colas@0
    37
</verbatim>
colas@0
    38
colas@0
    39
colas@0
    40
colas@0
    41
---++ StaticMethod *simpleMerge* <tt>($a,$b,$sep) -> \@arr</tt>
colas@0
    42
colas@0
    43
Perform a merge of two versions of the same text, returning
colas@0
    44
an array of strings representing the blocks in the merged context
colas@0
    45
where each string starts with one of "+", "-" or " " depending on
colas@0
    46
whether it is an insertion, a deletion, or just text. Insertions
colas@0
    47
and deletions alway happen in pairs, as text taken in from either
colas@0
    48
version that does not replace text in the other version will simply
colas@0
    49
be accepted.
colas@0
    50
colas@0
    51
The granularity of the merge depends on the setting of $sep.
colas@0
    52
For example, if it is ="\\n"=, a line-by-line merge will be done.
colas@0
    53
$sep characters are retained in the outout.
colas@0
    54
colas@0
    55
colas@0
    56
colas@0
    57
---++ StaticMethod *merge3* <tt>($arev,$a,$brev,$b,$crev,$c,$sep,</tt>
colas@0
    58
                          $session, $info )
colas@0
    59
colas@0
    60
   * =$arev= - rev for common ancestor (id e.g. ver no)
colas@0
    61
   * =$a= - common ancestor
colas@0
    62
   * =$brev= - rev no for first derivative string (id)
colas@0
    63
   * =$b= - first derivative string
colas@0
    64
   * =$crev= - rev no for second derivative string (id)
colas@0
    65
   * =$c= - second derivative string
colas@0
    66
   * =$sep= = separator, string RE e.g. '.*?\n' for lines
colas@0
    67
   * =$session= - TWiki object
colas@0
    68
   * =$info= - data block passed to plugins merge handler. Conventionally this will identify the source of the text being merged (the source form field, or undef for the body text)
colas@0
    69
colas@0
    70
Perform a merge of two versions (b and c) of the same text, using
colas@0
    71
HTML &lt;div> tags to mark conflicts. a is the common ancestor.
colas@0
    72
colas@0
    73
The granularity of the merge depends on the setting of $sep.
colas@0
    74
For example, if it is =".*?\\n"=, a line-by-line merge will be done.
colas@0
    75
colas@0
    76
Where conflicts exist, they are labeled using the provided revision
colas@0
    77
numbers.
colas@0
    78
colas@0
    79
The plugins =mergeHandler= is called for each merge.
colas@0
    80
colas@0
    81
Here's a little picture of a 3-way merge:
colas@0
    82
colas@0
    83
      a   <- ancestor
colas@0
    84
     / \
colas@0
    85
    b   c <- revisions
colas@0
    86
     \ /
colas@0
    87
      d   <- merged result, returned.
colas@0
    88
colas@0
    89
call it like this:
colas@0
    90
<verbatim>
colas@0
    91
    my ( $ancestorMeta, $ancestorText ) =
colas@0
    92
        $store->readTopic( undef, $webName, $topic, $originalrev );
colas@0
    93
    $newText = TWiki::Merge::merge3(
colas@0
    94
        $ancestorText, $prevText, $newText,
colas@0
    95
        $originalrev, $rev, "new",
colas@0
    96
        '.*?\n' );
colas@0
    97
</verbatim>
colas@0
    98
colas@0
    99