Add frontend module in launch, launch_xml and launch_yaml packages

launch/launch/__init__.py

@@ -17,7 +17,9 @@
 from . import actions
 from . import conditions
 from . import events
+from . import frontend
 from . import logging
+from . import substitutions
 from .action import Action
 from .condition import Condition
 from .event import Event
@@ -38,7 +40,9 @@
     'actions',
     'conditions',
     'events',
+    'frontend',
     'logging',
+    'substitutions',
     'Action',
     'Condition',
     'Event',

launch/launch/action.py

@@ -23,6 +23,10 @@
 from .launch_context import LaunchContext
 from .launch_description_entity import LaunchDescriptionEntity
 
+if False:
+    from .frontend import Entity
+    from .frontend import Parser
+
 
 class Action(LaunchDescriptionEntity):
     """
@@ -44,6 +48,32 @@ def __init__(self, *, condition: Optional[Condition] = None) -> None:
         """
         self.__condition = condition
 
+    @staticmethod
+    def parse(entity: 'Entity', parser: 'Parser'):
+        """
+        Return the `Action` action and kwargs for constructing it.
+
+        This is only intended for code reuse.
+        This class is not exposed with `expose_action`.
+        """
+        # Import here for avoiding cyclic imports.
+        from .conditions import IfCondition
+        from .conditions import UnlessCondition
+        if_cond = entity.get_attr('if', optional=True)
+        unless_cond = entity.get_attr('unless', optional=True)
+        kwargs = {}
+        if if_cond is not None and unless_cond is not None:
+            raise RuntimeError("if and unless conditions can't be used simultaneously")
+        if if_cond is not None:
+            kwargs['condition'] = IfCondition(
+                predicate_expression=parser.parse_substitution(if_cond)
+            )
+        if unless_cond is not None:
+            kwargs['condition'] = UnlessCondition(
+                predicate_expression=parser.parse_substitution(unless_cond)
+            )
+        return Action, kwargs
+
     @property
     def condition(self) -> Optional[Condition]:
         """Getter for condition."""

launch/launch/actions/execute_process.py

@@ -58,13 +58,17 @@
 from ..events.process import ProcessStdout
 from ..events.process import ShutdownProcess
 from ..events.process import SignalProcess
+from ..frontend import Entity
+from ..frontend import expose_action
+from ..frontend import Parser
 from ..launch_context import LaunchContext
 from ..launch_description import LaunchDescription
 from ..some_actions_type import SomeActionsType
 from ..some_substitutions_type import SomeSubstitutionsType
 from ..substitution import Substitution  # noqa: F401
 from ..substitutions import LaunchConfiguration
 from ..substitutions import PythonExpression
+from ..substitutions import TextSubstitution
 from ..utilities import create_future
 from ..utilities import is_a_subclass
 from ..utilities import normalize_to_list_of_substitutions
@@ -74,6 +78,7 @@
 _global_process_counter = 0  # in Python3, this number is unbounded (no rollover)
 
 
+@expose_action('executable')
 class ExecuteProcess(Action):
     """Action that begins executing a process and sets up event handlers for the process."""
 
@@ -225,6 +230,65 @@ def __init__(
         self.__stdout_buffer = io.StringIO()
         self.__stderr_buffer = io.StringIO()
 
+    @classmethod
+    def parse(
+        cls,
+        entity: Entity,
+        parser: Parser,
+        cmd_arg_name: str = 'cmd'
+    ):
+        """
+        Return the `ExecuteProcess` action and kwargs for constructing it.
+
+        :param: cmd_arg_name Allow changing the name of `cmd` tag.
+            Intended for code reuse in derived classes (e.g.: launch_ros.actions.Node).
+        """
+        _, kwargs = super().parse(entity, parser)
+
+        cmd = entity.get_attr(cmd_arg_name)
+        # `cmd` is supposed to be a list separated with ' '.
+        # All the found `TextSubstitution` items are split and
+        # added to the list again as a `TextSubstitution`.
+        cmd = parser.parse_substitution(cmd)
+        cmd_list = []
+        for arg in cmd:
+            if isinstance(arg, TextSubstitution):
+                text = arg.text
+                text = shlex.split(text)
+                text = [TextSubstitution(text=item) for item in text]
+                cmd_list.extend(text)
+            else:
+                cmd_list.append(arg)
+        kwargs[cmd_arg_name] = cmd_list
+
+        cwd = entity.get_attr('cwd', optional=True)
+        if cwd is not None:
+            kwargs['cwd'] = parser.parse_substitution(cwd)
+        name = entity.get_attr('name', optional=True)
+        if name is not None:
+            kwargs['name'] = parser.parse_substitution(name)
+        prefix = entity.get_attr('launch-prefix', optional=True)
+        if prefix is not None:
+            kwargs['prefix'] = parser.parse_substitution(prefix)
+        output = entity.get_attr('output', optional=True)
+        if output is not None:
+            kwargs['output'] = parser.escape_characters(output)
+        shell = entity.get_attr('shell', data_type=bool, optional=True)
+        if shell is not None:
+            kwargs['shell'] = shell
+        # Conditions won't be allowed in the `env` tag.
+        # If that feature is needed, `set_enviroment_variable` and
+        # `unset_enviroment_variable` actions should be used.
+        env = entity.get_attr('env', data_type=List[Entity], optional=True)
+        if env is not None:
+            env = {
+                tuple(parser.parse_substitution(e.get_attr('name'))):
+                parser.parse_substitution(e.get_attr('value')) for e in env
+            }
+            kwargs['additional_env'] = env
+
+        return cls, kwargs
+
     @property
     def output(self):
         """Getter for output."""
@@ -637,3 +701,8 @@ def additional_env(self):
     def shell(self):
         """Getter for shell."""
         return self.__shell
+
+    @property
+    def prefix(self):
+        """Getter for prefix."""
+        return self.__prefix

launch/launch/actions/group_action.py

@@ -23,10 +23,14 @@
 from .push_launch_configurations import PushLaunchConfigurations
 from .set_launch_configuration import SetLaunchConfiguration
 from ..action import Action
+from ..frontend import Entity
+from ..frontend import expose_action
+from ..frontend import Parser
 from ..launch_context import LaunchContext
 from ..some_substitutions_type import SomeSubstitutionsType
 
 
+@expose_action('group')
 class GroupAction(Action):
     """
     Action that yields other actions, optionally scoping launch configurations.
@@ -54,6 +58,16 @@ def __init__(
         else:
             self.__launch_configurations = {}
 
+    @classmethod
+    def parse(cls, entity: Entity, parser: Parser):
+        """Return `GroupAction` action and kwargs for constructing it."""
+        _, kwargs = super().parse(entity, parser)
+        scoped = entity.get_attr('scoped', data_type=bool, optional=True)
+        if scoped is not None:
+            kwargs['scoped'] = scoped
+        kwargs['actions'] = [parser.parse_action(e) for e in entity.children]
+        return cls, kwargs
+
     def execute(self, context: LaunchContext) -> Optional[List[Action]]:
         """Execute the action."""
         actions = []  # type: List[Action]

launch/launch/actions/include_launch_description.py

@@ -22,14 +22,19 @@
 
 from .set_launch_configuration import SetLaunchConfiguration
 from ..action import Action
+from ..frontend import Entity
+from ..frontend import expose_action
+from ..frontend import Parser
 from ..launch_context import LaunchContext
 from ..launch_description_entity import LaunchDescriptionEntity
 from ..launch_description_source import LaunchDescriptionSource
+from ..launch_description_sources import AnyLaunchDescriptionSource
 from ..some_substitutions_type import SomeSubstitutionsType
 from ..utilities import normalize_to_list_of_substitutions
 from ..utilities import perform_substitutions
 
 
+@expose_action('include')
 class IncludeLaunchDescription(Action):
     """
     Action that includes a launch description source and yields its entities when visited.
@@ -69,6 +74,23 @@ def __init__(
         self.__launch_description_source = launch_description_source
         self.__launch_arguments = launch_arguments
 
+    @classmethod
+    def parse(cls, entity: Entity, parser: Parser):
+        """Return `IncludeLaunchDescription` action and kwargs for constructing it."""
+        _, kwargs = super().parse(entity, parser)
+        file_path = parser.parse_substitution(entity.get_attr('file'))
+        kwargs['launch_description_source'] = AnyLaunchDescriptionSource(file_path)
+        args = entity.get_attr('arg', data_type=List[Entity], optional=True)
+        if args is not None:
+            kwargs['launch_arguments'] = [
+                (
+                    parser.parse_substitution(e.get_attr('name')),
+                    parser.parse_substitution(e.get_attr('value'))
+                )
+                for e in args
+            ]
+        return cls, kwargs
+
     @property
     def launch_description_source(self) -> LaunchDescriptionSource:
         """Getter for self.__launch_description_source."""

launch/launch/actions/set_launch_configuration.py

@@ -17,13 +17,17 @@
 from typing import List
 
 from ..action import Action
+from ..frontend import Entity
+from ..frontend import expose_action
+from ..frontend import Parser
 from ..launch_context import LaunchContext
 from ..some_substitutions_type import SomeSubstitutionsType
 from ..substitution import Substitution
 from ..utilities import normalize_to_list_of_substitutions
 from ..utilities import perform_substitutions
 
 
+@expose_action('let')
 class SetLaunchConfiguration(Action):
     """
     Action that sets a launch configuration by name.
@@ -44,6 +48,16 @@ def __init__(
         self.__name = normalize_to_list_of_substitutions(name)
         self.__value = normalize_to_list_of_substitutions(value)
 
+    @classmethod
+    def parse(cls, entity: Entity, parser: Parser):
+        """Return `SetLaunchConfiguration` action and kwargs for constructing it."""
+        name = parser.parse_substitution(entity.get_attr('name'))
+        value = parser.parse_substitution(entity.get_attr('value'))
+        _, kwargs = super().parse(entity, parser)
+        kwargs['name'] = name
+        kwargs['value'] = value
+        return cls, kwargs
+
     @property
     def name(self) -> List[Substitution]:
         """Getter for self.__name."""

launch/launch/frontend/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2019 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.
+
+"""Package for launch markup."""
+
+from . import type_utils
+from .entity import Entity
+from .expose import expose_action, expose_substitution
+from .parser import Parser
+
+
+__all__ = [
+    'Entity',
+    'Parser',
+    'expose_action',
+    'expose_substitution',
+    'type_utils',
+]

launch/launch/frontend/entity.py

@@ -0,0 +1,88 @@
+# Copyright 2019 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 Entity class."""
+
+from typing import Any
+from typing import List
+from typing import Optional
+from typing import Text
+from typing import Union
+
+
+class Entity:
+    """Single item in the intermediate front_end representation."""
+
+    @property
+    def type_name(self) -> Text:
+        """Get Entity type."""
+        raise NotImplementedError()
+
+    @property
+    def parent(self) -> Optional['Entity']:
+        """Get Entity parent."""
+        raise NotImplementedError()
+
+    @property
+    def children(self) -> List['Entity']:
+        """Get the Entity's children."""
+        raise NotImplementedError()
+
+    def get_attr(
+        self,
+        name: Text,
+        *,
+        data_type: Any = str,
+        optional: bool = False
+    ) -> Optional[Union[
+        List[Union[int, str, float, bool]],
+        Union[int, str, float, bool],
+        List['Entity']
+    ]]:
+        """
+        Access an attribute of the entity.
+
+        By default, it will try to return it as an string.
+        `types` states the expected types of the attribute. Type coercion or type checking is
+        applied depending on the particular frontend.
+
+        The allowed types are:
+            - a scalar type i.e. `str`, `int`, `float`, `bool`;
+            - a uniform list i.e `List[str]`, `List[int]`, `List[float]`, `List[bool]`;
+            - a non-uniform list of known scalar types e.g. `List[Union[int, str]]`;
+            - a non-uniform list of any scalar type i.e. `list` or `List`;
+            - a `Union` of any of the above;
+            - `List[Entity]`, see below.
+
+        `types = None` works in the same way as:
+            `Union[int, float, bool, list, str]`
+
+        `List[Entity]` allows accessing a list of subentities with an specific name.
+        Check the documentation of each specific frontend implementation to see how `list`
+        and `List[Entity]` look like.
+
+        If `optional` is `True` and the attribute cannot be found, `None` will be returned
+        instead of raising `AttributeError`.
+
+        :param name: name of the attribute
+        :param types: type of the attribute to be read. Default to 'str'
+        :param optional: when `True`, it doesn't raise an error when the attribute is not found.
+            It returns `None` instead. Defaults to `False`
+        :raises `AttributeError`: Attribute not found. Only possible if `optional` is `False`
+        :raises `TypeError`: Attribute found but it is not of the correct type.
+            Only happens in frontend implementations that do type checking
+        :raises `ValueError`: Attribute found but can't be coerced to one of the types.
+            Only happens in frontend implementations that do type coercion
+        """
+        raise NotImplementedError()