7. Reserved keys

Prev		Next

Some keys are reserved to KeyValue's use. They are explained in the sequel.

7.1. Processor

The task performed on a data set is defined exclusively by its content. Indeed, excluding the Default data set (see Section 9), the value assigned to key Processor informs the action to be performed. More precisely, the bridge library implements a number of processors which perform different tasks on data sets. In any data set, the value assigned to key Processor (if present) names the processor which process the data set.

For instance, on sheet Reserved keys, the formula in B2 creates data set A which selects processor Polygon while the one in E2 creates an anonymous data set which selects processor Area. Recalculate B2 to verify on the logger the called processors:

Figure 12. In each data set, its key Processor selects the processor for this data set.

[Debug  ] DataSet: A
  Size    : 4
  Key   #1: IsRegular
  Value #1: [Single] 1
  Key   #2: NumberOfEdges
  Value #2: [Single] 4
  Key   #3: Processor
  Value #3: [Single] Polygon
  Key   #4: Size
  Value #4: [Single] 1
[Debug  ] DataSet:
  Size    : 2
  Key   #1: Polygon
  Value #1: [Single] A
  Key   #2: Processor
  Value #2: [Single] Area

Processors that create objects are called builders (e.g. Polygon). Those that compute results to be displayed on the spreadsheet are called calculators (e.g. Area).

Key Processor is optional. A data set which does not have such key is called data-only.

7.1.1. Commands

Some processors might perform their tasks on empty data sets or, more precisely, on data sets whose unique key is Processor. For instance, as we see in Section 8.4, the processor DeleteDataSets resets the data set repository when key DataSets is not present. The bridge library can declare such processors as commands.

Front-ends may provide special support for commands. For instance, the Excel add-in presents a menu from which one can call any command. The add-in creates an anonymous data set with key Processor and whose value is DeleteDataSets. Since the data set is anonymous it is immediately processed (as explained in Section 7.2).

Notice that the name shown on the menu might be different of processor's name. In our example, processor DeleteDataSets becomes Reset repository.

7.2. ProcessNow

On sheet Reserved keys, the formula in B2 actually does not build any polygon. Indeed, for non anonymous data sets, by default KeyValue implements a lazy initialization strategy: It avoids to call processors until this is really necessary. In this case, all KEYVALUE does is creating the data set A which laterly might be used to build a polygon. In this example it will happen when we request its area in E2.

Key ProcessNow is used to change this behaviour. If ProcessNow is TRUE, then the data set is immediately processed and the result is returned to the front-end. Otherwise, KeyValue just creates and stores the data set for later use and the result returned to the front-end is the data set name. Change cell C10 to TRUE and FALSE and check the logger to see when the processor is called.

Anonymous data sets are always processed and, therefore, ProcessNow is ignored. Change F10 and check the logger.

This key is optional and when it cannot be resolved (see Section 9) assumes the value FALSE.

7.3. VectorOutput

When the result of KEYVALUE is a vector the user may choose how this vector should be returned to the front-end: As a column vector, as a row vector or unchanged, i.e., as it is returned by the processor. For this purpose, the key VectorOutput might be assigned to "Row", "Column" or "AsIs".

This key is optional and when it cannot be resolved (see Section 9) assumes the value "AsIs".

7.4. Imports

Key Imports is optional. Its value is a vector of data set names whose keys and values are imported to the current data set. For more details see Section 9.2.

7.5. Export

Key Export is reserved only in Default data (see Section 9) set where it defines whether key-value pairs in Default participate in key resolution or not. (See Section 9.)