Re: __goodies

[Sean Conner <sean@...>]

It was thus said that the Great Roberto Ierusalimschy once stated:
> > A propos the Lua 5.40 (beta) manual I note that the __tostring
> > event gets no mention in section 2.4 either. What other
> > __goodies are being hidden from our eyes? Yes, I know, it is
> > little hardship to scan the sources for them, but I did wonder
> > if some very mild censorship was in play here :). Reveal all
> > after beta, maybe?
> 
> __tostring is not part of the language itself, it is a peculiarity
> of the function 'tostring'. The manual does have a note about that
> at the end of Section 2.4:
> 
>     Because metatables are regular tables, they can contain arbitrary
>     fields, not only the event names defined above. Some functions in
>     the standard library (e.g., tostring) use other fields in metatables
>     for their own purposes.

  So Lua reserves names starting with '_[A-Z]' for itself, but no mention of
reserved names is made for metamethods (or metafields in the case of __name,
__metatable or __mode).  In my own case, I have added a metamethod to a few
of my modules [1] and I very specifically avoided naming the field with two
leading underscores..  Is it assumed that any metamethod starting with
'__[a-z]' is reserved for Lua?  Or is it open season per the reasoning in
RFC-6648 [4]?

> For a complete list of all indices used on metatables for all purposes,
> the following shell script gives an answer:
> 
>   $ grep -hoE '__[a-z]+' manual/manual.html | sort -u

  Along those lines, a table of currently defined metamethods for Lua:

                5.1     5.2     5.3     5.4     function

__add           *       *       *       *       a + b
__band                          *       *       a & b
__bnot                          *       *       ~a
__bor                           *       *       a | b
__bxor                          *       *       a ~ b
__call          *       *       *       *       a()
__close                                 *
__concat        *       *       *       *       a .. b
__div           *       *       *       *       a / b
__eq            *       *       *       *       a == b          result forced to boolean
__gc            *       *       *       *
__idiv                          *       *       a // b
__index         *       *       *       *       a = b[]         can be table
__ipairs                *
__le            *       *       *       *       a <= b          result forced to boolean
__len           *       *       *       *       #a
__lt            *       *       *       *       a < b           result forced to boolean
__metatable     *       *       *       *                       table
__mod           *       *       *       *       a % b
__mode          *       *       *       *                       string
__mul           *       *       *       *       a * b
__name                          *       *                       string
__newindex      *       *       *       *       a[] = b         can be table
__pairs                 *       *       *
__pow           *       *       *       *       a ^ b
__shl                           *       *       a << b
__shr                           *       *       a >> b
__sub           *       *       *       *       a - b
__tostring      *       *       *       *
__umn           *       *       *       *       -a

  -spc (Hmmm, seems I metioned the lack of reserved metamethod names 4 years
	ago this week [5])

[1]	In case anyone is interested, it's _tofd() (note the single
	underscore).  It's used in three modules:

		org.conman.fsys		POSIX file system stuff
		org.conman.net		network API
		org.conman.pollset	wrapper for select() [2]

	The fsys module actually monkeypatches Lua's FILE* metatable [3] to
	include _tofd(), and there are various calls in fsys and pollset
	that call it to obtain the underlying file descriptor for functions
	that need the file descriptor without having to have knowledge of
	private structures of other modules.

[2]	and poll() and epoll(), depending upon the system.

[3]	I dislike monkey patching in general, but I justify this as I'm only
	adding functionality, not changing functionality, and that this
	shouldn't break any existing code, nor change any existing behavior.

[4]	"Deprecating the "X-" Prefix and Similar Constructs in Application
	Protocols"

	By this meaning, if someone creates a metamethod starting with
	'_[a-z]' and it proves popular, it becomes difficult to change all
	existing code to use the new standard name starting with '__[a-z]'.

[5]	http://lua-users.org/lists/lua-l/2015-10/msg00102.html