Index

If you are looking for code samples, please see enumeration tests' and their source code.

• 1.0. What is an enumeration?
• 2.0. What is the goal of enumerations
• 3.0. Enumerations how-to
  • 3.1. When and how to use enumerations
  • 3.2. Enumeration values
    • 3.2.1. Enumeration flags

1.0 What is an enumeration?

An enumeration is an special class of constants.

2.0 What is the goal of enumerations?

In regular JavaScript, when some code needs to identify states uses integers (Number):

// "1" would mean that something is open (for example, an HTTP connection)
if(someVar == 1) {
    // Do stuff
}

jOOPL introduces true enumerations and the above code could be turned into:

$namespace.using("joopl.enumerations", function(enumerations) {
    enumerations.declareEnum("HttpState", {
        closed: 0,
        open: 1
    });

    var someVar = enumerations.HttpState.open;

    if(someVar == enumerations.HttpState.open) {
        // Do stuff
    }
});

The above code listing demonstrates how enumerations can turn states and kinds into a more verbose code which may increase code readibility, since developers will not need to check documentation in order to know what 0 or 1 states mean.

3. Enumerations how-to

Enumerations are created using the $enumdef operator. The $enumdef operator is a ctor accepting an object defining one or more constants:

$namespace.using("mynamespace", function(mynamespace) {
    mynamespace.declareEnum("State", {
        open: 0,
        closed: 1,
        disconnected: 2,
        working: 3
    });
});

The given constants must be always numeric and the enumeration must contain only numeric properties.

3.1 When and how to use enumerations

Enumerations are required when some code can define a closed set of values that may not change overtime.

For example, some code may have a class with a method accepting a limited number of HTTP verbs:

$namespace.using("mynamspace", function(mynamspace) {
    mynamspace.declareEnum("HttpVerb", {
        get: 0,
        post: 1,
        put : 2
    });

    mynamspace.declareClass("MyClass", {
        members: {
            // The @verb argument will only support verbs of the HttpVerb enumeration
            doRequest: function(verb, url, args) {
                switch(verb) {
                    case mynamspace.HttpVerb.get: 
                        // Perform the HTTP GET request
                        break;

                    case mynamspace.HttpVerb.post:
                        // Perform the HTTP POST request
                        break;

                    default: 
                        throw Error("Only HTTP POST and GET are supported!");
                }

            }
        }
    });
});

3.2 Enumeration values

An enumeration value is an instance of standard ECMA-Script Number object (the primitive Number type wrapper). jOOPL inherits Number and any enumeration value has also a reserved property enum ( see EnumValue to explore available methods and properties of an enumeration value).

The enum property represents a set of common operations for enum values.

3.2.1 Enumeration flags

Sometimes enumeration values should support more than a possible state. Using regular enumerations ends in single values:

var state = mynamspace.State.open;

jOOPL provides support for flags (combination of more than an enumeration values) using bit-wise operators like OR and AND in order to create enumeration values containing more than an enumeration value.

For example, taking this enumeration as example:

$namespace.using("joopl.enumerations", function(enumerations) {
    enumerations.declareEnum("States", {
        open: 0,
        closed: 1,
        working: 2
    });
});

Some code may need to express that something is open but it is also working. This is achieved by using the OR operator:

var openAndWorking = enumerations.State.open.enum.or(State.working);

And, finally, if some other code needs to evaluate that the enumeration value includes open (see EnumValue.EnumValue/hasFlag:method method for further details):

if(openAndWorking.enum.hasFlag(this.State.open)) {
    // Do stuff if it is open already
}