Re: [Enigma-devel] Lua API

[Ronald Lamprecht]

Hi,

Andreas Lochmann wrote:
> > For this reason I try to separate the different usages. "trigger" as a 
> > message with raising and trailing edge, and "toggle" as a universal 
> > messages suited for the target-action paradigm that takes no argument 
> > and is a request to toggle to the receivers next state.
> >
> > Thus "toggle" opens a closed door, closes an open door. It turns a 
> > mirror and a fourswitch.
> Okay.
>
> Particularly for the fourswitch, an "antitoggle" would be practical.
> Or maybe allow a number for the second argument and use ("toggle", -1)
> or ("toggle", 2 )?

Of course there are many tasks that have need of a message that is more
versatile than the simple "toggle" described above. But we need a simple
message that suffices 95% of the use cases where a switch like source
toggles a target. You should be able to connect the source with the
target without doing anything else - no message naming or additional
attribute settings. That is the responsibility of the "toggle" message
as defined above.

Turnable objects like the "fourswitch" will likely support additional
messages like "turn_clockwise" and "turn_anticlockwise".

But we should not request a general availibility of an "antitoggle"
message. E.g. a toggle may open an oxyd, but there will be no antitoggle
to close an arbitrary already opened oxyd. A traffic light object or an
object that toggles to a random state are further examples of possible
non-reversible toggle actions.

> [Using the old API]
>
> Will it be possible to use old-API-libraries (with compatibility <= 1.0)
> in new-API-levels (with compatibility 1.1) or vice versa?
>
> Why is mixing the two APIs no good idea?

Allowing to mix the APIs would cause trouble all over. On the Lua level
part the author could not rely on any boolean attributes as they are
passed with different values. The C++ engine would not be able to decide
which value type the author expects. The level compatibility is the best
way to guarantee a simple clean implementation:

case Value::BOOL:
    if (server::EnigmaCompatibility < 1.10) {
        if (val.to_bool())
            lua_pushnumber(L, 1);
        else
            lua_pushnil(L);
    } else {
        lua_pushboolean(L, val.to_bool());
    }
    break;

And there are many more reasons. The old API did not reserve any names
for special purposes. Thus object names were allowd to contain the
characters '*','?','#' which are reserved in the new API for autonaming
and wildcard purposes. We also have to rename some of the attributes and
messages. The usage of the names would be not unique for the engine
during runtime, if the names would be set by one API function and be
used by a function of the other API.

We do even introduce semantical changes with the new API. E.g. per
default oxyd stones are precolored in pairs modulo the max number of
colors in the new API whereas the old API did precolor all oxyd to blue
and did provide an optional oxyd() function that colored pairs of oxyds
and failed if it ran out of existing colors. Again the compatibility is
the simpelest way to code the difference within the engine:

  if (server::EnigmaCompatibility >= 1.10) {
      int color = ((instances.size() -1) / 2) % 8;
      o->set_attrib("color", color);
  }

Let us focus on writing a stable new API. It is a fraction of work to
rewrite the existing libraries. It is even a chance to improve them on
basis of the new API.

Greets,

Ronald