After thinking about this some more - methodmaps are a great way to transition our older API in a backwards compatible way. To make that easier, I'm going to lax the type checking of |this|. It will make the AdtArray example work without having to change the type signature of older natives in an incompatible way.

A more interesting question is how to approach newer APIs. I think I've settled there that, full-fledged OO is too difficult within spcomp1. The hardest problem is that we'd need garbage collection, which in and of itself is not terrible, but to make it work well we need to know which values in the heap point to GC objects. That's a daunting task, especially since the Pawn assembler plays fast and loose with function frame organization.

We can take baby steps though. What I'll implement next is something similar to methodmaps, that we can use on newer APIs:

class Transaction
{
  public native Transaction();
  public native ~Transaction();
  public native AddQuery(const String:name[], any:data = 0);
};

This will desugar into a methodmap internally. The native bindings will be unreachable, hiding the C-like nature of the underlying implementation (they'll bind as something like Transaction.AddQuery instead). Construction will happen via a method call on Transaction, and closing the handle will happen via a delete keyword.

There are two major differences between this API and methodmaps. Methodmaps expose the underlying C-like API, and are attached to existing tags. Classes will expose no such API, and classes must have a totally unique tag. These tags cannot be coerced to anything they cannot be stripped, and they cannot flow into variadic lists or anything marked any:.

These restrictions ensure that we can someday add GC support, bit-by-bit, to old natives. Without those restrictions, pointer values could flow all throughout SM data structures and it'd be a nightmare to get GC working at all (ahem, bug 3966).

I'm tentatively thinking of ditching Handles entirely for classes. New functions - like the transaction API - don't need handles, and it would be really good to define the C++ object API ahead of time. If we can require that new APIs have proper rooting, plugging in GC later will require almost no work.

Will methodmaps be limited to only tagged objects?

Cause for instance I can see this being useful for wrapping over all the entity/player APIs that pass around untagged entity indexes, such that something like this could exist:

methodmap Entity
{
    Teleport = TeleportEntity;
    GetClassname = GetEntityClassname;
    ...
}

methodmap Player < Entity
{
    GetName = GetClientName;
    ...
}

Additionally, I saw a comment in e3ddef8:

// Check the implicit this parameter. Currently we only allow scalars. As
// to not encourage enum-structs, we will not allow those either.

Is there a good reason against allowing enumstructs? I've grown pretty accustomed to using enumstructs in my own APIs any time I need to pass PODs around, or perform some actions on them, and it would be neat to be able to pass them around in methodmap functions instead of relying on old C-like functions.

Will methodmaps be limited to only tagged objects?

Methodmaps are usable with any tag, as long as the tag does not derive from a struct or class type (the latter is a pending construct). Indeed, psychonic mentioned a potential new methodmap-based entity API to unravel a lot of weirdness in the old one. It sounds like a good idea and that's exactly what methodmaps are there for: allowing us to transition to an OO API before having full OO support.

Is there a good reason against allowing enumstructs?

The technical reason is that methodmaps apply to tags. Tags are always scalar. Enum-structs are arrays. That is,

enum X {
    Y,
    Z,
};

In Pawn, this defines three constant symbols: Y=0, Z=1, and X=2. Declaring an enumstruct is allocating an array whose size is the highest enumeration value + 1. A methodmap over X can accept a Y or Z as this. To accept an X[], it would need to be a methodmap over X[] specifically. In theory we could make this work with some extra implementation effort - it doesn't look that hard.

On the other hand, enumstructs aren't really supported. I realize they happen to exist, and are used, but the instant we can provide something better they will be removed. They're offensive semantically and their implementation is awful.

Methodmaps are usable with any tag, as long as the tag does not derive from a struct or class type (the latter is a pending construct).

Currently doing

methodmap Entity {
    IsValid = IsValidEntity;
};

results in
error 108: method must have a first argument compatible with the methodmap type (Entity)

And you can't write methodmap _ {}; methodmap Entity < _ { .. }; to allow no tag.

So the only way is to define wrapper stocks or some new anonymous inline function declaration syntax you propsed in your first comment.

stock bool:IsValidEntityW(Entity:entity)
{
    return IsValidEntity(_:entity);
}

methodmap Entity {
    IsValid = IsValidEntityW;
};

vs.

methodmap Entity {
    IsValid = stock bool:(Entity:entity) { return IsValidEntity(_:entity); }
};

I'd encourage the second one to avoid cluttering. This would also be usable for a ClientCookie methodmap. The cookie Handle is passed as second argument in the GetClientCookie functions, so you need to switch the arguments around to have it work as an implicit this.

@peace-maker Yes, that is the intended behavior.

We'll see inline methods a few PRs later. The syntax will look like:

methodmap X {
    public bool:Function() {
    }

I just pushed a major refactoring of this PR to begin implementing the planned Transitional Syntax. This patch now introduces:

• Methodmaps, with new syntax that looks more similar to declaring a C++ class.
• Destructors and a "delete" keyword to normalize behavior across Handles and to-be-implemented Objects.
• Constructors, a suggestion from asherkin - constructors inherit the name of the methodmap.
• The beginnings of the new declaration style - that I'll fill out more in another patch.

What's left to do on methodmaps: more tests, support for inline declarations, properties.

In addition, to get this stuff working I did some bugfixing/refactoring within spcomp:

• sc.h now longer has that horrid hardcoded token list.
• the lex+tokeninfo pattern is replaced with lextok() in new code, which combines the two operations.
• there is a new symbol type called "proxies" that let one symbol redirect to another. this is what makes constructors work.
• there's a little compiler test harness now.
• there was a bug in line number computation for error reporting that is fixed.

Merged via command-line.