Overview DSL Reference

return

Returns the value of the expression that follows from a function

if / else

If statement

for

For loop

@Role

Indicates that the persistent object is associated with a user role (using this annotation on an object automatically makes it persistent, so you don’t have to explicitly use the persistent keyword)

@RoleName
string getGymEmployeeRoleName(GymEmployee employee){
	
	EN_GYM_EMPLOYEE_ROLE_TYPE employeeRoleType = employee.employeeType;
	if(employeeRoleType == EN_GYM_EMPLOYEE_ROLE_TYPE.Gym_Trainer){
		return "Trainer";
	}
	else if(employeeRoleType == EN_GYM_EMPLOYEE_ROLE_TYPE.Gym_Admin){
		return "Gym Admin";
	}
	else{
		return "Gym Employee";
	}
}

@RolesAllowed

Specifies the access rights for a specific role on an object (like the previous annotation, this annotation implicitly makes the object persistent)

@Scheduled

Specifies a scheduled task to run at a certain interval

"minute hour day-of-month month day-of-week"

@ReceiveSms

Indicates that a function can receive an SMS.

@Test

Indicates that a function is a unit test.

@{ID} eg. @FirstnameValidator

Annotations that start with @ followed by an ID, and that are used on object attributes are validator annotations. The ID value must be the same as any validator that is defined in the application:

@OneToOne @ManyToOne @ManyToMany @OneToMany

Indicates the multiplicity of a relationship

@OnSmsResultUpdate
void smsResultUpdateCallback(__sms_result__ smsResult) {
    if(smsResult.success == false) {
        FailedSms failedSms = FailedSms:new();
        failedSms.failureRecordedOn = Mez:now();
        failedSms.smsResultId = smsResult._id;
        failedSms.save();
    }
}

@OnScheduledFunctionResultUpdate
void scheduledFunctionResultUpdateCallback(__scheduled_function_result__ scheduledFunctionResult) {
    if(scheduledFunctionResult.success == false) {
        FailedScheduledFunction failedScheduledFunction = FailedScheduledFunction:new();
        failedScheduledFunction.failureRecordedOn = Mez:now();
        failedScheduledFunction.scheduledFunctionResultId = scheduledFunctionResult._id;
        failedScheduledFunction.save();
    }
}

The Identity object

The Identity object is an implicit interface that is implemented by every persistence object in your application that has a @Role annotation. This object has the following implicit declaration:

@NotTracked
persistent object __sms_result__ {
    datetime datetimestampStarted;
    datetime datetimestampFinished;
    string destination;    
    int attempt;
    bool success;
    string error;
    bool doneProcessing;
    uuid smsOutboundConfigurationVersionId;
    string smsOutboundConfigurationName;
    uuid smsId;
}

@NotTracked
persistent object __scheduled_function_result__ {
    datetime datetimestampStarted;
    datetime datetimestampFinished;
    string qualifiedName;
    string schedule;
    string error;
    string stackTrace;
    bool success;
}

These built-in functions are accessed via the pseudo unit “Date”

Date:addSeconds

Adds an interval to an existing date or datetime value. The interval expression should return a positive or negative integer value that represents the number of days that is to be added to the date/datetime value. The function returns a new date or datetime instance and doesn't alter the original value.

Date:addDays

Adds an interval to an existing date or datetime value. The interval expression should return a positive or negative integer value that represents the number of days that is to be added to the date/datetime value. The function returns a new date or datetime instance and doesn't alter the original value.

Date:addMonths

Adds an interval to an existing date or datetime value. The interval expression should return a positive or negative integer value that represents the number of months that is to be added to the date/datetime value. The function returns a new date or datetime instance and doesn't alter the original value.

If the target month has less days than the given one then the date may be reduced so as to not skip an additional month. ie. A month added to 31st January will result in the 28th of February (non leap year).

Date:daysBetween

Returns the number of full days that have to pass to get from the date returned by the first expression to the date returned by the second expression.

Date:extract

Returns an integer representing the component of the date which is identified by the field name string

@Test
void testFromTimeString(){
    datetime dt = Date:fromTimeString("2013-1-20 08:45:12 GMT");
    Assert:isEqual(2013, Date:extract(dt, "year"), "Date:extract returned an incorrect number of years");
    Assert:isEqual(1, Date:extract(dt, "month"), "Date:extract returned an incorrect number of months");
    Assert:isEqual(20, Date:extract(dt, "day"), "Date:extract returned an incorrect number of days");
    Assert:isEqual(8, Date:extract(dt, "hour"), "Date:extract returned an incorrect number of hours");
    Assert:isEqual(45, Date:extract(dt, "minute"), "Date:extract returned an incorrect number of minutes");
    Assert:isEqual(12, Date:extract(dt, "second"), "Date:extract returned an incorrect number of seconds");
}

Date:monthsBetween

Returns the number of full months that have to pass to get from the date returned by the first expression to the date returned by the second expression.

Date:fromString

Returns a date representation of the string value expression

Date:fromTimeString

Returns a date-time representation of the string value expression.  The time zone component of the expression is optional and will default to the logged in user's preferred time zone.

@Test
void testFromTimeString(){
    datetime dt = Date:fromTimeString("2013-1-20 08:45:12 GMT");
    Assert:isEqual(2013, Date:extract(dt, "year"), "Date:extract returned an incorrect number of years");
    Assert:isEqual(1, Date:extract(dt, "month"), "Date:extract returned an incorrect number of months");
    Assert:isEqual(20, Date:extract(dt, "day"), "Date:extract returned an incorrect number of days");
    Assert:isEqual(8, Date:extract(dt, "hour"), "Date:extract returned an incorrect number of hours");
    Assert:isEqual(45, Date:extract(dt, "minute"), "Date:extract returned an incorrect number of minutes");
    Assert:isEqual(12, Date:extract(dt, "second"), "Date:extract returned an incorrect number of seconds");

    dt = Date:fromTimeString("2013-1-20 08:45:12 Africa/Johannesburg");
    Assert:isEqual(2013, Date:extract(dt, "year"), "Date:extract returned an incorrect number of years");
    Assert:isEqual(1, Date:extract(dt, "month"), "Date:extract returned an incorrect number of months");
    Assert:isEqual(20, Date:extract(dt, "day"), "Date:extract returned an incorrect number of days");
    Assert:isEqual(6, Date:extract(dt, "hour"), "Date:extract returned an incorrect number of hours");
    Assert:isEqual(45, Date:extract(dt, "minute"), "Date:extract returned an incorrect number of minutes");
    Assert:isEqual(12, Date:extract(dt, "second"), "Date:extract returned an incorrect number of seconds");
}

Date:secondsBetween

Returns the total number of seconds between the first and second date-time expressions.  The value will be negative if the second argument is before the first argument.

 @Test
void testSecondsBetween(){
    datetime dt1 = Date:fromTimeString("2013-1-20 08:45:12 GMT");
    datetime dt2 = Date:fromTimeString("2013-1-20 08:45:40 GMT");
    
    int diff1 = Date:secondsBetween(dt1, dt2);
    Assert:isEqual(28, diff1, "Date:secondsBetween returned an incorrect number of seconds");
    
    int diff2 = Date:secondsBetween(dt2, dt1);
    Assert:isEqual(-28, diff2, "Date:secondsBetween returned an incorrect number of seconds");
}

Date:now()

Returns the current date and time as a datetime value.

Date:today()

Returns the current date as a date value.

These built-in functions are accessed via the pseudo unit “Integer”

Integer:fromString

Returns an integer representation of the string value expression

These BIFs are accessed via the pseudo unit “Mez”

now

Returns the current time

today

Returns the today's date

alert

Displays an alert dialog in the UI with the given message

log

Writes a log message with level INFO. The logging entry is saved in the __logging_log__ table of your application instance's schema. It will also be available via the Logging Service.

warn

Writes a log message with level WARNING

error

Writes a log message with level SEVERE

These BIFs are accessed via the pseudo unit “Math”

pow

Raises the first argument to the power of the second argument

sqrt

Calculates the square root of the argument

random

Generates a random decimal

These built-in functions are accessed via the pseudo unit “String”

String:concat

Returns a string value that is the concatenated result of two or more arguments passed to the function. As of Helium 1.3.1 null values will be treated as empty strings.

String:split

Returns an array of string values that represent the tokens from the value expression that are separated by the separator expression.

Note that in order to split a special character such as '|', one needs to escape the string with a '\' character.  The '\' may need to be escaped as well, so in this case one will end up with String:split(someText, "\\|").

String:length

Returns the length of the string being passed

String:substring

Substring of a string based on index positions

String:lower

Convert string to lowercase

String:upper

Convert string to uppercase

String:startsWith

Check if a particular string starts with a string

String:endsWith

Check if a particular string ends with a string

String:indexOf

Returns the index within this string of the first occurrence of the specified substring.

String:join

Join a collection of strings into one result string with the specified join character

These built-in functions can be accessed via the psuedo unit “Assert”

isEqual

Assert that two expressions are equal

isTrue

Assert that the expression returns true

isFalse

Assert that the expression returns false

isNull

isNotNull

isGreaterOrEqual

isLessOrEqual

isLess

isBoth

isEither

Assert:isEither(p.age > 5, isName(“Steve”, p), “Failed test.”);

isNotEqual

Assert that the two expression do not return the same value

These BIFs can be called on any variable that holds an object/collection instance. On variables that hold a reference to a list

pop

Pops (remove and return) the first element from the collection

drop

length

Returns the current length (number of elements) in the a list

first

Returns the first element in the list (without removing it)

last

Returns the last element in the list (without removing it)

append

Adds an element to the back of a list

prepend

Adds an element to the front of the list

get

Returns an element in the specific location in the list

add

Adds an element to the specified position in the list

remove

Remove the element at the specified position in the list

sortAsc

Sort the list in ascending order

sortDesc

Sort the list in descending order

clear

Remove all elements from the list

If the variable holds a reference to an object instance

save

Saves the object to the persistence layer if the object is persistent

notify

Prompts Helium to send a notification to the user associated with the object if the object declaration was annotated with @Role (this method can be called on a variable holding a reference to collection as well, provided that objects in the collection are instances of @Role objects)

object Person {
    string name;
}
 
void sampleSubSelect(){
	Person[] persons;

    Person p = Person:new();
    p.name = "A";
    persons.append(p);

    p = Person:new();
    p.name = "A";
    persons.append(p);

    p = Person:new();
    p.name = "A";
    persons.append(p);

    p = Person:new();
    p.name = "B";
    persons.append(p);

    Persons[] subset = persons.select(all()); //subset will be a copy of the original collection
 
	subset = persons.select(equals(name, "A")); //subset will contain only the first three items in the original collection
 
	subset = persons.select(and(equals(name, "A"), equals(name, "B"))); //and on mutually exclusive selectors will return an empty collection
}

These BIFs can be used to build up a complex selector for reading sets of data from the persistence layer. These BIFs are accessed via the pseudo unit with the same name as the object that is being queried eg. “Person” or “Car”

These BIFs perform operations on single persistent entities. They are accessed via a method call on a variable holding an object instance or on the pseudo unit with the same name as the object that the method is being performed on

new

Creates a new instance of an object. The object doesn’t have to be persistent for this method to be called on it

save

If the object instance is a persistent object it saves the object to the persistence layer, (if the developer added objects to the instance’s relationship member collections, they will be persisted aswell)

read

Reads an existing object instance from the persistence layer

delete

Delete the instance

user

Get the current user object

@Role("Nurse")
persistent object Nurse {
	string mobileNumber;
}
 
void sampleInvite(){
	Nurse n = Nurse:new();
    n.mobileNumber = "27820010001";
    n.invite(n.mobileNumber);
}

@Role("Nurse")
persistent object Nurse {
	string mobileNumber;
}
 
void exampleToRemoveRole(Nurse nurse){
    nurse.removeRole();
}

Trigger functions are special functions defined within an object declaration, and are executed at specific times during the object’s life cycle.

beforeCreate

Executes before the object is created, there is one implicit variable that developers can use within the function body, and that is the variable “before”

afterCreate

Executes after the object is created, there is one implicit variable that developers can use within the function body, and that is the variable “after”

beforeDelete

Executes before the object is deleted, there is one implicit variable that developers can use within the function body, and that is the variable “before”

afterDelete

Executes after the object is deleted, there is one implicit variable that developers can use within the function body, and that is the variable “after”

beforeUpdate

Executes before the object is updated, there are two implicit variables that developers can use within the function body, and that is the variables “before” and “after”

afterUpdate

Executes after the object is updated, there are two implicit variables that developers can use within the function body, and that is the variables “before” and “after”

before

A variable that holds a reference of an instance of the object that reflects the state before creation

after

A variable that holds a reference of an instance of the object that reflects the state after creation

These are the building blocks used for creating complex validators

notnull

Check that the attribute is not null. This validator does not take any arguments.

regex

Checks that the value conforms to a regular expression.

minval

Checks that the value is not less than the supplied minimum value.

maxval

Checks that the values is not greater than the supplied maximum value.

minlen

Checks that a string value does not have less characters than the supplied minimum value.

maxlen

Checks that a string value does not have more characters than the supplied maximum value.

Some examples:

Single line comments

Each block contains exactly one token, even if it has two characters, so typing [ ] (with a space between them) it is not the same token as [] (with no nested whitespace).

Example code for extracting nurses from CSV in a blob type:

Unit

Units are groupings of functions and also variables. They can be thought of as modules or namespaces. A Mezzanine script must have at least one unit. Units are defined as follows

This unit has one unit variable named myVar. This variable has unit scope and can be accessed by any function in the unit. The unit also has a function named factorial. A unit must have at least one function. To refer to a unit’s member functions or variables from another unit, you have to use the scope operator

Note: Unit variables cannot be in line initialized when they are declared. The following code will not compile

Objects

Although the Mezzanine scripting language is not an object oriented language, objects still play a very important role. The most basic objects in Mezzanine scripts can be likened to structs in C. A very basic object will look like this