A folder is not a file

That seems pretty obvious, right? Well, not for quite a few people. Just check out the opening sentence on the ActionScript reference for the File object:

A File object represents a path to a file or directory.

Uh? Why? When you bring this up some people start banging about old paradigms such as "system nodes" and other ancient stuff. Well, I think whoever designed the AIR API lost a great opportunity to make a difference and start applying some usability to API design. This is most likely due to the old inferiority complex about ActionScript being a "serious" language that Java and C developers cannot look down to.

Well, how do you think Java and C developers explain it to Grandma?

Yeah, you have 2 types of files, one is for storing information, the other is a special type of file which can contain other files (of the first type) and other special files like itself.

Or

Yeah, you have files for your docs, and folders where you can group other files and folders. Y'know, like real life files and folders.

Best part is, since they are forcing the concept so much, they end up with ugly APIs and code. Let's see:

Smelly code:
[code lang="actionscript"]// WTF? I want a folder but have to create a new File object?
var folder : File = new File(path);[/code]
[code lang="actionscript"]// The code below compiles although it doesn't make sense
// cause a file can't contain files. Wondering if returns 0 or throws an error
var file : File = new File(path);
var files : Array = file.getDirectoryListing();[/code]

Smelly API:
File.isDirectory says it pretty much all:

Indicates whether the reference is to a directory. The value is true if the File object points to a directory; false otherwise.

"The reference". Maybe they should've called the class Reference instead of File, then?

Also, if files and folders are the same, why there is File.deleteDirectory(deleteDirectoryContents) vs File.deleteFile()? Sure there should be a common method called File.delete(), right? Well, turns out that most systems don't allow you to remove a non-empty folder without confirmation and thus the deleteDirectoryContents parameter.

So, convinced now? If you are not, then enjoy the official API. If you are, check out XAPI for AIR : )

Benefits (IMHO):

* No instances, all methods are static.
* Different File and Folder APIs with consistent method names.
* Much simpler API. Compare:

Reading the contents of a text file in plain AIR:

[code lang="actionscript"]var file : File = new File(path);
var stream : FileStream = new FileStream();
stream.open(file, FileMode.READ);
var content : String = stream.readUTFBytes(stream.bytesAvailable);
stream.close();[/code]

Using XAPI:
[code lang="actionscript"]var content : String = xa.File.read(path);[/code]

You decide : )

XAPI for AIR hasn't been released yet, so if you can't wait just go and checkout the code from Github. Once it's done it will be released as a SWC, I guess.

Extra ball: XAPI for AIR would be almost 100% identical to XAPI for haXe which was the original implementation (differences due to platform limitations), so if you are up to developing build tools using haXe the jump would be much simpler cause you would be using the same (X)API.