From c29cd6e26ea4760e7a39313cc8f70c440a2043c8 Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Wed, 20 Sep 2023 08:27:12 +0200 Subject: [PATCH] Add documentation for environment variables expansion on XML (#556) * Refs #19583. Add documentation for environment variables expansion on XML. Signed-off-by: Miguel Company * Refs #19583. Document environment variable name restrictions. Signed-off-by: Miguel Company * Refs #19583. Document environment variable mixing with text. Signed-off-by: Miguel Company --------- Signed-off-by: Miguel Company --- code/XMLTesterSkipValidation.xml | 22 +++++++++++++ .../xml_configuration/making_xml_profiles.rst | 33 +++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/code/XMLTesterSkipValidation.xml b/code/XMLTesterSkipValidation.xml index 8d8f9c278..11d9edc6d 100644 --- a/code/XMLTesterSkipValidation.xml +++ b/code/XMLTesterSkipValidation.xml @@ -78,3 +78,25 @@ + +XML_PROFILE_ENVIRONMENT_VARIABLES<--> + + + + + + This is app '${MY_APP_NAME}' running on host '${MY_HOST_NAME}' + + + + +
${REMOTE_IP_ADDRESS}
+ + + + + + + + +<--> diff --git a/docs/fastdds/xml_configuration/making_xml_profiles.rst b/docs/fastdds/xml_configuration/making_xml_profiles.rst index 4d8ed1e3f..a88269b8a 100644 --- a/docs/fastdds/xml_configuration/making_xml_profiles.rst +++ b/docs/fastdds/xml_configuration/making_xml_profiles.rst @@ -125,3 +125,36 @@ XML profile. This allows the user to read and modify predefined XML profiles bef :start-after: //XML-MIX-WITH-CODE :end-before: //!-- :dedent: 8 + +Dynamic content by leveraging environment variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For deployment scenarios that require part of the XML content to be dynamically generated, Fast DDS supports using +environment variables on the text content of any XML tag. +The format for environment variables expansion is ``${ENV_VAR_NAME}``, where ``ENV_VAR_NAME`` follows the restrictions +from `IEEE 1003.1 `_: + +.. note:: + + Environment variable names ... consist solely of uppercase letters, digits, and the '_' (underscore) from the + characters defined in Portable Character Set and do not begin with a digit. + +More than one environment variable can be used, and they can be mixed with literal text. + +The expansion will take place when the XML file is loaded, so changing the value of an environment variable afterwards +will have no effect. + +The following is an example of an XML allowing a participant to exclusively communicate with the participants on a +fixed IP address, taken from ``REMOTE_IP_ADDRESS`` environment variable. +It also gives the participant a name that mixes literal text with the content from two environment variables. + +.. literalinclude:: /../code/XMLTesterSkipValidation.xml + :language: xml + :start-after: XML_PROFILE_ENVIRONMENT_VARIABLES<--> + :end-before: <--> + +.. warning:: + + The `Fast DDS XSD schema `_ + does not support the environment variables expansion feature, so validation of an XML file with environment + variables expansion expressions will fail.