Undebt requires a pattern file that describes what to replace and how to replace it. There are two different ways to write pattern files: basic style, and advanced style. Unless you know you need multi-pass parsing, you should use basic style by default.
If you don’t know what style you should be using, you should be using basic style. When writing a basic style pattern, you must define the following names in your pattern file:
grammardefines what pattern you want to replace, and must be a pyparsing grammar object.
replaceis a function of one argument, the tokens produced by
grammar, that returns the string they should be replaced with, or
Noneto do nothing (this is the single-argument form—multi-argument is also allowed as documented below).
extracan be set to a string that will be added to the beginning (after the standard Python header) of any file in which there’s at least one match for
grammarand in which
extradoes not already appear in the header (this feature is commonly used for adding in imports).
Unlike basic style, advanced style allows you to use custom multi-pass parsing—if that’s not something you need, you should use basic style. When writing an advanced style pattern, you need only define one name:
patternsis a list of
(grammar, replace)tuples, where each tuple in the list is only run if the previous one succeeded
patterns is defined, Undebt will ignore any definitions of
extra. Instead, all of that information should go into the
As an example, you can replicate the behavior of the basic style
extra by doing the following:
from undebt.pattern.lang.python import HEADER @tokens_as_list(assert_len=1) def extra_replace(tokens): if extra not in tokens: return tokens + extra + "\n" else: return None patterns.append((HEADER, extra_replace))
Or equivalently but more succinctly:
from undebt.pattern.interface import get_pattern_for_extra patterns.append( get_pattern_for_extra( extra ) )
In both styles, when writing a
replace function, it is sometimes useful to have access to the parsing location in the file and/or the text of the original file. If your
replace function takes two arguments, it will be passed
location, tokens, and for three arguments, it will get
text, location, tokens. This will work even if you are using one of the