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