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

fprime_cpp_codegen/__init__.py

@@ -10,6 +10,7 @@ The package is layered, and you can enter at whichever level suits the job:
 * :mod:`~fprime_cpp_codegen.comments` -- comment and banner formatting.
 * :mod:`~fprime_cpp_codegen.lines` -- the line model everything is built on.
 * :mod:`~fprime_cpp_codegen.output` -- rendering to text and to disk.
+* :mod:`~fprime_cpp_codegen.validation` -- whole-document checks.
 * :mod:`~fprime_cpp_codegen.formatting` -- optional post-processing through
   ``clang-format``.
 * :mod:`~fprime_cpp_codegen.fprime` -- F Prime conventions.  Import it explicitly;
@@ -52,6 +53,7 @@ from .doc import (
     VOID,
     Class,
     ClassMember,
+    Comment,
     Constructor,
     CppDoc,
     DefaultFileBanner,
@@ -83,6 +85,7 @@ from .lines import (
     wrap_in_scope,
 )
 from .output import WriteResult, collect_cpp_files, doc_files, write_doc
+from .validation import check_document, orphaned_members, unfilled_definitions
 from .writer import (
     Context,
     CppWriter,
@@ -108,6 +111,7 @@ __all__ = [
     "VOID",
     "Class",
     "ClassMember",
+    "Comment",
     "Constructor",
     "CppDoc",
     "DefaultFileBanner",
@@ -155,6 +159,10 @@ __all__ = [
     "collect_cpp_files",
     "doc_files",
     "write_doc",
+    # Validation
+    "check_document",
+    "orphaned_members",
+    "unfilled_definitions",
     # Errors
     "CppCodegenError",
     "ScopeError",

fprime_cpp_codegen/body.py

@@ -34,6 +34,7 @@ from .comments import (
     write_comment_body,
     write_doxygen_comment,
 )
+from .doc import Comment
 from .errors import ScopeError, ValidationError
 from .lines import Line, blank, indent_lines
 from .lines import line as _line
@@ -44,7 +45,9 @@ __all__ = ["Body", "Code", "Switch", "stmts"]
 
 #: Anything usable as a run of C++ statements.  ``None`` contributes nothing, so
 #: ``b.add(frag if condition else None)`` needs no branch.  A ``str`` is
-#: margin-stripped and taken verbatim, with no punctuation added.
+#: margin-stripped and taken verbatim, with no punctuation added; pass a
+#: :class:`~fprime_cpp_codegen.lines.Line` instead, or use :meth:`Body.line`, for text
+#: that must survive a leading ``|``.
 Code: TypeAlias = "None | str | Line | Body | Sequence[Code]"
 
 
@@ -216,9 +219,14 @@ class Body:
         """Append one line verbatim."""
         return self._emit([_line(text)])
 
-    def lines(self, text: str) -> Body:
-        """Append a margin-stripped, possibly multi-line block of C++."""
-        return self._emit(_lines(text))
+    def lines(self, text: str, *, margin: str | None = "|") -> Body:
+        """Append a margin-stripped, possibly multi-line block of C++.
+
+        ``margin=None`` turns the stripping off, for text taken from a generator's
+        input that may legitimately begin with the margin character.  :meth:`line`
+        never strips.
+        """
+        return self._emit(_lines(text, margin=margin))
 
     def raw(self, ll: Iterable[Line]) -> Body:
         """Append already-rendered lines."""
@@ -241,19 +249,19 @@ class Body:
     # Comments
     # ------------------------------------------------------------------
 
-    def comment(self, text: str) -> Body:
+    def comment(self, text: Comment) -> Body:
         """Append a ``//`` comment with no leading blank line."""
         return self._emit(write_comment_body(text))
 
-    def spaced_comment(self, text: str) -> Body:
+    def spaced_comment(self, text: Comment) -> Body:
         """Append a ``//`` comment preceded by a blank line."""
         return self._emit(write_comment(text))
 
-    def doc_comment(self, text: str) -> Body:
+    def doc_comment(self, text: Comment) -> Body:
         """Append a ``//!`` doxygen comment."""
         return self._emit(write_doxygen_comment(text))
 
-    def banner(self, text: str) -> Body:
+    def banner(self, text: Comment) -> Body:
         """Append a ruled banner comment."""
         return self._emit(write_banner_comment(text))
 

fprime_cpp_codegen/builder/coercion.py

@@ -95,3 +95,14 @@ def _extends(extends: str | Sequence[str] | None) -> str | None:
         return extends
     joined = ", ".join(extends)
     return joined or None
+
+
+def _as_attributes(attributes: str | Sequence[str]) -> tuple[str, ...]:
+    """Normalise a declaration-attribute specification into a tuple.
+
+    A single string is one attribute, not a sequence of characters, since one is the
+    common case: ``attributes='__attribute__((visibility("default")))'``.
+    """
+    if isinstance(attributes, str):
+        return (attributes,)
+    return tuple(attributes)

fprime_cpp_codegen/builder/decoration.py

@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING, Any
 from ..comments import write_access_tag, write_banner_comment
 from ..doc import (
     Class,
+    Comment,
     Constructor,
     Destructor,
     Function,
@@ -90,7 +91,7 @@ class _SectionBanner(_Builder[Lines]):
     definitions went.
     """
 
-    def __init__(self, comment: str) -> None:
+    def __init__(self, comment: Comment) -> None:
         self.comment = comment
         self.members: list[object] = []
 
@@ -179,7 +180,7 @@ class AccessSection:
     its label and banner back out again.
     """
 
-    def __init__(self, scope: ClassBuilder, tag: str, comment: str | None) -> None:
+    def __init__(self, scope: ClassBuilder, tag: str, comment: Comment | None) -> None:
         self._scope = scope
         self._count = 1
         scope._add(Lines(write_access_tag(tag), Output.HPP))

fprime_cpp_codegen/builder/definitions.py

@@ -11,12 +11,22 @@ from ..comments import (
     write_doxygen_comment,
     write_doxygen_comment_opt,
 )
-from ..doc import Constructor, Destructor, Function, Lines, Output, Param, Type, as_type
+from ..doc import (
+    Comment,
+    Constructor,
+    Destructor,
+    Function,
+    Lines,
+    Output,
+    Param,
+    Type,
+    as_type,
+)
 from ..errors import ValidationError
 from ..lines import Line, wrap_in_scope
 from ..lines import line as _line
 from .base import _Builder
-from .coercion import _as_body_lines, _as_params, _sv_qualifier
+from .coercion import _as_attributes, _as_body_lines, _as_params, _sv_qualifier
 
 
 class Radix(Enum):
@@ -53,7 +63,7 @@ class FunctionBuilder(_Builder[Function]):
         *,
         ret: Type | str = "void",
         params: Iterable[Param | Sequence[str]] = (),
-        comment: str | None = None,
+        comment: Comment | None = None,
         body: Code = None,
         const: bool = False,
         static: bool = False,
@@ -66,6 +76,8 @@ class FunctionBuilder(_Builder[Function]):
         noexcept: bool = False,
         deleted: bool = False,
         defaulted: bool = False,
+        declaration_only: bool = False,
+        attributes: str | Sequence[str] = (),
         template: str | None = None,
         inline_body: bool = False,
         cpp_file: str | None = None,
@@ -81,6 +93,8 @@ class FunctionBuilder(_Builder[Function]):
         self.noexcept = noexcept
         self.deleted = deleted
         self.defaulted = defaulted
+        self.declaration_only = declaration_only
+        self.attributes = _as_attributes(attributes)
         self.template = template
         self.inline_body = inline_body
         self.cpp_file = cpp_file
@@ -99,7 +113,7 @@ class FunctionBuilder(_Builder[Function]):
         type_name: Type | str,
         name: str,
         *,
-        comment: str | None = None,
+        comment: Comment | None = None,
         default: str | None = None,
     ) -> FunctionBuilder:
         """Append one formal parameter.  Returns self, so calls can be chained."""
@@ -125,6 +139,8 @@ class FunctionBuilder(_Builder[Function]):
             noexcept=self.noexcept,
             deleted=self.deleted,
             defaulted=self.defaulted,
+            declaration_only=self.declaration_only,
+            attributes=self.attributes,
             template=self.template,
             inline_body=self.inline_body,
             cpp_file=self.cpp_file,
@@ -145,13 +161,14 @@ class ConstructorBuilder(_Builder[Constructor]):
         *,
         params: Iterable[Param | Sequence[str]] = (),
         initializers: Iterable[str] = (),
-        comment: str | None = None,
+        comment: Comment | None = None,
         body: Code = None,
         explicit: bool = False,
         constexpr: bool = False,
         noexcept: bool = False,
         deleted: bool = False,
         defaulted: bool = False,
+        declaration_only: bool = False,
         template: str | None = None,
         inline_body: bool = False,
         cpp_file: str | None = None,
@@ -162,6 +179,7 @@ class ConstructorBuilder(_Builder[Constructor]):
         self.noexcept = noexcept
         self.deleted = deleted
         self.defaulted = defaulted
+        self.declaration_only = declaration_only
         self.template = template
         self.inline_body = inline_body
         self.cpp_file = cpp_file
@@ -174,7 +192,7 @@ class ConstructorBuilder(_Builder[Constructor]):
         type_name: Type | str,
         name: str,
         *,
-        comment: str | None = None,
+        comment: Comment | None = None,
         default: str | None = None,
     ) -> ConstructorBuilder:
         """Append one formal parameter."""
@@ -202,6 +220,7 @@ class ConstructorBuilder(_Builder[Constructor]):
             noexcept=self.noexcept,
             deleted=self.deleted,
             defaulted=self.defaulted,
+            declaration_only=self.declaration_only,
             template=self.template,
             inline_body=self.inline_body,
             cpp_file=self.cpp_file,
@@ -220,13 +239,14 @@ class DestructorBuilder(_Builder[Destructor]):
     def __init__(
         self,
         *,
-        comment: str | None = None,
+        comment: Comment | None = None,
         body: Code = None,
         virtual: bool = False,
         override: bool = False,
         noexcept: bool = False,
         deleted: bool = False,
         defaulted: bool = False,
+        declaration_only: bool = False,
         inline_body: bool = False,
         cpp_file: str | None = None,
     ) -> None:
@@ -236,6 +256,7 @@ class DestructorBuilder(_Builder[Destructor]):
         self.noexcept = noexcept
         self.deleted = deleted
         self.defaulted = defaulted
+        self.declaration_only = declaration_only
         self.inline_body = inline_body
         self.cpp_file = cpp_file
         self.body = Body(_as_body_lines(body))
@@ -249,6 +270,7 @@ class DestructorBuilder(_Builder[Destructor]):
             noexcept=self.noexcept,
             deleted=self.deleted,
             defaulted=self.defaulted,
+            declaration_only=self.declaration_only,
             inline_body=self.inline_body,
             cpp_file=self.cpp_file,
         )
@@ -269,7 +291,7 @@ class EnumBuilder(_Builder[Lines]):
         *,
         underlying: str | None = None,
         scoped: bool = False,
-        comment: str | None = None,
+        comment: Comment | None = None,
         output: Output = Output.HPP,
         cpp_file: str | None = None,
         radix: Radix = Radix.DECIMAL,
@@ -323,7 +345,7 @@ class EnumBuilder(_Builder[Lines]):
         name: str,
         value: int | str | None = None,
         *,
-        comment: str | None = None,
+        comment: Comment | None = None,
         radix: Radix | None = None,
     ) -> EnumBuilder:
         """Append one enumerator.

fprime_cpp_codegen/builder/document.py

@@ -10,7 +10,8 @@ from ..doc import CppDoc, FileBanner, HppFile
 from ..errors import ValidationError
 from ..formatting import Formatter
 from ..output import WriteResult, doc_files, write_doc
-from ..writer import render_cpp, render_hpp
+from ..validation import check_document
+from ..writer import CppWriter, HppWriter, render_cpp, render_hpp
 from .base import _DocContext
 from .scopes import _MemberScope
 
@@ -28,8 +29,13 @@ class CppDocBuilder(_MemberScope[CppDoc]):
         tool_name: str | None = None,
         file_banner: FileBanner | None = None,
         formatter: Formatter | None = None,
+        hpp_writer: HppWriter | None = None,
+        cpp_writer: CppWriter | None = None,
         hpp_extension: str = "hpp",
         cpp_extension: str = "cpp",
+        emit_hpp: bool = True,
+        emit_cpp: bool = True,
+        strict: bool = False,
     ) -> None:
         """Start a document whose files are named after ``file_base``.
 
@@ -39,7 +45,20 @@ class CppDocBuilder(_MemberScope[CppDoc]):
 
         ``formatter`` post-processes every file this document renders; see
         :mod:`fprime_cpp_codegen.formatting`.  Any render or write call can override
-        it, but cannot switch it off.
+        it, but cannot switch it off.  ``hpp_writer`` and ``cpp_writer`` work the same
+        way, substituting a :class:`~fprime_cpp_codegen.writer.DocWriter` subclass for
+        the default rendering.
+
+        ``emit_hpp=False`` or ``emit_cpp=False`` makes this a one-file document, which
+        a translation unit holding only a module-initialisation block wants.  Members
+        that would then have nowhere to go raise :class:`ValidationError` when the
+        document is built, rather than disappearing.
+
+        ``strict=True`` additionally rejects any definition that needs a body and has
+        none, which would otherwise render as an empty out-of-line definition -- valid
+        C++, and so easy for a generator to emit by accident.  Say
+        ``declaration_only=True`` to declare without defining, or ``body=""`` for a
+        definition that is deliberately empty.
         """
         super().__init__(_DocContext())
         if not file_base:
@@ -52,6 +71,23 @@ class CppDocBuilder(_MemberScope[CppDoc]):
         self.formatter = formatter
         """Applied to every file this document renders, unless a call overrides it."""
 
+        self.hpp_writer = hpp_writer
+        """Renders the header, unless a call overrides it.  ``None`` uses
+        :class:`~fprime_cpp_codegen.writer.HppWriter`."""
+
+        self.cpp_writer = cpp_writer
+        """Renders the source files, unless a call overrides it.  ``None`` uses
+        :class:`~fprime_cpp_codegen.writer.CppWriter`."""
+
+        self.emit_hpp = emit_hpp
+        """Whether this document produces a header at all."""
+
+        self.emit_cpp = emit_cpp
+        """Whether this document produces any source file at all."""
+
+        self.strict = strict
+        """Whether :meth:`build` rejects a definition that needs a body and has none."""
+
         self.file_banner = file_banner
         """Overrides the ``\\title``/``\\author``/``\\brief`` block atop each file.
         Distinct from :meth:`banner`, which emits a section comment."""
@@ -73,7 +109,8 @@ class CppDocBuilder(_MemberScope[CppDoc]):
         return f"{self.file_base}.{self.cpp_extension}"
 
     def build(self) -> CppDoc:
-        return CppDoc(
+        """Produce the IR, checking it against ``emit_hpp``/``emit_cpp``/``strict``."""
+        doc = CppDoc(
             description=self.description,
             hpp_file=HppFile(self.hpp_name, self.include_guard),
             cpp_file_name=self.cpp_name,
@@ -81,23 +118,55 @@ class CppDocBuilder(_MemberScope[CppDoc]):
             tool_name=self.tool_name,
             banner=self.file_banner,
         )
+        check_document(
+            doc,
+            emit_hpp=self.emit_hpp,
+            emit_cpp=self.emit_cpp,
+            strict=self.strict,
+        )
+        return doc
 
     # -- output -------------------------------------------------------
 
     def _formatter(self, override: Formatter | None) -> Formatter | None:
         return override if override is not None else self.formatter
 
-    def render_hpp(self, *, formatter: Formatter | None = None) -> str:
+    def _hpp_writer(self, override: HppWriter | None) -> HppWriter | None:
+        return override if override is not None else self.hpp_writer
+
+    def _cpp_writer(self, override: CppWriter | None) -> CppWriter | None:
+        return override if override is not None else self.cpp_writer
+
+    def _require_emitted(self, which: str) -> None:
+        """Reject rendering a file this document was told not to produce."""
+        if not (self.emit_hpp if which == "hpp" else self.emit_cpp):
+            raise ValidationError(
+                f"this document was built with emit_{which}=False, so it has no "
+                f"{which} file to render"
+            )
+
+    def render_hpp(
+        self,
+        *,
+        formatter: Formatter | None = None,
+        writer: HppWriter | None = None,
+    ) -> str:
         """Render the header as text."""
-        text = render_hpp(self.build())
+        self._require_emitted("hpp")
+        text = render_hpp(self.build(), writer=self._hpp_writer(writer))
         chosen = self._formatter(formatter)
         return chosen(text, self.hpp_name) if chosen else text
 
     def render_cpp(
-        self, cpp_file: str | None = None, *, formatter: Formatter | None = None
+        self,
+        cpp_file: str | None = None,
+        *,
+        formatter: Formatter | None = None,
+        writer: CppWriter | None = None,
     ) -> str:
         """Render one source file as text.  ``None`` selects the default one."""
-        text = render_cpp(self.build(), cpp_file)
+        self._require_emitted("cpp")
+        text = render_cpp(self.build(), cpp_file, writer=self._cpp_writer(writer))
         chosen = self._formatter(formatter)
         if not chosen:
             return text
@@ -109,9 +178,19 @@ class CppDocBuilder(_MemberScope[CppDoc]):
         cpp_files: Sequence[str] | None = None,
         *,
         formatter: Formatter | None = None,
+        hpp_writer: HppWriter | None = None,
+        cpp_writer: CppWriter | None = None,
     ) -> dict[str, str]:
         """Render every file this document owns, as a name-to-text mapping."""
-        return doc_files(self.build(), cpp_files, formatter=self._formatter(formatter))
+        return doc_files(
+            self.build(),
+            cpp_files,
+            formatter=self._formatter(formatter),
+            hpp_writer=self._hpp_writer(hpp_writer),
+            cpp_writer=self._cpp_writer(cpp_writer),
+            emit_hpp=self.emit_hpp,
+            emit_cpp=self.emit_cpp,
+        )
 
     def write(
         self,
@@ -119,6 +198,8 @@ class CppDocBuilder(_MemberScope[CppDoc]):
         cpp_files: Sequence[str] | None = None,
         *,
         formatter: Formatter | None = None,
+        hpp_writer: HppWriter | None = None,
+        cpp_writer: CppWriter | None = None,
         skip_unchanged: bool = True,
         encoding: str = "utf-8",
     ) -> WriteResult:
@@ -131,6 +212,10 @@ class CppDocBuilder(_MemberScope[CppDoc]):
             directory,
             cpp_files,
             formatter=self._formatter(formatter),
+            hpp_writer=self._hpp_writer(hpp_writer),
+            cpp_writer=self._cpp_writer(cpp_writer),
+            emit_hpp=self.emit_hpp,
+            emit_cpp=self.emit_cpp,
             skip_unchanged=skip_unchanged,
             encoding=encoding,
         )