doc/man/babeltrace2-query-babeltrace.support-info.7.txt

   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)