[util] Standardize auto-generated code warning msg
This PR attempts to provide a standalone Python method that returns a
warning message box indicating that the source is autogenerated.
The `get_autogen_banner()` takes two arguments - `command` and
`comment`. It wraps the command to 74 characters. The `comment` which is
the style supported by the generated file is applied to all lines and
the final text is returned as a string.
It will be great to standardize on how we indicate the source has been
autogenerated, considering we have a lot of scripts that autogenerate
things in our codebase. Happy to hear thoughts and opinions on improving
how this should look further.
Signed-off-by: Srikrishna Iyer <sriyer@google.com>
diff --git a/util/autogen_banner.py b/util/autogen_banner.py
new file mode 100644
index 0000000..e0b8f87
--- /dev/null
+++ b/util/autogen_banner.py
@@ -0,0 +1,48 @@
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+from textwrap import fill
+
+LICENSE_BANNER = (
+ "Copyright lowRISC contributors.\n"
+ "Licensed under the Apache License, Version 2.0, see LICENSE for details.\n"
+ "SPDX-License-Identifier: Apache-2.0")
+
+AUTOGEN_BANNER = (
+ "THIS FILE HAS BEEN GENERATED, DO NOT EDIT MANUALLY. COMMAND:\n{command}")
+
+MAX_LEN = 70
+
+
+def get_autogen_banner(command: str, comment: str = "") -> str:
+ """Returns a commented out auto-generated code warning banner.
+
+ command is a fully formatted string representing what command was used
+ to auto-generate the source.
+ comment is the style of comment supported by the file type.
+ """
+ command = fill(command.strip(),
+ width=MAX_LEN,
+ break_long_words=False,
+ break_on_hyphens=False)
+ text = AUTOGEN_BANNER.format(command=command)
+ return apply_comment(text, comment)
+
+
+def get_license_banner(comment: str = "") -> str:
+ """Returns a commented out license banner.
+
+ comment is the style of comment supported by the source file type.
+ """
+ return apply_comment(LICENSE_BANNER, comment)
+
+
+def apply_comment(text: str, comment: str) -> str:
+ """Applies comment to a text paragraph.
+
+ The returned string terminates in a newline.
+ """
+ if comment:
+ comment += " "
+ return "\n".join([f"{comment}{line}" for line in text.split("\n")]) + "\n"
