Re: Defining APIs, best practices.

[Dirk Laurie <dirk.laurie@...>]

2012/12/17 steve donovan <steve.j.donovan@gmail.com>:
> On Mon, Dec 17, 2012 at 9:08 AM, Coda Highland <chighland@gmail.com> wrote:
>> TL;DR: Don't bash on the "Java"-style properties; they're not bad.
>
> Well, when we have to spell them out as setEnabled() and getEnabled()
> they get pretty tedious.
>
…
>
> But (since self-documenting is never as sufficient as it seems at
> first) you do need to establish a documentation style for properties.

Lua is powerful enough that one can protect privacy of properties
in a transparent way without resorting to ancient methodology (heck,
I can remember programming that way in Turbo Pascal!)

1. Properties are stored in a proxy table. A special value `none`,
    unique to each table, is used for properties that have never been
    set.
2. Retrieval of items behaves normally; in particular `nil` means that
    the requested property does not exist.
3. Attempting to assign `nil` to an existing property actually assigns
    `none`.
4. Items stored in the table are passed through a filter. Attempting to
    store into an item for which no filter has been defined, is an error.
    The filter itself can also perform checks.

>From the point of view of the programmer who will write the
property table module, quite some metatable activity takes
place, with at least `__index`, `__newindex` and `__pairs` being
defined.  `none` is also an interesting object, having a __tostring
metamethod.

>From the API designer's point of view, some module provides
a function `property_table` that creates a property table.

option = property_table {
   enabled = check_boolean;
   verbosity = check_number;
}

where `check_boolean` and `check_number` are utility functions
whose names are self-documenting :-)

>From the API user's point of view, `option` looks like any other
table, except that some assigments into the table will throw
errors.

 >  for k,v in pairs(option) do print(k,v) end
enabled     none
verbosity   none