embeddedpy 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of embeddedpy might be problematic. Click here for more details.

embeddedpy/__init__.py ADDED
@@ -0,0 +1,55 @@
1
+ """embeddedpy language library: the target of user source ``import``.
2
+
3
+ The compiler lives in another package, ``embeddedpy.compiler``; this package does
4
+ **not** depend on it. The dependency direction is "compiler -> language library",
5
+ and the language library does not depend on the compiler.
6
+
7
+ User source imports language symbols by category:
8
+
9
+ from embeddedpy.types import int32, uint8, Str, Array, Ptr # all types
10
+ from embeddedpy.arrays import make_array # array functions
11
+ from embeddedpy.pointers import ptr # pointer functions
12
+ from embeddedpy.enums import auto # enum functions
13
+ from embeddedpy.memory import mem # heap memory
14
+ from embeddedpy.interop import c # C interop
15
+ from embeddedpy.io import File, io # file I/O
16
+ from embeddedpy.bytes import bytes # byte buffer
17
+
18
+ **All types live in ``embeddedpy.types``** (scalars, text, containers, pointers,
19
+ aggregates, modifiers); the other modules only hold functions. The file handle
20
+ ``File`` is an opaque handle of the io domain, kept in ``embeddedpy.io``.
21
+ """
22
+
23
+ from typing import Any, List
24
+
25
+ __version__ = "0.1.0"
26
+
27
+ # Language runtime submodules: lazily imported to avoid pulling in all the
28
+ # implementation when `import embeddedpy` is run.
29
+ _LANG_MODULES = (
30
+ "types",
31
+ "arrays",
32
+ "pointers",
33
+ "enums",
34
+ "memory",
35
+ "interop",
36
+ "io",
37
+ "bytes",
38
+ )
39
+
40
+ __all__ = ["__version__"] + list(_LANG_MODULES)
41
+
42
+
43
+ def __getattr__(name: str) -> Any:
44
+ """PEP 562 lazy attribute access."""
45
+ if name in _LANG_MODULES:
46
+ import importlib
47
+
48
+ module = importlib.import_module(f".{name}", __name__)
49
+ globals()[name] = module
50
+ return module
51
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
52
+
53
+
54
+ def __dir__() -> List[str]:
55
+ return sorted(__all__)
embeddedpy/arrays.py ADDED
@@ -0,0 +1,142 @@
1
+ """Array category of embeddedpy: constructor functions for fixed-length arrays.
2
+
3
+ External usage: `from embeddedpy.arrays import make_array`.
4
+
5
+ The ``Array`` type itself lives in ``embeddedpy.types`` (it is a language-level type
6
+ with length semantics); this module only provides **the function that builds arrays**.
7
+ """
8
+
9
+ import struct
10
+
11
+ from .types import Struct
12
+
13
+
14
+ # ---------------------------------------------------------------- Array flat addressing
15
+ #
16
+ # C's multi-dimensional arrays are row-major contiguous layouts, where
17
+ # arr[i * cols + j] is equivalent to &arr[0][0] + k. CPython's nested lists are not
18
+ # contiguous memory, so here we explicitly record the shape, map the flat offset back
19
+ # to nested indices, and write back to the original object on assignment, keeping the
20
+ # visible effect consistent with the compiled C code.
21
+
22
+
23
+ def _list_shape(obj: object) -> tuple:
24
+ """Infer the shape of a nested list, e.g. [[1, 2], [3, 4]] -> (2, 2)."""
25
+ shape = []
26
+ cur = obj
27
+ while isinstance(cur, list):
28
+ shape.append(len(cur))
29
+ if not cur:
30
+ break
31
+ cur = cur[0]
32
+ return tuple(shape)
33
+
34
+ def _flat_path(shape: tuple, offset: int) -> tuple:
35
+ """Translate a flat offset into a nested index path."""
36
+ strides = []
37
+ step = 1
38
+ for dim in reversed(shape):
39
+ strides.append(step)
40
+ step *= dim
41
+ strides.reverse()
42
+ path = []
43
+ for dim, stride in zip(shape, strides):
44
+ path.append(offset // stride)
45
+ offset = offset % stride
46
+ return tuple(path)
47
+
48
+ def _flat_get(base: list, shape: tuple, offset: int) -> object:
49
+ path = _flat_path(shape, offset)
50
+ obj = base
51
+ for i in path[:-1]:
52
+ obj = obj[i]
53
+ return obj[path[-1]]
54
+
55
+ def _flat_set(base: list, shape: tuple, offset: int, value: object) -> None:
56
+ path = _flat_path(shape, offset)
57
+ obj = base
58
+ for i in path[:-1]:
59
+ obj = obj[i]
60
+ obj[path[-1]] = value
61
+
62
+ def _elem_size(elem_type: object) -> int:
63
+ """Byte count of an element, for offset arithmetic on raw-address pointers."""
64
+ bits = getattr(elem_type, "bits", None)
65
+ if bits is None:
66
+ return 0
67
+ return bits // 8
68
+
69
+ _STRUCT_CODE = {
70
+ "int8": "b", "int16": "h", "int32": "i", "int64": "q",
71
+ "uint8": "B", "uint16": "H", "uint32": "I", "uint64": "Q",
72
+ "float32": "f", "float64": "d",
73
+ }
74
+
75
+ # Single-byte character types: the element values in the heap are str / bytes,
76
+ # consistent with the development track's character types.
77
+ _CHAR_ELEM_NAMES = ("char", "schar", "uchar")
78
+
79
+
80
+ def _decode(raw: bytes, elem_type: object) -> object:
81
+ """Decode several bytes into a value using C's fixed-width semantics."""
82
+ name = getattr(elem_type, "name", None)
83
+ if name in _CHAR_ELEM_NAMES:
84
+ # Text type (char) decodes into a str; byte types (schar / uchar) decode into bytes.
85
+ if name == "char":
86
+ return raw[0:1].decode("latin-1")
87
+ return raw[0:1]
88
+ code = _STRUCT_CODE.get(name)
89
+ if code is None:
90
+ raise TypeError(f"heap memory does not support element type {name}")
91
+ return struct.unpack("<" + code, raw)[0]
92
+
93
+
94
+ def _encode(value: object, elem_type: object) -> bytes:
95
+ """Encode a value into bytes using C's fixed-width semantics."""
96
+ name = getattr(elem_type, "name", None)
97
+ if name in _CHAR_ELEM_NAMES:
98
+ if isinstance(value, str):
99
+ return value.encode("latin-1")[0:1]
100
+ if isinstance(value, bytes):
101
+ return value[0:1]
102
+ raise ValueError(
103
+ f"value {value!r} cannot be stored in {name}; character types "
104
+ "take a string or bytes value"
105
+ )
106
+ code = _STRUCT_CODE.get(name)
107
+ if code is None:
108
+ raise TypeError(f"heap memory does not support element type {name}")
109
+ try:
110
+ return struct.pack("<" + code, value)
111
+ except struct.error as exc:
112
+ raise ValueError(f"value {value!r} cannot be stored in {name}") from exc
113
+
114
+
115
+ def _zero_field(ann: object) -> object:
116
+ """Build a zero value from a field annotation, recursively supporting nested structs."""
117
+ if isinstance(ann, type) and issubclass(ann, Struct):
118
+ return ann(*[
119
+ _zero_field(a) for a in getattr(ann, "__annotations__", {}).values()
120
+ ])
121
+ return 0
122
+
123
+
124
+ def make_array(elem_type: object, length: int) -> list:
125
+ """Create a fixed-length array: make_array(int32, 3) corresponds to C's int32_t buf[3] (all zeros)."""
126
+ if isinstance(length, bool) or not isinstance(length, int):
127
+ raise TypeError("make_array length must be an integer")
128
+ if length <= 0:
129
+ raise ValueError("make_array length must be a positive integer")
130
+ if isinstance(elem_type, type) and issubclass(elem_type, Struct):
131
+ # Structs build a zero value per field count, corresponding to C's (T){0};
132
+ # elem_type(0) can only handle single-field structs.
133
+ fields = list(getattr(elem_type, "__annotations__", {}).values())
134
+ return [elem_type(*[_zero_field(f) for f in fields]) for _ in range(length)]
135
+ if callable(elem_type):
136
+ return [elem_type(0) for _ in range(length)]
137
+ return [0] * length
138
+
139
+
140
+ __all__ = [
141
+ "make_array",
142
+ ]
embeddedpy/bytes.py ADDED
@@ -0,0 +1,65 @@
1
+ """Byte entry/exit points for byte buffers.
2
+
3
+ External usage: ``from embeddedpy.bytes import bytes``.
4
+
5
+ ``Bytes`` is an immutable value with a length; the C-side byte buffer interface
6
+ wants a raw address + length. This module provides an explicit pair of entry/exit
7
+ points between the two representations:
8
+
9
+ - ``bytes.data(b)``: copy out a byte copy and return an ``unsigned char *`` pointing to it;
10
+ - ``bytes.from_ptr(p, n)``: copy from "pointer + byte length" into a byte-string value.
11
+
12
+ Both directions copy: the outgoing copy and the incoming byte string are detached
13
+ from each other. Use ``bytes.byte_len(b)`` for the byte length (same as ``len(b)``);
14
+ raw bytes may contain 0x00, with no NUL terminator and no NUL-based truncation --
15
+ pointer and length are used as a pair.
16
+ """
17
+
18
+ import builtins
19
+ from typing import Any
20
+
21
+ from .pointers import _Ptr, _read_byte_view
22
+
23
+
24
+ class _BytesAPI:
25
+ """Byte buffer API: free functions, no methods introduced."""
26
+
27
+ __slots__ = ()
28
+
29
+ @staticmethod
30
+ def data(b: Any) -> Any:
31
+ """Get a copy pointer of the byte buffer (corresponds to C's ``unsigned char *``).
32
+
33
+ Copy: the bytes are copied into an owned buffer, and a pointer to the copy is
34
+ returned. Modifying the copy does not affect the original byte string; the copy
35
+ is byte-addressable and can be read/written with ``ptr.peek`` / ``ptr.poke`` and
36
+ moved with ``ptr.skip``.
37
+ """
38
+ if not isinstance(b, builtins.bytes):
39
+ raise TypeError("bytes.data expects a Bytes value")
40
+ return _Ptr._make_byte_copy(b, text=False)
41
+
42
+ @staticmethod
43
+ def byte_len(b: Any) -> int:
44
+ """Byte length (same as ``len(b)``)."""
45
+ if not isinstance(b, builtins.bytes):
46
+ raise TypeError("bytes.byte_len expects a Bytes value")
47
+ return len(b)
48
+
49
+ @staticmethod
50
+ def from_ptr(p: Any, n: Any) -> Any:
51
+ """Build a byte string from "pointer + byte length" (corresponds to C's
52
+ ``unsigned char *`` + length).
53
+
54
+ Copy: the resulting byte string is detached from the original buffer, so it is
55
+ unaffected even if the original buffer later becomes invalid. May contain 0x00,
56
+ with no NUL-based truncation.
57
+ """
58
+ return _read_byte_view(p, n)
59
+
60
+
61
+ bytes = _BytesAPI()
62
+
63
+ __all__ = [
64
+ "bytes",
65
+ ]
@@ -0,0 +1,55 @@
1
+ """embeddedpy compiler: compile programs written in valid Python syntax into C99 source files.
2
+
3
+ This is the **tool** implementation (CLI, type checking, code generation), kept
4
+ separate in its own top-level package from the language library ``embeddedpy``
5
+ that user source imports. The dependency direction is:
6
+
7
+ embeddedpy.compiler (compiler) → embeddedpy (language library)
8
+
9
+ The language library does not import the compiler, so when the user writes
10
+ ``from embeddedpy.types import int32``, the name they get belongs to the language
11
+ semantics layer and does not expose the compiler's internal implementation.
12
+
13
+ A host program can use it like this:
14
+
15
+ from embeddedpy.compiler import compile_file, CompileConfig
16
+ """
17
+
18
+ from typing import Any, List
19
+
20
+ # The version number is at the release-package level; its single source is the
21
+ # language library (the compiler depends on the language library, consistent
22
+ # direction).
23
+ from embeddedpy import __version__
24
+
25
+ # Public names of the compiler itself. **Lazy import**: the compiler is only
26
+ # loaded when one of these attributes is actually accessed, so the "language
27
+ # runtime only" path (running examples directly under CPython) does not pay the
28
+ # cost of importing ast/inspect.
29
+
30
+ _API_EXPORTS = (
31
+ "CompileError",
32
+ "Diagnostic",
33
+ "check_file",
34
+ "check_source",
35
+ "compile_file",
36
+ "compile_source",
37
+ "CompileConfig",
38
+ )
39
+
40
+ __all__ = ["__version__"] + list(_API_EXPORTS)
41
+
42
+
43
+ def __getattr__(name: str) -> Any:
44
+ """PEP 562 lazy attribute access."""
45
+ if name in _API_EXPORTS:
46
+ from . import api
47
+
48
+ value = getattr(api, name)
49
+ globals()[name] = value
50
+ return value
51
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
52
+
53
+
54
+ def __dir__() -> List[str]:
55
+ return sorted(__all__)
@@ -0,0 +1,8 @@
1
+ """Support invocation via python -m embeddedpy."""
2
+
3
+ import sys
4
+
5
+ from .cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
@@ -0,0 +1,337 @@
1
+ """Public API of the embeddedpy compiler.
2
+
3
+ The import stage does no compilation and does not probe for a C compiler, so it
4
+ can still be imported and produce C code even without a compiler installed.
5
+
6
+ - ``compile_source`` / ``check_source``: for **single-file string** source (no user module imports).
7
+ - ``compile_file`` / ``check_file`` : for an **entry file** on disk; it automatically resolves its imported user modules and inlines them into a single translation unit (see ``modules.build_program``).
8
+ """
9
+
10
+ import ast
11
+ import os
12
+ import re
13
+ import sys
14
+ from pathlib import Path
15
+ from typing import List, Optional, Union
16
+
17
+ from . import codegen, modules
18
+ from .checker import check_tree
19
+ from .config import DEFAULT_OUTPUT_DIR, CompileConfig
20
+ from .errors import CompileError, Diagnostic
21
+ from .frontend import gate, parse_source
22
+
23
+ # The single source of the version number is the language library (the compiler
24
+ # depends on the language library, consistent direction).
25
+ from embeddedpy import __version__
26
+
27
+ __all__ = [
28
+ "compile_source",
29
+ "compile_file",
30
+ "check_source",
31
+ "check_file",
32
+ "CompileConfig",
33
+ "Diagnostic",
34
+ "CompileError",
35
+ "__version__",
36
+ ]
37
+
38
+
39
+ def _tree_shake(tree: ast.Module, info) -> int:
40
+ """Remove unreachable top-level functions and return the number removed; must run after check_tree, so type errors in removed functions are still reported.
41
+
42
+ Roots = functions referenced by top-level statements that go into main + @c.export / @c.extern_function / weak functions + main.
43
+ If the source contains textual symbol references such as c.emit / c.asm / c.goto / c.label, skip the whole pass —
44
+ the AST cannot see symbol names inside strings, so removal cannot be guaranteed safe.
45
+ """
46
+ funcs = info.functions
47
+ if not funcs:
48
+ return 0
49
+ for node in ast.walk(tree):
50
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) \
51
+ and node.func.attr in ("emit", "asm", "goto", "label"):
52
+ return 0
53
+
54
+ def load_names(nodes) -> set:
55
+ found = set()
56
+ for node in nodes:
57
+ for sub in ast.walk(node):
58
+ if isinstance(sub, ast.Name) and isinstance(sub.ctx, ast.Load):
59
+ found.add(sub.id)
60
+ return found
61
+
62
+ roots = {"main"}
63
+ for name, fi in funcs.items():
64
+ if fi.is_extern or fi.export_c_name or fi.is_weak:
65
+ roots.add(name)
66
+ top_non_func = [s for s in tree.body if not isinstance(s, ast.FunctionDef)]
67
+ work = [n for n in (load_names(top_non_func) | roots) if n in funcs]
68
+ reachable = set()
69
+ while work:
70
+ name = work.pop()
71
+ if name in reachable:
72
+ continue
73
+ reachable.add(name)
74
+ for ref in load_names([funcs[name].node]):
75
+ if ref in funcs and ref not in reachable:
76
+ work.append(ref)
77
+ removed = set(funcs) - reachable
78
+ if not removed:
79
+ return 0
80
+ tree.body[:] = [s for s in tree.body
81
+ if not (isinstance(s, ast.FunctionDef) and s.name in removed)]
82
+ for name in removed:
83
+ del funcs[name]
84
+ info.scope.pop(name, None)
85
+ return len(removed)
86
+
87
+
88
+ def _compile_tree(
89
+ tree: ast.Module, filename: str, config: Optional[CompileConfig] = None
90
+ ) -> str:
91
+ gate(tree, filename)
92
+ info = check_tree(tree, filename, config)
93
+ _tree_shake(tree, info)
94
+ return codegen.generate(tree, info, filename, config)
95
+
96
+
97
+ def compile_source(
98
+ source: str, filename: str = "<string>", config: Optional[CompileConfig] = None
99
+ ) -> str:
100
+ """Compile **single-file** source into C text. Raises CompileError on failure."""
101
+ tree = parse_source(source, filename)
102
+ return _compile_tree(tree, filename, config)
103
+
104
+
105
+ def _default_output_name(src_path: Path) -> str:
106
+ """Default output name: the source file name; entry names like ``main.py`` use the containing folder name."""
107
+ stem = src_path.stem
108
+ if stem in ("main", "__main__", "index"):
109
+ parent = src_path.parent.name
110
+ if parent:
111
+ return parent
112
+ return stem
113
+
114
+
115
+ def _render_output_name(template: str, src_path: Path) -> str:
116
+ """Replace ``${fileName}`` in the output_name template with the source file base name.
117
+
118
+ Only the ``${fileName}`` variable is recognized; an unknown variable name
119
+ causes compilation to fail.
120
+ """
121
+ stem = src_path.stem
122
+
123
+ def repl(match: "re.Match") -> str:
124
+ var = match.group(1)
125
+ if var == "fileName":
126
+ return stem
127
+ raise CompileError(
128
+ [
129
+ Diagnostic(
130
+ message=(
131
+ f"unknown output_name variable: ${{{var}}} "
132
+ f"(only ${{fileName}} is supported)"
133
+ ),
134
+ code="config",
135
+ )
136
+ ]
137
+ )
138
+
139
+ return re.sub(r"\$\{([^}]+)\}", repl, template)
140
+
141
+
142
+ def _resolve_output_base(src_path: Path, config: Optional[CompileConfig]) -> Path:
143
+ """Compute the output base path (without the ``.c`` extension).
144
+
145
+ Priority: ``output`` in config (full path) > ``output_dir`` + ``output_name``
146
+ (supports the ``${fileName}`` template) > built-in default. Both the CLI and
147
+ TOML write into the same ``CompileConfig``, so there is only this one
148
+ resolution path.
149
+
150
+ The base for relative paths is "the directory containing the config file";
151
+ with no config file it degrades to "the directory containing the source file".
152
+ The caller appends ``.c`` per variant (if the template result already ends
153
+ with ``.c`` it is not appended again).
154
+ """
155
+ default_name = _default_output_name(src_path)
156
+
157
+ if config is None:
158
+ config = CompileConfig()
159
+
160
+ base = Path(config.config_dir) if config.config_dir else src_path.parent
161
+
162
+ # 1) Write the full path at once
163
+ if config.output:
164
+ target = base / config.output
165
+ else:
166
+ # 2) Directory + name configured separately
167
+ out_dir = config.output_dir if config.output_dir else DEFAULT_OUTPUT_DIR
168
+ name = (
169
+ _render_output_name(config.output_name, src_path)
170
+ if config.output_name
171
+ else default_name
172
+ )
173
+ target = base / out_dir / name
174
+
175
+ target = Path(os.path.normpath(str(target)))
176
+ return target.with_suffix("") if target.suffix in (".c", ".h") else target
177
+
178
+
179
+ def _flatten_assets(cfg: CompileConfig, out_dir: Path, written: List[Path]) -> None:
180
+ """Recursively flatten assets_dir into out_dir (flattening; subdirectory structure is lost).
181
+
182
+ After flattening, same-named files collide -> compilation fails.
183
+ """
184
+ root = (
185
+ Path(cfg.config_dir) / cfg.assets_dir
186
+ if cfg.config_dir
187
+ else Path(cfg.assets_dir)
188
+ )
189
+ if not root.is_dir():
190
+ return # Directory does not exist: silently skip (the default "assets"
191
+ # won't accidentally disturb projects without an asset directory)
192
+ files: List[Path] = []
193
+ for dirpath, _dirs, names in os.walk(root):
194
+ for name in names:
195
+ files.append(Path(dirpath) / name)
196
+ basenames = [f.name for f in files]
197
+ dupes = sorted({n for n in basenames if basenames.count(n) > 1})
198
+ if dupes:
199
+ raise CompileError(
200
+ [
201
+ Diagnostic(
202
+ message=f"assets_dir flatten collision: {', '.join(dupes)}",
203
+ code="config",
204
+ )
205
+ ]
206
+ )
207
+ for f in files:
208
+ dest = out_dir / f.name
209
+ dest.write_bytes(f.read_bytes())
210
+ written.append(dest)
211
+
212
+
213
+ def _link_script_source(cfg: CompileConfig, src_path: Path) -> Optional[Path]:
214
+ """Source path of the link script: relative to config_dir (or to the entry file directory if there is no config file)."""
215
+ if not cfg.link_script:
216
+ return None
217
+ path = Path(cfg.link_script)
218
+ if path.is_absolute():
219
+ return path
220
+ base = Path(cfg.config_dir) if cfg.config_dir else src_path.parent
221
+ return base / path
222
+
223
+
224
+ def validate_link_config(cfg: CompileConfig, src_path: Path) -> None:
225
+ """Only validate the shape of the link config and the script's existence; never invoke the linker."""
226
+ cfg.validate()
227
+ source = _link_script_source(cfg, src_path)
228
+ if source is not None and not source.is_file():
229
+ raise CompileError(
230
+ [
231
+ Diagnostic(
232
+ message=f"link_script not found: {source}",
233
+ filename=str(source),
234
+ code="config",
235
+ )
236
+ ]
237
+ )
238
+
239
+
240
+ def _copy_link_script(
241
+ cfg: CompileConfig, src_path: Path, out_dir: Path, written: List[Path]
242
+ ) -> Optional[Path]:
243
+ """Copy the link script into the output directory under its original name, returning the copied path."""
244
+ source = _link_script_source(cfg, src_path)
245
+ if source is None:
246
+ return None
247
+ dest = out_dir / source.name
248
+ dest.write_bytes(source.read_bytes())
249
+ written.append(dest)
250
+ return dest
251
+
252
+
253
+ def _print_link_hint(
254
+ cfg: CompileConfig, c_path: Path, script: Optional[Path]
255
+ ) -> None:
256
+ """Summarize the known information into a copyable link command, written to stderr."""
257
+ if not cfg.link_configured:
258
+ return
259
+ cc = os.environ.get("CC") or "cc"
260
+ parts = [cc, "-std=c99", *cfg.link_flags]
261
+ if script is not None:
262
+ parts += ["-T", str(script)]
263
+ parts += ["-o", str(c_path.with_suffix(".elf")), str(c_path)]
264
+ parts += ["-l" + name for name in cfg.link_libs]
265
+ print("link hint: " + " ".join(parts), file=sys.stderr)
266
+
267
+
268
+ def compile_file(
269
+ path: Union[str, Path],
270
+ config: Optional[CompileConfig] = None,
271
+ ) -> List[Path]:
272
+ """Compile the entry file on disk (including its imported user modules) and write out C.
273
+
274
+ Returns all written file paths: when ``line_output`` is ``both`` it includes
275
+ ``foo.c`` and ``foo.line.c``, otherwise only ``foo.c``; if ``assets_dir`` is
276
+ configured it also includes the flattened asset files.
277
+ """
278
+ src_path = Path(path)
279
+ cfg = config or CompileConfig()
280
+ validate_link_config(cfg, src_path)
281
+ tree, filename = modules.build_program(src_path)
282
+ gate(tree, filename)
283
+ info = check_tree(tree, filename, cfg)
284
+ _tree_shake(tree, info)
285
+
286
+ mode = cfg.line_output
287
+ ext = ".h" if cfg.output_type == "header" else ".c"
288
+ base = _resolve_output_base(src_path, cfg)
289
+ base.parent.mkdir(parents=True, exist_ok=True)
290
+
291
+ written: List[Path] = []
292
+ # Primary output foo.c / foo.h: line mode carries #line; noline / both do not
293
+ primary = codegen.generate(tree, info, filename, cfg, emit_line=(mode == "line"))
294
+ primary_path = base.with_suffix(ext)
295
+ primary_path.write_text(primary, encoding="utf-8")
296
+ written.append(primary_path)
297
+
298
+ if mode == "both" and cfg.output_type != "header":
299
+ line_text = codegen.generate(tree, info, filename, cfg, emit_line=True)
300
+ line_path = base.parent / (base.name + ".line.c")
301
+ line_path.write_text(line_text, encoding="utf-8")
302
+ written.append(line_path)
303
+
304
+ if cfg.assets_dir:
305
+ _flatten_assets(cfg, base.parent, written)
306
+
307
+ if cfg.link_configured:
308
+ script = _copy_link_script(cfg, src_path, base.parent, written)
309
+ _print_link_hint(cfg, primary_path, script)
310
+
311
+ return written
312
+
313
+
314
+ def check_source(source: str, filename: str = "<string>") -> List[Diagnostic]:
315
+ """Only run the subset gate and type checking (single file), returning the diagnostic list (empty list means passed)."""
316
+ try:
317
+ compile_source(source, filename)
318
+ except CompileError as exc:
319
+ return exc.diagnostics
320
+ return []
321
+
322
+
323
+ def check_file(
324
+ path: Union[str, Path],
325
+ config: Optional[CompileConfig] = None,
326
+ ) -> List[Diagnostic]:
327
+ """Only run the subset gate and type checking (including user module imports), returning the diagnostic list."""
328
+ src_path = Path(path)
329
+ cfg = config or CompileConfig()
330
+ try:
331
+ tree, filename = modules.build_program(src_path)
332
+ # Use the same config: check and build must report the same set of errors
333
+ # related to the output shape
334
+ _compile_tree(tree, filename, cfg)
335
+ except CompileError as exc:
336
+ return exc.diagnostics
337
+ return []