Lua: colon notation, 'self' and function definition vs. call

Question

I'm getting terribly confused by the colon notation used when defining/calling Lua functions.

I thought I'd got my head round it until I saw this piece of code:

function string.PatternSafe( str )
    return ( str:gsub( ".", pattern_escape_replacements ) );
end

function string.Trim( s, char )
    if char then char = char:PatternSafe() else char = "%s" end
    return string.match( s, "^" .. char .. "*(.-)" .. char .. "*$" ) or s
end

What's confusing me here is that string.PatternSafe() doesn't reference 'self' anywhere, yet the code seems to work.

I've also seen some scripts that use colon notation when defining the function, for example:

function foo:bar( param1 ) ... end

After several hours of googling I've still not managed to work out what precisely is happening in these two contexts. My current assumptions are as follows:

1. If a function is defined using colon notation, it gets an invisible 'self' parameter inserted as first parameter
2. If a function is called using colon notation, the object preceding ':' is inserted in to the arguments (so becomes the first parameter of the function)
3. If a function is called using dot notation, then even if it was defined using colon notation it will not get the object inserted as first argument/parameter

If my assumptions are correct, that raises an additional question: What is the best way to ensure that the function was called properly?

Answer 1

Your assumptions are all correct.

Assumption 1 from the manual:

The colon syntax is used for defining methods, that is, functions that have an implicit extra parameter self. Thus, the statement

 function t.a.b.c:f (params) body end

is syntactic sugar for

 t.a.b.c.f = function (self, params) body end

Assumption 2 from the manual:

A call v:name(args) is syntactic sugar for v.name(v,args), except that v is evaluated only once.

Assumption 3 doesn't have a direct manual section since that's just normal function call syntax.

Here's the thing though. self is just the auto-magic name given in the syntax sugar used as part of the colon assignment. It isn't a necessary name. The first argument is the first argument whatever the name happens to be.

So in your example:

function string.PatternSafe( str )
    return ( str:gsub( ".", pattern_escape_replacements ) );
end

the first argument is str so when the function is called as char:PatternSafe() is de-sugars (via assumption 2) to char.PatternSafe(char) which is just passing char to the function as the first argument (which, as I already said, is str).