✂️ Novident Editor Delta Simplify #

This is a package designed to facilitate the manipulation of documents in the Novident Editor Delta format within the Flutter ecosystem. The Delta format represents rich text content including text and inline attributes (such as bold or italic).

❓ Why use it? #

Manipulating content in a Delta format can be complex, especially when dealing with advanced operations such as searching, modifying, or filtering text based on specific attributes or patterns. Novident Editor Delta Simplify addresses this complexity by providing a user-friendly and powerful API that allows developers to perform these operations with ease and precision.

📎 QueryDelta Documentation #

For detailed usage and more complete examples of the API:

• Insert
• Replace
• Format
• Delete
• Diff
• Matching
• Extras

🔎 Introduction to QueryDelta #

The QueryDelta class is a query builder designed to create and modify Delta objects by applying various conditions. It allows for conditional operations and tracks changes made to the delta during the modification process. The purpose of QueryDelta is to provide a structured way to manipulate a Delta object, while keeping track of applied changes through conditions and ensuring the integrity of the final result.

final Delta delta = Delta()..insert('Hello, world!');
final BuildResult result = QueryDelta(delta: delta)
    .insert(
        insert: ' Beautiful ',
        target: ' world!',
        left: true,
    )
    .build();
print(result.delta);
// [{"insert": "Hello, Beautiful world!"}]

🛠️ Building the final Delta #

This is the key to finalizing the changes made to the QueryDelta. It applies all the conditions that were added to the query and generates the final Delta. This method is essential, as no modifications will be applied to the Delta until build() is run.

BuildResult build({
  List<TextOperation> Function(Object)? unknownObjectTypeBuilder,
  bool preventReuseConditions = true,
  bool maintainIgnoresConditions = true,
});

📝 Insert #

Add text at a specific position or relative to a matched target.

final Delta delta = Delta()..insert('Hello');
final BuildResult result = QueryDelta(delta: delta)
    .insert(
        insert: ', world!',
        startPoint: 5,
        target: null,
    )
    .build();
print(result.delta);
// [{"insert": "Hello, world!"}]

❌ Delete #

Remove text by range or matched target.

final Delta delta = Delta()..insert('This is a sample text to be used');
final BuildResult result = QueryDelta(delta: delta)
    .delete(
        target: 'sample ',
        startPoint: null,
        lengthOfDeletion: null,
    )
    .build();
print(result.delta);
// [{"insert": "This is a text to be used"}]

🔄 Replace #

Replace text by range, target, or pattern.

final Delta delta = Delta()..insert('Hello world!');
final BuildResult result = QueryDelta(delta: delta)
    .replace(
        target: 'world',
        replace: 'Dart',
        range: null,
    )
    .build();
print(result.delta);
// [{"insert": "Hello Dart!"}]

Dynamic replacement with replaceAllMapped:

final Delta delta = Delta()..insert('The price is 100 USD and 200 USD');
final BuildResult result = QueryDelta(delta: delta)
    .replaceAllMapped(
        replaceBuilder: (data, attrs, currentRange, matchRange) {
          final match = RegExp(r'\d+').firstMatch(data);
          if (match != null) {
            final num = int.parse(match.group(0)!);
            return [TextInsert('${num * 2}')];
          }
          return [];
        },
        target: r'\d+',
    )
    .build();
print(result.delta);
// [{"insert": "The price is 200 USD and 400 USD"}]

🎨 Format #

Apply inline attributes (bold, italic, color, etc.) by range or target.

final Delta delta = Delta()..insert('Hello, world!');
final BuildResult result = QueryDelta(delta: delta)
    .format(
        attribute: const MapEntry('bold', true),
        offset: 0,
        len: 5,
    )
    .build();
print(result.delta);
// [
//   {"insert": "Hello", "attributes": {"bold": true}},
//   {"insert": ", world!"}
// ]

🚫 Ignore #

Mark a range that should not be affected by other conditions.

final Delta delta = Delta()
    ..insert('Keep this safe')
    ..insert('But replace this');
final BuildResult result = QueryDelta(delta: delta)
    ..ignorePart(0, len: 14)  // protect "Keep this safe"
    ..replace(
        target: 'this',
        replace: 'that',
        range: null,
    )
    .build();
print(result.delta);
// [{"insert": "Keep this safe"}, {"insert": "But replace that"}]

🔍 Matching Methods #

Find text patterns across operations (supports cross-operation matching):

final Delta delta = Delta()
    ..insert('This is a bold text.', attributes: {'bold': true})
    ..insert('This is a normal paragraph.')
    ..insert('Another common paragraph.');
final List<DeltaRangeResult> results = QueryDelta(delta: delta)
    .allMatches(RegExp('paragraph', caseSensitive: false), null);
print(results);
// [
//   DeltaRangeResult(delta: [{"insert": "paragraph"}], Offset: [47, 56]),
//   DeltaRangeResult(delta: [{"insert": "paragraph"}], Offset: [82, 91]),
// ]

Find operations with specific attributes:

final results = QueryDelta(delta: delta).matchAttributes(
    inlineAttrs: {'bold': true},
    inlineAttrKeys: null,
);

📊 Diff Support #

Compare two Deltas and get a structured diff result:

final Delta delta = Delta()..insert('Experimental version Delta');
final QueryDelta query = QueryDelta(delta: delta)
    ..insert(insert: ' New data', target: 'Delta', startPoint: null, left: false)
    ..delete(target: null, startPoint: 14, lengthOfDeletion: 2)
    ..format(offset: 0, len: 12, attribute: const MapEntry('bold', true))
    ..build();
final DeltaCompareDiffResult result = query.compareDiff();
// parts: [
//   format('Experimental', 0, 12, {bold: true}),
//   equals(' v', 12, 14),
//   delete('er', 14, 16),
//   equals('sion Delta', 16, 26),
//   insert(' New data', 26, 35),
// ]