| 1 | = babeltrace2-query-babeltrace.support-info(7) |
| 2 | :manpagetype: query object |
| 3 | :revdate: 14 September 2019 |
| 4 | |
| 5 | |
| 6 | == NAME |
| 7 | |
| 8 | babeltrace2-query-babeltrace.support-info - Babeltrace 2's support info |
| 9 | query object |
| 10 | |
| 11 | |
| 12 | == DESCRIPTION |
| 13 | |
| 14 | The `babeltrace.support-info` Babeltrace~2 query object indicates, |
| 15 | for a given source component class, whether or not its instance can |
| 16 | handle a given input, and if so, what's the confidence of this support. |
| 17 | |
| 18 | Said input can be a simple string, an existing file path, or an existing |
| 19 | directory path. Components which expect some form of URI can handle a |
| 20 | string input, while components which expect an existing file or |
| 21 | directory can handle a file/directory path input. |
| 22 | |
| 23 | When the source component class's query method replies that its |
| 24 | component can handle a given input, it can also specify the name of a |
| 25 | group in which to put that input. All the inputs of a given group, for a |
| 26 | given component class, should be passed when instantiating the component |
| 27 | class as its nlparam:inputs initialization parameter (array of strings). |
| 28 | |
| 29 | The man:babeltrace2-convert(1) command queries this object from specific |
| 30 | source component classes to find the most appropriate for a given |
| 31 | non-option argument. |
| 32 | |
| 33 | |
| 34 | == PARAMETERS |
| 35 | |
| 36 | param:input='INPUT' vtype:[string]:: |
| 37 | Check input 'INPUT'. |
| 38 | + |
| 39 | Depending on the param:type parameter, this is a simple string, a file |
| 40 | path, or a directory path. |
| 41 | |
| 42 | param:type=(`string` | `file` | `directory`) vtype:[string]:: |
| 43 | Input type, one of: |
| 44 | + |
| 45 | -- |
| 46 | `string`:: |
| 47 | param:input parameter is a simple string. |
| 48 | |
| 49 | `file`:: |
| 50 | param:input parameter is a file path. |
| 51 | |
| 52 | `directory`:: |
| 53 | param:input parameter is a directory path. |
| 54 | + |
| 55 | It is expected that the query method does not recurse into this |
| 56 | directory: the result object indicates whether or not the component |
| 57 | class supports this specific directory (param:input). |
| 58 | -- |
| 59 | |
| 60 | |
| 61 | == RESULT OBJECT |
| 62 | |
| 63 | The result object can be one of: |
| 64 | |
| 65 | * [[simple-real]]A simple real value which is the weight, between 0 and |
| 66 | 1, of the support by the component class for the given input. |
| 67 | + |
| 68 | A weight of 0 means the input is unsupported while a weight of 1 means |
| 69 | it's fully supported. Any value in between shows how confident the |
| 70 | component class is about the support of the given input. |
| 71 | |
| 72 | * A map with a weight and an optional group name. |
| 73 | |
| 74 | When it's a map, the expected entries are: |
| 75 | |
| 76 | qres:group='GROUP-NAME' vtype:[optional string]:: |
| 77 | Put the given input into a group named 'GROUP-NAME' for this |
| 78 | component class. |
| 79 | + |
| 80 | If this entry is missing, then the given input gets its own, unique |
| 81 | group. |
| 82 | |
| 83 | qres:weight='WEIGHT' vtype:[real]:: |
| 84 | Weight, between 0 and 1, of the support by the component class for |
| 85 | the given input. |
| 86 | + |
| 87 | The semantics are the same as when the result object is a |
| 88 | <<simple-real,simple real value>>. |
| 89 | |
| 90 | |
| 91 | == EXAMPLES |
| 92 | |
| 93 | === Query parameters |
| 94 | |
| 95 | .String input. |
| 96 | ==== |
| 97 | [source,yaml] |
| 98 | ---- |
| 99 | input: net://relayd177/host/node23/active |
| 100 | type: string |
| 101 | ---- |
| 102 | ==== |
| 103 | |
| 104 | .File path input. |
| 105 | ==== |
| 106 | [source,yaml] |
| 107 | ---- |
| 108 | input: /home/user/traces/2019-08-26/quad.tr |
| 109 | type: file |
| 110 | ---- |
| 111 | ==== |
| 112 | |
| 113 | === Result object |
| 114 | |
| 115 | .Simple weight (unique group). |
| 116 | ==== |
| 117 | [source,yaml] |
| 118 | ---- |
| 119 | 0.5 |
| 120 | ---- |
| 121 | ==== |
| 122 | |
| 123 | .Weight and specific group. |
| 124 | ==== |
| 125 | [source,yaml] |
| 126 | ---- |
| 127 | group: 63a4b7e5-37f0-4254-a048-a0cff9e5b761 |
| 128 | weight: 0.75 |
| 129 | ---- |
| 130 | ==== |
| 131 | |
| 132 | .Weight within a map (unique group). |
| 133 | ==== |
| 134 | [source,yaml] |
| 135 | ---- |
| 136 | weight: 0.6 |
| 137 | ---- |
| 138 | ==== |
| 139 | |
| 140 | |
| 141 | include::common-footer.txt[] |
| 142 | |
| 143 | |
| 144 | == SEE ALSO |
| 145 | |
| 146 | man:babeltrace2-intro(7), |
| 147 | man:babeltrace2-query(1), |
| 148 | man:babeltrace2-convert(1) |