92 lines
2.7 KiB
Markdown
92 lines
2.7 KiB
Markdown
# Advanced Usage (Python)
|
|
|
|
## Edit Provenance
|
|
|
|
Track which changes came from where using `reconcile_with_history`:
|
|
|
|
```python
|
|
from reconcile_text import reconcile_with_history
|
|
|
|
result = reconcile_with_history(
|
|
"Hello world",
|
|
"Hello beautiful world",
|
|
"Hi world",
|
|
)
|
|
|
|
print(result["text"]) # "Hi beautiful world"
|
|
print(result["history"]) #
|
|
# [
|
|
# {"text": "Hello", "history": "RemovedFromRight"},
|
|
# {"text": "Hi", "history": "AddedFromRight"},
|
|
# {"text": " beautiful", "history": "AddedFromLeft"},
|
|
# {"text": " ", "history": "Unchanged"},
|
|
# {"text": "world", "history": "Unchanged"},
|
|
# ]
|
|
```
|
|
|
|
## Tokenization Strategies
|
|
|
|
`reconcile-text` offers different approaches to split text for merging:
|
|
|
|
- **Word tokenizer** (`"Word"`) - Splits on word boundaries (recommended for prose)
|
|
- **Character tokenizer** (`"Character"`) - Individual characters (fine-grained control)
|
|
- **Line tokenizer** (`"Line"`) - Line-by-line (similar to `git merge` or more precisely [`git merge-file`](https://git-scm.com/docs/git-merge-file))
|
|
- **Markdown tokenizer** (`"Markdown"`) - Splits on Markdown structural boundaries (headings, list items, paragraphs)
|
|
|
|
```python
|
|
from reconcile_text import reconcile
|
|
|
|
result = reconcile("abc", "axc", "abyc", "Character")
|
|
print(result["text"]) # "axyc"
|
|
```
|
|
|
|
## Cursor Tracking
|
|
|
|
`reconcile-text` automatically tracks cursor positions through merges, which is useful for collaborative editors. Selections can be tracked by providing them as a pair of cursors.
|
|
|
|
```python
|
|
from reconcile_text import reconcile
|
|
|
|
result = reconcile(
|
|
"Hello world",
|
|
{
|
|
"text": "Hello beautiful world",
|
|
"cursors": [{"id": 1, "position": 6}], # After "Hello "
|
|
},
|
|
{
|
|
"text": "Hi world",
|
|
"cursors": [{"id": 2, "position": 0}], # At the beginning
|
|
},
|
|
)
|
|
|
|
# Result: "Hi beautiful world" with repositioned cursors
|
|
print(result["text"]) # "Hi beautiful world"
|
|
print(result["cursors"]) # [{"id": 2, "position": 0}, {"id": 1, "position": 3}]
|
|
```
|
|
|
|
> The `cursors` list is sorted by character position (not IDs).
|
|
|
|
## Compact Diffs
|
|
|
|
Generate and apply compact diff representations:
|
|
|
|
```python
|
|
from reconcile_text import diff, undiff
|
|
|
|
original = "Hello world"
|
|
changed = "Hello beautiful world"
|
|
|
|
# Generate a compact diff
|
|
d = diff(original, changed)
|
|
print(d) # [5, ' beautiful world']
|
|
|
|
# Reconstruct the changed text from the diff
|
|
reconstructed = undiff(original, d)
|
|
assert reconstructed == changed
|
|
```
|
|
|
|
Diff entries are positive integers (retain N characters), negative integers (delete N characters), and strings (insert text).
|
|
|
|
## File Merging Example
|
|
|
|
For a complete file-merging CLI (a trivial `git merge-file`), see [`examples/merge_file.py`](../examples/merge_file.py).
|