diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d5289d..3b06437 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,7 +50,7 @@ There are a few concepts that must be assimilated in order to understand the des An Entity is just a data holder object that does not really do anything by itself, it has a purely information storage related purpose. The top class at the hierarchy of entities is `IEntity`. This one is a bit more complicated in the sense that it does the initialization of the entity in its constructor according to the information contained in the object provided as an argument or from the attributes static field. This ended up being a somewhat wacky runtime type system. Each subclass can specify its attributes static member variable of type object where each entry is either a value (the default value the attribute will have), a function (called to generate such default value) or an object and in that case it will be of type `AttributeInformation` (please note that in case one wants to assign as default value a specific object, the solution is either to wrap it into a `AttributeInformation` object or to return it from a function). ### Grammar and Serializer -In the `serialization/` folder the gentle reader will find all the classes responsible for transforming entities from and to text that the UE Blueprint Enditor can understand. One important class here is `Grammar` that contains similar formal grammar rules that use the [Parsimmon library](https://github.com/jneen/parsimmon) to create entities from Blueprint text. `ISerializer` is at the top of the serializer classes hierarchy and it uses a factory design pattern to register serializers for the various entities types (check `js/serialization/initializeSerializerFactory.js`). It does both read and write of entities: to read it will use the Grammar after creating a language using a function from Parsimmon, to write it will use methods from the class itself. +In the `serialization/` folder the gentle reader will find all the classes responsible for transforming entities from and to text that the UE Blueprint Enditor can understand. One important class here is `Grammar` that contains similar formal grammar rules that use the [Parsimmon library](https://github.com/jneen/parsimmon) to create entities from Blueprint text. `Serializer` is at the top of the serializer classes hierarchy and it uses a factory design pattern to register serializers for the various entities types (check `js/serialization/initializeSerializerFactory.js`). It does both read and write of entities: to read it will use the Grammar after creating a language using a function from Parsimmon, to write it will use methods from the class itself. Grammar is usually the first place to look when pasting valid Blueprint code does fail. Most likely newer version of Unreal Engine did add some new data type that was not implemented yet (or this library never managed to handle it in the first place). In that case the approach should be trying to fix the existing grammar and entities to accept it, then implement the new entities and attributes. diff --git a/cypress/e2e/entities.cy.js b/cypress/e2e/entities.cy.js index e289449..b5b0af8 100644 --- a/cypress/e2e/entities.cy.js +++ b/cypress/e2e/entities.cy.js @@ -2,10 +2,10 @@ import ComplexEntity from "../fixtures/ComplexEntity" import initializeSerializerFactory from "../../js/serialization/initializeSerializerFactory.js" +import Serializer from "../../js/serialization/Serializer.js" import SerializerFactory from "../../js/serialization/SerializerFactory.js" import SimpleEntity from "../fixtures/SimpleEntity" import SimpleObject from "../fixtures/SimpleObject" -import ISerializer from "../../js/serialization/ISerializer.js" describe("Entity initialization", () => { before(() => { @@ -19,7 +19,7 @@ describe("Entity initialization", () => { initializeSerializerFactory() SerializerFactory.registerSerializer( SimpleEntity, - new ISerializer( + new Serializer( SimpleEntity, v => `{\n${v}\n}`, " ", @@ -137,7 +137,7 @@ describe("Entity initialization", () => { initializeSerializerFactory() SerializerFactory.registerSerializer( ComplexEntity, - new ISerializer( + new Serializer( ComplexEntity, v => `[[\n${v}\n]]`, " ", @@ -149,7 +149,7 @@ describe("Entity initialization", () => { ) SerializerFactory.registerSerializer( SimpleObject, - new ISerializer( + new Serializer( SimpleObject, v => `SimpleObject(${v})`, "", diff --git a/dist/ueblueprint.js b/dist/ueblueprint.js index 49a2b1b..c3fa2f7 100755 --- a/dist/ueblueprint.js +++ b/dist/ueblueprint.js @@ -400,18 +400,18 @@ class ComputedType { */ /** * @template {AnyValue} T - * @typedef {import("./ISerializer").default} ISerializer + * @typedef {import("./Serializer").default} Serializer */ class SerializerFactory { - /** @type {Map, ISerializer>} */ + /** @type {Map, Serializer>} */ static #serializers = new Map() /** * @template {AnyValue} T * @param {AnyValueConstructor} entity - * @param {ISerializer} object + * @param {Serializer} object */ static registerSerializer(entity, object) { SerializerFactory.#serializers.set(entity, object); @@ -420,7 +420,7 @@ class SerializerFactory { /** * @template {AnyValue} T * @param {new () => T} entity - * @returns {ISerializer} + * @returns {Serializer} */ static getSerializer(entity) { // @ts-expect-error @@ -3919,13 +3919,13 @@ class Grammar { } /** - * @typedef {import("../entity/IEntity").EntityConstructor} EntityConstructor - * @typedef {import("../entity/IEntity").AnyValue} AnyValue - * @typedef {import("../entity/IEntity").AnyValueConstructor<*>} AnyValueConstructor + * @typedef {import("../entity/IEntity.js").EntityConstructor} EntityConstructor + * @typedef {import("../entity/IEntity.js").AnyValue} AnyValue + * @typedef {import("../entity/IEntity.js").AnyValueConstructor<*>} AnyValueConstructor */ /** @template {AnyValue} T */ -class ISerializer { +class Serializer { /** @type {(v: String, entityType: AnyValueConstructor) => String} */ static bracketsWrapped = ((v, entityType) => `(${v})`) @@ -3935,7 +3935,7 @@ class ISerializer { /** @param {AnyValueConstructor} entityType */ constructor( entityType, - wrap = ISerializer.bracketsWrapped, + wrap = Serializer.bracketsWrapped, attributePrefix = "", attributeSeparator = ",", trailingSeparator = false, @@ -4009,7 +4009,7 @@ class ISerializer { result += this.doWrite( value, insideString, - ISerializer.notWrapped, + Serializer.notWrapped, `${attributePrefix}${key}.`, attributeSeparator, trailingSeparator, @@ -4037,8 +4037,8 @@ class ISerializer { + this.attributeValueConjunctionSign + ( isSerialized - ? `"${this.doWriteValue(value, true)}"` - : this.doWriteValue(value, insideString) + ? `"${this.doWriteValue(value, true)}"` + : this.doWriteValue(value, insideString) ); } } @@ -4083,7 +4083,7 @@ class ISerializer { } } -class ObjectSerializer extends ISerializer { +class ObjectSerializer extends Serializer { constructor() { super(ObjectEntity, undefined, " ", "\n", false); @@ -10047,9 +10047,9 @@ function defineElements() { /** * @template {AnyValue} T - * @extends {ISerializer} + * @extends {Serializer} */ -class CustomSerializer extends ISerializer { +class CustomSerializer extends Serializer { #objectWriter @@ -10080,9 +10080,9 @@ class CustomSerializer extends ISerializer { /** * @template {AnyValue} T - * @extends {ISerializer} + * @extends {Serializer} */ -class ToStringSerializer extends ISerializer { +class ToStringSerializer extends Serializer { /** @param {AnyValueConstructor} entityType */ constructor(entityType) { @@ -10163,7 +10163,7 @@ function initializeSerializerFactory() { SerializerFactory.registerSerializer( FunctionReferenceEntity, - new ISerializer(FunctionReferenceEntity, ISerializer.bracketsWrapped) + new Serializer(FunctionReferenceEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( @@ -10188,27 +10188,27 @@ function initializeSerializerFactory() { SerializerFactory.registerSerializer( InvariantTextEntity, - new ISerializer(InvariantTextEntity, v => `${InvariantTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") + new Serializer(InvariantTextEntity, v => `${InvariantTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") ); SerializerFactory.registerSerializer( KeyBindingEntity, - new ISerializer(KeyBindingEntity, ISerializer.bracketsWrapped) + new Serializer(KeyBindingEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( LinearColorEntity, - new ISerializer(LinearColorEntity, ISerializer.bracketsWrapped) + new Serializer(LinearColorEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( LocalizedTextEntity, - new ISerializer(LocalizedTextEntity, v => `${LocalizedTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") + new Serializer(LocalizedTextEntity, v => `${LocalizedTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") ); SerializerFactory.registerSerializer( MacroGraphReferenceEntity, - new ISerializer(MacroGraphReferenceEntity, ISerializer.bracketsWrapped) + new Serializer(MacroGraphReferenceEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( @@ -10240,17 +10240,17 @@ function initializeSerializerFactory() { SerializerFactory.registerSerializer( PinEntity, - new ISerializer(PinEntity, v => `${PinEntity.lookbehind} (${v})`, "", ",", true) + new Serializer(PinEntity, v => `${PinEntity.lookbehind} (${v})`, "", ",", true) ); SerializerFactory.registerSerializer( PinReferenceEntity, - new ISerializer(PinReferenceEntity, v => v, "", " ", false, "", _ => "") + new Serializer(PinReferenceEntity, v => v, "", " ", false, "", _ => "") ); SerializerFactory.registerSerializer( TerminalTypeEntity, - new ISerializer(TerminalTypeEntity, ISerializer.bracketsWrapped) + new Serializer(TerminalTypeEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( @@ -10260,7 +10260,7 @@ function initializeSerializerFactory() { SerializerFactory.registerSerializer( RotatorEntity, - new ISerializer(RotatorEntity, ISerializer.bracketsWrapped) + new Serializer(RotatorEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( @@ -10306,22 +10306,22 @@ function initializeSerializerFactory() { SerializerFactory.registerSerializer( UnknownKeysEntity, - new ISerializer(UnknownKeysEntity, (string, entity) => `${entity.lookbehind ?? ""}(${string})`) + new Serializer(UnknownKeysEntity, (string, entity) => `${entity.lookbehind ?? ""}(${string})`) ); SerializerFactory.registerSerializer( VariableReferenceEntity, - new ISerializer(VariableReferenceEntity, ISerializer.bracketsWrapped) + new Serializer(VariableReferenceEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( Vector2DEntity, - new ISerializer(Vector2DEntity, ISerializer.bracketsWrapped) + new Serializer(Vector2DEntity, Serializer.bracketsWrapped) ); SerializerFactory.registerSerializer( VectorEntity, - new ISerializer(VectorEntity, ISerializer.bracketsWrapped) + new Serializer(VectorEntity, Serializer.bracketsWrapped) ); } diff --git a/js/entity/PinCategoryEntity.js b/js/entity/PinTypeEntity.js similarity index 95% rename from js/entity/PinCategoryEntity.js rename to js/entity/PinTypeEntity.js index 9d424f8..b0235ad 100755 --- a/js/entity/PinCategoryEntity.js +++ b/js/entity/PinTypeEntity.js @@ -62,7 +62,7 @@ export default class PinTypeEntity extends IEntity { /** @type {Boolean} */ this.bIsUObjectWrapper } - /** @param {PinCategoryEntity} other */ + /** @param {PinTypeEntity} other */ copyTypeFrom(other) { this.PinCategory = other.PinCategory this.PinSubCategory = other.PinSubCategory diff --git a/js/serialization/CustomSerializer.js b/js/serialization/CustomSerializer.js index 229e63c..8ff13ed 100755 --- a/js/serialization/CustomSerializer.js +++ b/js/serialization/CustomSerializer.js @@ -1,4 +1,4 @@ -import ISerializer from "./ISerializer.js" +import Serializer from "./Serializer.js" /** * @typedef {import("../entity/IEntity").AnyValue} AnyValue @@ -7,9 +7,9 @@ import ISerializer from "./ISerializer.js" /** * @template {AnyValue} T - * @extends {ISerializer} + * @extends {Serializer} */ -export default class CustomSerializer extends ISerializer { +export default class CustomSerializer extends Serializer { #objectWriter diff --git a/js/serialization/ObjectSerializer.js b/js/serialization/ObjectSerializer.js index b1c425e..6ffb91c 100755 --- a/js/serialization/ObjectSerializer.js +++ b/js/serialization/ObjectSerializer.js @@ -1,10 +1,10 @@ import Grammar from "./Grammar.js" -import ISerializer from "./ISerializer.js" +import Serializer from "./Serializer.js" import ObjectEntity from "../entity/ObjectEntity.js" import PinEntity from "../entity/PinEntity.js" import SerializerFactory from "./SerializerFactory.js" -export default class ObjectSerializer extends ISerializer { +export default class ObjectSerializer extends Serializer { constructor() { super(ObjectEntity, undefined, " ", "\n", false) diff --git a/js/serialization/ISerializer.js b/js/serialization/Serializer.js similarity index 91% rename from js/serialization/ISerializer.js rename to js/serialization/Serializer.js index dadef69..47d8b92 100644 --- a/js/serialization/ISerializer.js +++ b/js/serialization/Serializer.js @@ -4,13 +4,13 @@ import SerializerFactory from "./SerializerFactory.js" import Utility from "../Utility.js" /** - * @typedef {import("../entity/IEntity").EntityConstructor} EntityConstructor - * @typedef {import("../entity/IEntity").AnyValue} AnyValue - * @typedef {import("../entity/IEntity").AnyValueConstructor<*>} AnyValueConstructor + * @typedef {import("../entity/IEntity.js").EntityConstructor} EntityConstructor + * @typedef {import("../entity/IEntity.js").AnyValue} AnyValue + * @typedef {import("../entity/IEntity.js").AnyValueConstructor<*>} AnyValueConstructor */ /** @template {AnyValue} T */ -export default class ISerializer { +export default class Serializer { /** @type {(v: String, entityType: AnyValueConstructor) => String} */ static bracketsWrapped = ((v, entityType) => `(${v})`) @@ -20,7 +20,7 @@ export default class ISerializer { /** @param {AnyValueConstructor} entityType */ constructor( entityType, - wrap = ISerializer.bracketsWrapped, + wrap = Serializer.bracketsWrapped, attributePrefix = "", attributeSeparator = ",", trailingSeparator = false, @@ -94,7 +94,7 @@ export default class ISerializer { result += this.doWrite( value, insideString, - ISerializer.notWrapped, + Serializer.notWrapped, `${attributePrefix}${key}.`, attributeSeparator, trailingSeparator, @@ -122,8 +122,8 @@ export default class ISerializer { + this.attributeValueConjunctionSign + ( isSerialized - ? `"${this.doWriteValue(value, true)}"` - : this.doWriteValue(value, insideString) + ? `"${this.doWriteValue(value, true)}"` + : this.doWriteValue(value, insideString) ) } } diff --git a/js/serialization/SerializerFactory.js b/js/serialization/SerializerFactory.js index e4012dd..ca685b6 100755 --- a/js/serialization/SerializerFactory.js +++ b/js/serialization/SerializerFactory.js @@ -9,18 +9,18 @@ */ /** * @template {AnyValue} T - * @typedef {import("./ISerializer").default} ISerializer + * @typedef {import("./Serializer").default} Serializer */ export default class SerializerFactory { - /** @type {Map, ISerializer>} */ + /** @type {Map, Serializer>} */ static #serializers = new Map() /** * @template {AnyValue} T * @param {AnyValueConstructor} entity - * @param {ISerializer} object + * @param {Serializer} object */ static registerSerializer(entity, object) { SerializerFactory.#serializers.set(entity, object) @@ -29,7 +29,7 @@ export default class SerializerFactory { /** * @template {AnyValue} T * @param {new () => T} entity - * @returns {ISerializer} + * @returns {Serializer} */ static getSerializer(entity) { // @ts-expect-error diff --git a/js/serialization/ToStringSerializer.js b/js/serialization/ToStringSerializer.js index 08aac94..81f9948 100755 --- a/js/serialization/ToStringSerializer.js +++ b/js/serialization/ToStringSerializer.js @@ -1,4 +1,4 @@ -import ISerializer from "./ISerializer.js" +import Serializer from "./Serializer.js" import Utility from "../Utility.js" /** @@ -8,9 +8,9 @@ import Utility from "../Utility.js" /** * @template {AnyValue} T - * @extends {ISerializer} + * @extends {Serializer} */ -export default class ToStringSerializer extends ISerializer { +export default class ToStringSerializer extends Serializer { /** @param {AnyValueConstructor} entityType */ constructor(entityType) { diff --git a/js/serialization/initializeSerializerFactory.js b/js/serialization/initializeSerializerFactory.js index 4d3e7be..d1491b6 100755 --- a/js/serialization/initializeSerializerFactory.js +++ b/js/serialization/initializeSerializerFactory.js @@ -7,7 +7,7 @@ import IdentifierEntity from "../entity/IdentifierEntity.js" import Integer64Entity from "../entity/Integer64Entity.js" import IntegerEntity from "../entity/IntegerEntity.js" import InvariantTextEntity from "../entity/InvariantTextEntity.js" -import ISerializer from "./ISerializer.js" +import Serializer from "./Serializer.js" import KeyBindingEntity from "../entity/KeyBindingEntity.js" import LinearColorEntity from "../entity/LinearColorEntity.js" import LocalizedTextEntity from "../entity/LocalizedTextEntity.js" @@ -96,7 +96,7 @@ export default function initializeSerializerFactory() { SerializerFactory.registerSerializer( FunctionReferenceEntity, - new ISerializer(FunctionReferenceEntity, ISerializer.bracketsWrapped) + new Serializer(FunctionReferenceEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( @@ -121,27 +121,27 @@ export default function initializeSerializerFactory() { SerializerFactory.registerSerializer( InvariantTextEntity, - new ISerializer(InvariantTextEntity, v => `${InvariantTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") + new Serializer(InvariantTextEntity, v => `${InvariantTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") ) SerializerFactory.registerSerializer( KeyBindingEntity, - new ISerializer(KeyBindingEntity, ISerializer.bracketsWrapped) + new Serializer(KeyBindingEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( LinearColorEntity, - new ISerializer(LinearColorEntity, ISerializer.bracketsWrapped) + new Serializer(LinearColorEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( LocalizedTextEntity, - new ISerializer(LocalizedTextEntity, v => `${LocalizedTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") + new Serializer(LocalizedTextEntity, v => `${LocalizedTextEntity.lookbehind}(${v})`, "", ", ", false, "", _ => "") ) SerializerFactory.registerSerializer( MacroGraphReferenceEntity, - new ISerializer(MacroGraphReferenceEntity, ISerializer.bracketsWrapped) + new Serializer(MacroGraphReferenceEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( @@ -173,17 +173,17 @@ export default function initializeSerializerFactory() { SerializerFactory.registerSerializer( PinEntity, - new ISerializer(PinEntity, v => `${PinEntity.lookbehind} (${v})`, "", ",", true) + new Serializer(PinEntity, v => `${PinEntity.lookbehind} (${v})`, "", ",", true) ) SerializerFactory.registerSerializer( PinReferenceEntity, - new ISerializer(PinReferenceEntity, v => v, "", " ", false, "", _ => "") + new Serializer(PinReferenceEntity, v => v, "", " ", false, "", _ => "") ) SerializerFactory.registerSerializer( TerminalTypeEntity, - new ISerializer(TerminalTypeEntity, ISerializer.bracketsWrapped) + new Serializer(TerminalTypeEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( @@ -193,7 +193,7 @@ export default function initializeSerializerFactory() { SerializerFactory.registerSerializer( RotatorEntity, - new ISerializer(RotatorEntity, ISerializer.bracketsWrapped) + new Serializer(RotatorEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( @@ -239,21 +239,21 @@ export default function initializeSerializerFactory() { SerializerFactory.registerSerializer( UnknownKeysEntity, - new ISerializer(UnknownKeysEntity, (string, entity) => `${entity.lookbehind ?? ""}(${string})`) + new Serializer(UnknownKeysEntity, (string, entity) => `${entity.lookbehind ?? ""}(${string})`) ) SerializerFactory.registerSerializer( VariableReferenceEntity, - new ISerializer(VariableReferenceEntity, ISerializer.bracketsWrapped) + new Serializer(VariableReferenceEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( Vector2DEntity, - new ISerializer(Vector2DEntity, ISerializer.bracketsWrapped) + new Serializer(Vector2DEntity, Serializer.bracketsWrapped) ) SerializerFactory.registerSerializer( VectorEntity, - new ISerializer(VectorEntity, ISerializer.bracketsWrapped) + new Serializer(VectorEntity, Serializer.bracketsWrapped) ) }