Good Practices for JavaScript “asm” sections in DWS/OP4JS
The compiler supports writing “asm” aka JavaScript section in the middle of Object Pascal, there are a few good practices as well as tips to keep in mind, let’s review the menu:
- Name conflicts and obfuscation support
- Do you really need an “asm” section?
- Don’t rely on implicit parameters structure
- Handling callbacks with “Variant” methods
- Handling callbacks in an “asm” section
- Current limitations
1. Name conflicts and obfuscation support
This should be a point zero actually, but the first thing to have in mind is that you are allowed in Pascal to use as names identifiers that are reserved in JavaScript. Those can be language keywords (“this”, “delete”, etc.) or common DOM objects and properties (“document”, “window”).
The compiler automatically protects you from such conflicts by transparently renaming your identifiers (currently by adding a “$”+number at the end).
Then there is the obfuscator, which will basically rename everything to short, meaningless names. That’s good for more than obfuscation: it reduces the size of the JavaScript, improves the parsing and lookup-based performance in the browser.
The consequence is that in an “asm” section, you should prefix all Pascal identifiers with an ‘@’, so the compiler can correctly compile your asm. For instance in:
var window : String; ... asm @window = window.name end;
The ‘@window’ refers to the ‘window’ string variable (which the compiler will rename), while ‘window.name’ will be compiled “as is”, as it reads the ‘name’ property of the global ‘window’ JavaScript object.
2. Do you really need an “asm”‘ section?
Though for some weird cases you might (like this gem), there are many cases in which you don’t need “asm”, as the language supports a “Variant” type which is a raw JavaScript object, and upon which you can call methods, read properties directly or via indexes.
For instance, with v a Variant, the following code:
v := v.getNext(); v['hello'] := v.space + 'world';
will get compiled (almost) straight into
v = v.getNext(); v['hello'] = v.space + 'world';
When using Variant, you don’t have strong compile-time checks (it’s just you vs JavaScript), property and function names are case-sensitive, so use them with care. This is similar in syntax and essence to using OLE Variants and Delphi.
On the other hand, you have compiler support, and you get automatic casts when assigning a variant to a strong type (Integer, String, etc.), and you also get name conflict protection & obfuscation support without having to ‘@’ your Pascal references.
3. Don’t rely on implicit parameters structure
Because they may change in future compiler revisions!
For instance, methods are currently invoked with an implicit “Self” parameters, and the others behind, so currently “arguments[0]” is Self, and everything else if after that. But don’t rely on it.
Future compiler revisions may change that parameter’s name, may obfuscate it, may remove it entirely in favor of an implicit “this”, may inline your function, etc.
So if you need explicit parameters, declare them, if you’re in a method and need to access the object (Self), use “@Self”, if you need to access a field of the current object use “@Self.FieldName”, etc. That will keep working.
4. Avoid declaring variables in “asm” sections
Declare them in the parent function/method instead, and reference them with the ‘@’ prefix.
There are three main reasons for that, the first is that doing so means they’ll be case-insensitive, the second is that it will allow the obfuscator to obfuscate them reason for that, and the third is that you’ll get compiler warnings if you declare a variable but do not use it (or if you forgot to @-prefix it).
So don’t write that:
asm var myTemp; myTemp = ...whatever...; ... end;
But write this instead:
var myTemp : Variant; ... asm @myTemp = ...whatever...; ... end;
5. Handling callbacks with “Variant” methods
A common occurrence is to register a callback to a JavaScript object, when that object is hosted in a Variant, that’s fairly simple to achieve:
procedure DoImageLoaded; begin ... end; ... var myImage : Variant; // will refer to an image object ... myImage.onload(@DoImageLoaded);
There we use the ‘@’ operator Pascal-side, to make it explicit that we want a function pointer, and not call the function. The ‘@’ isn’t necessary when the function is declared Pascal-side, as the compiler can figure it out, but when invoking a Variant method, it doesn’t know the parameters type.
Note that since function pointers are unified, you can get a function pointer from an object method or an interface method in the same fashion:
myImage.onload(@myObject.DoImageLoaded); myImage.onload(@myInterface.DoImageLoaded);
6. Handling callbacks in an “asm” section
If you want to register the callback in an “asm” section, the situation is a little more complex, as “@myObject.myMethod” will refer to the function prototype, outside of its context. It means it’s okay for standalone functions or procedures, but may not do what you’re expecting for object or interface methods.
The solution is to acquire the function pointer outside of the “asm” section:
var myCallback : Variant; ... myCallback := @myObject.DoImageLoaded; asm @myImage.onload(@myCallback); end;
7. Current limitations
Currently the parser for “asm” sections doesn’t really understand JavaScript:
- it’s still treating JS as a weird invalid form of Pascal, and notably {} define comments for it, so it will pass whatever is inside curlies “as is”, and will annoyingly ignore @ signs inside curlies
- some weird operator combos (but valid JS) may throw off the parser, if that happens, place that code in between curlies, and post a bug report
Hopefully in time, there will be a proper JS parser, but currently the focus is more on the Pascal side, and “asm” sections are intended for handling corner cases more than as a main workhorse.
Deformations and vertex shaders
