diff --git a/packages/web/spec/program/context/name.mdx b/packages/web/spec/program/context/name.mdx new file mode 100644 index 0000000000..31fd7fb17d --- /dev/null +++ b/packages/web/spec/program/context/name.mdx @@ -0,0 +1,14 @@ +--- +sidebar_position: 6 +--- + +import SchemaViewer from "@site/src/components/SchemaViewer"; + +# Named contexts + +Contexts may include a `name` property for distinguishing them from +other contexts. This is particularly useful inside `pick` alternatives, +where several possible contexts may apply at a given point in execution +and runtime information is needed to select which one is active. + + diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts index 194cdf0344..619c35b043 100644 --- a/packages/web/src/schemas.ts +++ b/packages/web/src/schemas.ts @@ -224,7 +224,7 @@ const programSchemaIndex: SchemaIndex = { href: "/spec/program/context", }, - ...["code", "variables", "remark", "pick", "gather", "frame"] + ...["name", "code", "variables", "remark", "pick", "gather", "frame"] .map((name) => ({ [`schema:ethdebug/format/program/context/${name}`]: { href: `/spec/program/context/${name}`, diff --git a/schemas/program/context.schema.yaml b/schemas/program/context.schema.yaml index 1a82386220..ba5a4ee87d 100644 --- a/schemas/program/context.schema.yaml +++ b/schemas/program/context.schema.yaml @@ -26,6 +26,12 @@ description: | type: object allOf: + - if: + required: ["name"] + then: + description: | + A label for distinguishing this context from others. + $ref: "schema:ethdebug/format/program/context/name" - if: required: ["code"] then: diff --git a/schemas/program/context/name.schema.yaml b/schemas/program/context/name.schema.yaml index 57d0ce77c3..7591610593 100644 --- a/schemas/program/context/name.schema.yaml +++ b/schemas/program/context/name.schema.yaml @@ -3,9 +3,15 @@ $id: "schema:ethdebug/format/program/context/name" title: ethdebug/format/program/context/name description: | - The name of the context, for use in disambiguating future instruction - annotations that specify one of several possible contexts based on - information only available at runtime. + A label for distinguishing this context from other contexts. + This is particularly useful inside `pick` alternatives, + where several possible contexts may apply at a given point in + execution and runtime information is needed to select which one + is active. + + Context names are opaque strings with no format-imposed semantics. + Compilers **should** choose names that are meaningful to debugger + users. type: object properties: @@ -15,4 +21,7 @@ required: - name examples: + # example: naming an inlined call site + - name: "inlined-call" + # example: naming a generic instantiation - name: "Array" diff --git a/schemas/program/context/pick.schema.yaml b/schemas/program/context/pick.schema.yaml index c36c8a9bee..3250900d4d 100644 --- a/schemas/program/context/pick.schema.yaml +++ b/schemas/program/context/pick.schema.yaml @@ -33,3 +33,20 @@ examples: range: offset: 132 length: 16 + + - # example: named alternatives for disambiguation + pick: + - name: "inlined-call" + code: + source: + id: 5 + range: + offset: 68 + length: 16 + - name: "original-site" + code: + source: + id: 5 + range: + offset: 132 + length: 16