Package com.deltawalker.script

Interface TextComparison

All Superinterfaces:
Comparison, FileComparison, HistoryEntry
public interface TextComparison extends FileComparison
A Comparison of text files. Its results are DeltaRanges - blocks of text, given by an offset and a length in each document - that can be inspected, merged from one Role into another, and saved. 

 const Comparison = Java.type('com.deltawalker.script.Comparison');
 const Role = Java.type('com.deltawalker.script.Role');

 const IN = App.getProperty('user.home') + '/test/samples';
 const comp = App.getComparisons().create(Comparison.Type.TEXT,
         [IN + '/q0.txt', IN + '/q1.txt'], null);
 await comp.compare();

 const deltas = comp.getAllDeltas();
 console.log('Blocks: ' + deltas.length);
 for (let i = 0; i < deltas.length; i++) {
     const d = deltas[i];
     if (d.isChanged()) {
         console.log('Changed: '
                 + comp.getText(Role.ONE, d.offset(Role.ONE), d.length(Role.ONE)));
     }
 }

  • Method Details

    • deleteText

      void deleteText(DeltaRange[] deltas, Role[] roles, ProgressListener pm) throws IllegalArgumentException, BadLocationException
      Deletes the text of the specified DeltaRanges from the documents with the specified Roles. The change is made in the comparison only; call FileComparison.save(Role, String, ProgressListener) to save it.
      Parameters:
      deltas - the ranges whose text is to be deleted; cannot be null or empty
      roles - the roles of the documents to delete text from; cannot be null or empty, and must all be roles of this comparison
      pm - an optional ProgressListener to track the progress of this operation and to cancel it; can be null
      Throws:
      NullPointerException - if deltas or roles is null
      IllegalArgumentException - if deltas or roles is empty, or if a role is not a role of this comparison, for instance Role.TWO in a two-way comparison
      BadLocationException - if a range refers to an offset or length that does not exist in a document

    • getAllDeltas

      DeltaRange[] getAllDeltas()
      Returns the top-level blocks of text found by the last Comparison.compare(). Use the is...() methods of Delta to tell what kind of difference each block represents, and DeltaRange.getChildren() for the inline differences within a block. 
      
 await comp.compare();
 const deltas = comp.getAllDeltas();
 console.log('Blocks found: ' + deltas.length);
      Returns:
      an array of this comparison's DeltaRanges

    • getText

      String getText(Role role, int offset, int length) throws BadLocationException, IllegalArgumentException
      Returns part of the text of the document with the specified Role, for instance the text a DeltaRange refers to: 
      
 const text = comp.getText(Role.ONE, delta.offset(Role.ONE), delta.length(Role.ONE));

      To get the entire content of a document use an offset of 0 and the length returned by length(Role). Be careful with very large documents: the text is copied, which can run out of memory.

      Parameters:
      role - the role of the document; must be a role of this comparison
      offset - the 0-based offset of the first character to return
      length - the number of characters to return
      Returns:
      the text of the document with the specified role at the specified offset with the specified length
      Throws:
      BadLocationException - if offset and length do not describe a range within the document
      IllegalArgumentException - declared for compatibility

    • length

      int length(Role role) throws IllegalArgumentException
      Returns the number of characters in the document with the specified Role.
      Parameters:
      role - the role of the document; must be a role of this comparison, for instance not Role.TWO in a two-way comparison
      Returns:
      the length of the document, in characters
      Throws:
      IllegalArgumentException - declared for compatibility

    • merge

      ScriptOperation merge(MergeOp mergeOp, DeltaRange[] ranges, Role src, Role dst, ProgressListener pl) throws BadLocationException, IllegalArgumentException
      Applies the specified MergeOp to the specified DeltaRanges, from the source role to the destination role, and returns an operation that settles when the merge completes. The merge changes the documents in the comparison only; call FileComparison.save(Role, String, ProgressListener) to save the result. 
      
 const MergeOp = Java.type('com.deltawalker.script.MergeOp');

 // Three-way: bring all non-conflicting changes into Role.REF
 await comp.merge(MergeOp.MERGE, comp.getAllDeltas(), null, Role.REF, null);
 comp.save(Role.REF, '/path/to/merged.txt', null);

 // Replace the Role.REF text of one block with its Role.ONE text
 await comp.merge(MergeOp.REPLACE, [delta], Role.ONE, Role.REF, null);
      Parameters:
      mergeOp - the operation to perform; cannot be null
      ranges - the ranges to merge; cannot be null. When empty, nothing is done and the returned operation is already resolved.
      src - the source role. Pass null for MergeOp.MERGE, which takes its sources from both Role.ONE and Role.TWO.
      dst - the destination role
      pl - an optional ProgressListener to track the progress of this operation and to cancel it; can be null
      Returns:
      an operation that resolves when the merge completes
      Throws:
      BadLocationException - if a range is invalid in the source or the destination document
      NullPointerException - if mergeOp or ranges is null
      IllegalArgumentException - if Role.TWO is used in a two-way comparison, or if MergeOp.MERGE is used in a two-way comparison

    • report

      ScriptOperation report(String path, ReportKind kind, PatchFormat format) throws IllegalArgumentException
      Writes an HTML report of the results of this comparison to a file, and returns an operation that settles when the report has been written. 
      
 const ReportKind = Java.type('com.deltawalker.script.ReportKind');

 await comp.report('/path/to/report.html', ReportKind.HTML, null);

      Text comparisons always produce an HTML report; kind and format are only checked, not used to choose another format.

      Parameters:
      path - the path of the report file; cannot be null or empty
      kind - the kind of report; cannot be null. Use ReportKind.HTML.
      format - the format of a patch report; cannot be null when kind is ReportKind.PATCH, otherwise can be null
      Returns:
      an operation that resolves when the report has been written
      Throws:
      NullPointerException - if path or kind is null, or if format is null for a patch report
      IllegalArgumentException - if path is empty
      See Also:

    • reportEx

      ScriptOperation reportEx(UriInfo uriInfo, ReportKind kind, PatchFormat format) throws IllegalArgumentException
      Like report(String, ReportKind, PatchFormat), but takes a UriInfo for the report file, so that, for example, a remote location, a user name and password, a character encoding or a line ending can be specified. When the UriInfo specifies no character encoding, UTF-8 is used.
      Parameters:
      uriInfo - the location of the report file; cannot be null and must have a non-empty URI
      kind - the kind of report; cannot be null. Use ReportKind.HTML.
      format - the format of a patch report; cannot be null when kind is ReportKind.PATCH, otherwise can be null
      Returns:
      an operation that resolves when the report has been written
      Throws:
      NullPointerException - if uriInfo or kind is null, or if format is null for a patch report
      IllegalArgumentException - if the URI of uriInfo is empty

    • setText

      void setText(Role role, int offset, int length, String text) throws BadLocationException, IllegalArgumentException
      Replaces the specified range of the document with the specified Role with the specified text. The change is made in the comparison only; call FileComparison.save(Role, String, ProgressListener) to save it. 
      
 // Insert a line at the beginning of the Role.ONE document
 comp.setText(Role.ONE, 0, 0, 'First line\n');
      Parameters:
      role - the role of the document to change; cannot be null
      offset - the 0-based offset of the range to replace
      length - the length of the range to replace; 0 to insert
      text - the replacement text; cannot be null
      Throws:
      BadLocationException - if offset and length do not describe a range within the document
      NullPointerException - if role or text is null
      IllegalArgumentException - if Role.TWO is specified in a two-way comparison