Proposal: A Unified Name-Matching Facility for llcppg

The proposal specifies a new newMatcher constructor and matcher.match API but names no implementation files or tests. Start by locating how MethodCheck is currently parsed and matched, then inspect the existing test layout and run the relevant tests. Done means the shared rule matcher follows the documented syntax, validation, ordering, and match-mode behavior, with tests covering the examples and errors.

Summary

llcppg needs to match and transform C/C++ names in many places: deciding which logical type a function belongs to (MethodCheck), abbreviating type names (TypeAbbr), and stripping prefixes (FuncPrefix, TypePrefix, ...). Today each option has its own ad-hoc mechanism. This proposal introduces one small, shared matching facility: a list of "pattern: replacement" rules using a single wildcard character * and positional references $1, $2, ...

It is much simpler than regular expressions, yet expressive enough for every naming convention we have met so far (for example, the Python C API).

Motivation

MethodCheck already uses such a mechanism. For Python it is configured as:

"MethodCheck": ["PyObject_: Object", "Py_: ", "Py*_: $1Object"]

This means:

• PyObject_XXX functions belong to class Object.
• Py_IsTrue (and other Py_XXX functions) belong to class "".
• PyList_XXX belongs to class ListObject ($1 = List), PyDict_XXX to DictObject, and so on.

One rule covers an entire family of names.

TypeAbbr, in contrast, is a plain map from a full type name to its abbreviation. That makes batch configuration impossible. To abbreviate ListObject to List, DictObject to Dict, TupleObject to Tuple, and so on, every type must be listed one by one. With the shared mechanism, the whole family becomes a single rule:

"TypeAbbr": ["*Object: $1"]

The same need exists for FuncPrefix, VarPrefix, EnumPrefix, MacroPrefix and TypePrefix (see the prefix-wildcard proposal). Instead of re-implementing matching per option, we extract it once.

Rule Syntax

A rule is a string of the form:

<pattern>: <replacement>

• The rule is split at the first :. Whitespace around the pattern and the replacement is trimmed. An empty replacement (e.g. "Py_: ") is valid and yields the empty string.
• Pattern: literal text, in which * is a wildcard matching one or more characters. A pattern may contain several wildcards.
• Replacement: literal text, in which $n (n = 1, 2, ...) is replaced by the text captured by the n-th wildcard in the pattern. $$ produces a literal $.

Wildcard semantics

• Each * captures at least one character.
• A * that is followed by more pattern text is non-greedy: it captures the shortest text that lets the rest of the pattern match (so Py*_ against PyList_Append captures List).
• A * at the very end of the pattern is greedy: it captures everything that remains.
• Matching is case-sensitive.

Match modes

The same rule list is evaluated in one of two modes, chosen by the caller:

Mode	matchFull	Meaning
Prefix match	false	The pattern must match the beginning of the source. The unmatched remainder is ignored.
Full match	true	The pattern must match the entire source.

MethodCheck uses prefix match (PyList_Append is matched by Py*_ although Append is left over). TypeAbbr uses full match (*Object must account for the whole type name).

Rule order

Rules are tried in order and the first matching rule wins. Order is therefore significant. In the Python example, PyObject_ must come before Py*_; otherwise PyObject_Str would match Py*_ and produce ObjectObject.

API

// newMatcher parses and validates a list of rule expressions and
// returns a matcher holding the compiled rules, in the given order.
// name identifies the config option (e.g. "MethodCheck", "TypeAbbr")
// and is used in error messages.
func newMatcher(name string, exprs []string) (matcher, error)

// match evaluates the rules against source, in order.
// If matchFull is true the pattern must cover the whole source;
// otherwise it only needs to match a prefix of it.
// matched reports whether any rule matched; ret is the expanded
// replacement of the first matching rule.
func (p matcher) match(source string, matchFull bool) (ret string, matched bool)

Notes:

• matched is needed because ret may legitimately be the empty string ("Py_: "). "Matched with empty result" and "no rule matched" must remain distinguishable.
• newMatcher is called once when the configuration is loaded, so all syntax errors surface early with the option name attached, for example: TypeAbbr[1]: invalid rule "Foo*": missing ':'.
• A matcher is an immutable compiled form of the whole rule list (literal segments plus wildcard positions and the replacement templates), so match involves no regular-expression engine and no allocation beyond the result string. Being immutable, it is safe to share across goroutines. The zero value holds no rules and matches nothing.

Usage sketch:

m, err := newMatcher("TypeAbbr", cfg.TypeAbbr)
if err != nil {
	return err
}
if abbr, ok := m.match("ListObject", true); ok {
	// abbr == "List"
}

Validation errors

newMatcher rejects:

• a rule without :;
• an empty pattern;
• a replacement referencing $n where the pattern has fewer than n wildcards;
• a malformed reference ($ followed by neither a digit nor $).

Examples

MethodCheck (prefix match)

Rules: ["PyObject_: Object", "Py_: ", "Py*_: $1Object"]

Source	Result
PyObject_Str	matched, Object
Py_IsTrue	matched, ""
PyList_Append	matched, ListObject
PyDict_GetItem	matched, DictObject
malloc	not matched

TypeAbbr (full match)

Rules: ["*Object: $1"]

Source	Result
ListObject	matched, List
DictObject	matched, Dict
Object	not matched (* needs at least one character)
ListObjectFoo	not matched (full match required)

A single exact entry is just a rule without a wildcard: "PyObject: Obj" replaces the old map entry {"PyObject": "Obj"}.

Multiple wildcards

Rules: ["lua_*_*: $1$2"] against lua_table_get → tableget.

Where It Applies

This proposal only introduces the facility. It does not plan to replace every existing mechanism in one step. Each option will be evaluated on its own, and whether (and how) it adopts the matcher is left for future decisions.

The table below lists the candidates and the mode each would naturally use:

Option	Mode	Notes
MethodCheck	prefix	Already behaves this way; can be refactored onto the shared code.
TypeAbbr	full	Natural fit; see the map equivalence below.
FuncPrefix, VarPrefix, EnumPrefix, MacroPrefix, TypePrefix	prefix	Possible follow-up: wildcard plus replacement in prefix stripping. NSPrefix is out of scope.

Equivalence with a map

A rule list is a strict generalization of a map from names to names, so adopting it never loses expressiveness. A map entry corresponds directly to a rule without wildcards. For TypeAbbr, these two are semantically identical (full match, no wildcard means exact equality):

{"ListObject": "List", "DictObject": "Dict"}

["ListObject: List", "DictObject: Dict"]

Wildcards are an optional addition on top of this: when many entries follow one pattern, they collapse into one rule (["*Object: $1"]). Existing exact entries can be kept as they are, or mixed with wildcard rules in the same list, as long as exact rules that should win over a wildcard come first.

Compatibility

Introducing newMatcher and matcher.match changes no existing behavior by itself. Whether an option such as TypeAbbr (currently a map) switches to a rule list, keeps accepting the map form alongside it, or stays as it is will be decided separately for each option, and is outside the scope of this proposal.

Because a map entry converts one-to-one into an exact-match rule (see "Equivalence with a map"), any such migration is mechanical. Converted entries contain no wildcards and cannot overlap one another, so the undefined iteration order of a map does not affect the result.

Non-Goals

• Full regular-expression power (alternation, character classes, quantifiers). If a case cannot be expressed with literals and *, it should be handled by a dedicated option rather than by growing this syntax.
• Matching against anything other than a single name string (no path or namespace awareness).

Open Questions

1. Should a pattern be allowed to contain no wildcard in prefix mode and still strip only the prefix ("Py_: ")? This proposal says yes; it is already the behaviour of MethodCheck.
2. Should we provide an escape for a literal * in patterns? C identifiers cannot contain *, so this is currently unnecessary, but it would matter if the facility is ever used for non-identifier text.
3. Should rules that can never fire because an earlier rule shadows them produce a warning at load time?