fixes for insert includes

- avoid infinite loop condition
    - follow pep8 style guide
    - encapsulate some functionality to decrease visual nesting

scripts/insert-includes.py

@@ -1,80 +1,120 @@
 #!/usr/bin/env python
+"""
+replaces a `include with the full include file.
 
-# replaces a `include with the full include file.
+args
-# recursively replaces `include's until none are left
+$1 - file which has includes to be replaced
-#
+$2 - file in which output will be written
-# args
+$3 - list of directories to search for includes
-# $1 - file to remove includes from
+     (note: NON-RECURSIVE must specify all dirs)
-# $2 - file to write output to
+      includes are found relative to this path
-# $3 - list of directories to search for includes in (note: NON-RECURSIVE must specify all dirs)
+      this is equivalent to something like +incdir+
-#      includes are found relative to this path
+"""
-#      this is equivalent to something like +incdir+
 
-import sys
-import re
 import os
-import tempfile
+import re
 import shutil
+import sys
+import tempfile
 
-inVlog = sys.argv[1]
-outVlog = sys.argv[2]
-print("[INFO] Replaces includes from: " + str(inVlog))
 
-if inVlog == outVlog:
+def print_info(msg):
-    sys.exit("[ERROR] The input and output file cannot be the same.")
+    """
+    Print an info message.
 
-# add directories to search list
+    Args:
-incDirs = sys.argv[3:]
+        msg (str): message to print
-print("[INFO] Searching following dirs for includes: " + str(incDirs))
+    """
+    print(f"[INFO] {msg}")
 
-def process(inF, outF):
+
-    # open file
+def print_error(msg, critical=True):
-    with open(inF, 'r') as inFile:
+    """
-        with open(outF, 'w') as outFile:
+    Print an error message.
-            # for each include found, search through all dirs and replace if found, error if not
+
-            for num, line in enumerate(inFile, 1):
+    Args:
+        msg (str): message to print
+        critical (bool): whether to exit after printing the message
+    """
+    if critical:
+        sys.exit(f"[ERROR] {msg}")
+    else:
+        print(f"[ERROR] {msg}")
+
+
+def find_include(file_name, inc_dirs):
+    """
+    Find the include file in the list of directories.
+
+    Args:
+        file_name (str): include file name
+        inc_dirs (list): list of directories to search for includes
+
+    Returns:
+        str: full path to the include file
+    """
+    for d in inc_dirs:
+        inc_file_name = d + "/" + file_name
+        if os.path.exists(inc_file_name):
+            return inc_file_name
+    print_error(f"Include file {file_name} not found in {inc_dirs}")
+    return None
+
+
+def process(in_fname, out_fname, inc_dirs=None):
+    """
+    Replace include directives in a file with the full include file.
+
+    Args:
+        in_fname (str): input file name
+        out_fname (str): output file name
+        inc_dirs (list): list of directories to search for includes
+    """
+    with open(in_fname, "r", encoding="utf-8") as in_file:
+        with open(out_fname, "w", encoding="utf-8") as out_file:
+            # for each include found, search through all dirs
+            # and replace if found, error if not
+            for num, line in enumerate(in_file, 1):
                 match = re.match(r"^ *`include +\"(.*)\"", line)
                 if match and match.group(1) != "uvm_macros.svh":
-                    print("[INFO] Replacing includes for {}".format(match.group(1)))
+                    print_info(
+                        f"Replacing includes for {match.group(1)}"
+                        f" at line {num}"
+                    )
                     # search for include and replace
-                    found = False
+                    inc_file_name = find_include(match.group(1), inc_dirs)
-                    for d in incDirs:
+                    with open(inc_file_name, "r", encoding="utf-8") as inc_file:
-                        potentialIncFileName = d + "/" + match.group(1)
+                        out_file.writelines(inc_file)
-                        if os.path.exists(potentialIncFileName):
-                            found = True
-                            print("[INFO] Found missing include in {}".format(potentialIncFileName))
-                            with open(potentialIncFileName, 'r') as incFile:
-                                for iline in incFile:
-                                    outFile.write(iline)
-                            break
 
-                    # must find something to include with
-                    if not found:
-                        sys.exit("[ERROR] Couldn't replace include \"" + str(match.group(1)) + "\" found on line " + str(num))
                 else:
-                    outFile.write(line)
+                    out_file.write(line)
 
-inF = inVlog
 
-while True:
+def main():
-    # create a copy of the input
+    """
-    fd, temp_path = tempfile.mkstemp()
+    Entry point for the script.
-    shutil.copy2(inF, temp_path)
 
-    with open(temp_path, 'r') as inFile:
+    Args:
-        anyIncludes = False
+    <input file> <output file> <list of directories to search for includes>
-        for line in inFile:
+    """
-            match = re.match(r"^ *`include +\"(.*)\"", line)
+    in_vlog = sys.argv[1]
-            if match:
+    out_vlog = sys.argv[2]
-                anyIncludes = True
-                break
 
-        if anyIncludes:
+    if in_vlog == out_vlog:
-            process(temp_path, outVlog)
+        sys.exit("[ERROR] The input and output file cannot be the same.")
-            inF = outVlog
-            os.remove(temp_path)
-        else:
-            os.remove(temp_path)
-            break
 
-print("[INFO] Success. Writing output to: " + str(outVlog))
+    # add directories to search list
+    inc_dirs = sys.argv[3:]
+    print("[INFO] Replaces includes from: " + str(in_vlog))
+    print("[INFO] Searching following dirs for includes: " + str(inc_dirs))
+
+    # make a copy of the input file
+    _, temp_path = tempfile.mkstemp()
+    shutil.copy2(in_vlog, temp_path)
+    process(temp_path, out_vlog, inc_dirs)
+
+    print("[INFO] Success. Output written to: " + str(out_vlog))
+
+
+if __name__ == "__main__":
+    main()