Add 'this_dir' argument file token

Author: amykyta3

docs/argfiles.rst

@@ -0,0 +1,33 @@
+Argument Files
+==============
+
+PeakRDL supports reading argument files using the ``-f FILE`` flag.
+Argument files can be used to provide source file lists, or to simply reduce the
+amount of text provided in the command-line.
+
+Argument files contain additional command-line text, as well as a few other
+things described below.
+
+
+Comments
+--------
+Anything after a ``#`` character is treated as a comment and is discarded.
+
+
+Nested -f Flags
+---------------
+Argument files can include other additional argument files by using the ``-f``
+flag.
+
+
+Environment Variables
+---------------------
+Argument files can contain references to environment variables. Both
+``$VAR_NAME`` and ``${VAR_NAME}`` styles are supported.
+
+
+Anchor to current directory
+---------------------------
+If referencing files that are relative to an argument file, the
+``${{this_dir}}`` token can be used. This token expands to the directory path
+that contains the current agument file.

docs/index.rst

@@ -49,6 +49,7 @@ Links
 
     self
     gallery
+    argfiles
     processing-input
     configuring
     licensing

docs/licensing.rst

@@ -25,7 +25,7 @@ licensed individually.
 
 
 What is exempt from the LGPL v3 license?
----------------------------------------
+----------------------------------------
 Don't worry. Not everything that the PeakRDL project touches is considered
 LGPL v3 code.
 

peakrdl-cli/src/peakrdl/argfile.py

@@ -4,20 +4,35 @@
 import re
 from typing import List, Optional, Set, Match
 
-def expand_tokens(argv: List[str]) -> List[str]:
+def expand_tokens(argv: List[str], path) -> List[str]:
     """
     Expand environment variables in args
     """
-    pattern = re.compile(r"\$(\w+|\{[^}]*\})")
-    def repl(m: Match) -> str:
-        k = m.group(1)
-        if k.startswith("{") and k.endswith("}"):
-            k = k[1:-1]
+    token_queries = [
+        ("cwd", r"\$\{\{this_dir\}\}"), # ${{this_dir}}
+        ("env1", r"\$(\w+)"),           # $ENV_VAR
+        ("env2", r"\$\{(\w+)\}"),       # ${ENV_VAR}
+    ]
+    token_regex = re.compile(
+        '|'.join('(?P<%s>%s)' % pair for pair in token_queries)
+    )
 
-        v = os.environ.get(k, m.group(0))
-        return v
+    def repl(m: Match) -> str:
+        if m.lastgroup in {"env1", "env2"}:
+            k = m.group(m.lastindex + 1)
+            if k in os.environ:
+                v = os.environ.get(k)
+            else:
+                print(f"warning: environment variable '{k}' is not set", file=sys.stderr)
+                v = ""
+            return v
+        elif m.lastgroup == "cwd":
+            this_dir = os.path.normpath(os.path.dirname(path))
+            return this_dir
+        else:
+            raise RuntimeError
 
-    return [pattern.sub(repl, arg) for arg in argv]
+    return [token_regex.sub(repl, arg) for arg in argv]
 
 
 def parse_argfile(path: str) -> List[str]:
@@ -27,7 +42,7 @@ def parse_argfile(path: str) -> List[str]:
 
     with open(path, "r", encoding='utf-8') as f:
         args = shlex.split(f.read(), comments=True)
-        args = expand_tokens(args)
+        args = expand_tokens(args, path)
         return args
 
 

test/test_argfile.py

@@ -0,0 +1,42 @@
+import os
+from unittest_utils import PeakRDLTestcase
+
+class TestArgfile(PeakRDLTestcase):
+    def do_argfile_test(self, filename: str):
+        os.environ["PEAKRDL_TOP_TEST_ENVVAR"] = "nested"
+        self.run_commandline([
+            '-f', os.path.join(self.testdata_dir, filename),
+        ])
+        captured = self.capsys.readouterr()
+        expected = "\n".join([
+            "0x00-0x03: nested.rf_inst.r_inst1",
+            "0x04-0x07: nested.rf_inst.r_inst2",
+            "0x08-0x0b: nested.r1_inst",
+            "0x0c-0x0f: nested.r1_inst2",
+            "",
+        ])
+        self.assertEqual(captured.out, expected)
+
+    def test_env1(self):
+        self.do_argfile_test("dump_nested_env1.f")
+
+    def test_env2(self):
+        self.do_argfile_test("dump_nested_env2.f")
+
+    def test_this_dir(self):
+        self.do_argfile_test("dump_nested_this_dir.f")
+
+    def test_err_dne(self):
+        self.run_commandline([
+            '-f', os.path.join(self.testdata_dir, "dne.f"),
+        ], expects_error=True)
+
+    def test_err_missing(self):
+        self.run_commandline([
+            '-f',
+        ], expects_error=True)
+
+    def test_err_circular(self):
+        self.run_commandline([
+            '-f', os.path.join(self.testdata_dir, "circular.f"),
+        ], expects_error=True)

test/test_basics.py

@@ -59,34 +59,3 @@ def test_input_dne(self):
             'dump',
             os.path.join(self.testdata_dir, "this_file_doesnt_exist.rdl"),
         ], expects_error=True)
-
-    def test_f_argfile(self):
-        os.environ["PEAKRDL_TOP_TEST_ENVVAR"] = "nested"
-        self.run_commandline([
-            '-f', os.path.join(self.testdata_dir, "dump_nested.f"),
-        ])
-        captured = self.capsys.readouterr()
-        expected = "\n".join([
-            "0x00-0x03: nested.rf_inst.r_inst1",
-            "0x04-0x07: nested.rf_inst.r_inst2",
-            "0x08-0x0b: nested.r1_inst",
-            "0x0c-0x0f: nested.r1_inst2",
-            "",
-        ])
-        self.assertEqual(captured.out, expected)
-
-    def test_f_argfile_errors(self):
-        with self.subTest("file DNE"):
-            self.run_commandline([
-                '-f', os.path.join(self.testdata_dir, "dne.f"),
-            ], expects_error=True)
-
-        with self.subTest("file missing"):
-            self.run_commandline([
-                '-f',
-            ], expects_error=True)
-
-        with self.subTest("circular ref"):
-            self.run_commandline([
-                '-f', os.path.join(self.testdata_dir, "circular.f"),
-            ], expects_error=True)

test/testdata/dump_nested.f

@@ -1 +1 @@
-dump testdata/parameters.rdl --top ${PEAKRDL_TOP_TEST_ENVVAR}
+dump testdata/parameters.rdl --top nested

test/testdata/dump_nested_env1.f

@@ -0,0 +1 @@
+dump testdata/parameters.rdl --top $PEAKRDL_TOP_TEST_ENVVAR

test/testdata/dump_nested_env2.f

@@ -0,0 +1 @@
+dump testdata/parameters.rdl --top ${PEAKRDL_TOP_TEST_ENVVAR}

test/testdata/dump_nested_this_dir.f

@@ -0,0 +1 @@
+dump ${{this_dir}}/parameters.rdl --top nested