@geastack/compiler 1.0.15

package/dist/targets/cpp/prototype/emit-prototype-regexp.d.ts

@@ -0,0 +1,335 @@
+import type { IrOperand, IrResult, SetOperation, DefineOwnPropertyOperation } from '../../../ir/model.js';
+import type { IrValueId } from '../../../identity/ids.js';
+import type { Representation } from '../../../representation/model.js';
+import type { RegExpDeclarationKind } from '../../../representation/policies.js';
+import { type EmitContext, type PrototypeMethodRead } from '../emit-context.js';
+/**
+ * `RegExp.prototype`, `RegExpExecArray` and `RegExpMatchArray`, as this
+ * backend renders them.
+ *
+ * The mechanism for the two METHODS is `emit-prototype-invoke.ts`'s deferred
+ * `[[Get]]` fused with the call that follows -- the same one String and Array
+ * use, for the same reason: `re.test` on its own is a function value bound to
+ * a receiver, and this backend mints no such value.
+ *
+ * The DATA members are rendered here and now, because on this carrier they
+ * really are native slots. `lastIndex` is deliberately different: it is the
+ * one writable own data property, so its cell retains a `gea::Value` and the
+ * typed read/write paths use the same native property operations as computed
+ * paths. Pattern itself remains a native shared reference throughout.
+ *
+ * Nothing here is allowed to fall through to the generic struct-member path.
+ * That path emits `receiver->key` for ANY key, so an unimplemented member
+ * would reach clang as an unknown-member error instead of a refusal naming the
+ * member -- which is the exact bug this lane exists to fix on the String side.
+ */
+/** Which of the three regular-expression carriers an operand holds, or `null` for anything else. */
+export declare const regexpRoleOf: (representation: Representation) => RegExpDeclarationKind | null;
+/**
+ * ECMA-262 22.2.4.1 steps 5-7 for a pattern argument that is an ordinary
+ * OBJECT -- neither a string nor a value already carrying `[[RegExpMatcher]]`.
+ *
+ * Step 5 has already been answered `false` by the caller: a value with the
+ * internal slot is exactly this backend's `Pattern` carrier, which the caller
+ * spells directly. What remains is the choice between step 6 and step 7, and
+ * it turns on `patternIsRegExp` -- `IsRegExp` (22.1.3.6), which for an object
+ * without the slot is `ToBoolean(Get(pattern, @@match))`.
+ *
+ * That is a RUNTIME question here even though the shape is fully static:
+ * `{ [Symbol.match]: true }` gives the member the widened type `boolean`, so
+ * no carrier proves which branch runs and both are rendered. The WHOLE
+ * construction is what the conditional selects, not the two arguments
+ * separately: `patternIsRegExp` is computed once at step 2 in the language, and
+ * a conditional per argument would read the member twice, in an order C++ does
+ * not fix, with step 7's ToString -- potentially a call to the object's own
+ * `toString` -- able to run between the two reads and change the second.
+ *
+ * A shape that declares no `@@match` member at all answers `IsRegExp` false
+ * statically, and only step 7 is rendered.
+ *
+ * `null` is returned for anything this cannot answer exactly, leaving the
+ * caller's own refusal to name the carrier.
+ */
+export declare const regExpConstructionFromObject: (ctx: EmitContext, argument: IrOperand, flagsArgument: IrOperand | null) => string | null;
+/**
+ * A `[[Get]]` off any of the three regular-expression carriers, or `null` when
+ * the receiver is not one -- in which case `emitGet` carries on unchanged.
+ *
+ * An empty string is a deferred method read, the same convention every other
+ * prototype table in this directory uses.
+ */
+/**
+ * Whether a RegExp-family member read is a deferred prototype-method read, and
+ * what it is.
+ *
+ * Two shapes under one claim, because `regexpRoleOf` is what tells them apart:
+ * a PATTERN's own `RegExp.prototype` method, and an `Array.prototype` method
+ * reached through a match RESULT, which really is an Array in the language
+ * (22.1.3.13) and is read through `gea::runtime::regex::matchElements` -- a
+ * view over the receiver, which is why the receiver travels as its own kind
+ * rather than as pre-rendered text.
+ *
+ * Stated once; `regexpMemberText` and the prototype-read walk both ask it.
+ */
+export declare const deferredRegexpMethodClaim: (staticKeyTexts: ReadonlyMap<IrValueId, string>, receiver: IrOperand, key: IrOperand) => PrototypeMethodRead | null;
+export declare const regexpMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, result: IrValueId | null, resultRepresentation: Representation | undefined, narrow: (fieldName: string, storage: string) => string) => string | null;
+/**
+ * `regexpStoreRefusal`'s whole decision, spelled as three outcomes rather than
+ * collapsed into "throws or doesn't":
+ *
+ * - `null`: the receiver is not a RegExp-family carrier at all.
+ * - `{ kind: 'declines' }`: the receiver IS one, but this write needs no
+ *   refusal -- either `lastIndex` (falls through to the ordinary
+ *   struct-member write, since on this carrier it IS one) or a genuine
+ *   expando (falls through to Pattern's identity-keyed native sidecar).
+ * - `{ kind: 'result-mutation' | 'exec-override' | 'unsupported-member' }`: a
+ *   REFUSAL, with the facts its message is built from (`role`/`staticKey`)
+ *   rather than the message itself -- the receiver operand the message also
+ *   needs (for `representationKey`) is already in the caller's hand, so
+ *   nothing here pre-renders any of it.
+ *
+ * `declines` and a genuine refusal used to be one `return`/`throw` choice
+ * buried in the same branch; keeping them apart is the whole point of lifting
+ * this into a claim instead of a boolean.
+ */
+export type RegExpStoreRefusalDecision = {
+    readonly kind: 'declines';
+} | {
+    readonly kind: 'result-mutation';
+    readonly role: RegExpDeclarationKind;
+    readonly staticKey: string;
+} | {
+    readonly kind: 'exec-override';
+} | {
+    readonly kind: 'unsupported-member';
+    readonly role: RegExpDeclarationKind;
+    readonly staticKey: string | undefined;
+};
+/**
+ * Lifted out of `regexpStoreRefusal` below. Unlike `namespaceMemberStoreClaim`
+ * and `regexpDynamicSetClaim`, this one has exactly ONE caller
+ * (`regexpStoreRefusal` itself): its only outcomes past "not a RegExp" are
+ * "declines silently" and "refuses", and neither is a fact anything else
+ * reads. A refusal has no C++ to schedule and no value id to key a census by,
+ * so recording it in a prepass walk would mean either throwing from the walk
+ * -- which would report whichever refusal this store-only walk reaches
+ * first, rather than whichever operation of ANY kind actually renders first
+ * in the body, a reordering this refactor's own byte-identical gate cannot
+ * see -- or keeping a map nothing consults, the "capability with zero
+ * consumers" shape this codebase has already paid for once. So this claim is
+ * extracted for the same reason every other one is (the resolver no longer
+ * decides anything inline), without manufacturing a second caller it has no
+ * honest use for yet.
+ */
+export declare const regexpStoreRefusalClaim: (ctx: EmitContext, receiver: IrOperand, key: IrOperand) => RegExpStoreRefusalDecision | null;
+/**
+ * A store into a regular-expression member.
+ *
+ * `lastIndex` is the one writable own data property ECMA-262 defines
+ * (22.2.6.9). It stays in the Pattern-owned `Value` cell through both direct
+ * and computed stores; the runtime applies ToLength only when matching.
+ *
+ * The `exec` override is the one case worth naming outright. `r.exec = fn` is
+ * legal TypeScript and legal ECMAScript, and 22.2.7.1 `RegExpExec` really does
+ * look the own property up and call it -- v1 carries a `gea_cpp_value
+ * exec_override` field for exactly this. Supporting it here would mean giving
+ * every pattern a boxed callable slot and routing every `exec`/`match`/
+ * `replace` through a dynamic check for it, which is the boxing this backend
+ * does not do. So it is refused, by name, with what it would cost.
+ *
+ * Decides nothing itself any more -- `regexpStoreRefusalClaim` above is the
+ * one authority; this only spells whichever of its outcomes came back.
+ */
+export declare const regexpStoreRefusal: (ctx: EmitContext, receiver: IrOperand, key: IrOperand) => void;
+/**
+ * A capture-slot STORE -- `m[0] = s`, `m[j] = s` -- with the slot's own text,
+ * or `null` when the operation is not one.
+ *
+ * A match result IS an Array in the language, and its capture slots are that
+ * Array's elements rather than members of the result object, so writing one is
+ * an ordinary element store and not a mutation of an answer the runtime owns.
+ * The read side has always agreed: `captureReadText` renders `m[i]` off both a
+ * static canonical index and a computed numeric key. This is the same access
+ * in the other direction, admitted on the same two key shapes, so the pair
+ * cannot disagree about which keys name a slot.
+ *
+ * hono's `Trie.insert` is the program that named it: `tokens[j] =
+ * tokens[j].replace(mark, groups[i][1])` over `path.match(re) || []`, whose
+ * union collapses to the match result alone (`normalize/structural.ts` drops
+ * the empty-array arm).
+ */
+export declare const regexpCaptureSlotStoreClaim: (ctx: EmitContext, operation: SetOperation | DefineOwnPropertyOperation) => {
+    readonly slotText: string;
+} | null;
+/**
+ * `emitRegExpSet`'s whole decision: is this a `set` whose receiver is a
+ * Pattern and whose key is NOT one of the ten `RegExp.prototype` members (a
+ * computed key, or a named expando) -- the dynamic write into Pattern's
+ * identity-keyed native sidecar. `null` for anything else, including a
+ * `define-own-property` (this dynamic path only ever reached a `set` even
+ * before the extraction) and a write to a method name, which stays refused
+ * by `regexpStoreRefusalClaim` instead of silently accepted here.
+ *
+ * Carries the resolved static key text (or `undefined` for a computed key)
+ * rather than the `site` diagnostic string built from it -- a fact, not
+ * pre-rendered text, exactly like every other claim in this file.
+ */
+export interface RegExpDynamicSetClaim {
+    readonly staticKey: string | undefined;
+}
+export declare const regexpDynamicSetClaim: (ctx: EmitContext, operation: SetOperation | DefineOwnPropertyOperation) => RegExpDynamicSetClaim | null;
+/**
+ * RegExp [[Set]] for every key whose writability must be decided at run time.
+ * The receiver remains Ref<Pattern>; only the property value crosses the
+ * dynamic boundary required by a computed key.
+ *
+ * Decides nothing itself any more -- `regexpDynamicSetClaim` above is the one
+ * authority; this only spells the write once the claim admits it.
+ */
+export declare const emitRegExpSet: (ctx: EmitContext, lines: string[], operation: SetOperation | DefineOwnPropertyOperation) => boolean;
+/**
+ * The call text for a deferred `RegExp.prototype` method read.
+ *
+ * `test` is a member call on the `shared_ptr` because it is a member of the
+ * ported `Pattern` (v1: `Pattern::test`). `exec` is a free function because it
+ * builds an `ExecResult`, which is a second type -- and because the boxed
+ * `gea_cpp_value exec(...)` overload sitting beside it in v1 is deliberately
+ * not ported; this is the typed one (v1: `Pattern::exec_typed`).
+ */
+export declare const regexpMethodCallText: (ctx: EmitContext, member: string, receiverText: string, args: readonly IrOperand[], result: IrResult | null) => string;
+/** ECMA-262 22.1.3.11 `String.prototype.match(regexp)` -> 22.2.6.8, answering `RegExpMatchArray | null`. */
+export declare const regexpMatchText: (ctx: EmitContext, receiverText: string, args: readonly IrOperand[], result: IrResult | null) => string;
+/** ECMA-262 22.1.3.13 `String.prototype.search(regexp)` -> 22.2.6.11, answering the index of the first match or -1. */
+export declare const regexpSearchText: (ctx: EmitContext, receiverText: string, args: readonly IrOperand[]) => string;
+/**
+ * ECMA-262 22.1.3.23 `String.prototype.split(separator)` -> 22.2.6.14, when
+ * the separator is a pattern -- `null` when it is not, so the string form
+ * renders unchanged.
+ *
+ * The spec APPENDS every capture group to the output (step 19.d), so
+ * `'a1b'.split(/(\d)/)` is three elements, not two. That is in the runtime's
+ * `splitByPattern`, which is why the element carrier is checked here: an
+ * array of anything but strings would mean the plan and the runtime disagree
+ * about what a split produces.
+ */
+export declare const regexpSplitText: (ctx: EmitContext, receiverText: string, args: readonly IrOperand[], result: IrResult | null) => string | null;
+/**
+ * ECMA-262 22.1.3.18 `replace` / 22.1.3.20 `replaceAll` with a pattern
+ * searchValue -- `null` when the searchValue is a string, so the two-string
+ * form renders unchanged.
+ *
+ * The replacement may be a CALLBACK (22.2.6.11 step 14.a), or any value that
+ * `toStringText` can provably convert before 22.1.3.19 `GetSubstitution`
+ * interprets `$&`, `` $` ``, `$'`, `$n`, `$<name>` and `$$`. The two resulting
+ * carriers are real overloads of the ported `replaceByPattern`, selected by
+ * C++ overload resolution; a carrier whose ToString can run unknown user code
+ * remains refused.
+ *
+ * `replaceAll` renders a DIFFERENT runtime entry point, and that is 22.1.3.20
+ * step 2: a non-global RegExp is a TypeError there, and which pattern object
+ * reaches this call site is not a fact any emitter can read, so the check
+ * lives in `replaceAllByPattern`.
+ */
+export declare const regexpReplaceText: (member: "replace" | "replaceAll", ctx: EmitContext, receiverText: string, args: readonly IrOperand[]) => string | null;
+/**
+ * The one String member with a regular-expression argument that this backend
+ * refuses, and the true reason.
+ *
+ * Read by `emit-prototype-string.ts`'s refusal table so there is one authority
+ * for it.
+ */
+export declare function matchAllRefusal(): string;
+/**
+ * `new String(x)` -- the ECMAScript String WRAPPER OBJECT (ECMA-262 22.1.5),
+ * kept in this file alongside the three regular-expression carriers above
+ * rather than a file of its own: all four are native-record-ref types this
+ * backend intercepts EARLY, at the identical two dispatch points in
+ * `emit-properties.ts` (right after `regexpMember`/`regexpStoreRefusal`),
+ * for the identical architectural reason -- nothing here may fall through to
+ * the generic struct-member path. Deliberately separate from
+ * `emit-prototype-string.ts`, which is `String.prototype` over this
+ * backend's PRIMITIVE `string` carrier, not this rarer OBJECT
+ * `new String(x)` allocates -- one with identity that can carry own
+ * properties no primitive can (`escapedString.isEscaped = true`, hono's
+ * `utils/html.ts`, the case this carrier exists for).
+ *
+ * `gea::runtime::StringObject`'s ambient body (`interface String` in
+ * `lib.es5.d.ts`) survives `declaredBodyOf`'s method stripping with a real
+ * data member (`length`) AND a number index signature -- the same
+ * "plausible-looking struct that is not the real layout" shape
+ * `RegExpExecArray` warns about in `derive.ts`'s own comment. The generic
+ * struct-member path would happily emit `receiver->length`, and
+ * `gea::runtime::StringObject` has no such field (see its doc comment in
+ * `runtime/gea_runtime.h`: `length` is ECMA-262 22.1.4's own READ-ONLY view
+ * over `[[StringData]]`, not a second, driftable copy of it).
+ *
+ * The bigger landmine is the NUMBER index signature: `String`'s derived
+ * shape lays out as `record-with-index` with a NUMBER-domain sidecar
+ * (`[index: number]: string`), and `emitRecordIndexSidecarStore`/
+ * `recordIndexSidecarReadText` (`emit-carrier-members.ts`) run for ANY
+ * `native-record-ref` whose shape has one, over ANY constant key that does
+ * not name a declared field, with no domain check ahead of the subscript
+ * conversion. A STRING key like `isEscaped` reaching that path is coerced
+ * with `Number('isEscaped')` (`NaN`) and throws a "does not spell a numeric
+ * key" refusal unrelated to what the program wrote. So the two functions
+ * below must fully own EVERY constant key on a String-object receiver, not
+ * just `length`, so nothing falls through into a sidecar keyed by the wrong
+ * domain -- unlike `regexpMemberText`/`regexpStoreRefusal` above, which only
+ * intercept a refusal and let everything else fall through.
+ *
+ * A constant, non-`length` key (`isEscaped`, `callbacks`) is routed through
+ * the identical `gea::nativeDynamicGet`/`nativeDynamicSet` machinery
+ * `nativeSidecarGetText`/`emitNativeSidecarSet` (`emit-dynamic-properties.ts`)
+ * already use for a COMPUTED key on any other native-record-ref type --
+ * reusing their `boxedValueText`/`unboxedReadText` rather than duplicating
+ * the box/unbox logic. Those two functions skip a constant key outright
+ * (their own doc comment: "a constant key names a declared member"), true
+ * for every native-record-ref type before this one and false for `String`,
+ * whose whole point is accepting arbitrary, program-chosen constant keys as
+ * dynamic properties.
+ */
+/** Whether a carrier is the String wrapper-object native type, or `null`/anything else. */
+export declare const isStringObjectCarrier: (representation: Representation) => boolean;
+/**
+ * A `[[Get]]` off a String object, or `null` when the receiver is not one --
+ * in which case `emitGet` carries on unchanged.
+ *
+ * `length` is a real field computed off `StringObject::value`, not stored
+ * separately (see the struct's own doc comment). A computed numeric key is
+ * indexed character access (ECMA-262 22.1.5.1's exotic `[[GetOwnProperty]]`),
+ * a real spec'd capability this backend has not built a renderer for, and is
+ * refused by name -- the same posture taken above for `RegExp.prototype
+ * .compile`. Every other CONSTANT key is a dynamic own property, routed
+ * through the native dynamic-property sidecar directly (see this section's
+ * header comment for why it cannot defer to `nativeSidecarGetText`, which
+ * only fires for a computed key).
+ */
+export declare const stringObjectMemberText: (ctx: EmitContext, receiver: IrOperand, key: IrOperand, resultRepresentation: Representation | undefined) => string | null;
+/**
+ * A store into a String object -- `null`/no-op when the receiver is not one,
+ * in which case `emitFieldStoreLines` carries on unchanged. Unlike
+ * `regexpStoreRefusal` above, this function OWNS every constant key for a
+ * String-object receiver and returns `true` for all of them.
+ *
+ * `length` is refused: ECMA-262 22.1.4.1 makes it a read-only accessor, never
+ * a data property a program can write. A computed key is refused for the
+ * identical reason the GET side refuses one: indexed character mutation has
+ * no renderer here. Every other constant key is an own-property write,
+ * routed through `gea::nativeDynamicSet` directly.
+ */
+export declare const emitStringObjectSet: (ctx: EmitContext, lines: string[], operation: SetOperation | DefineOwnPropertyOperation) => boolean;
+/**
+ * The runtime text that stringifies a String-object carrier down to this
+ * backend's plain `std::string`, or `null` for anything else.
+ *
+ * The one real datum on `gea::runtime::StringObject` -- see its doc comment
+ * in `runtime/gea_runtime.h` -- so this is a field read, not a call:
+ * ECMA-262 22.1.3.34/22.1.5.4 (`toString`/`valueOf`, `thisStringValue`) both
+ * answer exactly `[[StringData]]` with no transformation.
+ *
+ * `emit-narrowing.ts` keeps a small, deliberately duplicated twin
+ * (`stringObjectStringifyText`) for the one native wrapper-to-primitive route;
+ * it cannot import this helper because this file already imports
+ * `convertedValueText` from there. This is not a dynamic boundary coercion.
+ */
+export declare const stringObjectToStringText: (heldRepresentation: Representation, text: string) => string | null;