semvec/pypi-packages huggingface dataset:
parsy-extn 0.0.2
Some small extensions to parsy

# Some small extensions to parsy

This offers a small extension to the behaviour of Parsy.

## Note-keeping

Input streams gain the ability to keep notes. These are additional information
associated with a particular index in the stream. As the parsing process proceeds,
new notes may be written. An attempt to fetch the most recent set of notes can be performed
by:

    recent_notes = yield parsy_extn.get_notes

and notes at the current point in parsing may be written by

    yield put_notes(new_notes)

As the parser backtracks, older sets of notes may be thrown away.

### Notes on the mutability of notes

Notes are kept in a dictionary. `get_notes` performs a shallow copy of this dictionary;
however, references to embedded objects are identical.

This is intentional; the utility of notes is in allowing a parser to back-fill
already-generated placeholder values with actual content.

However, care should be taken when writing new sets of notes that references to other
mutable objects (such as lists) are not duplicated accidentally; this will result in
the backtracking process losing the immutability of previous notes.

## Handling augmentation

### Manually augmenting the stream

An input `str` or `list` may be augmented before being passed to a parser. This should
be done at the initial point of ingestion into the grammar:

    result = grammar_entry_point.parse(parsy_extn.Noted.augment(original_input))

### Wrapping a single entry-point's `parse` method

Alternatively, a grammar's entry-point may be decorated to automatically wrap values as
they are passed to the `parse` method:

    grammar_entry_point = parsy_ext.keeps_notes(grammar_entry_point)
    result = grammar_entry_point.parse(original_input)

### Monkey-patching `parsy.Parser`

Finally, the `parsy.Parser` object itself may be monkey-patched to wrap any input on
entry to `parse` or `parse_partial`:

    parsy_extn.monkeypatch_parsy()
    result = grammar_entry_point.parse(original_input)

## Motivation

The motivation for this is to handle constructs like shell 'heredocs' with a single
pass of a parser. They are otherwise notoriously difficult to handle; even with
this facility, the resulting grammars are fiddly.

A trivial example is given in the `test_parsy_extn` module.