with() - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

In GML, EDL, and some other scripting languages including JavaScript, with() statements change the variable scope to that of a certain object. In the case of ENIGMA, this object happens to have a graphical representation. In other languages, however, with() is intended for use with classes.

In EDL and GML, this is a good use case for the statement:

with (instance_nearest(x,y,object0))
{
  repeat (10)
    instance_create(x,y,myExplodeParticle);
  instance_destroy();
}

In the code above, the with() statement changes the active scope to that of the nearest instance of object0 to our current position. In the braces after the with, the code is interpreted as though that nearest instance was the one calling it. The x, y, and myExplodeParticle passed to instance_create belong to that object0, and the instance_destroy() erases that object0. After the {}, the scope is restored to the original instance.

During that scope, the original instance can be accessed via the variable "other."

In ENIGMA, with() is a macro that instantiates a structure called "with_iter." The sole purpose of that structure is to push the current instance information (on construct), then to pop it afterward (on destruct).

The variables it pushes are used elsewhere in the system (like in functions which interact with the current instance, such as instance_destroy()) to resolve who the current instance actually is.

Since this mechanism is also used in resolving "self", with() re-scoping works in ENIGMA by prefixing "self . " to each non-script-local, non-global variables. The above code undergoes two phases during parse, listed as such:

with (instance_nearest(x,y,object0))
{
  repeat (10)
    instance_create(self.x,self.y,myExplodeParticle);
  instance_destroy();
}

with (instance_nearest(x,y,object0))
{
  repeat (10)
    instance_create(enigma::glaccess(self)->x,enigma::glaccess(self)->y,enigma::varaccess_myExplodeParticle(self));
  instance_destroy();
}

For an explanation on the variance in accessor methods, see Integer access.