Parameters
A DSL has been provided for creating Parameters to store values like primitive types, collection types or domain specific types, to be used for ParameterSets in Events and Commands. This DSL is built over abstractions like Parameter, KeyType, etc. offered by CSW. Refer to the CSW docs for more information about this.
Keys¶
Following table lists all the key types, and their corresponding DSL.
| KeyType | DSL |
|---|---|
| Boolean | booleanKey |
| Character | charKey |
| Byte | byteKey |
| Short | shortKey |
| Long | longKey |
| Int | intKey |
| Float | floatKey |
| Double | doubleKey |
| String | stringKey |
| UtcTime | utcTimeKey |
| TaiTime | taiTimeKey |
| ByteArray | byteArrayKey |
| ShortArray | shortArrayKey |
| LongArray | longArrayKey |
| IntArray | intArrayKey |
| FloatArray | floatArrayKey |
| DoubleArray | doubleArrayKey |
| ByteMatrix | byteMatrixKey |
| ShortMatrix | shortMatrixKey |
| LongMatrix | longMatrixKey |
| IntMatrix | intMatrixKey |
| FloatMatrix | floatMatrixKey |
| DoubleMatrix | doubleMatrixKey |
| Choice | choiceKey |
| EqCoord | eqCoordKey |
| SolarSystemCoord | solarSystemCoordKey |
| MinorPlanetCoord | minorPlanetCoordKey |
| CometCoord | cometCoordKey |
| AltAzCoord | altAzCoordKey |
| Coord (*) | coordKey |
The example below shows usages of the DSL for different types of keys. Some other DSL helpers like choicesOf, arrayData, matrixData, etc. have also been provided for ease of access. Usage of this helper DSLs is also shown in the example below.
source// Primitive keys
val encoderKey: Key<Int> = intKey("encoder")
val flagKey: Key<Boolean> = booleanKey("flag")
val eventTimeKey: Key<UTCTime> = utcTimeKey("event-time")
// Arrays
val arrayKey: Key<ArrayData<Int>> = intArrayKey("arrayKey")
val elms: Array<Int> = arrayOf(1, 2, 3, 4)
val values1: ArrayData<Int> = arrayData(elms)
val values2: ArrayData<Int> = arrayData(5, 6, 7, 8)
val arrayParam: Parameter<ArrayData<Int>> = arrayKey.set(values1, values2)
// Matrix
val matrixKey: Key<MatrixData<Int>> = intMatrixKey("matrixKey")
val arr1: Array<Int> = arrayOf(1, 2, 3, 4)
val arr2: Array<Int> = arrayOf(5, 6, 7, 8)
val elms1: Array<Array<Int>> = arrayOf(arr1, arr2)
val data1: MatrixData<Int> = matrixData(elms1)
val data2: MatrixData<Int> = matrixData(arr1, arr2)
val matrixParameter: Parameter<MatrixData<Int>> = matrixKey.set(data1, data2)
// Domain specific types
val choiceKey: Key<Choice> = choiceKey("choice", choicesOf("A", "B", "C"))
val choiceParam: Parameter<Choice> = choiceKey.set(Choice("A"), Choice("C"))
// with units
val temperatureInKelvinKey: Key<Int> = intKey("encoder", JUnits.kelvin)Creating Parameters¶
The example below shows different ways of creating parameters and adding them to a command.
sourceval temperatureKey: Key<Int> = intKey("temperature")
val temperatureParam: Parameter<Int> = temperatureKey.set(1, 2, 3)
// with values as Array
val encoderKey: Key<Int> = intKey("encoder")
val encoderValues: Array<Int> = arrayOf(1, 2, 3)
val encoderParam: Parameter<Int> = encoderKey.setAll(encoderValues)
// with units
val powerKey: Key<Double> = doubleKey("power")
val values: Array<Double> = arrayOf(1.1, 2.2, 3.3)
val powerParam: Parameter<Double> = powerKey.setAll(values).withUnits(JUnits.watt)
// adding a param to command or event
val setupCommand: Setup = Setup("ESW.IRIS_darkNight", "move").add(temperatureParam)
val systemEvent: SystemEvent = SystemEvent("ESW.IRIS_darkNight", "movement").add(temperatureParam)
// adding multiple params
val setupCommand2: Setup = Setup("ESW.IRIS_darkNight", "move").madd(temperatureParam, encoderParam)
// adding params of one command to other
val paramsFromIncomingCommand: Params = command.params
val commandForDownstream: Setup = Setup("ESW.IRIS_darkNight", "move").add(paramsFromIncomingCommand)Extracting a parameter from Params/Command/Event¶
Extracting parameter¶
You can extract a parameter from Params/Command/Event using another parameter with the same key name and key type (values of the parameter passed in are ignored).
sourceval params: Params = setupCommand.params
val maybeParam: Parameter<Int>? = params.kFind(temperatureParam)
val maybeParam2: Parameter<Int>? = setupCommand.kFind(temperatureParam)Extracting parameter by key¶
Yuo can also use a Key:
source// extracting a param from Params instance
val temperatureParameter: Parameter<Int>? = setupCommand.params.kGet(temperatureKey)
val temperatureParameter2: Parameter<Int> = (setupCommand.params)(temperatureKey) // alternative
// extracting a param directly from the command or event
val temperatureParameter3: Parameter<Int>? = setupCommand.kGet(temperatureKey)
val temperatureParameter4: Parameter<Int> = setupCommand(temperatureKey) // alternativeExtracting parameter by keyName and KeyType¶
Or, you can use the key name and type:
sourceval keyName = "temperature"
val keyType: KeyType<Int> = JKeyType.IntKey()
val param: Parameter<Int>? = setupCommand.params.kGet(keyName, keyType)Extracting values from a parameter¶
The example below shows the accessing a List of values or a specific value of a parameter.
sourceval temperatureKey: Key<Int> = intKey("temperature")
val temperatureParam: Parameter<Int> = temperatureKey.set(1, 2, 3)
// extracting values from parameter
val temperatureValues: List<Int> = temperatureParam.values
// extracting first value from parameter
val firstValue: Int = temperatureParam.first
// extracting value of the parameter at a given index
val temperatureValue: Int? = temperatureParam.kGet(1)
val temperatureValue2: Int = temperatureParam(1) //alternativeNote that the shorthand alternatives shown with // alternative comment in above examples, do not return optional values unlike their corresponding full version. This means, with shorthand DSL, an error will occur in the absence of the specified key/index.
Removing a parameter¶
A parameter could be removed from a Params instance or from a Command directly. The example below demonstrates both of these DSL methods.
source// remove param from params by key
val updatedParams: Params = setupCommand.params.remove(temperatureKey)
// remove param from params
val updatedParams2: Params = setupCommand.params.remove(temperatureParameter)
// remove param from command by key
val updatedCommand: Setup = setupCommand.remove(temperatureKey)
// remove param from command
val updatedCommand2: Setup = setupCommand.remove(temperatureParameter)Checking if a parameter exists¶
source// check if parameter with specified key exists in Params
val temperatureKeyExists: Boolean = setupCommand.params.exists(temperatureKey)
// check if parameter with specified key exists directly from command
val temperatureKeyExists2: Boolean = setupCommand.exists(temperatureKey)