Proposal: `MethodPrefix` in llcppg.cfg

This is a design proposal, so confirm with maintainers before coding. Start with how TypeAbbr and FuncPrefix are read from llcppg.cfg, then find the step where a global function judged to be a method of a type has its prefix removed. The fix should strip a literal per-type prefix there and leave other types unchanged. Done when gzbuffer on GzFile becomes Buffer and existing configs produce the same output.

Summary

Add a MethodPrefix field to llcppg.cfg that lets a library author declare, per type, a literal prefix to remove from the names of that type's methods. It targets older C libraries such as zlib, where the type is encoded in the function name by a short prefix (gz for gzFile) that cannot be recovered by lexical analysis.

"MethodPrefix": {
    "GzFile": "gz"
}

With this configuration, gzbuffer(gzFile file, unsigned size) becomes (*GzFile).Buffer.

Background

When llcppg turns a global C function into a method, it has to decide what the method is called. For most modern C libraries the type name is embedded in the function name, separated from the rest by _ or by a camel-case boundary, and llcppg strips it using lexical rules:

CXTargetInfo
clang_getTranslationUnitTargetInfo(CXTranslationUnit CTUnit);

Here TranslationUnit appears as a whole word inside the name, so after the library prefix (clang_) and the type name are removed, what remains is TargetInfo. Type abbreviations (TypeAbbr) extend this for names where the type is written in a shortened form.

All of these mechanisms work at the lexical level: they only remove things that form complete, well-delimited words.

Problem

Older libraries often do not follow that convention. In zlib:

int gzbuffer(gzFile file, unsigned size);
int gzread(gzFile file, voidp buf, unsigned len);
int gzclose(gzFile file);

The receiver type is gzFile, but the function name only carries the two-letter prefix gz, glued directly to the rest of the name (gz + buffer). There is no _, no case change, and no complete type word to match. Because gz is not a lexically valid unit, neither the built-in type-name stripping nor TypeAbbr can remove it, and the generated method ends up with an awkward name like Gzbuffer.

The existing FuncPrefix cannot help either: it is global rather than per type, and it removes the prefix from function names whether or not the function becomes a method of that type.

Proposal

MethodPrefix is a map from a type's Go name to the prefix to strip from that type's method names.

{
    "MethodPrefix": {
        "GzFile": "gz"
    }
}

Key points of the design:

• The key is the type's goName, consistent with TypeAbbr. In the example above, the C type gzFile has the Go name GzFile.
• The value is a literal prefix, written the way it appears in the C function name. Following the convention used throughout llcppg.cfg, Prefix and Suffix fields ignore lexical boundaries, while all other concepts work within them. MethodPrefix is a Prefix field, so gz is removed from gzbuffer even though gz and buffer are not separated by any word boundary.
• Matching is on the C function name, case-sensitive, and the prefix must match at the start of the name.

When it runs

MethodPrefix is applied at the point where the type's goName and cName are both known, but the method's name is still in its original C style (before any conversion to Go-style camel case). In terms of the function-name pipeline, it takes part in the step where a global function that has been judged to be a method gets its type-related prefix removed.

After the prefix is removed, the remainder goes through the normal C-style to Go-style conversion, so the result is exported and camel-cased as usual:

What it does not do

• It does not decide whether a function is a method. That is still determined by the existing mechanisms (the receiver is the first parameter, and so on). MethodPrefix only affects the name of a function that has already been classified as a method of the given type.
• It does not change functions that are not methods of that type. gzopen(const char *path, const char *mode) returns a gzFile but does not take one as its first parameter, so it remains a plain function and MethodPrefix does not touch it.

Behavior details

• No match. If a method of the type does not start with the configured prefix, MethodPrefix has no effect on that name, and the usual lexical rules apply as before, including TypeAbbr.
• Match. If the prefix matches, it is removed and the remainder is used as the base of the method name. For that name, MethodPrefix and TypeAbbr are mutually exclusive: once MethodPrefix matches, TypeAbbr is not consulted at all, neither for type-prefix removal nor for suffix removal. The built-in lexical type-name stripping is likewise not applied on top of the removed prefix, since the author has explicitly said how this type's methods are prefixed. The remainder only goes through the normal C-style to Go-style conversion.
• Empty remainder. If removing the prefix would leave nothing (a function named exactly gz), the prefix is not applied.
• Types without an entry. Behave exactly as today. The option is purely additive, and existing configurations keep working unchanged.

Interaction with TypeAbbr

TypeAbbr has two roles: every abbreviation can be used for suffix removal, and only the last abbreviation is used for type-prefix removal. When MethodPrefix matches a method name, neither role runs for that name.

Consider this configuration:

{
    "MethodPrefix": {
        "FooType": "foo"
    },
    "TypeAbbr": [
        "FooType: InFoo, Foo"
    ]
}

For a method named fooBarInFoo:

fooBarInFoo
-> MethodPrefix "foo" matches, remove it
-> BarInFoo
-> TypeAbbr is skipped (no prefix removal, no suffix removal)
-> BarInFoo

The result is BarInFoo, not Bar. If a type needs both a literal prefix and an abbreviation suffix stripped, that combination is not supported for now. A method of the same type that does not start with foo is unaffected by MethodPrefix and still goes through TypeAbbr as usual.

The reason for keeping the two mechanisms mutually exclusive is predictability: a name is handled either by the literal rule the author wrote or by the lexical rules, never by a mix of both. This is also the more conservative choice, because it can be relaxed later without breaking any configuration, whereas the opposite direction cannot.

Relationship to other options

MethodPrefix fills the one gap the others leave: a type-specific prefix that has no lexical structure.

Example: zlib

{
    "name": "zlib",
    "MethodPrefix": {
        "GzFile": "gz"
    }
}

Generated Go (abridged):

func (p GzFile) Buffer(size c.Uint) c.Int
func (p GzFile) Read(buf c.Pointer, len c.Uint) c.Int
func (p GzFile) Close() c.Int

Without the option, the same functions would appear as Gzbuffer, Gzread and Gzclose.

Possible extensions (out of scope)

• Wildcard or replacement syntax in the value, in the style of the unified name matcher. The literal prefix covers the zlib case, and the matcher can be reused later if a real need appears.
• Allowing a list of prefixes for a type whose methods are spread over several prefixes. This can be added later by accepting a list in addition to a string without breaking existing configurations.
• Letting TypeAbbr suffix removal continue to apply after a MethodPrefix match, for types that need both. This would only relax the current mutual exclusion, so it can be added later if a real library needs it.