dev: Begin a script help the refactor

Author: jorisv

development/scripts/misc/refactor_headers.py

@@ -0,0 +1,210 @@
+#! /usr/bin/env python3
+# Refactor headers according to
+# https://github.com/stack-of-tasks/pinocchio/pull/2572
+# Run test with python -m doctest -v refactor_headers.py
+
+import re
+import argparse
+
+# Walk in a directory
+# Find all xxx.hpp
+# Rename it into xxx-def.hxx
+#  Update guards
+#  Remove includes
+#  Add clangd_hack
+# if xxx.hxx associated
+#   Rename into xxx-decl.hxx
+#     Update guards
+#     Remove includes
+#     Add clangd_hack
+# if xxx.txx associated
+#   Rename into xxx-tpl.hxx
+#    Update guards
+#    Remove includes
+#     Add clangd_hack
+# Create xxx.hpp
+#   Add guards
+#   Add includes form def, decl and tpl
+#   include def, decl and tpl
+
+GUARD_PATTERN = re.compile("^#ifndef __(.*)__$", re.MULTILINE)
+INCLUDE_PATTERN = re.compile(r"^#include ([\"<].*[\">])\n", re.MULTILINE)
+
+TEST_CPP_CONTENT_GOOD_GUARD = """//
+// Copyright (c) 2015-2024 CNRS INRIA
+// Copyright (c) 2016 Wandercraft, 86 rue de Paris 91400 Orsay, France.
+//
+
+#ifndef __pinocchio_python_spatial_se3_hpp__
+#define __pinocchio_python_spatial_se3_hpp__
+
+#include <eigenpy/eigenpy.hpp>
+#include <boost/python/tuple.hpp>
+
+#include "pinocchio/spatial/se3.hpp"
+#include "pinocchio/spatial/explog.hpp"
+// ...
+#endif // ifndef __pinocchio_python_spatial_se3_hpp__"""
+
+TEST_CPP_CONTENT_BAD_GUARD = """//
+// Copyright (c) 2015-2024 CNRS INRIA
+// Copyright (c) 2016 Wandercraft, 86 rue de Paris 91400 Orsay, France.
+//
+
+#ifndef _pinocchio_python_spatial_se3_hpp__
+#define _pinocchio_python_spatial_se3_hpp__
+// ...
+#endif // ifndef _pinocchio_python_spatial_se3i_hpp__"""
+
+HPP_MODULE = """//
+// Copyright (c) 2025 INRIA
+//
+
+#ifndef {guard}
+#define {guard}
+
+// Module dependencies
+{dep_includes}
+
+// Module headers
+{module_includes}
+
+#endif // ifndef {guard}
+"""
+
+LSP_GUARD = """#ifdef PINOCCHIO_LSP
+#include "{module_hpp}"
+#endif // PINOCCHIO_LSP
+"""
+
+
+def find_guard(content: str) -> None | str:
+    """Find guard in a C++ header file.
+    :ivar content: File content to parse.
+    :return: Guard name if found (without __), None if no guard is found.
+    >>> find_guard(TEST_CPP_CONTENT_GOOD_GUARD)
+    'pinocchio_python_spatial_se3_hpp'
+    >>> find_guard(TEST_CPP_CONTENT_BAD_GUARD)
+    """
+    match = GUARD_PATTERN.search(content)
+    if match:
+        return match.group(1)
+    return None
+
+
+def update_guard(content: str, old_guard_name, new_guard_name: str) -> None | str:
+    """Replace guards in a C++ header file.
+    :ivar content: File content to parse.
+    :ivar old_guard_name: Guard to replace.
+    :ivar new_guard_name: New guard name.
+    :return: New content if the 3 guards are changed, None otherwise.
+    >>> res = update_guard(TEST_CPP_CONTENT_GOOD_GUARD, "pinocchio_python_spatial_se3_hpp", "pinocchio_python_spatial_se3_def_hpp")
+    >>> print(res)
+    //
+    // Copyright (c) 2015-2024 CNRS INRIA
+    // Copyright (c) 2016 Wandercraft, 86 rue de Paris 91400 Orsay, France.
+    //
+    <BLANKLINE>
+    #ifndef __pinocchio_python_spatial_se3_def_hpp__
+    #define __pinocchio_python_spatial_se3_def_hpp__
+    <BLANKLINE>
+    #include <eigenpy/eigenpy.hpp>
+    #include <boost/python/tuple.hpp>
+    <BLANKLINE>
+    #include "pinocchio/spatial/se3.hpp"
+    #include "pinocchio/spatial/explog.hpp"
+    // ...
+    #endif // ifndef __pinocchio_python_spatial_se3_def_hpp__
+    >>> update_guard(TEST_CPP_CONTENT_BAD_GUARD, "pinocchio_python_spatial_se3_hpp", "pinocchio_python_spatial_se3_def_hpp")
+    """
+    (new_content, nr_sub) = re.subn(f"{old_guard_name}", new_guard_name, content)
+    if nr_sub == 3:
+        return new_content
+    return None
+
+
+def remove_includes(content: str, module_header: str) -> (str, list[str]):
+    """Remove includes, add LSP guard instead and return them.
+    :ivar content: File content to parse.
+    :ivar module_header: Module header path (without < or ")
+    :return: New content and list of removed includes (path with < or ")
+    >>> res = remove_includes(TEST_CPP_CONTENT_GOOD_GUARD, "pinocchio/bindings/python/spatial/se3.hpp")
+    >>> print(res[0])
+    //
+    // Copyright (c) 2015-2024 CNRS INRIA
+    // Copyright (c) 2016 Wandercraft, 86 rue de Paris 91400 Orsay, France.
+    //
+    <BLANKLINE>
+    #ifndef __pinocchio_python_spatial_se3_hpp__
+    #define __pinocchio_python_spatial_se3_hpp__
+    <BLANKLINE>
+    <BLANKLINE>
+    #ifdef PINOCCHIO_LSP
+    #include "pinocchio/bindings/python/spatial/se3.hpp"
+    #endif // PINOCCHIO_LSP
+    // ...
+    #endif // ifndef __pinocchio_python_spatial_se3_hpp__
+    >>> print(res[1])
+    ['<eigenpy/eigenpy.hpp>', '<boost/python/tuple.hpp>', '"pinocchio/spatial/se3.hpp"', '"pinocchio/spatial/explog.hpp"']
+    """
+    # TODO: warning if 0 includes, LSP_GUARD will not be added
+    includes = INCLUDE_PATTERN.findall(content)
+    new_content = INCLUDE_PATTERN.sub("", content, count=len(includes) - 1)
+    new_content2 = INCLUDE_PATTERN.sub(
+        LSP_GUARD.format(module_hpp=module_header), new_content
+    )
+    # (new_content2, _) = INCLUDE_PATTERN.subn("", new_content)
+    return new_content2, includes
+
+
+def create_hpp_module(
+    guard: str, dependencies_includes: list[str], module_includes: list[str]
+) -> str:
+    """Create a module content.
+    :ivar guard: Guard name.
+    :ivar dependencies_includes: Module dependencies include paths (path with < or ").
+    :ivar module_includes: Module internal include paths (path with < or ").
+    :return: Module content.
+    >>> res = create_hpp_module("__pinocchio_python_spatial_se3_hpp__",\
+        ['<eigenpy/eigenpy.hpp>', '<boost/python/tuple.hpp>', '"pinocchio/spatial/se3.hpp"', '"pinocchio/spatial/explog.hpp"'],\
+        ['"pinocchio/bindings/python/spatial/se3_decl.hxx"', '"pinocchio/bindings/python/spatial/se3_def.hxx"'])
+    >>> print(res)
+    //
+    // Copyright (c) 2025 INRIA
+    //
+    <BLANKLINE>
+    #ifndef __pinocchio_python_spatial_se3_hpp__
+    #define __pinocchio_python_spatial_se3_hpp__
+    <BLANKLINE>
+    // Module dependencies
+    #include <eigenpy/eigenpy.hpp>
+    #include <boost/python/tuple.hpp>
+    #include "pinocchio/spatial/se3.hpp"
+    #include "pinocchio/spatial/explog.hpp"
+    <BLANKLINE>
+    // Module headers
+    #include "pinocchio/bindings/python/spatial/se3_decl.hxx"
+    #include "pinocchio/bindings/python/spatial/se3_def.hxx"
+    <BLANKLINE>
+    #endif // ifndef __pinocchio_python_spatial_se3_hpp__
+    <BLANKLINE>
+    """
+    deps = "\n".join([f"#include {d}" for d in dependencies_includes])
+    modules = "\n".join([f"#include {d}" for d in module_includes])
+    return HPP_MODULE.format(guard=guard, dep_includes=deps, module_includes=modules)
+
+
+def argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Refactor headers in a Pinocchio subdirectory"
+    )
+
+    return parser
+
+
+def main(args: list[str]):
+    pass
+
+
+if __name__ == "__main__":
+    main()