refex.formatting

Utilities for generating, applying, and displaying Substitution objects.

User Display

diff_substitutions(content: str, subs: Iterable[refex.substitution.Substitution], filename: str, renderer: refex.formatting.Renderer) → Iterable[Tuple[bool, str]]

Yields (is_diff, displayable diff/match information) for subs.

class Renderer(match_format: str = '{head}{match}{tail}', color: bool = True)

Applies substitutions and gives styled output for humans.

Matches and diffs are styled via colorama.

Non-diff spans with the same label will always be styled the same, even across multiple calls to \(render()\). (Renderer keeps the styling as state). However, just because two spans are styled the same doesn’t mean they have the same label – styles can be reused.

The one exception to this is the primary label / primary span, which is only styled normally if there are no other labels. If there are other labels, then instead of being assigned its normal color, the primary span is just given a neutral bright style.

Overlapping non-diff spans are given their own unique color, per-combination.

The displayed output covers the entire substitution, even when nothing changes.

Parameters

• match_format –

  The format string when displaying a match (a Substitution without a replacement). It can use the following variables:

  match

  The styled match.

  head

  The part of the line before the match.

  tail

  The part of the line after the match.

  As well as anything in the extra argument passed to render().

• color – Whether to style and colorize human-readable output or not.

render(contents: str, sub: refex.substitution.Substitution, extra: Mapping[str, Any]) → Tuple[bool, str]

Renders a single Substitution for display on the terminal.

Parameters

• contents – the original string the substitution is against.

• sub – a Substitution object.

• extra – extra substitution variables for the match format template.

Returns

(is_diff, display)

is_diff is True if this represents a diff, False if it represents a mere match with no replacement.

display is a human-readable string to represent the substitution, printable to the terminal.

Rewriting

apply_substitutions(data: str, subs: Iterable[refex.substitution.Substitution]) → str

Applies all substitutions and returns the result.

exception RewriteError

Rewriting failed.

After a RewriteError, that particular set of rewrites is skipped, but the rest of the program moves on.

Templates

class Template

A substitution template for matches within a ParsedFile.

Implementations must define a substitute_match() method which returns a replacement string for any given match. Implementations apply some template, whose results may be tweaked according to knowledge about the syntax being used and the context in which it is used. (For example, parenthesization, formatting, etc.)

abstract substitute_match(parsed: refex.parsed_file.ParsedFile, match: refex.match.Match, matches: Mapping[str, Tuple[int, int]]) → str

Substitute in pre-existing matches into the template.

Parameters

• parsed – The ParsedFile each match was on.

• match – The match being replaced.

• matches – A mapping from variable name to (start, end) span.

Returns

The rendered template.

abstract property variables

Returns the set of metavariables present in the template.

class LiteralTemplate(template: str)

Bases: refex.formatting.Template

A no-op template which does no substitution at all.

template = None

The source template.

substitute_match(parsed, match, matches)

Substitute in pre-existing matches into the template.

Parameters

• parsed – The ParsedFile each match was on.

• match – The match being replaced.

• matches – A mapping from variable name to (start, end) span.

Returns

The rendered template.

class ShTemplate(template: str)

Bases: refex.formatting.Template

A string.Template-style literal template.

This does no special reformatting.

template = None

The source template.

substitute_match(parsed, match, matches)

Substitute in pre-existing matches into the template.

Parameters

• parsed – The ParsedFile each match was on.

• match – The match being replaced.

• matches – A mapping from variable name to (start, end) span.

Returns

The rendered template.

class RegexTemplate(template: str)

Bases: refex.formatting.Template

A template using regex template syntax.

template = None

The source template.

substitute_match(parsed, match, matches)

Substitute in pre-existing matches into the template.

Parameters

• parsed – The ParsedFile each match was on.

• match – The match being replaced.

• matches – A mapping from variable name to (start, end) span.

Returns

The rendered template.