Commit | Line | Data |
---|---|---|
e70712b3 PP |
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) |