Printing replacements for deprecated syntax #
A replacement alternative of deprecated_syntax turns deprecated syntax into new syntax, which is
offered as an edit of the source text of the deprecated syntax. The goal is that the edited source
parses as the new syntax, while keeping the edit as small as the source allows.
Pretty-printing the new syntax on its own does not achieve this, as the surrounding source is not
printed again: the new syntax may bind less tightly than the deprecated syntax, and its first and
last tokens may merge with the adjacent tokens of the source, e.g. - followed by -1 starts a
comment. The parenthesizer and formatter avoid this when printing a whole syntax tree, but only
the deprecated syntax itself is available here, so we approximate them:
- A replacement term or tactic is parenthesized unless it binds at least as tightly as the deprecated syntax on both sides, in which case it parses the same in any position where the deprecated syntax parses. As the actual position is unknown, this can add parentheses that are not needed there.
- A space is inserted between the replacement and an adjacent source token if the formatter's
token separation rule, using the current token table, requires one. The token to the left is
recovered by lexing the preceding whitespace-delimited source text. No space is inserted before
trivia following the deprecated syntax, nor between an identifier and a following
., which continues the identifier as field notation.
Always parenthesizing the replacement and surrounding it with spaces would be safer, but it would change the source more than needed in most cases.
This is an incomplete heuristic, and the edited source may still parse differently from the new
syntax. For example, syntax of categories other than terms and tactics is never parenthesized, the
lexed text to the left can start inside a comment or string literal so that the wrong token is
recovered, and a replacement ending in - merges with a comment directly following it.
Returns the text replacing the source of stx, which has category cat and source range range,
by newStx. See the module docstring for how the text is made to fit into the surrounding source.
Equations
- One or more equations did not get rendered due to their size.