fprime-cpp-codegen 0.1.0__py3-none-any.whl

fprime_cpp_codegen/doc.py

@@ -0,0 +1,371 @@
+"""The C++ document IR: one ``.hpp`` file plus one or more ``.cpp`` files.
+
+The layer the writers consume: a tree of frozen dataclasses.
+:mod:`fprime_cpp_codegen.builder` assembles it for you.
+
+A single :class:`CppDoc` describes a header and any number of source files.  Every
+definition with a body, and every block of raw lines, can name the ``.cpp`` file it
+belongs to via ``cpp_file``; those naming nothing land in the document's default
+``.cpp``.  The header always gets everything, so one class can be split across
+translation units without duplicating its declaration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Protocol, runtime_checkable
+
+from .lines import Line
+
+__all__ = [
+    "VOID",
+    "Class",
+    "ClassMember",
+    "Constructor",
+    "CppDoc",
+    "DefaultFileBanner",
+    "Definition",
+    "Destructor",
+    "FileBanner",
+    "Function",
+    "HppFile",
+    "Lines",
+    "Member",
+    "Namespace",
+    "Output",
+    "Param",
+    "SVQualifier",
+    "Type",
+    "Variable",
+    "as_type",
+]
+
+
+class Output(Enum):
+    """Which of a document's files a block of raw lines is emitted into."""
+
+    HPP = "hpp"
+    """Header only."""
+
+    CPP = "cpp"
+    """Source only."""
+
+    BOTH = "both"
+    """Both the header and the source."""
+
+
+class SVQualifier(Enum):
+    """A function's static/virtual specifier, mutually exclusive by construction.
+
+    ``OVERRIDE`` and ``FINAL`` render as trailing specifiers; ``STATIC``, ``VIRTUAL``
+    and ``PURE_VIRTUAL`` as leading ones.  ``PURE_VIRTUAL`` also terminates the
+    declaration with ``= 0``.
+    """
+
+    NONE = "none"
+    STATIC = "static"
+    VIRTUAL = "virtual"
+    PURE_VIRTUAL = "pure-virtual"
+    OVERRIDE = "override"
+    FINAL = "final"
+
+
+@dataclass(frozen=True)
+class Type:
+    """A C++ type.
+
+    The source file may need a different spelling from the header, typically because
+    the header sits inside the namespace qualifying the name.  ``cpp_type`` supplies
+    it; when absent, both files use ``hpp_type``.
+    """
+
+    hpp_type: str
+    cpp_type: str | None = None
+
+    @property
+    def cpp(self) -> str:
+        """The spelling to use in a ``.cpp`` file."""
+        return self.cpp_type if self.cpp_type is not None else self.hpp_type
+
+    @property
+    def hpp(self) -> str:
+        """The spelling to use in the ``.hpp`` file."""
+        return self.hpp_type
+
+
+#: The ``void`` type, and the default return type of a :class:`Function`.
+VOID = Type("void")
+
+
+def as_type(t: Type | str | tuple[str, str]) -> Type:
+    """Coerce a type specification to a :class:`Type`.
+
+    A single string is used in both files.  A ``(header, source)`` pair supplies the
+    two spellings a nested type needs: ``Status`` inside the class,
+    ``MyClass::Status`` in the source file where the return type precedes
+    ``MyClass::``.
+    """
+    if isinstance(t, Type):
+        return t
+    if isinstance(t, tuple):
+        hpp, cpp = t
+        return Type(hpp, cpp)
+    return Type(t)
+
+
+@dataclass(frozen=True)
+class Param:
+    """A formal parameter of a function, constructor, or destructor."""
+
+    type: Type
+    name: str
+    comment: str | None = None
+    """A doxygen post-comment, rendered after the parameter in the header."""
+
+    default: str | None = None
+    """A default argument, rendered in the header declaration only."""
+
+
+@dataclass(frozen=True)
+class Lines:
+    """A block of raw, already-rendered C++ lines.
+
+    Access tags, banner comments, ``#include`` directives, enums and structs are all
+    lines.  ``output`` decides which files see them.
+    """
+
+    content: list[Line] = field(default_factory=list)
+    output: Output = Output.HPP
+    cpp_file: str | None = None
+    """Restrict source-file output to this ``.cpp`` base name.  Header output is
+    unaffected."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class Definition:
+    """Fields shared by everything that has a body.
+
+    Keyword-only, so subclasses can take their own defining field as the first
+    positional argument.
+
+    ``deleted`` and ``defaulted`` replace the body with ``= delete`` or
+    ``= default``; ``inline_body`` and ``template`` move the definition into the
+    header, since a template's definition must be visible at every use.  In all four
+    cases the source file gets nothing.
+    """
+
+    body: list[Line] = field(default_factory=list)
+    comment: str | None = None
+    cpp_file: str | None = None
+    """Which ``.cpp`` file the definition goes in.  ``None`` means the default."""
+
+    noexcept: bool = False
+    deleted: bool = False
+    defaulted: bool = False
+    inline_body: bool = False
+
+    template: str | None = None
+    """A template parameter list without the keyword, e.g. ``"typename T"``.
+    Implies :attr:`inline_body`."""
+
+    @property
+    def defined_in_header(self) -> bool:
+        return self.inline_body or self.template is not None
+
+    @property
+    def has_definition(self) -> bool:
+        """Whether there is a body to write at all."""
+        return not (self.deleted or self.defaulted)
+
+
+@dataclass(frozen=True)
+class Function(Definition):
+    """A C++ function, either free-standing or a class member."""
+
+    name: str
+    params: list[Param] = field(default_factory=list)
+    ret_type: Type = VOID
+    """``Type("")`` emits no return type, as a conversion operator needs."""
+
+    sv: SVQualifier = SVQualifier.NONE
+    const: bool = False
+    constexpr: bool = False
+    inline: bool = False
+
+    @property
+    def defined_in_header(self) -> bool:
+        """``constexpr`` and ``inline`` force the definition into the header: both
+        require it visible in every translation unit that uses the function."""
+        return super().defined_in_header or self.constexpr or self.inline
+
+
+@dataclass(frozen=True)
+class Constructor(Definition):
+    """A C++ constructor.  Its name is taken from the enclosing class."""
+
+    params: list[Param] = field(default_factory=list)
+    initializers: list[str] = field(default_factory=list)
+    """Member-initializer-list entries, e.g. ``"m_size(size)"``, rendered wherever the
+    definition goes."""
+
+    explicit: bool = False
+    constexpr: bool = False
+
+    @property
+    def defined_in_header(self) -> bool:
+        return super().defined_in_header or self.constexpr
+
+
+@dataclass(frozen=True)
+class Destructor(Definition):
+    """A C++ destructor.  Its name is taken from the enclosing class."""
+
+    virtual: bool = False
+    override: bool = False
+
+
+@dataclass(frozen=True)
+class Class:
+    """A C++ class, possibly nested inside another class."""
+
+    name: str
+    superclass_decls: str | None = None
+    """Everything after the colon, verbatim, e.g. ``"public Fw::Serializable"``.
+    Multiple bases go in one comma-separated string."""
+
+    members: list[ClassMember] = field(default_factory=list)
+    comment: str | None = None
+    final: bool = False
+    template: str | None = None
+    """A template parameter list without the keyword, e.g. ``"typename T"``.  A
+    templated class defines all its members in the header, so its source file output
+    is empty."""
+
+    struct: bool = False
+    """Emit ``struct``, making members public by default."""
+
+
+@dataclass(frozen=True)
+class Variable:
+    """A variable: a class data member, or a constant or global at namespace scope.
+
+    Where the initialiser goes depends on the kind of variable:
+
+    * A non-static data member takes its initialiser in the class body.
+    * A static data member is only declared in the class; the definition, with the
+      initialiser, goes in a source file.  A ``constexpr`` static is initialised in
+      the class and needs no out-of-line definition unless something takes its
+      address -- see ``out_of_line_definition``.
+    * At namespace scope, ``extern`` splits declaration from definition the same way.
+      Without it the variable is defined where it is declared, as a ``constexpr`` or
+      ``const`` constant in a header should be.
+    """
+
+    name: str
+    type: Type
+    init: str | None = None
+    array: str | None = None
+    """An array extent, without brackets, e.g. ``"SIZE"`` for ``m_data[SIZE]``."""
+
+    comment: str | None = None
+    static: bool = False
+    const: bool = False
+    constexpr: bool = False
+    mutable: bool = False
+    extern: bool = False
+    out_of_line_definition: bool = False
+    """Also emit a source-file definition for a ``constexpr`` static member."""
+
+    cpp_file: str | None = None
+
+    @property
+    def declarator(self) -> str:
+        """The name plus any array extent, e.g. ``"m_data[SIZE]"``."""
+        return f"{self.name}[{self.array}]" if self.array is not None else self.name
+
+
+@dataclass(frozen=True)
+class Namespace:
+    """A C++ namespace.  Nest instances to nest namespaces."""
+
+    name: str
+    members: list[Member] = field(default_factory=list)
+
+
+#: What may appear at document or namespace scope.
+Member = Class | Lines | Function | Namespace | Variable
+
+#: What may appear at class scope.  Namespaces may not; constructors and
+#: destructors may.
+ClassMember = Class | Lines | Function | Constructor | Destructor | Variable
+
+
+@runtime_checkable
+class FileBanner(Protocol):
+    """Supplies the ``\\title``/``\\author``/``\\brief`` lines atop each file."""
+
+    def title(self, file_name: str) -> str:
+        """The ``\\title`` text for ``file_name``."""
+        ...
+
+    def author(self, file_name: str) -> str:
+        """The ``\\author`` text for ``file_name``."""
+        ...
+
+    def description(self, file_name: str, generic_description: str) -> str:
+        """The ``\\brief`` text.  ``generic_description`` is the writer's own phrasing,
+        e.g. ``"hpp file for my component"``."""
+        ...
+
+
+@dataclass(frozen=True)
+class DefaultFileBanner:
+    """The banner used when a document does not supply one."""
+
+    tool_name: str | None = None
+
+    def title(self, file_name: str) -> str:
+        return file_name
+
+    def author(self, file_name: str) -> str:
+        return f"Generated by {self.tool_name or 'fpp tools'}"
+
+    def description(self, file_name: str, generic_description: str) -> str:
+        return generic_description
+
+
+@dataclass(frozen=True)
+class HppFile:
+    """The header file of a document."""
+
+    name: str
+    """The file name including extension, e.g. ``"MyClass.hpp"``."""
+
+    include_guard: str
+    """The include-guard macro, e.g. ``"Fw_MyClass_HPP"``."""
+
+
+@dataclass(frozen=True)
+class CppDoc:
+    """A C++ document: one header, one default source file, and the members."""
+
+    description: str
+    """Used in the file banners, as ``"hpp file for <description>"``."""
+
+    hpp_file: HppFile
+    cpp_file_name: str
+    """The default source file name including extension, e.g. ``"MyClass.cpp"``."""
+
+    members: list[Member] = field(default_factory=list)
+    tool_name: str | None = None
+    banner: FileBanner | None = None
+
+    @property
+    def file_banner(self) -> FileBanner:
+        """The document's banner, falling back to :class:`DefaultFileBanner`."""
+        return (
+            self.banner
+            if self.banner is not None
+            else DefaultFileBanner(self.tool_name)
+        )

fprime_cpp_codegen/errors.py

@@ -0,0 +1,25 @@
+"""The exception hierarchy.
+
+Everything raised here derives from :class:`CppCodegenError`, so a generator can
+catch one type.
+"""
+
+from __future__ import annotations
+
+__all__ = ["CppCodegenError", "ScopeError", "ValidationError"]
+
+
+class CppCodegenError(Exception):
+    """Base class for every error raised here."""
+
+
+class ScopeError(CppCodegenError):
+    """A builder scope was used in a way its structure does not allow.
+
+    ``else`` with no preceding ``if``, a ``case`` outside a ``switch``, building a body
+    with a scope still open.
+    """
+
+
+class ValidationError(CppCodegenError):
+    """A document or declaration is malformed and could not produce valid C++."""

fprime_cpp_codegen/formatting.py

@@ -0,0 +1,89 @@
+"""Passing generated files through an external formatter.
+
+``clang-format`` is lexical: it needs no compilation database, include paths, or
+working compiler, so generated text with missing includes and unknown types
+formats fine.  It cannot tell a type name from a variable, so ``a * b;`` becomes
+``a *b;``.
+
+A formatter takes the file text and its name.  ``clang-format`` locates the
+governing ``.clang-format`` by searching upward from the file's path, so the name
+determines which project style applies.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from .errors import CppCodegenError
+
+__all__ = ["ClangFormat", "Formatter"]
+
+
+@runtime_checkable
+class Formatter(Protocol):
+    """Post-processes one generated file's text."""
+
+    def __call__(self, text: str, file_name: str) -> str:
+        """Return ``text`` reformatted.  ``file_name`` is the name it is written as."""
+        ...
+
+
+@dataclass(frozen=True)
+class ClangFormat:
+    """Runs ``clang-format`` over generated text, through stdin and stdout::
+
+        doc.write("build-artifacts", formatter=ClangFormat())
+
+    With no ``style``, ``clang-format``'s default applies, which searches for a
+    ``.clang-format`` upward from the generated file's directory.  ``style`` may be
+    a named style such as ``"LLVM"`` or inline YAML like
+    ``"{BasedOnStyle: LLVM, ColumnLimit: 120}"``.
+
+    This reformats everything: a ``Ret Class ::`` line and its indented signature
+    collapse onto one, and namespace bodies lose their indentation.
+    """
+
+    executable: str = "clang-format"
+    style: str | None = None
+    timeout: float = 30.0
+
+    def available(self) -> bool:
+        """Whether the executable can be found on ``PATH``."""
+        return shutil.which(self.executable) is not None
+
+    def version(self) -> str:
+        """The formatter's version string."""
+        return self._run(["--version"], text=None).strip()
+
+    def __call__(self, text: str, file_name: str) -> str:
+        """Return ``text`` as ``clang-format`` writes it for ``file_name``."""
+        args = [f"--assume-filename={file_name}"]
+        if self.style is not None:
+            args.append(f"--style={self.style}")
+        return self._run(args, text=text)
+
+    def _run(self, args: list[str], *, text: str | None) -> str:
+        try:
+            result = subprocess.run(
+                [self.executable, *args],
+                input=text,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+            )
+        except FileNotFoundError as exc:
+            raise CppCodegenError(
+                f"{self.executable!r} was not found on PATH; install clang-format or "
+                "pass a different executable to ClangFormat"
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise CppCodegenError(
+                f"{self.executable!r} did not finish within {self.timeout}s"
+            ) from exc
+        if result.returncode != 0:
+            detail = result.stderr.strip() or f"exit status {result.returncode}"
+            raise CppCodegenError(f"{self.executable!r} failed: {detail}")
+        return result.stdout

fprime_cpp_codegen/fprime.py

@@ -0,0 +1,149 @@
+"""F Prime idioms, kept separate from the general-purpose layers.
+
+The conventions that show up in every F Prime autocoded file, collected so a
+generator does not have to retype them.  All strings and lines; no knowledge of the
+FPP model.
+
+Import it explicitly; the core API stays framework-neutral.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from .doc import ClassMember, Lines, Member, Output
+from .lines import Line, blank, lines, wrap_in_scope
+
+__all__ = [
+    "BUILD_UT",
+    "FW_ENABLE_TEXT_LOGGING",
+    "STANDARD_SYSTEM_CPP_HEADERS",
+    "STANDARD_SYSTEM_HPP_HEADERS",
+    "STANDARD_USER_CPP_HEADERS",
+    "STANDARD_USER_HPP_HEADERS",
+    "buffer_name",
+    "external_string_decl",
+    "guard_class_members_for_text_log",
+    "guard_class_members_for_unit_test",
+    "guard_members_for_text_log",
+    "guard_members_for_unit_test",
+    "write_assert",
+    "write_ostream_operator",
+]
+
+#: The preprocessor condition guarding text-log support.
+FW_ENABLE_TEXT_LOGGING = "#if FW_ENABLE_TEXT_LOGGING"
+
+#: The preprocessor condition guarding unit-test-only code.
+BUILD_UT = "#ifdef BUILD_UT"
+
+#: Project headers an autocoded F Prime header normally needs.
+STANDARD_USER_HPP_HEADERS = [
+    f'#include "{path}"'
+    for path in (
+        "Fw/FPrimeBasicTypes.hpp",
+        "Fw/Types/ExternalString.hpp",
+        "Fw/Types/Serializable.hpp",
+        "Fw/Types/String.hpp",
+    )
+]
+
+#: System headers an autocoded F Prime header normally needs.  Empty, but kept so a
+#: generator can splice it in unconditionally.
+STANDARD_SYSTEM_HPP_HEADERS: list[str] = []
+
+#: Project headers an autocoded F Prime source file normally needs.
+STANDARD_USER_CPP_HEADERS = ['#include "Fw/Types/Assert.hpp"']
+
+#: System headers an autocoded F Prime source file normally needs.
+STANDARD_SYSTEM_CPP_HEADERS: list[str] = []
+
+
+def write_assert(condition: str, *args: str) -> list[Line]:
+    """Render an ``FW_ASSERT``.
+
+    Extra arguments become the assert's reported values, making a flight-side
+    assertion diagnosable after the fact.  Each must already be spelled as a C++
+    expression, casts included.
+    """
+    joined = ", ".join([condition, *args])
+    return lines(f"FW_ASSERT({joined});")
+
+
+def buffer_name(name: str) -> str:
+    """The backing-array name for a generated ``Fw::ExternalString``."""
+    return f"__fprime_ac_{name}_buffer"
+
+
+def external_string_decl(name: str, size: str) -> list[Line]:
+    """Declare an ``Fw::ExternalString`` over a stack buffer of ``size`` characters.
+
+    F Prime avoids dynamic memory, so a string-typed local is a fixed char array plus
+    a view onto it, not an owning string object.
+    """
+    buf = buffer_name(name)
+    return lines(f"""|char {buf}[Fw::StringBase::BUFFER_SIZE({size})];
+            |Fw::ExternalString {name}({buf}, sizeof {buf});""")
+
+
+def _guard_members(directive: str, members: Sequence[Any], output: Output) -> list[Any]:
+    """Bracket a non-empty run of members with ``directive`` and ``#endif``."""
+    if not members:
+        return []
+    return [
+        Lines(lines(f"\n{directive}"), output),
+        *members,
+        Lines([blank(), *lines("#endif")], output),
+    ]
+
+
+def guard_class_members_for_text_log(
+    members: Sequence[ClassMember], output: Output = Output.BOTH
+) -> list[ClassMember]:
+    """Bracket class members with ``#if FW_ENABLE_TEXT_LOGGING``."""
+    return _guard_members(FW_ENABLE_TEXT_LOGGING, members, output)
+
+
+def guard_members_for_text_log(
+    members: Sequence[Member], output: Output = Output.BOTH
+) -> list[Member]:
+    """Bracket document members with ``#if FW_ENABLE_TEXT_LOGGING``."""
+    return _guard_members(FW_ENABLE_TEXT_LOGGING, members, output)
+
+
+def guard_class_members_for_unit_test(
+    members: Sequence[ClassMember], output: Output = Output.BOTH
+) -> list[ClassMember]:
+    """Bracket class members with ``#ifdef BUILD_UT``."""
+    return _guard_members(BUILD_UT, members, output)
+
+
+def guard_members_for_unit_test(
+    members: Sequence[Member], output: Output = Output.BOTH
+) -> list[Member]:
+    """Bracket document members with ``#ifdef BUILD_UT``."""
+    return _guard_members(BUILD_UT, members, output)
+
+
+def write_ostream_operator(name: str, body: Sequence[Line]) -> list[ClassMember]:
+    """Declare and define a friend ``operator<<`` for ``name``, unit-test only.
+
+    Returns the header declaration and the source-file definition, both inside a
+    ``BUILD_UT`` guard, ready to splice into a class's member list.
+    """
+    declaration = Lines(lines(f"""|
+                |//! Ostream operator
+                |friend std::ostream& operator<<(
+                |    std::ostream& os, //!< The ostream
+                |    const {name}& obj //!< The object
+                |);"""))
+    definition = Lines(
+        wrap_in_scope(
+            f"\nstd::ostream& operator<<(std::ostream& os, const {name}& obj) {{",
+            body,
+            "}",
+        ),
+        Output.CPP,
+    )
+    return guard_class_members_for_unit_test([declaration, definition])