Add file-content launch substitution (#708)

This substitution implements a portable mechanism to read the contents
of a file on disk. This procedure is used in various scenarios
throughout ROS 2, and currently relies on `exec` and `command`
substitutions to read files.

Signed-off-by: Scott K Logan <[email protected]>

Author: cottsay

launch/launch/substitutions/__init__.py

@@ -23,6 +23,7 @@
 from .command import Command
 from .environment_variable import EnvironmentVariable
 from .equals_substitution import EqualsSubstitution
+from .file_content import FileContent
 from .find_executable import FindExecutable
 from .launch_configuration import LaunchConfiguration
 from .launch_log_dir import LaunchLogDir
@@ -43,6 +44,7 @@
     'Command',
     'EqualsSubstitution',
     'EnvironmentVariable',
+    'FileContent',
     'FindExecutable',
     'LaunchConfiguration',
     'LaunchLogDir',

launch/launch/substitutions/file_content.py

@@ -0,0 +1,69 @@
+# Copyright 2023 Open Source Robotics Foundation, Inc.
+#
+# 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
+#
+#     http://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.
+
+"""Module for the FileContent substitution."""
+
+from typing import List
+from typing import Sequence
+from typing import Text
+
+from .substitution_failure import SubstitutionFailure
+from ..frontend import expose_substitution
+from ..launch_context import LaunchContext
+from ..some_substitutions_type import SomeSubstitutionsType
+from ..substitution import Substitution
+
+
+@expose_substitution('file-content')
+class FileContent(Substitution):
+    """
+    Substitution that reads the contents of a file.
+
+    If the file is not found a `SubstitutionFailure` error is raised.
+    """
+
+    def __init__(self, path: SomeSubstitutionsType) -> None:
+        """Create a FileContent substitution."""
+        super().__init__()
+
+        from ..utilities import normalize_to_list_of_substitutions
+        self.__path = normalize_to_list_of_substitutions(path)
+
+    @classmethod
+    def parse(cls, data: Sequence[SomeSubstitutionsType]):
+        """Parse `FileContent` substitution."""
+        if not data or len(data) != 1:
+            raise AttributeError('file content substitutions expect 1 argument')
+        kwargs = {'path': data[0]}
+        return cls, kwargs
+
+    @property
+    def path(self) -> List[Substitution]:
+        """Getter for path."""
+        return self.__path
+
+    def describe(self) -> Text:
+        """Return a description of this substitution as a string."""
+        return 'FileContent({})'.format(
+            ', '.join([sub.describe() for sub in self.path]))
+
+    def perform(self, context: LaunchContext) -> Text:
+        """Perform the substitution by evaluating the expression."""
+        from ..utilities import perform_substitutions
+        path = perform_substitutions(context, self.path)
+        try:
+            with open(path, 'r') as f:
+                return f.read()
+        except FileNotFoundError:
+            raise SubstitutionFailure('File not found: {}'.format(path))

launch/test/launch/substitutions/test_file_content.py

@@ -0,0 +1,52 @@
+# Copyright 2023 Open Source Robotics Foundation, Inc.
+#
+# 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
+#
+#     http://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.
+
+"""Tests the FileContent substitution."""
+
+import pathlib
+
+from launch.launch_context import LaunchContext
+from launch.substitutions import FileContent
+from launch.substitutions.substitution_failure import SubstitutionFailure
+
+import pytest
+
+
+@pytest.fixture(scope='module')
+def files():
+    this_dir = pathlib.Path(__file__).parent
+
+    files = {
+        'foo': str(this_dir / 'test_file_content' / 'foo.txt'),
+        'bar': str(this_dir / 'test_file_content' / 'bar.txt'),
+    }
+
+    return files
+
+
+def test_file_content(files):
+    """Test a simple file."""
+    context = LaunchContext()
+    file_content = FileContent(files['foo'])
+    output = file_content.perform(context)
+    assert output == 'Foo\n'
+
+
+def test_missing_command_raises(files):
+    """Test that a file that doesn't exist raises."""
+    context = LaunchContext()
+    file_content = FileContent(files['bar'])
+    with pytest.raises(SubstitutionFailure) as ex:
+        file_content.perform(context)
+    ex.match('File not found: .*')

launch/test/launch/substitutions/test_file_content/foo.txt

@@ -0,0 +1 @@
+Foo