extend Prefix class with join() member to support dynamic directories (#8329)

* extend Prefix class with join() member to support dynamic directories

* add more tests for Prefix.join()

* more tests for Prefix.join()

* add docstring

* add example to docstring of Prefix class

* cleanup Prefix.join() tests

* use Prefix.join() in Packaging Guide

lib/spack/docs/packaging_guide.rst

@@ -2763,11 +2763,11 @@ Prefix Attribute        Location
 
 Of course, this only works if your file or directory is a valid Python
 variable name. If your file or directory contains dashes or dots, use
-``join_path`` instead:
+``join`` instead:
 
 .. code-block:: python
 
-   join_path(prefix.lib, 'libz.a')
+   prefix.lib.join('libz.a')
 
 
 .. _spec-objects:

lib/spack/spack/test/util/prefix.py

@@ -36,6 +36,35 @@ def test_prefix_attributes():
     assert prefix.include == '/usr/include'
 
 
+def test_prefix_join():
+    """Test prefix join  ``prefix.join(...)``"""
+    prefix = Prefix('/usr')
+
+    a1 = prefix.join('a_{0}'.format(1)).lib64
+    a2 = prefix.join('a-{0}'.format(1)).lib64
+    a3 = prefix.join('a.{0}'.format(1)).lib64
+
+    assert a1 == '/usr/a_1/lib64'
+    assert a2 == '/usr/a-1/lib64'
+    assert a3 == '/usr/a.1/lib64'
+
+    assert isinstance(a1, Prefix)
+    assert isinstance(a2, Prefix)
+    assert isinstance(a3, Prefix)
+
+    p1 = prefix.bin.join('executable.sh')
+    p2 = prefix.share.join('pkg-config').join('foo.pc')
+    p3 = prefix.join('dashed-directory').foo
+
+    assert p1 == '/usr/bin/executable.sh'
+    assert p2 == '/usr/share/pkg-config/foo.pc'
+    assert p3 == '/usr/dashed-directory/foo'
+
+    assert isinstance(p1, Prefix)
+    assert isinstance(p2, Prefix)
+    assert isinstance(p3, Prefix)
+
+
 def test_multilevel_attributes():
     """Test attributes of attributes, like ``prefix.share.man``"""
     prefix = Prefix('/usr/')

lib/spack/spack/util/prefix.py

@@ -44,6 +44,8 @@ class Prefix(str):
     /usr/share/man
     >>> prefix.foo.bar.baz
     /usr/foo/bar/baz
+    >>> prefix.join('dashed-directory').bin64
+    /usr/dashed-directory/bin64
 
     Prefix objects behave identically to strings. In fact, they
     subclass ``str``. So operators like ``+`` are legal::
@@ -55,3 +57,14 @@ class Prefix(str):
     """
     def __getattr__(self, attr):
         return Prefix(os.path.join(self, attr))
+
+    def join(self, string):
+        """Concatenates a string to a prefix.
+
+        Parameters:
+            string (str): the string to append to the prefix
+
+        Returns:
+            Prefix: the newly created installation prefix
+        """
+        return Prefix(os.path.join(self, string))