Advertisement

Exclusive Freebie: Tr.ace(), an Excellent AS3 Debugging Utility

by

We've got another Activetuts+ Exclusive Freebie for you! This time, Matt Stuttard (aka MSFX) is offering you his brand new debugging utility, Tr.ace(), which adds some very useful extra features to Flash's trace() function. Read on to find out more, and to download your copy.

Tra.ce 2.0 is out! Get it here.

All developers use some form of tracing as a loose method of debugging at some point whilst developing their applications. The problem with the trace statement within AS3 though is that it's rather limited. If you're working within a team it's possible you've no idea who's trace is whose or where any of the traces are coming from, and there's no automated formatting to help distinguish traces from different users and classes!

Wouldn't it be awesome if you could restrict your applications' trace statements to specific classes or particular users, or even completely ignore traces from specific users or classes altogether?

Wouldn't it be great to have a little more control over the formatting of your traces so that you'd know who traced it, the class it's traced from, and the time the trace was executed?

How about the ability to add automatic linebreaks between each trace, and neatly trace out complex, nested Arrays and Objects, all while automatically copying the output to the clipboard?

Welcome to Tr.ace()!


Downloading Tr.ace()

Tr.ace() is an open source library that's available to download here at Activetuts+ in ZIP format, and is also available as a public repository on my GitHub for those who are little more nerdy or who wish to fork and/or contribute towards the Tr.ace() library.

The library is AS3-only and has two separate repositories: one for Flash Player 9 and one for Flash Player 10+.

Tra.ce 2.0 is out! Get it here.

To use the Tr.ace() library you must download and extract one of the above source packages, and then copy the 'uk' directory, located within the 'src' directory, into your global classpath directory. You're then all set to go!

(Any problems? Check out this extensive guide to using an external library in your Flash projects.)


Configuring Tr.ace()

Firstly, a little theory and explanation.

Tr.ace() is a library focused on tracing. 'Tr' is the main class and 'ace()' is a function of the Tr class, hence the library name Tr.ace().

The name of the library also illustrates the library's usage. As 'Tr' is a static class you don't need to create an instance of it to use its functions or configure any of its settings; you simply use Tr.whateverTheValue or Tr.whateverTheFunction().

Lastly, because the internal workings of the library use the Singleton Design Pattern, any of the settings you apply to Tr.ace() only need applying once within your application - I'd suggest within your Document / Main Class.

There are two versions of the library, one for Flash Player 9 and one for Flash Player 10 and up. The only difference (currently) is that the Flash Player 10 version supports automatic copying to the Clipboard.

Lets now take a look at some of these settings (the following are excerpts from ExampleMain.as, which can be found in the src directory) :

		// restrict the trace output(s) to only the 'ExampleClass2' Class
		Tr.restrictToClasses = [ExampleClass2];
		
		
		// ignore the trace output(s) from the 'ExampleMain' Class only
		Tr.ignoreClasses = [ExampleMain];
		
		
		// restrict the trace output(s) from user 'MSFX' only
		Tr.restrictToUsers = [TrUsers.MSFX];
		
		
		// ignore the trace output(s) from user 'MSFX' only
		Tr.ignoreUsers = [TrUsers.MSFX];
		 
	
	
	

As you should be able to see from the above examples it's easy to very quickly tailor your output to either restrict the output to only be from specific users or classes, or to ignore the output from specific users or classes.

As the below examples also demonstrate, it's very easy to toggle linebreaks, timestamps and copying to the clipboard (FP10 only). You can also very easily switch tracing off all together.

		// show the time with each trace
		Tr.useTimeStamp = true;
		
		
		// copy the trace output to the clipboard (non IDE debugging - FP10 only)
		Tr.copyToClipboard = true;
		
		
		// add linebreaks between each output
		Tr.useLineBreaks = true;
		
		
		// switch tracing off entirely
		Tr.off = true;
		 
	
	
	

Lets now have a quick look over the functions available within the Tr.ace() library.


Tr.ace(...)

The Tr.ace(...) function requires three parameters: the output, the username and the class being traced from.

All three of these parameters are required, to allow the library to restrict to or ignore traces from particular users or classes; if you're worried about this taking longer to type than a usual trace you can wrap it up as a Code Snippet in your favourite IDE - more later.

// A String as the output from user MSFX within the Class 'ClassName'.
Tr.ace("here is the output", TrUsers.MSFX, ClassName);
 
// Sum of several numbers as the output from user DEFAULT within the Class 'AnotherClassName'.
Tr.ace( ((1 + 2.5 + 6.999) * 12), TrUsers.DEFAULT, AnotherClassName);
 
// tracing a variable as the output from user MSFX within the Class 'YetAnotherClassName'.
Tr.ace("variable equals: " + variableName, TrUsers.MSFX, YetAnotherClassName);

Tr.aceArray(...)

The Tr.aceArray(...) function requires three parameters: the Array, the username and the class being traced from.

All three of these parameters are required, to allow the library to restrict to or ignore traces from particular users or classes; if you're worried about this taking longer to type than a usual trace you can wrap it up as a Code Snippet in your favourite IDE - more later.

// A String as the output from user MSFX within the Class 'ClassName'.
Tr.aceArray("here is the output", TrUsers.MSFX, ClassName);
 
// Sum of several numbers as the output from user DEFAULT within the Class 'AnotherClassName'.
Tr.aceArray( ((1 + 2.5 + 6.999) * 12), TrUsers.DEFAULT, AnotherClassName);

Tr.aceMulti(...)

The Tr.aceMulti(...) function requires a mimimum of three parameters: the username, the class being traced from and an unlimited list of arguments (seperated via commas) to trace out. Note that these parameters are in a different order than in the other functions.

All three of these parameters are required, to allow the library to restrict to or ignore traces from particular users or classes; if you're worried about this taking longer to type than a usual trace you can wrap it up as a Code Snippet in your favourite IDE - more later.

// A String as the output from user MSFX within the Class 'ClassName'.
Tr.aceMulti("here is the output", TrUsers.MSFX, ClassName);
 
// Sum of several numbers as the output from user DEFAULT within the Class 'AnotherClassName'.
Tr.aceMulti( ((1 + 2.5 + 6.999) * 12), TrUsers.DEFAULT, AnotherClassName);

Tr.aceObject(...)

The Tr.aceObject(...) function requires three parameters: the Object, the username and the class being traced from.

All three of these parameters are required, to allow the library to restrict to or ignore traces from particular users or classes; if you're worried about this taking longer to type than a usual trace you can wrap it up as a Code Snippet in your favourite IDE - more later.

// A String as the output from user MSFX within the Class 'ClassName'.
Tr.aceObject("here is the output", TrUsers.MSFX, ClassName);
 
// Sum of several numbers as the output from user DEFAULT within the Class 'AnotherClassName'.
Tr.aceObject( ((1 + 2.5 + 6.999) * 12), TrUsers.DEFAULT, AnotherClassName);

Adding Users to the Tr.ace() Library

You may have noticed several pre-existing usernames within the Tr.ace() library such as TrUsers.DEFAULT and TrUsers.MSFX in the above examples. To remove the chance of typos it's recommended that you add your name as a Static Constant to the Tr.ace() Library as with the pre-existing usernames.

To add yourself to the library, open the 'TrUsers.as' file located at 'uk/msfx/utils/tracing/users/TrUsers.as'. Add your own user name as a public static constant to the bottom of the list and you're ready to go!

/**
 * Your username!
 */
public static const MATT:String = "Matt";

Using Tr.ace() With Code Snippets

Although Tr.ace() provides lots of advantages over using the usual trace() statement within Flash there is quite a lot more to type, which could potentially slow down your development. Enter Code Snippets.

Code Snippets are exactly what you'd think: automatically-inserted snippets of code. Most IDEs, if not all, support them and they speed up your development like you're Superman. I use FlashDevelop (and you should too!) so let's quickly have a look at adding a new code snippet for Tr.ace().

The code snippet must be usable wherever you decide to add it to your application with as little adjustments as possible. With Tr.ace() you must provide both the user tracing and the Class traced from along with the output. The user is easy enough to wrap up in the code snippet since it'll likely not change very often; however, it's likely we'll trace from different Classes quite often.

Therefore, instead of entering the class manually each time, we can use a simple piece of code to return the class we're tracing from automatically. I performed some tests using Grant Skinners Performance Harness on different approaches of achieving this and found the method below to be the most efficient (other than using the actual class name itself). You can find the results within the src directory.

If you're using FlashDevelop, open the Code Snippets Panel and click 'Add' to create a new snippet. (There's bound to be a similar menu option in whatever IDE you use.)

code snippets menu

Add a new snippet and call it whatever you want (I used 'tr') and add the main body to the snippet - with your own username of course. Object(this).constructor returns the Class from which the function is called, no matter where you enter this line in your project.

adding snippet

Add the entry point where the output for the trace should go.

adding entry point to snippet

Finally, click 'Save'.

adding entry point to snippet

Code snippet complete! To use the snippet within FlashDevelop, simply press Ctrl+B, type 'tr' and hit Enter. Then, type in whatever you want to trace.


Documentation for Tr.ace()

Within the download package you'll find a 'docs' directory, open the 'index.html' file to view the ASDocs-generated Documentation for Tr.ace(). You can also find the documentation online: http://docs.msfx.co.uk/as3/trace/.


Happy Tracing!

So, that's it really. If you have any questions or suggestions for the library feel free to get in touch in the comments.

Happy Tracing!

Advertisement