texted

Compact domain specific language (DSL) for editing blocks of plain text

texted is a line-oriented DSL that focus on simple text editing operations, operating on independent chunks of text (for example commenting/uncommenting lines).

It is not suitable for complex changes. If you need those, please consider using a library that is syntax-aware, like configupdater for .ini/.cfg files, tomlkit for .toml and libCST or refactor for Python files.

Installation

You can install texted with the help of pip:

$ pip install texted

After doing that you will be able to use texted in your Python scripts.

Quickstart

Using texted involves the following workflow:

1. Select the relevant lines of a given text.
2. Perform an edition operation over the selection.

This is workflow is shown in the example below:

>>> from texted import edit, find, until, contains, startswith, blank, remove_prefix
>>> example = """\
... # [testenv:typecheck]
... # deps = mypy
... # commands = python -m mypy {posargs:src}
... [testenv:docs]
... deps = sphinx
... changedir = docs
... commands = python -m sphinx -W --keep-going . {toxinidir}/build/html
... """
>>> new_text = edit(
...    example,
...    find(contains("[testenv:typecheck]")) >> until(startswith("[testenv") | blank),
...    remove_prefix("# "),
... )
>>> print(new_text)
[testenv:typecheck]
deps = mypy
commands = python -m mypy {posargs:src}
[testenv:docs]
deps = sphinx
changedir = docs
commands = python -m sphinx -W --keep-going . {toxinidir}/build/html

One of the most basic kinds of select operations can be created with find. This operation will select the first line that matches a criteria. For example:

find(lambda line: "[testenv:typecheck]" in line)

… will select the first line of a text that contains the "[testenv:typecheck]" string. We can then extend (>>) this selection for all the contiguous lines that are not empty with:

find(lambda line: "[testenv:typecheck]" in line) >> whilist(bool)
# => bool is handy! bool("") == False, bool("not empty") == True

After you have selected the block of lines, you can apply a edit operation. For example:

add_prefix("# ")  # => equivalent to: replace(lambda line: "# " + line)

… will add the prefix "# " to all the non empty lines in the selection.

Note that all these functions are lazy and don't do anything until they are called with edit.

Note

This library supports only \n line endings.

Note

This project has been set up using PyScaffold 4.4. For details and usage information on PyScaffold see https://pyscaffold.org/.