skulpt/skulpt — pull request #144 by david-geo-holmes (2013-08-21 05:51:37+00:00)
Title: Rework ffi towards a cleaner API.

Begin an on-going process to clean up the Foreign Function Interface (ffi.js). This is clearly going to take much more effort because it is clear from my testing that Boolean and String values are still being passed in the 'v' property. This refactoring incorporates a few ideas:

Sk.ffi.remapToJs and Sk.ffi.remapToPy should always work but will need hint parameters when mappings aren't 1:1

Sk.ffi.remapXyzToJs and Sk.ffi.remapXyzToPy functions for better performance and assertions when the types being mapped are known.

1) {'v': ?, 'tp$name': ?} protocol manifest in function to provide better reporting when a Python client mis-names the properties on an object.
2) #1 combined with remapToPy to support wrapping of JavaScript library classes.
3) message configurable in the 'incoming data' remapXyzToJs functions to support easy localizable validation.
4) assert message standard in the 'outgoing data' remapXyzToPy functions.
5) Identification of functions to be deprecated and ignoreDeprecation argument. This isn't exactly backwards compatible, but it seems to be the approach used in libraries like Three.JS. A client can at least test, add a few true arguments and postpone the inevitable migration. Is there a better way to send warning messages?
6) Modify Regular Expression module not to use deprecated functions.

TODO: Wrapping functions e.g. callbacks
TODO: Delegate deprecated functions to the permanent API.
TODO: General handling of Python values inside Skulpt (valuePy representation).
TODO: Schedule and removal of deprecated functions.
TODO: Modify more of the standard library to make use of the ffi API rather than ad-hoc entry points. This would provide the benefits of better testing, better example code, potential for optimizations that avoid object creation.
TODO: "Hint' metadata arguments when mappings aren't 1:1
TODO: We also need better testing because a lot of the conversion functions aren't exercised by the standard library.