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

fprime_cpp_codegen/builder/definitions.py

@@ -0,0 +1,381 @@
+"""Builders for the things a scope holds: functions, constructors, enums."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from enum import Enum
+
+from ..body import Body, Code
+from ..comments import (
+    add_param_comment,
+    write_doxygen_comment,
+    write_doxygen_comment_opt,
+)
+from ..doc import 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
+
+
+class Radix(Enum):
+    """How to spell an integer literal."""
+
+    DECIMAL = "decimal"
+    HEX = "hex"
+
+
+def _wrap_in_enum(
+    body: list[Line],
+    *,
+    name: str | None = None,
+    scoped: bool = False,
+    underlying: str | None = None,
+) -> list[Line]:
+    """Wrap enumerators in an ``enum``, ``enum <name>`` or ``enum class <name>``."""
+    if scoped:
+        suffix = f" : {underlying}" if underlying is not None else ""
+        opening = f"enum class {name}{suffix} {{"
+    elif name is not None:
+        opening = f"enum {name} {{"
+    else:
+        opening = "enum {"
+    return wrap_in_scope(opening, body, "};", keep_empty=True)
+
+
+class FunctionBuilder(_Builder[Function]):
+    """A function or member function under construction."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        ret: Type | str = "void",
+        params: Iterable[Param | Sequence[str]] = (),
+        comment: str | None = None,
+        body: Code = None,
+        const: bool = False,
+        static: bool = False,
+        virtual: bool = False,
+        pure_virtual: bool = False,
+        override: bool = False,
+        final: bool = False,
+        constexpr: bool = False,
+        inline: bool = False,
+        noexcept: bool = False,
+        deleted: bool = False,
+        defaulted: bool = False,
+        template: str | None = None,
+        inline_body: bool = False,
+        cpp_file: str | None = None,
+    ) -> None:
+        if not name:
+            raise ValidationError("a function needs a name")
+        self.name = name
+        self.ret = as_type(ret)
+        self.comment = comment
+        self.const = const
+        self.constexpr = constexpr
+        self.inline = inline
+        self.noexcept = noexcept
+        self.deleted = deleted
+        self.defaulted = defaulted
+        self.template = template
+        self.inline_body = inline_body
+        self.cpp_file = cpp_file
+        self._sv = _sv_qualifier(
+            static=static,
+            virtual=virtual,
+            pure_virtual=pure_virtual,
+            override=override,
+            final=final,
+        )
+        self._params = _as_params(params)
+        self.body = Body(_as_body_lines(body))
+
+    def param(
+        self,
+        type_name: Type | str,
+        name: str,
+        *,
+        comment: str | None = None,
+        default: str | None = None,
+    ) -> FunctionBuilder:
+        """Append one formal parameter.  Returns self, so calls can be chained."""
+        self._params.append(Param(as_type(type_name), name, comment, default))
+        return self
+
+    def params(self, *params: Param | Sequence[str]) -> FunctionBuilder:
+        """Append several formal parameters at once."""
+        self._params.extend(_as_params(params))
+        return self
+
+    def build(self) -> Function:
+        return Function(
+            self.name,
+            params=list(self._params),
+            ret_type=self.ret,
+            body=self.body.build(),
+            comment=self.comment,
+            sv=self._sv,
+            const=self.const,
+            constexpr=self.constexpr,
+            inline=self.inline,
+            noexcept=self.noexcept,
+            deleted=self.deleted,
+            defaulted=self.defaulted,
+            template=self.template,
+            inline_body=self.inline_body,
+            cpp_file=self.cpp_file,
+        )
+
+    def __enter__(self) -> FunctionBuilder:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+class ConstructorBuilder(_Builder[Constructor]):
+    """A constructor under construction."""
+
+    def __init__(
+        self,
+        *,
+        params: Iterable[Param | Sequence[str]] = (),
+        initializers: Iterable[str] = (),
+        comment: str | None = None,
+        body: Code = None,
+        explicit: bool = False,
+        constexpr: bool = False,
+        noexcept: bool = False,
+        deleted: bool = False,
+        defaulted: bool = False,
+        template: str | None = None,
+        inline_body: bool = False,
+        cpp_file: str | None = None,
+    ) -> None:
+        self.comment = comment
+        self.explicit = explicit
+        self.constexpr = constexpr
+        self.noexcept = noexcept
+        self.deleted = deleted
+        self.defaulted = defaulted
+        self.template = template
+        self.inline_body = inline_body
+        self.cpp_file = cpp_file
+        self._params = _as_params(params)
+        self._initializers = list(initializers)
+        self.body = Body(_as_body_lines(body))
+
+    def param(
+        self,
+        type_name: Type | str,
+        name: str,
+        *,
+        comment: str | None = None,
+        default: str | None = None,
+    ) -> ConstructorBuilder:
+        """Append one formal parameter."""
+        self._params.append(Param(as_type(type_name), name, comment, default))
+        return self
+
+    def params(self, *params: Param | Sequence[str]) -> ConstructorBuilder:
+        """Append several formal parameters at once."""
+        self._params.extend(_as_params(params))
+        return self
+
+    def init(self, *entries: str) -> ConstructorBuilder:
+        """Append member-initializer entries, e.g. ``init("m_size(size)")``."""
+        self._initializers.extend(entries)
+        return self
+
+    def build(self) -> Constructor:
+        return Constructor(
+            params=list(self._params),
+            initializers=list(self._initializers),
+            body=self.body.build(),
+            comment=self.comment,
+            explicit=self.explicit,
+            constexpr=self.constexpr,
+            noexcept=self.noexcept,
+            deleted=self.deleted,
+            defaulted=self.defaulted,
+            template=self.template,
+            inline_body=self.inline_body,
+            cpp_file=self.cpp_file,
+        )
+
+    def __enter__(self) -> ConstructorBuilder:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+class DestructorBuilder(_Builder[Destructor]):
+    """A destructor under construction."""
+
+    def __init__(
+        self,
+        *,
+        comment: str | None = None,
+        body: Code = None,
+        virtual: bool = False,
+        override: bool = False,
+        noexcept: bool = False,
+        deleted: bool = False,
+        defaulted: bool = False,
+        inline_body: bool = False,
+        cpp_file: str | None = None,
+    ) -> None:
+        self.comment = comment
+        self.virtual = virtual
+        self.override = override
+        self.noexcept = noexcept
+        self.deleted = deleted
+        self.defaulted = defaulted
+        self.inline_body = inline_body
+        self.cpp_file = cpp_file
+        self.body = Body(_as_body_lines(body))
+
+    def build(self) -> Destructor:
+        return Destructor(
+            body=self.body.build(),
+            comment=self.comment,
+            virtual=self.virtual,
+            override=self.override,
+            noexcept=self.noexcept,
+            deleted=self.deleted,
+            defaulted=self.defaulted,
+            inline_body=self.inline_body,
+            cpp_file=self.cpp_file,
+        )
+
+    def __enter__(self) -> DestructorBuilder:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+class EnumBuilder(_Builder[Lines]):
+    """An enum or enum class under construction.  Renders as raw lines."""
+
+    def __init__(
+        self,
+        name: str | None = None,
+        *,
+        underlying: str | None = None,
+        scoped: bool = False,
+        comment: str | None = None,
+        output: Output = Output.HPP,
+        cpp_file: str | None = None,
+        radix: Radix = Radix.DECIMAL,
+        trailing_comma: bool = True,
+        comment_above: bool = False,
+        qualifier: str = "",
+    ) -> None:
+        if underlying is not None and not scoped:
+            raise ValidationError(
+                "an underlying type needs a scoped enum; pass scoped=True (or use "
+                "enum_class())"
+            )
+        if scoped and not name:
+            raise ValidationError("a scoped enum needs a name")
+        self.name = name
+        self.underlying = underlying
+        self.scoped = scoped
+        self.comment = comment
+        self.output = output
+        self.cpp_file = cpp_file
+        self.radix = radix
+        self.trailing_comma = trailing_comma
+        """Whether the last enumerator carries a comma.  Legal either way."""
+
+        self.comment_above = comment_above
+        """Put each enumerator's comment on a ``//!`` line above it, instead of a
+        ``//!<`` post-comment after it."""
+
+        self.qualifier = qualifier
+        self._constants: list[list[Line]] = []
+
+    @property
+    def type(self) -> Type:
+        """This enum as a :class:`Type`, qualified for use in a source file.
+
+        A nested enum is spelled bare inside its class, but a source-file return type
+        precedes ``Class::`` and so is not yet in the class's scope.  Pass this to
+        ``ret=`` for both spellings::
+
+            status = cls.enum_class("Status", underlying="U8")
+            cls.function("check", ret=status.type)
+        """
+        if self.name is None:
+            raise ValidationError("an anonymous enum has no type name")
+        return Type(
+            self.name, f"{self.qualifier}::{self.name}" if self.qualifier else None
+        )
+
+    def constant(
+        self,
+        name: str,
+        value: int | str | None = None,
+        *,
+        comment: str | None = None,
+        radix: Radix | None = None,
+    ) -> EnumBuilder:
+        """Append one enumerator.
+
+        ``value`` may be an integer, an arbitrary C++ expression, or ``None`` to let
+        the compiler assign the next value.
+        """
+        if value is None:
+            text = f"{name},"
+        elif isinstance(value, int):
+            spelled = (
+                f"0x{value:x}" if (radix or self.radix) is Radix.HEX else str(value)
+            )
+            text = f"{name} = {spelled},"
+        else:
+            text = f"{name} = {value},"
+        if comment is not None and self.comment_above:
+            entry = [*write_doxygen_comment(comment)[1:], _line(text)]
+        else:
+            entry = add_param_comment(text, comment)
+        self._constants.append(entry)
+        return self
+
+    def constants(self, *names: str) -> EnumBuilder:
+        """Append several auto-numbered enumerators at once."""
+        for name in names:
+            self.constant(name)
+        return self
+
+    def _body(self) -> list[Line]:
+        """The enumerators, with the last one's comma removed if asked."""
+        entries = [list(e) for e in self._constants]
+        if entries and not self.trailing_comma:
+            last = entries[-1]
+            last[-1] = Line(last[-1].string.rstrip(","), last[-1].indent)
+        return [l for entry in entries for l in entry]
+
+    def build(self) -> Lines:
+        inner = _wrap_in_enum(
+            self._body(),
+            name=self.name,
+            scoped=self.scoped,
+            underlying=self.underlying,
+        )
+        return Lines(
+            [*write_doxygen_comment_opt(self.comment), *inner],
+            self.output,
+            self.cpp_file,
+        )
+
+    def __enter__(self) -> EnumBuilder:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None

fprime_cpp_codegen/builder/document.py

@@ -0,0 +1,155 @@
+"""The document scope: one header plus one or more source files, and their output."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from pathlib import Path
+
+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 .base import _DocContext
+from .scopes import _MemberScope
+
+
+class CppDocBuilder(_MemberScope[CppDoc]):
+    """A whole C++ document: one header and one or more source files."""
+
+    def __init__(
+        self,
+        file_base: str,
+        *,
+        description: str | None = None,
+        include_guard: str | None = None,
+        namespaces: Sequence[str] = (),
+        tool_name: str | None = None,
+        file_banner: FileBanner | None = None,
+        formatter: Formatter | None = None,
+        hpp_extension: str = "hpp",
+        cpp_extension: str = "cpp",
+    ) -> None:
+        """Start a document whose files are named after ``file_base``.
+
+        ``include_guard`` defaults to one derived from ``file_base`` and
+        ``namespaces``; ``namespaces`` is used for nothing else, so pass it when you
+        want ``Fw_Cfg_MyClass_HPP`` without spelling the macro out.
+
+        ``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.
+        """
+        super().__init__(_DocContext())
+        if not file_base:
+            raise ValidationError("a document needs a file name base")
+        self.file_base = file_base
+        self.description = description if description is not None else file_base
+        self.hpp_extension = hpp_extension
+        self.cpp_extension = cpp_extension
+        self.tool_name = tool_name
+        self.formatter = formatter
+        """Applied to every file this document renders, unless a call overrides it."""
+
+        self.file_banner = file_banner
+        """Overrides the ``\\title``/``\\author``/``\\brief`` block atop each file.
+        Distinct from :meth:`banner`, which emits a section comment."""
+
+        self.include_guard = (
+            include_guard
+            if include_guard is not None
+            else _default_guard(file_base, namespaces, hpp_extension)
+        )
+
+    @property
+    def hpp_name(self) -> str:
+        """The header file name, e.g. ``"MyClass.hpp"``."""
+        return f"{self.file_base}.{self.hpp_extension}"
+
+    @property
+    def cpp_name(self) -> str:
+        """The default source file name, e.g. ``"MyClass.cpp"``."""
+        return f"{self.file_base}.{self.cpp_extension}"
+
+    def build(self) -> CppDoc:
+        return CppDoc(
+            description=self.description,
+            hpp_file=HppFile(self.hpp_name, self.include_guard),
+            cpp_file_name=self.cpp_name,
+            members=self._built_members(),
+            tool_name=self.tool_name,
+            banner=self.file_banner,
+        )
+
+    # -- 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:
+        """Render the header as text."""
+        text = render_hpp(self.build())
+        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
+    ) -> str:
+        """Render one source file as text.  ``None`` selects the default one."""
+        text = render_cpp(self.build(), cpp_file)
+        chosen = self._formatter(formatter)
+        if not chosen:
+            return text
+        name = f"{cpp_file}.{self.cpp_extension}" if cpp_file else self.cpp_name
+        return chosen(text, name)
+
+    def files(
+        self,
+        cpp_files: Sequence[str] | None = None,
+        *,
+        formatter: Formatter | 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))
+
+    def write(
+        self,
+        directory: str | Path = ".",
+        cpp_files: Sequence[str] | None = None,
+        *,
+        formatter: Formatter | None = None,
+        skip_unchanged: bool = True,
+        encoding: str = "utf-8",
+    ) -> WriteResult:
+        """Write every file this document owns into ``directory``.
+
+        Supplemental source files are discovered automatically.
+        """
+        return write_doc(
+            self.build(),
+            directory,
+            cpp_files,
+            formatter=self._formatter(formatter),
+            skip_unchanged=skip_unchanged,
+            encoding=encoding,
+        )
+
+    def __enter__(self) -> CppDocBuilder:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+def _default_guard(
+    file_base: str, namespaces: Sequence[str], hpp_extension: str
+) -> str:
+    """Derive an include-guard macro from the file base, namespaces and extension.
+
+    ``_default_guard("MyClass", ["Fw", "Cfg"], "hpp")`` gives ``"Fw_Cfg_MyClass_HPP"``.
+    Namespace arguments may themselves be qualified with ``::`` or ``.``.
+    """
+    parts = [part for ns in namespaces for part in re.split(r"::|\.", ns) if part]
+    ident = re.sub(r"[^A-Za-z0-9_]+", "_", "_".join([*parts, file_base])).strip("_")
+    return f"{ident}_{hpp_extension.upper()}"