Mercurial > hgrepos > Python > libs > ConfigMix

comparison docs/introduction.rst @ 315:21fa4b4bfdaa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Docu: .getvarl() and .getvarl_s()
author Franz Glasner <fzglas.hg@dom66.de>
date Wed, 05 May 2021 01:41:01 +0200
parents dc4280451e0c
children fe2e28e5fd08
comparison
equal deleted inserted replaced
314:043a6412be3c 315:21fa4b4bfdaa
199 .. _getting-values: 199 .. _getting-values:
200 200
201 Getting configuration variables 201 Getting configuration variables
202 ------------------------------- 202 -------------------------------
203 203
204 Get a -- possibly interpolated -- configuration variable's value with:: 204 Get a -- possibly interpolated -- configuration variable's value with ::
205 205
206 value1 = config.getvar_s("key1") 206 value1 = config.getvar_s("key1")
207 207 value2 = config.getvar_s("key1.subkey2")
208 Get a raw configuration variable's value with:: 208
209 or equivalently with ::
210
211 value1 = config.getvarl_s("key1")
212 value2 = config.getvarl_s("key1", "subkey2")
213
214 Get a raw configuration variable's value with ::
209 215
210 value1_raw = config.getvar("key1") 216 value1_raw = config.getvar("key1")
217 value2_raw = config.getvarl("key1.subkey2")
218
219 or equivalently with ::
220
221 value1_raw = config.getvarl("key1")
222 value2_raw = config.getvarl("key1", "subkey2")
211 223
212 Because the configuration is not only a plain list of but a tree of 224 Because the configuration is not only a plain list of but a tree of
213 key-value pairs you will want to fetch them by separating the individual 225 key-value pairs you will want to fetch a nested configuration value
214 level keys with a point ``.``. 226 using two access methods:
227
228 :py:meth:`.Configuration.getvar` and :py:meth:`.Configuration.getvar_s`
229
230 Use a single key variable where the invidual level keys are joined
231 using a dot (``.``)
232
233 :py:meth:`.Configuration.getvarl` and :py:meth:`.Configuration.getvarl_s`
234
235 Use just positional Python arguments for each level key
215 236
216 Looking at the example in chapter :ref:`yaml-files` -- when calling 237 Looking at the example in chapter :ref:`yaml-files` -- when calling
217 ``config.getvar_s("tree1.tree2.key4")`` you will get the value 238 ``config.getvar_s("tree1.tree2.key4")`` you will get the value
218 ``get this as `tree1.tree2.key4'``. 239 ``get this as `tree1.tree2.key4'``.
219 240
220 This is true for both methods :py:meth:`.Configuration.getvar` and 241 Alternatively ``config.getvarl_s("tree1", "tree2", "key4")`` can be called
221 :py:meth:`.Configuration.getvar_s`. 242 with the very same result.
222 243
223 Both methods also perform direct :ref:`variable-interpolation` and handle 244 All four methods also perform direct :ref:`variable-interpolation` and
224 :ref:`variable-namespaces`. Filtering is not supported. So -- the 245 handle :ref:`variable-namespaces` -- yet in different ways.
225 variable name arguments of :py:meth:`.Configuration.getvar` and 246 Filtering is not supported.
226 :py:meth:`.Configuration.getvar_s` are of the form 247 So -- the variable name arguments of :py:meth:`.Configuration.getvar`
227 ``[namespace:]variable``. 248 and :py:meth:`.Configuration.getvar_s` are of the form
249 ``[namespace:]variable`` where for :py:meth:`.Configuration.getvarl`
250 and :py:meth:`.Configuration.getvarl_s` the namespace is given as
251 optional keyword parameter `namespace`.
228 252
229 253
230 .. _merging-deletions: 254 .. _merging-deletions:
231 255
232 Deletions 256 Deletions
312 336
313 337
314 Examples 338 Examples
315 ~~~~~~~~ 339 ~~~~~~~~
316 340
317 :: 341 Both ::
318 342
319 config.getvar("OS:cwd") 343 config.getvar("OS:cwd")
320 344
321 yields the current working directory as :py:func:`os.getcwd` does. 345 or ::
346
347 config.getvarl("cwd", namespace="OS")
348
349 yield the current working directory -- just as :py:func:`os.getcwd` does.
322 350
323 351
324 .. _variable-interpolation: 352 .. _variable-interpolation:
325 353
326 Variable Interpolation 354 Variable Interpolation
327 ---------------------- 355 ----------------------
328 356
329 Configuration variable values that are read with 357 Configuration variable values that are read with
330 :py:meth:`.Configuration.getvar_s` are subject to variable 358 :py:meth:`.Configuration.getvar_s` or :py:meth:`.Configuration.getvarl_s`
331 interpolation. The general syntactic pattern for this is:: 359 are subject to variable interpolation.
360 The general syntactic pattern for this is::
332 361
333 {{[namespace:]variable[|filter[|filter...]]}} 362 {{[namespace:]variable[|filter[|filter...]]}}
334 363
335 I.e.: between double curly braces an optional `namespace` name followed by 364 I.e.: between double curly braces an optional `namespace` name followed by
336 a colon ``:``, the `variable` and then zero or more filters, each one 365 a colon ``:``, the `variable` and then zero or more filters, each one
337 introduced by a pipe symbol ``|``. 366 introduced by a pipe symbol ``|``.
338 367
339 Variables are expanded *lately* at runtime -- exactly when calling 368 Variables are expanded *lately* at runtime -- exactly when calling
340 :py:meth:`.Configuration.getvar_s`, 369 :py:meth:`.Configuration.getvar_s`,
370 :py:meth:`.Configuration.getvarl_s`,
341 :py:meth:`.Configuration.substitute_variables_in_obj` or 371 :py:meth:`.Configuration.substitute_variables_in_obj` or
342 :py:meth:`.Configuration.expand_variable` 372 :py:meth:`.Configuration.expand_variable`
343 373
344 374
345 Filter functions 375 Filter functions