|
3 | 3 | SPDX-License-Identifier: GFDL-1.3-only
|
4 | 4 | -->
|
5 | 5 |
|
6 |
| -This document covers some technical details for matching script programmers |
| 6 | +This document covers some technical details for matching script programmers. |
7 | 7 |
|
8 |
| -## Matching script interacting with swift |
| 8 | +The matching script consists of a JavaScript file containing an anonymous function: |
9 | 9 |
|
10 |
| -There are classes, which may be used as objects in Matching script (i.e. JavaScript). |
11 |
| -Those classes start with a `MS` prefix (matching script). |
12 |
| -Those classes can be found in `BlackMisc::Simulation` and `BlackCore`. |
| 10 | +```js |
| 11 | +(function() { /* your code goes here */ }) |
| 12 | +``` |
| 13 | + |
| 14 | +Inside the function, the following objects are available: |
13 | 15 |
|
14 |
| -- MSInOutValues |
15 |
| -- MSModelSet |
16 |
| -- MSWebServices |
| 16 | +- ``inObject``: Object with all the data from the network and the swift-provided reverse lookup stage |
| 17 | +- ``outObject``: The object that should contain the script results. |
| 18 | + In the beginning, this object contains the same content as ``matchedObject`` and can be changed by your script. |
| 19 | +- ``matchedObject``: Object with the model (and additional information) deduced so far in previous stages. In the reverse lookup script, this is identical to ``inObject`` as no further stages were already executed. |
| 20 | +- ``modelSet``: User's current model set. Not available in reverse lookup |
| 21 | +- ``webServices``: Wrapper to access the swift web services |
| 22 | + |
| 23 | +As already stated, your script must return the ``outObject``: |
| 24 | + |
| 25 | +```js |
| 26 | +(function() { |
| 27 | + /* Do some modifications of outObject here */ |
| 28 | + return outObject; |
| 29 | +}) |
| 30 | +``` |
17 | 31 |
|
18 | 32 | ## Using properties
|
19 | 33 |
|
| 34 | +The provided objects contain properties that you can use. |
| 35 | +These properties are listed in the [``matchingscript.h``](https://github.com/swift-project/pilotclient/blob/main/src/blackmisc/simulation/matchingscript.h) as ``Q_PROPERTY``. |
20 | 36 |
|
21 |
| -MS class properties as below |
22 | 37 |
|
23 |
| -```cpp |
24 |
| -//! MSNetworkValues properties @{ |
25 |
| -Q_PROPERTY(QString callsign READ getCallsign WRITE setCallsign NOTIFY callsignChanged) |
26 |
| -Q_PROPERTY(QString callsignAsSet READ getCallsignAsSet) |
27 |
| -Q_PROPERTY(QString flightNumber READ getFlightNumber) |
28 |
| -Q_PROPERTY(int dbAircraftIcaoId READ getDbAircraftIcaoId WRITE setDbAircraftIcaoId NOTIFY |
29 |
| -``` |
| 38 | +| Javascript Object | Corresponding C++ class | |
| 39 | +|---------------------|-------------------------| |
| 40 | +| ``inObject`` | ``MSInOutValues`` | |
| 41 | +| ``outObject`` | ``MSInOutValues`` | |
| 42 | +| ``matchedObject`` | ``MSInOutValues`` | |
| 43 | +| ``modelSet`` | ``MSModelSet`` | |
30 | 44 |
|
31 |
| -can be used in matching script as follows |
| 45 | +The second parameter of ``Q_PROPERTY`` is the name of the property in JavaScript. |
| 46 | +They can be used in the scripts as like as follows: |
32 | 47 |
|
33 | 48 | ```js
|
34 |
| -outObject.aircraftIcao = "C172"; |
35 |
| -outObject.modified = true; // tell we changed something |
| 49 | +if (outObject.airlineIcao == "ABC") { |
| 50 | + outObject.aircraftIcao = "A320"; |
| 51 | +} |
36 | 52 | ```
|
37 | 53 |
|
38 |
| -Some properties are read only, and you can see the type from property definition. |
| 54 | +Some properties are read only, and you can see the type from the ``Q_PROPERTY`` definition. |
39 | 55 |
|
40 | 56 | ## Using functions
|
| 57 | +Some of the provided JavaScript objects contain functions that can be invoked by your script. |
| 58 | +These functions are listed in the [``matchingscript.h``](https://github.com/swift-project/pilotclient/blob/main/src/blackmisc/simulation/matchingscript.h) as ``Q_INVOKABLE``. |
| 59 | +They can be invoked like this: |
41 | 60 |
|
42 |
| -Functions of MS classes can be used if they are marked as `Q_INVOKABLE` (only those you can invoke from matching script). |
43 |
| - |
44 |
| -```cpp |
45 |
| -//! Functions calling the web services @{ |
46 |
| -Q_INVOKABLE int countAircraftIcaoCodesForDesignator(const QString &designator) const; |
47 |
| -Q_INVOKABLE int countAirlineIcaoCodesForDesignator(const QString &designator) const; |
48 |
| -//! @} |
| 61 | +```js |
| 62 | +var contains = modelSet.containsModelString("C172"); |
49 | 63 | ```
|
50 | 64 |
|
51 |
| -or |
| 65 | +## Effect of the ``outObject`` properties on reverse lookup and matching |
52 | 66 |
|
53 |
| -```cpp |
54 |
| -//! Model string of model with closest color distance |
55 |
| -Q_INVOKABLE QString findCombinedTypeWithClosestColorLivery(const QString &combinedType, const QString &rgbColor) const; |
56 |
| -``` |
| 67 | +After executing the script, the following properties are used by swift to influence the reverse lookup or matching: |
57 | 68 |
|
58 |
| -Those you can call those as functions in matching script |
| 69 | +- ``logMessage``: Contains a string message that is logged individually for each callsign/aircraft the matching script was invoked for. |
| 70 | + See also [this section](#log-messages-from-the-matching-script). |
| 71 | +- ``modified:`` Boolean flag that **must** be set to ``true`` if any of the other properties should be used. |
| 72 | + If set to ``false``, the data from this script run are discarded. |
| 73 | +- ``rerun``: When set to ``true``, rerun the stage that runs before this script but without executing the script again. |
| 74 | + Example: When this is set to ``true`` in the reverse lookup script, the swift-provided reverse lookup stage is executed again (it was already executed before the script was invoked). |
| 75 | +- ``dbModelId``: New model ID. Set this to -1 if you do not want to set the model ID explicitly. This invalidates the model ID as ``outObject`` is prepoulated with data from ``matchedModel``. |
| 76 | + When this property contains a different value than -1, the model is fetched from the webservices. |
| 77 | + If the fetched model is valid, all other properties are discarded and the specified model is used. |
| 78 | +- ``modelString``: String with a new model string. Set this to empty if you do not want to set it explicitly. |
| 79 | + This invalidates the model string as ``outObject`` is prepoulated with data from ``matchedModel``. |
| 80 | + The model string is first searched in the webservices and if not found there in the user's model set. |
| 81 | + If the model string is valid, all other properties are discarded and the specified model is used. |
| 82 | +- ``aircraftIcao``: Set the aircraft ICAO as a string. The webservices are used to find more information about the aircraft ICAO. |
| 83 | + If the webservice search was unsuccessful, the aircraft ICAO as a string is used anyway. |
| 84 | +- ``liveryId``: ID of the livery to use. |
| 85 | + The corresponding database entry is always fetched from the webservice. |
| 86 | + Invalid livery IDs might lead to some default livery. |
| 87 | + All airline ICAO options (below) are skipped if this property is set. |
| 88 | +- ``airlineIcaoId``: ID of the airline ICAO to use. |
| 89 | + Further data about the ID is gathered from the webservices. |
| 90 | + If the ID is not found via the webservices, some default/empty airline will be used. |
| 91 | + As a livery, the "standard" livery for the specified airline is used. |
| 92 | + This option is discarded when using ``liveryId``. |
| 93 | + This property takes precedence over ``airlineIcao``. |
| 94 | + The ``airlineIcao`` property is discarded in this case. |
| 95 | +- ``airlineIcao``: Airline ICAO string to use. |
| 96 | + Further data about the airline ICAO string is gathered from the webservices. |
| 97 | + If the ICAO is not found via the webservices, some default/empty airline will be used. |
| 98 | + As a livery, the "standard" livery for the specified airline is used. |
| 99 | + This option does not work when using ``liveryId`` or ``airlineIcaoId``. |
59 | 100 |
|
60 |
| -```js |
61 |
| -var mscl = modelSet.findCombinedTypeWithClosestColorLivery(combinedType, white); |
62 |
| -``` |
| 101 | +## Log messages from the matching script |
| 102 | + |
| 103 | +The ``outObject`` contains a ``logMessage`` property to display a log message for each invokation. |
| 104 | + |
| 105 | +!!! warning |
| 106 | + |
| 107 | + These messages are **not** displayed in the normal swift application log! |
| 108 | + |
| 109 | +### swiftgui |
| 110 | +In swiftgui, this logging only works if the corresponding logging (reverse lookup or matching) **and** "detailed" logging is enabled on the ``Models->Matching Log`` page. |
| 111 | +The log is shown on the same page after entering a callsign. |
| 112 | + |
| 113 | +{: style="width:50%"} |
| 114 | + |
| 115 | +### swiftdata |
| 116 | + |
| 117 | +Within the model matcher of swiftdata, the script log messages are always displayed. |
| 118 | + |
| 119 | +## Error logs |
| 120 | +If the script for some reason fails to execute (syntax errors, ...), a log file with the cause of the error is created at the following locations: |
| 121 | + |
| 122 | +- for the reverse lookup script: ``<SWIFT_LOG_DIR>/logMatchingScriptReverseLookup.log`` |
| 123 | +- for the matching script: ``<SWIFT_LOG_DIR>/logMatchingScriptMatchingStage.log`` |
63 | 124 |
|
64 |
| -## Examples |
| 125 | +To find your log directory, see [this page](./../swift_log_files.md). |
65 | 126 |
|
| 127 | +## Example scripts |
66 | 128 |
|
67 |
| -Check out the `matchingscript` directory for examples, like `\swift-0.9.2-64bit\share\matchingscript`. |
| 129 | +Check out the `matchingscript` directory for examples: `<SWIFT_INSTALL_DIR>\share\matchingscript`. |
0 commit comments