| 1 |
= YAML configuration object |
| 2 |
|
| 3 |
The _**configuration object**_ is the root of a barectf YAML |
| 4 |
configuration document. It describes a complete barectf configuration. |
| 5 |
|
| 6 |
The configuration object must have the YAML tag |
| 7 |
`tag:barectf.org,2020/3/config`. |
| 8 |
|
| 9 |
The configuration object has a mandatory xref:trace-obj.adoc[trace |
| 10 |
object] and <<opts-obj,options>>. |
| 11 |
|
| 12 |
== Properties |
| 13 |
|
| 14 |
[%autowidth.stretch] |
| 15 |
|=== |
| 16 |
|Name |Type |Description |{req-abbr} |Default |
| 17 |
|
| 18 |
|`options` |
| 19 |
|<<opts-obj>> |
| 20 |
|Configuration options. |
| 21 |
|No |
| 22 |
|See <<opts-obj>> for default values. |
| 23 |
|
| 24 |
|[[trace-prop]]`trace` |
| 25 |
|xref:trace-obj.adoc[Trace object] |
| 26 |
|Configuration's trace. |
| 27 |
|Yes |
| 28 |
| |
| 29 |
|=== |
| 30 |
|
| 31 |
[[opts-obj]] |
| 32 |
== Options object |
| 33 |
|
| 34 |
The options of a configuration object. |
| 35 |
|
| 36 |
=== Properties |
| 37 |
|
| 38 |
[%autowidth.stretch] |
| 39 |
|=== |
| 40 |
|Name |Type |Description |Default |
| 41 |
|
| 42 |
|`code-generation` |
| 43 |
|<<code-gen-opts-obj>> |
| 44 |
|Code generation options. |
| 45 |
|See <<code-gen-opts-obj>> for default values. |
| 46 |
|=== |
| 47 |
|
| 48 |
[[code-gen-opts-obj]] |
| 49 |
== Code generation options object |
| 50 |
|
| 51 |
The code generation options of a configuration object. |
| 52 |
|
| 53 |
=== Properties |
| 54 |
|
| 55 |
All the properties are optional. |
| 56 |
|
| 57 |
[%autowidth.stretch, cols="d,d,a,d"] |
| 58 |
|=== |
| 59 |
|Name |Type |Description |Default |
| 60 |
|
| 61 |
|[[prefix-prop]]`prefix` |
| 62 |
|String or <<prefix-obj,prefix object>> |
| 63 |
|Identifier and file name prefixes. |
| 64 |
|
| 65 |
If the value is the string `__PREFIX__`, then the identifier prefix is |
| 66 |
`__PREFIX___` and the file name prefix is `__PREFIX__`. |
| 67 |
|The identifier prefix `barectf_` and the file name prefix `barectf`. |
| 68 |
|
| 69 |
|`header` |
| 70 |
|<<code-gen-header-opts-obj>> |
| 71 |
|C{nbsp}header generation options. |
| 72 |
|See <<code-gen-header-opts-obj>> default values. |
| 73 |
|=== |
| 74 |
|
| 75 |
[[prefix-obj]] |
| 76 |
== Prefix object |
| 77 |
|
| 78 |
Identifier and file name prefixes. |
| 79 |
|
| 80 |
=== Properties |
| 81 |
|
| 82 |
All the properties are required. |
| 83 |
|
| 84 |
[%autowidth.stretch, cols="d,d,a"] |
| 85 |
|=== |
| 86 |
|Name |Type |Description |
| 87 |
|
| 88 |
|`file-name` |
| 89 |
|String |
| 90 |
|Prefix of any C{nbsp}file which barectf generates. |
| 91 |
|
| 92 |
barectf adds `-` between this prefix and other file name parts if |
| 93 |
needed. |
| 94 |
|
| 95 |
This prefix must only contain valid characters for a file name. |
| 96 |
|
| 97 |
|`identifier` |
| 98 |
|String |
| 99 |
|Prefix of any public C identifier which barectf generates. |
| 100 |
|
| 101 |
barectf does _not_ add anything between this prefix and the rest of the |
| 102 |
identifier. |
| 103 |
|
| 104 |
For example, if this prefix is `acme_corp_`, then a tracing function |
| 105 |
name could be `+acme_corp_trace_my_event()+`. |
| 106 |
|
| 107 |
This prefix must be a valid C{nbsp}identifier. |
| 108 |
|=== |
| 109 |
|
| 110 |
[[code-gen-header-opts-obj]] |
| 111 |
== Code generation header options object |
| 112 |
|
| 113 |
The C{nbsp}header generation options of a configuration object. |
| 114 |
|
| 115 |
=== Properties |
| 116 |
|
| 117 |
All the properties are optional. |
| 118 |
|
| 119 |
[%autowidth.stretch, cols="d,d,a,d", role="can-break"] |
| 120 |
|=== |
| 121 |
|Name |Type |Description |Default |
| 122 |
|
| 123 |
|[[iden-prefix-def-prop]]`identifier-prefix-definition` |
| 124 |
|Boolean |
| 125 |
|If this property is true, then barectf generates a public |
| 126 |
C{nbsp}preprocessor definition named `_BARECTF_IDENTIFIER_PREFIX` which |
| 127 |
is set to the configuration's <<prefix-prop,identifier prefix>>. |
| 128 |
|False |
| 129 |
|
| 130 |
|[[def-dst-name-def-prop]]`default-data-stream-type-name-definition` |
| 131 |
|Boolean |
| 132 |
|If this property is true, then barectf generates a public |
| 133 |
C{nbsp}preprocessor definition named |
| 134 |
`_BARECTF_DEFAULT_DATA_STREAM_TYPE_NAME` which is set to the name of the |
| 135 |
trace type's |
| 136 |
xref:dst-obj.adoc#is-def-prop[default data stream type]. |
| 137 |
|False |
| 138 |
|=== |
| 139 |
|
| 140 |
== Examples |
| 141 |
|
| 142 |
NOTE: The following examples omit the <<trace-prop,trace object>> for |
| 143 |
clarity. |
| 144 |
|
| 145 |
.Basic configuration object. |
| 146 |
==== |
| 147 |
[source,yaml] |
| 148 |
---- |
| 149 |
--- !<tag:barectf.org,2020/3/config> |
| 150 |
trace: |
| 151 |
# ... |
| 152 |
---- |
| 153 |
==== |
| 154 |
|
| 155 |
.Configuration object with custom <<prefix-obj,prefixes>>. |
| 156 |
==== |
| 157 |
[source,yaml] |
| 158 |
---- |
| 159 |
--- !<tag:barectf.org,2020/3/config> |
| 160 |
options: |
| 161 |
code-generation: |
| 162 |
prefix: |
| 163 |
file-name: acme-corp |
| 164 |
identifier: acme_corp_ |
| 165 |
trace: |
| 166 |
# ... |
| 167 |
---- |
| 168 |
==== |
| 169 |
|
| 170 |
.Configuration object with <<code-gen-header-opts-obj,identifier and default data stream type name C{nbsp}preprocessor definitions>>. |
| 171 |
==== |
| 172 |
[source,yaml] |
| 173 |
---- |
| 174 |
--- !<tag:barectf.org,2020/3/config> |
| 175 |
options: |
| 176 |
code-generation: |
| 177 |
header: |
| 178 |
identifier-prefix-definition: true |
| 179 |
default-data-stream-type-name-definition: true |
| 180 |
trace: |
| 181 |
# ... |
| 182 |
---- |
| 183 |
==== |
| 184 |
|
| 185 |
.Basic configuration object with a YAML directive. |
| 186 |
==== |
| 187 |
This https://yaml.org/spec/1.2/spec.html#id2781553[YAML directive] |
| 188 |
indicates that the YAML document honours the YAML{nbsp}1.2 |
| 189 |
specification. |
| 190 |
|
| 191 |
[source,yaml] |
| 192 |
---- |
| 193 |
%YAML 1.2 |
| 194 |
--- !<tag:barectf.org,2020/3/config> |
| 195 |
trace: |
| 196 |
# ... |
| 197 |
---- |
| 198 |
==== |