|
API
API reference.
IntroductionBecause Tamarin define very few API, we decided to implement our own API. Make no mistake, designing an API is a very hard task (maybe the hardest ?) and we'll probably not get it right (ever), but to be able to offer native functionalities we needed anyway to provide a way for you (the developer) to access these native definitions. Also, the AS3 language being already quite powerful with just few builtin classes, when you add native system call you kind of multiply exponentially all the things you can do with the language. So, instead of trying to target the perfect API, we will target a good enougth API and show you how you can write your own API, but off course if you like our API you can still use it :). The following will hopefully explain clearly why we did things in a certain way. API LayersThere are different layers of implementations, from closer to the metal (native implementations) to AS3 wrapper code (around already existing AS3 code). The code design is based on this idea If you don't like to use flash.net.URLLoader class for whatever reason we simply give you the tools to wrap your own class to suit your taste. In short, that means we provide you avmplus::FileSystem.write( filename, data ) and you can define sys::File which when initialized new File( filename ) will write the file directly. Layer 0 : Lower LevelThe Lower Level API, or AVMAPI, is a combination of the Builtins classes, the Standard C classes and the AVMPlus classes. for ex: C.stdlib.* , avmplus.FileSystem, avmplus.OperatingSystem, etc. those classes are
you need to -import file.abc to compile your code over the symbols but the file.abc is embeded by default in the redtamarin executable.
the class definition is in AS3 but the implementation is in C/C++
if we add a functionality it HAVE TO work on Windows, OS X, Linux, etc.
if foobar class exists in v0.1, it will always be present in 0.2, 0.3, etc. at the very worst we will "add to it" but NEVER "remove from it" Layer 1 : Flash PlatformThe Flash Platform API, or FPAPI, is based on the fact that most of our/your usage of the AS3 language is within the Flash Player host or the AIR host. for ex: flash.display.Sprite, flash.system.Capabilities, flash.filesystem.File, etc. Tamarin by default implement almost NONE of the FPAPI. With redtamarin we took an hybrid approach
of the FPAPI as mock objects (or dumb implementations if you prefer).
we make the difference between FP_9_0, AIR_1_0, FP_10_0, AIR_2_0, etc. (HAVE TO compile with ASC.jar, but can still use asdoc)
we add a concrete implementation of the FPAPI in parallel of the mock implementation. For that, we use the Conditional Compilations MOCK::API and REDTAMARIN::API.
TODO Layer 2 : Any OtherAny other API, or for short *API (or "Any API"), ... With enougth lower level API (being able to use sockets, connect to a DB like SQLite, etc.) So for example if you like how CommonJS or Python or PHP are doing stuff, Here a small example with CommonJS Filesystem/A/0 package fs
{
import avmplus.FileSystem;
import C.unistd.chmod;
public function makeDirectory( path:String, permissions_opt:* ):void
{
FileSystem.createDirectory( path );
if( permissions_opt )
{
var permisssions:int = _translatePermissions( permissions_opt );
chmod( path, permissions );
}
}
public function workingDirectory():String
{
return FileSystem.workingDirectory;
}
public function changeWorkingDirectory( path:String ):void
{
FileSystem.workingDirectory = path;
}
public function exists( path:String ):Boolean
{
return FileSystem.exists( path );
}
public function isFile( path:String ):Boolean
{
return FileSystem.isRegularFile( path );
}
}TODO | |