Home

Welcome to the ansilib wiki!

ansilib is the perfect excuse to study different use cases on how to build AS3 libraries for redtamarin and as3shebang.

It's still a regular library you can use in your projects to add some colors to the terminal.

Sharing Code

In the Flash world you could share code in 2 ways

• as plain source code
• as a SWC (a pre-compiled SWF)

You can do almost exactly the same with redtamarin and as3shebang, but here few details you should know.

Binary formats

• ABC - ActionScript ByteCode
  When you compile ActionScript 3.0 source code
  the compiler produce bytecode.
  You probably never heard of it before.
• SWF - Small Web Format
  The good old "swiff" file format that everybody knows,
  it can contain a lot of different things from bitmap images,
  to audio, to vector, and also ActionScript bytecode.
• SWC - Small Web Component
  Used by Flash and Flex developers to share libraries
  or more exactly pre-compiled code and other "assets".

With the redtamarin shell: redshell, our runtime can understand 3 formats.

• AS - plain ActionScript source code
  the redshell will "eval" this source code at runtime
  it read the file, transform it into bytecode and execute it.
• ABC - ActionScript ByteCode
  the redshell will directly execute those files
  it's kind of the "de facto" format (or preferred).
• SWF - "Swiff" file
  the redshell will see it as a container of ABC files
  and will extract/interpret/execute only those.

Also remember that as3shebang is simply a compact distribution of the redshell made to run shell scripts, it is basically the first scenario: read plain ActionScript source code and eval it at runtime.

With redtamarin

We are in a logic of writing "big" programs and "big" libraries so we will favour producing ABC libraries (that we will double with SWC libraries).

ABC libraries are the "go to" format to produce and share libraries, they will directly run with the redshell, can be loaded dynamically by as3shebang.

If we double them with SWC libraries it is simply to be able to have code completion in different IDE (Flash Builder, FDT, Flash Develop, etc.), as well as documentation (by embedding the asdoc in a "fat" SWC).

With as3shebang

We are in the logic of writing small and quick shell scripts so here we will favour plain source code, easy to copy and paste.

That said, there are some cases where we would want to use a library instead of copying/pasting a huge chunk of code.

To do that, we could agree on storing all the ABC libraries in the same place, for example /usr/share/redtamarin/lib-abc and decide on a common way to load those libraries.

var load:Function = function( name:String ):String
{
    return Domain.currentDomain.load( "/usr/share/redtamarin/lib-abc/" + name );
}

Off course, if someone does not agree or simply doesn't know where to look for those libraries he/she will end up with a broken script.

So, another way to reuse an ABC library (which is a binary file) inside a shell script file (a text file) is to simply embed this ABC lib as plain text inside the script.

It sound a bit crazy but it has the advantages of being self substainable or put another way: just distribute a shell script, don't need to explain how to install a dependency (like a library), it just works.

To do this, we will need a little utility make_hexdata.as which basically gonna take an ABC library ansilib.abc and transform it in such a way that you can embed it as text in your shell script.

$ ./make_hexdata ansilib.abc ansilib will produce a file ansilib.inc

Now we just need to copy and paste the content in our shell script and reuse the goodness of the ABC library without worrying of installign this library or finding it on the system.

See the example test_binembed.as.

And let illustrate how it works

function ansilib():*
{
//...
    var bytes:* = new ByteArray();
 
    var i:uint;
    var len:uint = hex.length;
    for( i = 0; i < len; i += 2 )
    {
        var b:String = hex.substr( i , 2 );
        var result:uint = uint( "0x" + b );
        bytes.writeByte( result );
    }
    bytes.position = 0;
    return bytes;
}

var result:* = Domain.currentDomain.loadBytes( ansilib() );
trace( "result = " + result ); //should output "ansilib 1.0"

We have already seen Domain.currentDomain.load() which load an external file
but here we use Domain.currentDomain.loadBytes() which load an in-memory ByteArray.

We obtained this ByteArray by parsing a stream of hexadecimal strings and converting them into bytes.

This sequence of bytes happen to be an ABC library that our shell script can load and interpret at runtime.

This way of doing have pros and cons

pros

• no need to distribute/explain/install 3rd party libraries
• it will work with any number of ABC libraries
• in fact, it will work with a SWF file containing many ABC libraries
• in fact, it will work with ANY binary file
• in a remote SSH session, you can copy/paste the whole script
• totally obfuscated, you can protect somehow your code/library

cons

• much much bigger file size, if ansilib.abc weight 4.2K,
  embedded as hex strings it weight 11K.
• it is slower to execute (even if "not that slow")
• totally obfuscated, some people would never run that kind of opaque scripts

All that said, in those case where you know as3shebang is installed and you need to distribute/deploy a big program, this can be a possible alternative to execute your AS3 code.