Padre::Delta

Padre::Delta(3pm)     User Contributed Perl Documentation    Padre::Delta(3pm)



NAME
       Padre::Delta - A very simple diff object that can be applied to editors
       fast

SYNOPSIS
           my $editor = Padre::Current->editor;
           my $from   = $editor->GetText;
           my $to     = transform_function($from);
           Padre::Delta->from_scalars( \$from => \$to )->to_editor($editor);

DESCRIPTION
       As a refactoring IDE many different modules and tools may wish to
       calculate changes to a document in the background and then apply the
       changes in the foreground.

       Padre::Delta objects provide a mechanism for defining change to an
       editor, with the representation stored in a way that is extremely well
       aligned with the Padre::Wx::Editor and Wx::Scintilla APIs.

       By doing as much preliminary calculations as possible in the background
       and passing a Padre::Delta object back to the parent, the amount of
       time spent blocking in the foreground is kept to an absolute minimum.

METHODS
           # Alter a document by line range, in loose form
           my $delta1 = Padre::Delta->new(
               'line',
               [ 1, 1, 'Content'   ], # Insert a single line
               [ 4, 3, ''          ], # Remove a single line
               [ 6, 9, 'Alternate' ], # Replace three lines with one
           )->tidy;

           # Alter a document by character range in tight form
           my $delta2 = Padre::Delta->new(
               'position',
               [ 35, 37, 'fghjkl' ], # Replace two characters with six
               [ 23, 27, ''       ], # Remove four characters
               [ 12, 12, 'abcd'   ], # Insert four characters
           );

       The "new" constructor takes a replacement mode and a list of targets
       and returns the delta object, which can then be applied to a "SCALAR"
       reference of Padre::Wx::Editor object.

       The first parameter should be the replacement mode. This will be either
       'line' for line range deltas as per the diff program, or 'position' for
       character position range deltas which operate at a lower level and
       directly on top of the position system of Wx::Scintilla.

       After the replacement mode, the constructor is provided with an
       arbitrarily sized list of replacement targets.

       Each replacement target should be an "ARRAY" reference containing three
       elements which will be the start of the range to be removed, the end of
       the range to be removed, and the text to replace the range with.

       The start of the range must always be a lower value than the end of the
       range. While providing a high to low range may incidentall work on some
       operating systems, on others it can cause Wx::Scintilla to segfault.

       Each replacement target will both remove existing content and replace
       it with new content. To achieve a simple insert, both range positions
       should be set to the same value at the position you wish to insert at.
       To achieve a simple deletion the replacement string should be set to
       the null string.

       The ordering of the replacement target is critically important. When
       the changes applied they will always be made naively and in the same
       order as supplied to the constructor.

       Because a change early in the document will alter the positions of all
       content after it, you should be very careful to ensure that your change
       makes sense if applied in the supplied order.

       If the positions of your replacement targets are not inherently
       precalculated to adjust for content changes, you should supply your
       changes from the bottom of the document upwards.

       Returns the new Padre::Delta object.

   mode
       The "mode" accessor indicates if the replacement will be done using
       line numbers or character positions.

       Returns 'line' or 'position'.

   null
       The "null" method returns true if the delta contains zero changes to
       the document and thus has no effect, or false if the delta contains any
       changes to the document.

       The ability to create null deltas allows refactoring to indicate a
       successful transform resulting in no changes to the current document,
       as opposed to some other response indicating a failure to apply the
       transform or similar response.

   from_diff
           my $delta = Padre::Delta->from_diff(
               Algorithm::Diff::diff( \@from => \@to )
           );

       The "from_diff" method takes a list of hunk structures as returned by
       the Algorithm::Diff function "diff" and creates a new delta that will
       apply that diff to a document.

       Returns a new Padre::Delta object.

   from_scalars
           my $delta = Padre::Delta->from_scalars( \$from => \$to );

       The "from_scalars" method takes a pair of documents "from" and "to" and
       creates a Padre::Delta object that when applied to document "from" will
       convert it into document "to".

       The documents are provided as SCALAR references to avoid the need for
       superfluous copies of what may be relatively large strings.

       Returns a new Padre::Delta object.

   tidy
           Padre::Delta->new( line => @lines )->tidy->to_editor($editor);

       The "tidy" method is provided as a convenience for situations where the
       quality of the replacement targets passed to the constructor is
       imperfect.

       To ensure that changes are applied quickly and editor objects are
       locked for the shortest time possible, the replacement targets in the
       delta are considered to have an inherent order and are always applied
       naively.

       For situations where the replacement targets do not have an inherent
       order, applying them in the order provided will result in a corrupted
       transform.

       Calling tidy on a delta object will correct ranges that are not
       provided in low to high order and sort them so changes are applied from
       the bottom of the document upwards to avoid document corruption.

       Returns the same Padre::Delta object as a convenience so that the tidy
       method can be used in changed calls as demonstrated above.

   to_editor
           my $changes = $delta->to_editor($editor);

       The "to_editor" method applies the changes in a delta object to a
       Padre::Wx::Editor instance.

       The changes are applied in the most simple and direct manner possible,
       wrapped in a single Undo action for easy of reversion, and in an update
       locker for speed.

       Return the number of changes made to the text contained in the editor,
       which may be zero in the case of a null delta.

COPYRIGHT & LICENSE
       Copyright 2008-2012 The Padre development team as listed in Padre.pm.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       The full text of the license can be found in the LICENSE file included
       with this module.



perl v5.14.2                      2012-04-19                 Padre::Delta(3pm)