Options Arrays and Dot Notation

 

An options array is an array containing a sub-array for each option. Options have a name and a value, which itself can be an array. For example, here is a simple options array, with two options:

 

opts = {{"Color", ColorRGB(0,0,0)}, {"Line Width", 4.5}}

 

An alternate format for specifying an options array is an array containing names and values separated by colons. For example, here is the same options array:

 

opts = {Color: ColorRGB(0,0,0), [Line Width]: 4.5}

 

Names can also be surrounded by quotes. For example, here is the same options array:

 

opts = {"Color": ColorRGB(0,0,0), "Line Width": 4.5}

 

You can use a dot notation to get, set, add, and remove options in options arrays, with statements such as:

 

prev_clr = opts.Color	//gets the value of the "Color" option
opts.Color = ColorRGB(255, 0, 0)	//sets the value of the "Color" option
opts.[Line Width] = 3.0	//sets the value of the "Line Width" option. Note that since the option key includes a spoace we should encolose it in bracketss
opts.Font = "Caliper Cartographic|8"	//adds a new "Font" option
opts.Color = NULL	//removes the "Color" option

 

The array opts now has the form:

 

{{"Line Width", 3},

{"Font", "Caliper Cartographic|8"}} 

 

Dot notation works with an option that has a single value, including an array, but will not work for an option with more than one value, such as:

 

opts = {{"Position", 32, 60}}

 

However, if the value of an option is an array, you can reference an item in the array by its index:

 

opts = {{"Position", {32, 60}}}

x = opts.Position[2]     // x = 60

 

To start an options array from scratch, you should (though you do not have to) declare an array of one element whose value is NULL. Then you can start adding options; for example:

 

customer = {}	// This is optional but is good programming style
customer.Name = "John"	// opts is now {{"Name", "John"}}
customer.[Date of Birth] = "1/1/1990"	// option key enclosed in brackets, since it includes spaces

 

You can get the values of the options array using the dot notation

 

  name  = customer.Name

  birth_date=  customer.[Date of Birth]

 

This approach can only be used if the option has only one value, it would not work in a case like this

  

  rectangle_parameters= { {"WidthHeigth", 3, 5}}

  dimensions =  rectangle_dimensions.[WidthHeigth]  // this will return null

  

If you set the value of an option to False or null, the option will be removed from the array:

 

opts = {}

opts.Name = True

ShowArray(opts)  // Shows an array {{"Name", 1}}

opts.Name = False

ShowArray(opts)  // Shows nothing

 

However, you can still test for the value of an option, even if it is not in the options array:

 

if not opts.Name then do

    // do something

    end

 

You can use this notation to easily manage data structures with named properties in your GISDK macros. In fact, you can nest the structures within each other to create quite complex objects. e.g.:

 

company = {}

company.Name = "Caliper"

company.Address = {}

company.Address.Street = "1172 Beacon St"

company.Address.ZIP = "02461"

 

dim employees[5]

employees[1] = {}

employees[1].Name = "Simon"

company.Employees = employees

 

You can use ShowArray() to view these data structures, and even easily make them persistent using SaveArray() and LoadArray(). You can optionally save or load arrays in proper JSON (JavaScript Object Notation) literal object format, and you can convert between an option array and a proper JSON literal object with ArrayToJson() and JsonToArray().

 

You can also use options arrays to provide indirection. You can use the name of an option to retrieve its values. This is done by putting parentheses around the variable that contains the name of the option, so that it will be evaluated at run time. Here is an example:

 

options={{'a', 'a string'}}

x='a'

ShowMessage(options.(x)) // Displays "a string"

 

This makes it easy to use an options array to do a table lookup. For example, if you had an options array StateNames with the postal abbreviations of states as the option name and the full state name as the option value, instead of a For clause to search for the postal abbreviation and get the full name, like this:

 

for i = 1 to StateNames.length do

if abbr = StateNames[i][1] then do 

fullname = StateNames[i][2] 

goto skip 

end 

end 

skip:

 

You can use just this:

 

fullname = StateNames.(abbr)