Add the wbenv JavaScript module (cyberbotics#6793)

* Add the wbenv JavaScript module

Add the `wbenv` JavaScript module as a wrapper around C++ functions.
Only implements `wbenv.getFromEnv` as of now.

Signed-off-by: Gaël Écorchard <gael@km-robotics.cz>

* Update the changelog

Signed-off-by: Gaël Écorchard <gael@km-robotics.cz>

* Satisfy clang-format

Signed-off-by: Gaël Écorchard <gael@km-robotics.cz>

* Update docs/reference/javascript-procedural-proto.md

Co-authored-by: CoolSpy3 <55305038+CoolSpy3@users.noreply.github.com>

* Update docs/reference/javascript-procedural-proto.md

Co-authored-by: CoolSpy3 <55305038+CoolSpy3@users.noreply.github.com>

* Update docs/reference/changelog-r2025.md

Co-authored-by: CoolSpy3 <55305038+CoolSpy3@users.noreply.github.com>

---------

Signed-off-by: Gaël Écorchard <gael@km-robotics.cz>
Co-authored-by: Gaël Écorchard <gael@km-robotics.cz>
Co-authored-by: Olivier Michel <Olivier.Michel@cyberbotics.com>
Co-authored-by: CoolSpy3 <55305038+CoolSpy3@users.noreply.github.com>

Author: 4 people

docs/reference/changelog-r2025.md

@@ -1,5 +1,10 @@
 # Webots R2025 Change Log
 
+## Webots R2025b
+Released on ??.
+  - New Features
+    - Added the `wbenv` Javascript module for procedural protos to get environment variables ([#6793](https://github.com/cyberbotics/webots/pull/6793)).
+
 ## Webots R2025a
 Released on January 31st, 2025.
   - New Features

docs/reference/javascript-procedural-proto.md

@@ -70,12 +70,12 @@ Sphere {
 
 %end
 
-- Although not mandatory, the usage of semi-colons for JavaScript statements is highly encouraged.
+- Although not mandatory, the usage of semicolons for JavaScript statements is highly encouraged.
 Which tokens will be considered depends on whether the comment line `# template language: javascript` is present.
-- The `wbfile` module for file manipulation does not need to, and should not, be imported as it is added automatically to each instance of the engine.
-- Performance degradation has been observed when the number of evaluations requested (i.e expressions of the form `%<= ... >%`) is large, generally in the tens of thousands.
+- The modules `wbfile` for file manipulation and `wbenv` for environment variables do not need to, and should not, be imported as they are added automatically to each instance of the engine.
+- Performance degradation has been observed when the number of evaluations requested (i.e. expressions of the form `%<= ... >%`) is large, generally in the tens of thousands.
 This is typically the case when expressions of this form are used to define the coordinates or indexes of, for instance, a [IndexedFaceSet](indexedfaceset.md).
-To greatly speed-up the generation of this sort of PROTO file, it is highly suggested to use a string buffer to which the coordinates are progressively appended and to only evaluate this buffer once at the end, as shown in the following snippet.
+To greatly speed up the generation of this sort of PROTO file, it is highly suggested to use a string buffer to which the coordinates are progressively appended and to only evaluate this buffer once at the end, as shown in the following snippet.
 
 %tab-component "generic"
 
@@ -183,12 +183,14 @@ The available modules are the following:
 
 - `wbutility`: provides commonly needed functions.
 
-Additionally, the following module is automatically loaded to the engine and therefore does not need to be imported:
+Additionally, the following modules are automatically loaded to the engine and therefore do not need to be imported:
 
 - `wbfile`: provides functions for the reading and writing of files.
 
-> **Note:**: contrary to the other JavaScript modules, `wbfile` is a C++ wrapped class and therefore cannot and should not be imported manually, attempting to do so will return an error.
-The functions exported by this module are available globally.
+- `wbenv`: provides functions to get environment variables.
+
+> **Note:**: contrary to the other JavaScript modules, `wbfile` and `wbenv` are C++-wrapped classes and therefore cannot and should not be imported manually, attempting to do so will return an error.
+The functions exported by these modules are available globally.
 
 The functions exported by each module are:
 
@@ -821,6 +823,20 @@ The location of this path can be retrieved from the `context` field object, see
 
 %tab-end
 
+%tab "wbenv"
+
+```javascript
+/**
+ * @param {String} variableName;
+ * @returns {String}
+ */
+wbenv.getFromEnv(variableName);
+```
+
+Returns the value of the environment variable `variableName` or an empty string if it does not exist.
+
+%tab-end
+
 %end
 
 ### PROTO Regeneration

src/webots/Makefile

@@ -380,6 +380,7 @@ QT_SOURCES = WbAboutBox.cpp \
   WbProtoModel.cpp \
   WbProtoTemplateEngine.cpp \
   WbProtoTreeItem.cpp \
+  WbQjsEnv.cpp \
   WbQjsFile.cpp \
   WbRadar.cpp \
   WbRadio.cpp \

src/webots/core/WbQjsEnv.cpp

@@ -0,0 +1,21 @@
+// Copyright 1996-2025 Cyberbotics Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "WbQjsEnv.hpp"
+
+#include <cstdlib>  // For std::getenv.
+
+QString WbQjsEnv::getFromEnv(const QString &name) const {
+  return std::getenv(name.toStdString().c_str());
+}

src/webots/core/WbQjsEnv.hpp

@@ -0,0 +1,30 @@
+// Copyright 1996-2025 Cyberbotics Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef WB_QJS_ENV_HPP
+#define WB_QJS_ENV_HPP
+
+#include <QtCore/QObject>
+
+class WbQjsEnv : public QObject {
+  Q_OBJECT
+
+public:
+  Q_INVOKABLE WbQjsEnv(){};
+  ~WbQjsEnv(){};
+
+  Q_INVOKABLE QString getFromEnv(const QString &name) const;
+};
+
+#endif

src/webots/core/WbTemplateEngine.cpp

@@ -16,6 +16,7 @@
 
 #include "WbLog.hpp"
 #include "WbProject.hpp"
+#include "WbQjsEnv.hpp"
 #include "WbQjsFile.hpp"
 #include "WbStandardPaths.hpp"
 
@@ -209,6 +210,10 @@ bool WbTemplateEngine::generateJavascript(QHash<QString, QString> tags, const QS
   WbQjsFile *jsFileObject = new WbQjsFile();
   QJSValue jsFile = engine.newQObject(jsFileObject);
   engine.globalObject().setProperty("wbfile", jsFile);
+  // create and add environment module
+  WbQjsEnv *jsEnvObject = new WbQjsEnv();
+  QJSValue jsEnv = engine.newQObject(jsEnvObject);
+  engine.globalObject().setProperty("wbenv", jsEnv);
   // add stream holders
   QJSValue jsStdOut = engine.newArray();
   engine.globalObject().setProperty("stdout", jsStdOut);