Python XCHAT API question

I am writing a script in XCHAT and from reading other scripts I notice use of return xchat.EAT_ALL in most of them. Here is what the documentation for the XCHAT Python API says:

Callback return constants (EAT_) When a callback is supposed to return one of the EAT_ macros, it is able control how xchat will proceed after the callback returns. These are the available constants, and their meanings:

• EAT_PLUGIN Don't let any other plugin receive this event.
• EAT_XCHAT Don't let xchat treat this event as usual.
• EAT_ALL Eat the event completely.
• EAT_NONE Let everything happen as usual.
• Returning None is the same as returning EAT_NONE.

I am wondering why to do this. I really don't understand what this is sa开发者_StackOverflow社区ying and there isn't that much documentation for the XCHAT Python API. I am curious as to when to use which one of these.

---

Just from what you've pasted in:

Certain events occur in XChat, which you can register a function to handle. It is possible for there to be more than one callback function registered for each event - either by plugins or by XChat itself.

So after your function has done whatever it wants to do, it needs to decide whether to allow other callbacks to be triggered as well. As a simple example, let's say you're writing a script which filters incoming messages that have certain words. It's triggered whenever a message is received, and goes something like:

if any(word in swearwords for word in message):
    return xchat.EAT_ALL    # The 'message received' event stops here
else:
    return xchat.EAT_NONE   # Let it be handled normally.