util.js - some useful JS util functions

[aubergine]

New home for this library:

https://warzone.atlassian.net/wiki/display/UtilJS/Home

Latest release v0.5 has lots of bug fixes, improvements and several new functions Plus full documentation!

As part of developing my EggPlant AI, I've had to create some utility functions and decided to put them in to their own file so others can easily re-use them if desired.

.uAddProperty() - add accessor/data properties to objects

Availability: v0.1

Usage:

oObj.uAddProperty(nMask,sKey,vVal_fGet,fSet);

Where:

* oObj = the object on which the property will be added
* nMask = property descriptor represented as a number (see Constants below)
* sKey = name of property as a string
* vVal = value of property (data descriptors only)
* fGet = property getter function (accessor descriptors only)
* fSet = property setter function (accessor descriptors only)

Constants (nMask options):

* ACCESSOR_HIDDEN = accessor descriptor - not configurable, not enumerable (0000).
* ACCESSOR_NORMAL = accessor descriptor - not configurable, enumerable (0001).
* DATA_READONLY_HIDDEN = readonly data descriptor - not configurable, not enumerable (0100).
* DATA_READONLY = readonly data descriptor - not configurable, enumerable (0101).
* DATA_HIDDEN = writable data descriptor - not configurable, not enumerable (1000).
* DATA_NORMAL = writable data descriptor - not configurable, enumerable (1001).

Example:

Code: Select all

var foo = {bar:true};

foo.uAddProperty(DATA_HIDDEN_READONLY,"_name","Team Alpha");
foo.uAddProperty(ACCESSOR_HIDDEN,"toString",function() { return this._name; });

console(foo); // Team Alpha
foo._name = "Team Beta";
foo.toString = "Team Gamma";
console(foo); // Team Alpha

var i;
for (i in foo) console(i+" = "+foo[i]); // bar = true

Notes:

Only a few of the possible nMask values are exposed as constants - a full list of possible values and what they do is shown in comments in the constants section near the top of the .js file.

The DATA_NORMAL constant was removed in v0.2 as it seems pointless to define a normal property in this manner. If you want to still define normal properties using uAddProperty, just send in an nMask value of 9.

.uInherit() - make a class inherit a superclass

Availability: v0.1

Usage:

fClass.uInherit(fSuperclass);

Where:

* fClass = class function
* fSuperclass = superclass function

Example:

Code: Select all

function foo() {
 console("foo constructor");
}
foo.prototype.whoami = function(){ console("i am foo"); };
foo.prototype.fooVal = "foo";

function bar() {
 console("bar constructor");
}
bar.uInherit(foo);
bar.prototype.whoami = function(){ console("i am bar"); };
bar.prototype.barVal = "bar";

// make new instance of bar:
var barInstance = new bar(); // bar constructor
barInstance.whoami(); // i am bar
console(barInstance.fooVal); // foo

Notes:

.uInherit() must be used immediately after defining the class, before any prototypes are defined on the class.

.uSuper() - call the superclass method of same name (or constructor if used in constructor)

Availability: v0.1

Usage:

this.uSuper(); // call superclass method/constructor with no arguments
this.uSuper(vArg1,..,vArgN); // pass arguments to superclass method/constructor
this.uSuper.apply(this,aArguments); // pass an array of arguments to superclass method/constructor

Example:

Code: Select all

// continuing on from previous example in which foo and bar were defined...

function chimp() {
 console("chimp constructor");
 this.uSuper();
}
chimp.uInherit(bar);
chimp.prototype.whoami = function(){ console("i am chimp"); this.uSuper();};

// make a new instance of chimp
var chimpInstance = new chimp(); // chimp constructor, bar constructor
chimpInstance.whoami(); // i am chimp, i am bar
console(chimpInstance.barVal); // bar
console(chimpInstance.fooVal); // foo

.uTardis() - turn a function property in to a TARDIS

Availability: v0.2

Usage:

this.uTardis(sFunctionName); // create a tardis
this.<sFunctionName> = function(...) {...}; // add a function
this.<sFunctionName> = function(...) {...}; // and another one - as many as you want!

Example:

Code: Select all

// when defining event handlers on the global scope (eg. where constants are defined) you can omit "this."

// turn an event handler in to a tardis
uTardis("eventAttacked"); // the quotes around function name are mandatory!

// now let's add some handlers to the tardis
function eventAttacked(victim,attacker) { .... }; // handler #1
function eventAttacked(victim,attacker) { .... }; // handler #2

Notes:

The handlers will be called in the same order in which they are defined.

[aubergine]

(reserved for future use)

[aubergine]

(reserved for future use #2)

[aubergine]

v0.2 includes a new uTardis() method which allows you to create TARDIS-like function properties in which you can store multiple functions and have each of them called in order when the function property is invoked. See documentation in opening post for more info.

[milo christiansen]

Correct me if I'm wrong but this looks like the kind of classic OO crutches someone not used to dynamic objects would use

[aubergine]

Yeah, it's sort of classic OO but I actually quite like it and I enjoy tinkering with prototype chains and stuff like that. There's plenty of other ways to get any desired result, I just like this way. Most of the inbuilt objects in ECMA-262 inherit using the same mechanism (eg. Array properly inherits Object, etc).

How would you approach it?

[milo christiansen]

I just construct my objects on-the-fly although sometimes I will use a constructor function for something that will be passed around a lot and/or HAS to be a certain way.

The thing that makes JavaScript one of my favorite languages is the way that objects are so flexible. If it was classic classes style OO I would just use Go or C++ for everything

Oh well, to each his own

[aubergine]

I also love the flexibility of JS - just sometimes I want things to be a little more classic in nature, particularly if they are the foundations of lots of other stuff. Making the foundations of my script use a more classic OO approach forces me to think about things differently so I guess it's more of a design pattern for me than anything else.

I find that in many cases I might start out with a structure that's quite classic in terms of implementation and then based on experience of using it I make bits of it more "javascripty" to simplify it or make using it easier. I find going in the other direction to be much more difficult.

[aubergine]

Util.js has a new home: https://warzone.atlassian.net/wiki/display/UtilJS/Home

That site contains full documentation and examples and within a week should have it's own bug tracker and git repo.

The downloads are still only available in this forum topic, but they'll eventually move over to the URL above.