@typecad/framework-arduino 0.1.0-alpha.1

package/dist/strategy.d.ts

@@ -0,0 +1,174 @@
+import type { PlatformStrategy, ExpressionIR, ProgramIR, Diagnostic, PlatformContext, BoardConstants, RuntimePolyfillIR, StdLibSupport, AsyncRuntimeConfig, GraphicsCapacity, DisplayHALOp } from "@typecad/cuttlefish/api/shared";
+import type { HALOpIR } from "@typecad/cuttlefish/api/shared";
+/**
+ * Arduino-specific platform context.
+ * Accessed via `PlatformContext` index signature: `arduinoCtx(ctx)`.
+ */
+export interface ArduinoPlatformContext {
+    buildTarget?: string;
+}
+export declare class ArduinoStrategy implements PlatformStrategy {
+    readonly id = "arduino";
+    private _cachedProfile;
+    private _cachedProfileKey;
+    /** Architecture extracted from FQBN, used for ISR attribute emission. */
+    private _cachedArch;
+    /** Track whether the current program uses createPinGroup() */
+    private _usesPinGroup;
+    /**
+     * Allows the emitter to inform this strategy which enums have large values
+     * so that static_cast uses `long` instead of `int`.
+     */
+    setLargeEnumNames(names: ReadonlySet<string>): void;
+    /**
+     * Clears the cached profile. Should be called between transpilations.
+     */
+    clearProfileCache(): void;
+    /**
+     * Gets or resolves the Arduino profile, caching the result.
+     */
+    private getOrResolveProfile;
+    forcedIncludes(program: ProgramIR, ctx?: PlatformContext): string[];
+    symbolAliases(program: ProgramIR, ctx?: PlatformContext): Record<string, string>;
+    shimLines(program: ProgramIR, ctx?: PlatformContext): string[];
+    profileDiagnostics(program: ProgramIR, ctx?: PlatformContext): Diagnostic[];
+    /**
+     * Default implementation returns empty set.
+     * Board packages can override to provide native implementations.
+     */
+    nativePolyfills(): Set<string>;
+    /**
+     * Generate native helpers: cuttlefish_halt macro, Arduino string helpers,
+     * and (when stdlib supports it) the cooperative async Promise runtime.
+     */
+    generateNativePolyfills(program: ProgramIR, ctx?: PlatformContext): RuntimePolyfillIR[];
+    /**
+     * Injects Serial.begin(baudRate) at the top of setup() when the program uses
+     * console.* calls and has a baudRate configured, and no explicit .begin() call
+     * is already present.
+     */
+    setupInitCode(program: ProgramIR, ctx?: PlatformContext): string[];
+    sourceExtension(isEntryFile: boolean, isNpmPackage: boolean): string;
+    entrypointFunctionName(): string;
+    requiresLoopFunction(): boolean;
+    overrideBaseName(originalBaseName: string, outDirBaseName: string, isEntryFile: boolean, isNpmPackage: boolean): string;
+    effectiveEmitMode(_requestedMode: string, isNpmPackage: boolean): string;
+    defaultNumericType(): string;
+    normalizeCppType(typeName: string): string;
+    mapReturnType(functionName: string, returnType: string): string;
+    isStringLikeType(cppType: string): boolean;
+    isPointerType(cppType: string): boolean;
+    mapFunctionName(originalName: string): string;
+    currentTimeMillis(): string;
+    normalizeRawExpression(value: string): string;
+    nullValue(): string;
+    wrapStringConcat(leftRendered: string, rightRendered: string, leftIsString: boolean): string | undefined;
+    wrapStringObject(value: string): string;
+    useSnprintfForStrings(): boolean;
+    floatToSnprintfArg(renderedExpr: string, precision: number | undefined, tempId: number): {
+        format: string;
+        arg: string;
+        estimatedLength: number;
+        preludeLines: string[];
+    } | undefined;
+    renameEnumMember(_enumName: string, memberName: string): string;
+    enumCastType(enumName: string): string | undefined;
+    private static readonly _passthroughEnumNames;
+    passthroughEnumNames(): ReadonlySet<string>;
+    renderBoardDefinitionAccess(chain: string[], boardConstants?: BoardConstants): string | undefined;
+    mapPeripheralIdentifier(name: string): string | undefined;
+    resolvePinType(objectName: string, fieldName: string): string | undefined;
+    renderThrow(_valueExpr: string): string;
+    isConsoleCall(callee: string): boolean;
+    transformConsoleCall(method: string, renderedArgs: string, forHeader: boolean): string;
+    transformConsoleExpression(_method: string, _renderedArgs: string): string | undefined;
+    objectFieldInitializer(fieldValue: ExpressionIR, _renderExpr: (e: ExpressionIR) => string): string | undefined;
+    overrideClassFieldType(fieldName: string, normalizedType: string): string;
+    renderSerialPrintWithSnprintf(params: {
+        receiver: string;
+        method: string;
+        bufferName: string;
+    }): {
+        finalLine: string;
+    } | undefined;
+    forwardDeclarationExclusions(): string[];
+    ambientTypeDeclarations(): string[];
+    reservedNames(): ReadonlySet<string>;
+    passthroughMacroNames(): ReadonlySet<string>;
+    apiReservedEnumNames(): ReadonlySet<string>;
+    apiReservedEnumGuard(): string;
+    isHeapAllocationUnsafe(architecture: string): boolean;
+    isExceptionSupportDisabled(architecture: string): boolean;
+    needsIostream(): boolean;
+    needsStdString(): boolean;
+    needsStdVector(): boolean;
+    needsStdExcept(): boolean;
+    needsStdFunction(): boolean;
+    mathHeader(): string;
+    cstringHeader(): string;
+    needsVectorOverload(): boolean;
+    needsLargeEnumUnderlying(): boolean;
+    renameStructField(fieldName: string): string;
+    structFieldInitializer(fieldValue: ExpressionIR, compiletimeVarNames: Set<string>, _renderExpr: (e: ExpressionIR) => string): string | undefined;
+    getAsyncRuntimeConfig(): AsyncRuntimeConfig;
+    asyncLoopInjection(taskVarNames: string[], config: AsyncRuntimeConfig): string[];
+    asyncLoopInjection(taskVarNames: string[], hasPromiseRuntime: boolean, hasTimers: boolean): string[];
+    asyncDriverFunctionName(): string;
+    /**
+     * On ESP32 (Xtensa LX6/LX7), ISR functions must be placed in IRAM so they
+     * can execute while the SPI flash cache is busy.  Other architectures don't
+     * need this attribute.
+     */
+    isrFunctionAttribute(): string;
+    shouldSkipTypeAlias(cppType: string): boolean;
+    emitDiagnostics(_emitMode: string): Diagnostic[];
+    isrUnsafeOperations(): Map<string, {
+        reason: string;
+        severity: 'warning' | 'info';
+    }>;
+    asyncQueueCapacity(): number;
+    outputSubdirectory(baseName: string): string;
+    generateHeaderFile(): boolean;
+    enumApiGuard(_enumName: string): {
+        open: string;
+        close: string;
+    } | undefined;
+    private static readonly STDLIB_SUPPORT;
+    getStdLibSupport(architecture?: string): StdLibSupport;
+    private static readonly DEFAULT_STDLIB;
+    generateDebugInitCode(): string[];
+    generateDebugBreakpointCode(params: {
+        fileName: string;
+        lineNum: number;
+        originalLine: string;
+        variables: Array<{
+            name: string;
+            isFunction?: boolean;
+        }>;
+        normalizedCondition?: string;
+    }): string[];
+    generateDebugLogpointCode(params: {
+        fileName: string;
+        lineNum: number;
+        parts: Array<{
+            type: 'text' | 'variable';
+            value: string;
+        }>;
+        variables: Array<{
+            name: string;
+            isFunction?: boolean;
+        }>;
+    }): string[];
+    resolveHALOperation(op: HALOpIR): {
+        code?: string;
+        expression?: string;
+    } | undefined;
+    private _displayCtx;
+    resolveDisplayOp(op: DisplayHALOp): {
+        code?: string;
+        expression?: string;
+    } | undefined;
+    supportedDisplayDrivers(): ReadonlySet<string>;
+    colorFormat(): "rgb565" | "mono";
+    graphicsCapacity(): GraphicsCapacity;
+}