Object

Variables, attributes or expressions of the object type can contain various types of data. The structure of QodlyScript objects is based on the classic principle of "property/value" pairs. The syntax of these objects is based on JSON notation:

• A property name is always a text, for example "Name". It must follow specific rules.

• A property value can be of the following type:

  • number (number, integer)
  • string
  • null
  • boolean
  • date (date type or ISO date format string)
  • object(1) (objects can be nested on several levels)
  • picture(2)
  • collection

(1) ORDA objects such as entities or entity selections cannot be stored in attributes of the object type; however, they are fully supported in object variables.

(2) When exposed as text in the debugger or exported to JSON, picture object properties print "[object Picture]".

note

Attribute names are case-sensitive.

You manage object type variables, attributes or expressions using the object notation or the commands such as instanceOf.

Each property value accessed through the object notation is considered an expression. You can use such values wherever expressions are expected.

Instantiation

Objects must have been instantiated, otherwise trying to read or modify their properties will generate a syntax error.

Object instantiation can be done in one of the following ways:

• using the newObject command,
• using the {} operator.

info

Several commands and functions return objects, for example jsonParse or file. In this case, it is not necessary to instantiate the object explicitly, the QodlyScript language does it for you.

newObject command

The newObject command creates a new empty or prefilled object and returns its reference.

Examples:

 var obVar : object //declaration of an object type variable
 obVar = newObject //instantiation and assignment to the variable

 var obFilled : object
 obFilled = newObject("name","Smith","age",42) //instantiation and assignment of a prefilled object

{} operator

The {} operator allows you to create an object literal. An object literal is a semi-column separated list of zero or more pairs of property names and associated values of an object, enclosed in curly braces ({}). The object literal syntax creates empty or filled objects.

Since any property value is considered an expression, you can create sub-objects using {} in property values. You can also create and reference collection literals.

Examples:

 var o, o2, o3 : object //declaration of object variables
 o = {} // instantiation of an empty object
 o2 = {a: "foo", b: 42, c: {}, d: (toto) ? true : false \} // instantiation of an object
    // with properties {"a":"foo","b":42,"c":{},"d":false})

    // same properties using variables
 var a : string
 var b : integer
 var c : object
 a = "foo"
 b = 42
 c = {}
 o3 = { a:a, b:b, c:c } // {"a":"foo",b":42,"c":{}}

You can mix the newObject and literal syntaxes:

var o : object
var result : string
o = {\
    ob1: {age: 42}, \
    ob2: newObject("message", "Hello"), \
    form1: formula(return this.ob1.age+10), \
    form2 : formula(return $1+" World")), \
    col: [1, 2, 3, 4, 5, 6]\
    }

o.form1()  //52
result = o.form2(o.ob2.message)  // Hello World
col = o.col[5] //6

Regular or shared object

You can create two types of objects:

• regular (non-shared) objects, using the newObject command or object literal syntax ({}). These objects can be edited without any specific access control but cannot be shared between processes.
• shared objects, using the newSharedObject command. These objects can be shared between processes, including preemptive threads. Access to these objects is controlled by use...end structures.

Syntax basics

Object notation can be used to access object property values through a chain of tokens.

Object properties

With object notation, object properties can be accessed in two ways:

• using a "dot" symbol:

  object.propertyName

Example:

     employee.name = "Smith"

• using a string within square brackets:

  object["propertyName"]

Examples:

     vName = employee["name"]
     //or also:
     property = "name"
	 vName = employee[property]

Since an object property value can be an object or a collection, object notation accepts a sequence of symbols to access sub-properties, for example:

 vAge = employee.children[2].age

Object notation is available on any language element that can contains or returns an object, i.e:

• Objects themselves (stored in variables, attributes, object properties, or collection elements). Examples:

     age = myObjVar.employee.age //variable
     addr = myEntity.data_obj.address //attribute
     city = addr.city //property of an object
     val = myCollection[3].subvalue //collection element

• QuodlyScript commands that return objects. Example:

     storage.mydata.prop2 = 10

• Methods that return objects. Example:

      //myMethod1
     declare -> result : object
     result = newObject("a",10,"b",20)

      //myMethod2
     value = myMethod1.a //10

• Collections Example:

     myColl.length //size of the collection

Null value

When using the object notation, the null value is supported though the null command. This command can be used to assign or compare the null value to object properties or collection elements, for example:

 myObject.address.zip = null
 if(myColl[2] == null)

For more information, please refer to the null description.

Undefined value

Evaluating an object property can sometimes produce an undefined value. Typically when trying to read or assign undefined expressions, the QodlyScript will generate errors. This does not happen in the following cases:

• Reading a property of an undefined object or value returns undefined; assigning an undefined value to variables has the same effect as calling clearVariable with them:

     var o : object
     var val : integer
     val = 10 //val:10
     val = o.a //o.a is undefined (no error), and assigning this value clears the variable
      //val:0

• Reading the length property of an undefined collection produces 0:

     var c : collection //variable created but no collection is instanciated
     size = c.length //size = 0

• An undefined value passed as parameter to a project method is automatically converted to 0 or "" according to the declared parameter type.

     var o : object
     mymethod(o.a) //pass an undefined parameter

      //In mymethod method
     declare (param : text)
      // param: ""

• A condition expression is automatically converted to false when evaluating to undefined with the if and case of keywords:

     var o : object
     if(o.a) // false
     end
     switch
        :(o.a) // false
     end

• Assigning an undefined value to an existing object property reinitializes or clears its value, depending on its type:
• object, collection: null
• picture: empty picture
• boolean: false
• string: ""
• number: 0
• date: !00-00-00! if "Use date type" setting is enabled, otherwise ""
• time: 0 (number of ms)
• undefined, null: no change

     var o : object
     o = newObject("a",2)
     o.a = o.b //o.a = 0

• Assigning an undefined value to a non existing object property does nothing.

When expressions of a given type are expected in your code, you can make sure they have the correct type even when evaluated to undefined by surrounding them with the appropriate QodlyScript cast command: string, num, date, time, bool. These commands return an empty value of the specified type when the expression evaluates to undefined. For example:

 myString = lowercase(string(o.a.b)) //make sure you get a string value even if undefined
  //to avoid errors in the code

Object operators

You can use comparison operators with object references, which means that you can evaluate if two or more references point to the same instance of an object.

var o1 = {a: 42} //reference to an instance
var o2 = {a: 42} //reference to a different instance
var o3 = o1 //reference to the same instance

Based upon the code above, the comparison table is:

Operation	Syntax	Returns	Expression	Value
Equality	objectRef == objectRef	boolean	o1 == o3	true
			o1 == o2	false
Inequality	objectRef # objectRef	boolean	o1 != o3	false
			o1 != o2	true

Examples

• Writing and reading objects:

  // Using newObject
 var myObj : object //declares an object variable
 myObj = newObject //instanciates object and assigns to the variable
 myObj.age = 56
 age = myObj.age //56

  // Alternate code
 var myObj2 : object
 myObj2 = {"age":42} //instanciates object and adds the age property
 myObj2.age //42

• Create a property and assign values, including objects:

 var Emp : object
 Emp = newObject
 Emp.city = "London" //creates the city property and sets its value to "London"
 Emp.city = "Paris" //modifies the city property
 Emp.phone = {"office":"123456789","home":"0011223344"}
  //creates the phone property and sets its value to an object

• Get a value in a sub-object:

 vCity = Emp.city //"Paris"
 vPhone = Emp.phone.home //"0011223344"

• You can access properties as strings using the [] operator

 Emp["city"] = "Berlin" //modifies the city property
  //this can be useful for creating properties through variables
 var addr : string
 var i : integer
 addr = "address"
 for(i,1,4)
    Emp[addr+string(i)] = ""
 end
  // creates 4 empty properties "address1...address4" in the Emp object