From f3c0b744c99a22cf322008d62a1e17b49d632f9d Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Sat, 6 Jan 2024 07:48:28 -0500 Subject: [PATCH] Allow types to have definitions like, in code --- schemas/type/base.schema.yaml | 1 + schemas/type/complex/alias.schema.yaml | 2 + schemas/type/complex/struct.schema.yaml | 2 + schemas/type/definition.schema.yaml | 45 ++++++++++++++++++++ schemas/type/elementary/contract.schema.yaml | 3 ++ schemas/type/elementary/enum.schema.yaml | 2 + tests/src/schemas.ts | 1 + web/spec/type/concepts.mdx | 34 +++++++++++++++ web/src/schemas.ts | 6 +++ 9 files changed, 96 insertions(+) create mode 100644 schemas/type/definition.schema.yaml diff --git a/schemas/type/base.schema.yaml b/schemas/type/base.schema.yaml index 7e4cf577..47b79582 100644 --- a/schemas/type/base.schema.yaml +++ b/schemas/type/base.schema.yaml @@ -57,6 +57,7 @@ $defs: - $ref: "#/$defs/TypeWrapper" - $ref: "#/$defs/TypeWrapperArray" - $ref: "#/$defs/TypeWrapperObject" + required: - kind - contains diff --git a/schemas/type/complex/alias.schema.yaml b/schemas/type/complex/alias.schema.yaml index 072f4697..3c0b4730 100644 --- a/schemas/type/complex/alias.schema.yaml +++ b/schemas/type/complex/alias.schema.yaml @@ -15,6 +15,8 @@ properties: const: alias contains: $ref: "schema:ethdebug/format/type/wrapper" + definition: + $ref: "schema:ethdebug/format/type/definition" required: - kind diff --git a/schemas/type/complex/struct.schema.yaml b/schemas/type/complex/struct.schema.yaml index cd3837b0..01a86369 100644 --- a/schemas/type/complex/struct.schema.yaml +++ b/schemas/type/complex/struct.schema.yaml @@ -17,6 +17,8 @@ properties: type: array items: $ref: "#/$defs/MemberField" + definition: + $ref: "schema:ethdebug/format/type/definition" required: - kind diff --git a/schemas/type/definition.schema.yaml b/schemas/type/definition.schema.yaml new file mode 100644 index 00000000..a4974bf6 --- /dev/null +++ b/schemas/type/definition.schema.yaml @@ -0,0 +1,45 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "schema:ethdebug/format/type/definition" + +title: ethdebug/format/type/definition +description: | + Object containing name and location information for a type. + + This schema does not require any particular field, but it **must** contain + at least one property. + +type: object +properties: + name: + type: string + + source: + type: object + properties: + id: + type: + - string + - number + range: + type: object + properties: + offset: + type: number + length: + type: number + +anyOf: + - title: Required `name` + required: + - name + - title: Required `source` + required: + - source + +examples: + - name: Ballot + source: + id: 5 + range: + offset: 10 + length: 56 diff --git a/schemas/type/elementary/contract.schema.yaml b/schemas/type/elementary/contract.schema.yaml index 10f90a72..ef9e3e45 100644 --- a/schemas/type/elementary/contract.schema.yaml +++ b/schemas/type/elementary/contract.schema.yaml @@ -16,6 +16,9 @@ properties: description: If this field is omitted, this type represents an address whose payability is not known. + definition: + $ref: "schema:ethdebug/format/type/definition" + oneOf: - properties: library: diff --git a/schemas/type/elementary/enum.schema.yaml b/schemas/type/elementary/enum.schema.yaml index 10915751..799062b3 100644 --- a/schemas/type/elementary/enum.schema.yaml +++ b/schemas/type/elementary/enum.schema.yaml @@ -17,6 +17,8 @@ properties: values are allowed here. type: array items: true + definition: + $ref: "schema:ethdebug/format/type/definition" required: - kind diff --git a/tests/src/schemas.ts b/tests/src/schemas.ts index f4060dba..33935a8c 100644 --- a/tests/src/schemas.ts +++ b/tests/src/schemas.ts @@ -15,6 +15,7 @@ const readSchemas = (): { "type/base.schema.yaml", "type/wrapper.schema.yaml", "type/reference.schema.yaml", + "type/definition.schema.yaml", "type/elementary/uint.schema.yaml", "type/elementary/int.schema.yaml", "type/elementary/bool.schema.yaml", diff --git a/web/spec/type/concepts.mdx b/web/spec/type/concepts.mdx index ffd52db7..2aedf159 100644 --- a/web/spec/type/concepts.mdx +++ b/web/spec/type/concepts.mdx @@ -155,6 +155,7 @@ possibly includes other fields alongside `"type"`. + ## Type wrappers and type references This schema defines the concept of a type wrapper and the related concept of a @@ -213,3 +214,36 @@ must be a string or a number. + +## Sometimes types are defined in code + +Languages provide certain kinds of types by way of allowing their definition +in user (or runtime) code. These include [struct](/spec/type/complex/struct), +[enum](/spec/type/elementary/enum), and [alias](/spec/type/complex/alias) +types. + +Types with definition information **may** include a `definition` field that +specifies the name of the type (its identifier) and/or the source location of +its definition. + +:::note + +When extending the [base type schema](/spec/type/base) for custom kinds of +types with definitions, these custom schemas **must** require the specification +of such definitions by way of this same `definition` field and its associated +schema. + +::: + +This format does not prohibit the inclusion of this `definition` field for any +type, so as to support languages where array types, etc. may be defined by name +directly. It is recommended, however, that +compilers implementing this format **should** prefer to use +[alias](/spec/type/complex/alias) type for the common case of assigning a name +to a type expression. + +### Type definition schema + + diff --git a/web/src/schemas.ts b/web/src/schemas.ts index de7bc485..777dc778 100644 --- a/web/src/schemas.ts +++ b/web/src/schemas.ts @@ -3,6 +3,7 @@ import YAML from "yaml"; import typeBaseSchemaYaml from "../../schemas/type/base.schema.yaml"; import typeWrapperSchemaYaml from "../../schemas/type/wrapper.schema.yaml"; import typeReferenceSchemaYaml from "../../schemas/type/reference.schema.yaml"; +import typeDefinitionSchemaYaml from "../../schemas/type/definition.schema.yaml"; import typeElementaryUintSchemaYaml from "../../schemas/type/elementary/uint.schema.yaml"; import typeElementaryIntSchemaYaml from "../../schemas/type/elementary/int.schema.yaml"; import typeElementaryBoolSchemaYaml from "../../schemas/type/elementary/bool.schema.yaml"; @@ -26,6 +27,7 @@ export const schemaYamls = [ typeBaseSchemaYaml, typeWrapperSchemaYaml, typeReferenceSchemaYaml, + typeDefinitionSchemaYaml, typeElementaryUintSchemaYaml, typeElementaryIntSchemaYaml, typeElementaryUfixedSchemaYaml, @@ -72,6 +74,10 @@ export const schemaIndex: SchemaIndex = { title: "Type reference schema", href: "/spec/type/concepts#type-reference-schema" }, + "schema:ethdebug/format/type/definition": { + title: "Type definition schema", + href: "/spec/type/concepts#type-definition-schema" + }, "schema:ethdebug/format/type": { href: "/spec/type" },