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

= babeltrace2-query-babeltrace.support-info(7)
:manpagetype: query object
:revdate: 14 September 2019


== NAME

babeltrace2-query-babeltrace.support-info - Babeltrace 2's support info
query object


== DESCRIPTION

The `babeltrace.support-info` Babeltrace~2 query object indicates,
for a given source component class, whether or not its instance can
handle a given input, and if so, what's the confidence of this support.

Said input can be a simple string, an existing file path, or an existing
directory path. Components which expect some form of URI can handle a
string input, while components which expect an existing file or
directory can handle a file/directory path input.

When the source component class's query method replies that its
component can handle a given input, it can also specify the name of a
group in which to put that input. All the inputs of a given group, for a
given component class, should be passed when instantiating the component
class as its nlparam:inputs initialization parameter (array of strings).

The man:babeltrace2-convert(1) command queries this object from specific
source component classes to find the most appropriate for a given
non-option argument.


== PARAMETERS

param:input='INPUT' vtype:[string]::
    Check input 'INPUT'.
+
Depending on the param:type parameter, this is a simple string, a file
path, or a directory path.

param:type=(`string` | `file` | `directory`) vtype:[string]::
    Input type, one of:
+
--
`string`::
    param:input parameter is a simple string.

`file`::
    param:input parameter is a file path.

`directory`::
    param:input parameter is a directory path.
+
It is expected that the query method does not recurse into this
directory: the result object indicates whether or not the component
class supports this specific directory (param:input).
--


== RESULT OBJECT

The result object can be one of:

* [[simple-real]]A simple real value which is the weight, between 0 and
  1, of the support by the component class for the given input.
+
A weight of 0 means the input is unsupported while a weight of 1 means
it's fully supported. Any value in between shows how confident the
component class is about the support of the given input.

* A map with a weight and an optional group name.

When it's a map, the expected entries are:

qres:group='GROUP-NAME' vtype:[optional string]::
    Put the given input into a group named 'GROUP-NAME' for this
    component class.
+
If this entry is missing, then the given input gets its own, unique
group.

qres:weight='WEIGHT' vtype:[real]::
    Weight, between 0 and 1, of the support by the component class for
    the given input.
+
The semantics are the same as when the result object is a
<<simple-real,simple real value>>.


== EXAMPLES

=== Query parameters

.String input.
====
[source,yaml]
----
input: net://relayd177/host/node23/active
type: string
----
====

.File path input.
====
[source,yaml]
----
input: /home/user/traces/2019-08-26/quad.tr
type: file
----
====

=== Result object

.Simple weight (unique group).
====
[source,yaml]
----
0.5
----
====

.Weight and specific group.
====
[source,yaml]
----
group: 63a4b7e5-37f0-4254-a048-a0cff9e5b761
weight: 0.75
----
====

.Weight within a map (unique group).
====
[source,yaml]
----
weight: 0.6
----
====


include::common-footer.txt[]


== SEE ALSO

man:babeltrace2-intro(7),
man:babeltrace2-query(1),
man:babeltrace2-convert(1)
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)