Mercurial > hgrepos > Python > libs > ConfigMix

comparison docs/introduction.rst @ 333:5ec0ae3bb8db

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Docs: quoting
author Franz Glasner <fzglas.hg@dom66.de>
date Fri, 07 May 2021 09:31:22 +0200
parents cffa4fcd0a4d
children ebd662a8376e
comparison
equal deleted inserted replaced
332:5c2c72d26b63 333:5ec0ae3bb8db
248 and :py:meth:`.Configuration.getvar_s` are of the form 248 and :py:meth:`.Configuration.getvar_s` are of the form
249 ``[namespace:]variable`` where for :py:meth:`.Configuration.getvarl` 249 ``[namespace:]variable`` where for :py:meth:`.Configuration.getvarl`
250 and :py:meth:`.Configuration.getvarl_s` the namespace is given as 250 and :py:meth:`.Configuration.getvarl_s` the namespace is given as
251 optional keyword parameter `namespace`. 251 optional keyword parameter `namespace`.
252 252
253 .. note:: Special characters within namespace, key and filter names
254 *must* be quoted (see :ref:`quoting`) when using
255 :py:meth:`~.Configuration.getvar` or
256 :py:meth:`~.Configuration.getvar_s` to retrieve variables.
257
258 With :py:meth:`~.Configuration.getvarl` or
259 :py:meth:`~.Configuration.getvarl_s` quoting is neither needed
260 and not supported.
253 261
254 .. _merging-deletions: 262 .. _merging-deletions:
255 263
256 Deletions 264 Deletions
257 --------- 265 ---------
281 Currently there are 6 namespaces: 289 Currently there are 6 namespaces:
282 290
283 1. The unnamed namespace (which is also default). 291 1. The unnamed namespace (which is also default).
284 292
285 All the configuration variables are part of this namespace. 293 All the configuration variables are part of this namespace.
294
295 .. seealso:: :ref:`quoting`
286 296
287 2. The namespace ``ref`` to be used for configuration references. 297 2. The namespace ``ref`` to be used for configuration references.
288 298
289 This is a namespace that is handled special within "ConfigMix". 299 This is a namespace that is handled special within "ConfigMix".
290 300
375 :py:meth:`.Configuration.getvar_s`, 385 :py:meth:`.Configuration.getvar_s`,
376 :py:meth:`.Configuration.getvarl_s`, 386 :py:meth:`.Configuration.getvarl_s`,
377 :py:meth:`.Configuration.substitute_variables_in_obj` or 387 :py:meth:`.Configuration.substitute_variables_in_obj` or
378 :py:meth:`.Configuration.expand_variable` 388 :py:meth:`.Configuration.expand_variable`
379 389
390 .. note:: Special characters within namespace, key and filter names
391 *must* be quoted (see :ref:`quoting`) when using variable
392 interpolation syntax.
393
380 394
381 Filter functions 395 Filter functions
382 ~~~~~~~~~~~~~~~~ 396 ~~~~~~~~~~~~~~~~
383 397
384 Interpolated values can be processed through a series of filter functions:: 398 Interpolated values can be processed through a series of filter functions::
437 451
438 With ``{{ref:my.other.key}}`` 452 With ``{{ref:my.other.key}}``
439 453
440 - special namespace ``ref`` 454 - special namespace ``ref``
441 - No special handling when merging is done 455 - No special handling when merging is done
442 - Keys within `.getvar_s()` and `.getvar()` are handled 456 - Keys within :meth:`.Configuration.getvar_s()` and
443 - in `.getvar()` only, when it is the directly referenced value 457 :py:meth:`.Configuration.getvar()` are handled
444 - recursive expandion in `.getvar_s()` expands 458 - in :py:meth:`.Configuration.getvar()` only, when it is the directly
459 referenced value
460 - recursive expandion in :py:meth:`.Configuration.getvar_s()` expands
461
462
463 .. _quoting:
464
465 Quoting
466 -------
467
468 When using :py:meth:`.Configuration.getvar` and
469 :py:meth:`.Configuration.getvar_s` and when retrieving values in the
470 default namespace the namespace separator ``:`` or the hierarchy
471 separator ``.`` are characters with a special meaning. When using
472 :ref:`variable interpolation <variable-interpolation>` the filter
473 separator ``|`` is also special. To use then in key names they must be
474 quoted.
475
476 Quoting is done with a variant of the well-known percent-encoding in
477 URIs (:rfc:`3986`).
478
479 A percent-encoded character consists of the percent character ``%``,
480 followed by one of the characters ``x``, ``u`` or ``U``, followed by
481 the two, four or eight hexadecimal digits of the unicode codepoint
482 value of the character that is to be quoted. ``x`` must be followed by
483 two hex digits, ``u`` by four and ``U`` by eight.
484
485 Example:
486
487 The character ``.`` with the Unicode (and ASCII) value 46 (hex 0x2e)
488 can be encoded as ``%x2e`` or ``%u002e`` or ``%U0000002e``.
489
490 .. note:: Filters neeed no quoting -- and quoting within filters is *not*
491 supported.
445 492
446 493
447 Custom filename extensions and custom loaders 494 Custom filename extensions and custom loaders
448 --------------------------------------------- 495 ---------------------------------------------
449 496