Update registry

Author: LightningLaser8

README.md

@@ -1,16 +1,23 @@
 # Integrate
 
-A library for mod loading into serialisable registries.
+A library for mod loading into serialisable registries.  
+Can be used in conjunction with [ISL](https://github.com/LightningLaser8/ISL) to perform complex operations.
 
 ## Terminology
 
 - A _registry_ is a data structure for holding case-insensitive key-value pairs. Simply, it matches names to objects, without caring about capitalisation. They are instances of `Integrate.Registry`.
-- *Registry name*s are string locations of an item in a _registry_.
-- *Constructible object*s are basic objects with a `type` property, holding a _registry name_ of a class.
-- _Content_ refers to any constructible object with a registry name, defined by the mod. Any content is an instance of `Integrate.Content`.
+- *Registry name*s or *Registry location*s are strings which are keys in a _registry_. They can be used to refer to a _constructible object_.
+- *Constructible object*s are basic, serialisable objects with a `type` property, holding a _registry name_ of a class.
+- _Content_ refers to any _constructible object_ with a _registry name_, defined by the _mod_. Any content is an instance of `Integrate.Content`.
 - A _mod_ is a directory of files, each one adding _content_.
 - A _content file_ is a JSON file holding a _constructible object_.
 
+### ISL
+
+- _ISL_, or _Integrate Scripting Language_ is an external interpreted scripting language for use with this modloader, to create complex events.
+- A _script_ is a `.isl` file to be executed when an _event_ is fired.
+- An _event_ is a signal from the game that Integrate needs to run some scripts. Every script needs to define which events they fire on.
+
 ## Example (JS)
 
 _Adding Integrate mods to your project_
@@ -91,11 +98,13 @@ This is the most important file in any Integrate mod, defining paths and registr
 It consists of a _single array_, each entry being an object with these three properties:  
 `path` defining the _relative location_ of the _content file_ being described.  
 `name` being the _registry name_ of this content.  
-`registry` being optional, defining the registry this content will be added to. By default, this will be `"content"`. **This registry does not exist by default, and will throw errors if not defined.**
+`registry` being optional, defining the registry this content will be added to. By default, this will be `"content"`. **This registry does not exist by default, and will throw errors if not defined using `Integrate.addModdableRegistry()`.**
 
 ### Content Files
 
 These describe the actual content itself, not metadata.
+They can be anywhere, even outside the mod directory, as long as `definitions.json` points to them, and the program can reach them.  
+This is to leave organisation up to the mod developer, so you can organise the files hovever you like.
 
 ```json
 {
@@ -112,6 +121,7 @@ These describe the actual content itself, not metadata.
 ## Interface
 
 Integrate has several functions to customise modloading, which are documented here.
+This section assumes you imported Integrate in a single namespace, called `Integrate`.
 
 ### Integrate.add()
 
@@ -142,7 +152,7 @@ Returns an `Integrate.Mod` object, holding all the info about the imported mod.
 Integrate.addModdableRegistry(reg: Integrate.Registry, name: string): void
 ```
 
-`reg` is the `Integrate.Registry` (or similar implementing the same methods) to allow modification of.  
+`reg` is the `Integrate.Registry` (or similar object implementing the same methods) to allow modification of.  
 `name` is the string that this registry will be referred to by.
 
 ### Integrate.setPrefix()
@@ -163,7 +173,7 @@ Integrate.setPrefix(value: boolean): void
 Integrate.setInfoOutput(func: (info: string) => void): void
 ```
 
-`func` callback for each status message. THe parameter `info` contains the message, as a string. By default, this function is `console.log`.
+`func` callback for each status message. The parameter `info` contains the message, as a string. By default, this function is `console.log`.
 
 ### Integrate.types
 `Integrate.types` is an `Integrate.Registry` holding all types mod content can be an instance of.
@@ -172,7 +182,7 @@ Integrate.types: Integrate.Registry
 ```
 
 ### Integrate.construct()
-`Integrate.construct()` is a helpful function that combines `Integrate.Registry.create()` and `Integrate.Registry.construct` for mod content.
+`Integrate.construct()` is a helpful function that combines `Integrate.Registry.create()` and `Integrate.Registry.construct()` for mod content. It constructs an object either literally or from any moddable registry, using types from `Integrate.types`.
 ```ts
 Integrate.construct(object: object | string, defaultType: class): object
 ```
@@ -247,8 +257,8 @@ class Registry {
 `add()` Adds an item to registry.  
 `has()` Checks for an item in registry.
 `get()` Gets an item from registry name.  
-`create()` Constructs an item from registry. Note that this only works with objects. The parameter `registry` should be the registry holding all types, such as `Integrate.types`.  
-`construct()` Constructs an item using a type from registry. Note that this only works with object entries.  
+`create()` Constructs an item from this registry. Note that this only works with object entries. The parameter `registry` should be the registry holding all types, such as `Integrate.types`.  
+`construct()` Constructs an item using a type from this registry. Note that this only works with object parameters.  
 `rename()` Renames a registry item. Neither parameter is case-sensitive.  
 `alias()` Adds another registry item with the same content as the specified one.  
 `forEach()` Executes a function for each element in the registry.  

integrate.png

@@ -0,0 +1,41 @@
+## ISL
+_Integrate Scripting Language_
+
+ISL is a scripting language designed for use with this loader, allowing mods to script complex events in addition to simple content.  
+This can be disabled by game devs, so check the project's Integrate documentation for this information.
+
+There are no standard keywords in Integrate, as they are all added by the developer. Because of this, it is recommended to fully read through their extension documentation before making an ISL mod for their project.
+
+This documentation from this point assumes you know about ISL, and have familiarised yourself with its basic features. If not, go read the [ISL wiki](https://github.com/LightningLaser8/ISL/wiki).
+
+### Creating Scripts
+Scripts are a bit different to normal mod content. They don't have a `type`, and are defined in `.isl` files, instead of `.json`.
+
+A script file is essentially a normal ISL program, with some extra properties, defined in metatags.
+
+An example script file (`script.isl`):
+```isl
+[onevent mod-load] // When the mod loads
+[with loadstate, contentnamelist] // Using some properties from the event
+
+// Regular ISL from here
+function logstr name:string
+log :\name\
+end logstr
+
+if \loadstate\ = true log "Mod loaded."
+else log "Loading failed."
+| stop
+
+iterate \contentnamelist\ with logstr
+```
+
+Definitions look like this:
+```json
+[
+  {
+    "type": "script",
+    "path": "./script.isl"
+  }
+]
+```

isl.md

@@ -13,10 +13,8 @@ class Registry {
    * @param {*} item Item to add to registry.
    */
   add(name, item) {
-    if (!name) return; //catch empty name
-    if (!item) return; //catch null items
-    if (typeof name !== "string") name = name.toString(); //Stringify name
-    name = name.toLowerCase(); //Remove case sensitivity.
+    name = Registry.#processName(name);
+    if (!item) throw new TypeError("Registries cannot contain null");
     //Throw an error if the item already exists.
     if (this.has(name))
       throw new SyntaxError(
@@ -33,8 +31,8 @@ class Registry {
    * @returns Whether or not the name exists.
    */
   has(name) {
-    if (typeof name !== "string") name = name.toString(); //Stringify name
-    name = name.toLowerCase(); //Remove case sensitivity.
+    if (!name) return false;
+    name = Registry.#processName(name);
     //Return presence
     return this.#content.has(name);
   }
@@ -44,7 +42,8 @@ class Registry {
    * @returns The item, if present.
    */
   get(name) {
-    if (typeof name !== "string") name = name.toString(); //Stringify name
+    if (!name) throw new ReferenceError("No registry contains null!");
+    name = Registry.#processName(name);
     name = name.toLowerCase(); //Remove case sensitivity.
     //Throw an error if the item doesn't exist.
     if (!this.has(name))
@@ -54,53 +53,21 @@ class Registry {
           " does not exist in registry! Consider checking your spelling."
       );
     //Return item, if it exists.
-    return this.#content.get(name);
-  }
-  /**
-   * Constructs an item from registry. Note that this only works with objects.
-   * @param {string} name Name of item to construct.
-   * @param {Registry} registry Registry for the type of the item.
-   * @param {Function} [defaultType=Object] Constructor function or class to use if there's no defined type.
-   */
-  create(name, registry, defaultType = Object) {
-    return this.#construct(this.get(name), registry, defaultType);
-  }
-  /**
-   * Constructs an item using a type from registry. Note that this only works with objects.
-   * @param {object} object Object to construct.
-   * @param {Function} [defaultType=Object] Constructor function or class to use if there's no defined type.
-   */
-  construct(object, defaultType = Object) {
-    return this.#construct(object, this, defaultType);
-  }
-  #construct(object, registry, defaultType = Object) {
-    if (!object) return; //Catch accidental calls using null, undefined or similar
-    //Constructs an instance using type from registry, if it exists. If not, throw error.
-    //If type is undefined, use the default.
-    let instantiated = new (
-      object.type ? registry.get(object.type) : defaultType
-    )();
-    let cloned = {};
-    //Clone the object if possible, to copy stuff like bullet drawers, or weapon.shoot.pattern. If it fails, just use the original.
+    let item = this.#content.get(name);
     try {
-      cloned = structuredClone(object);
-    } catch (error) {
-      cloned = object;
-      console.warn("Could not clone object:", error);
+      item.registryName = name;
+    } catch (e) {
+      console.warn("Non-object entries do not have full feature support.");
     }
-    checkForClashingFunctions(cloned, instantiated)
-    instantiated = Object.assign(instantiated, cloned);
-    instantiated.init ? instantiated.init() : {}; //Initialise if possible.
-    return instantiated;
+    return item;
   }
   /**
    * Renames a registry item. Neither parameter is case-sensitive.
    * @param {string} name Registry name to change.
    * @param {string} newName What to change the name to.
    */
   rename(name, newName) {
-    if (typeof name !== "string") name = name.toString(); //Stringify name
-    name = name.toLowerCase(); //Remove case sensitivity.
+    name = Registry.#processName(name);
     //Throw an error if the item doesn't exist.
     if (!this.has(name))
       throw new ReferenceError(
@@ -121,8 +88,7 @@ class Registry {
    * @param {string} as What to change the name to.
    */
   alias(name, as) {
-    if (typeof name !== "string") name = name.toString(); //Stringify name
-    name = name.toLowerCase(); //Remove case sensitivity.
+    name = Registry.#processName(name);
     //Throw an error if the item doesn't exist.
     if (!this.has(name))
       throw new ReferenceError(
@@ -136,13 +102,84 @@ class Registry {
     this.add(as, current);
   }
   /**
-   * Executes a function for each element in the registry.
-   * @param {(item, name: string) => void} func Callback for each element.
+   * Performs a function on each item in registry.
+   * @param {(name: string, item) => void} callback Function to perform on each item.
    */
-  forEach(func) {
-    this.#content.forEach((element, name) => {
-      void func(element, name);
-    });
+  forEach(callback) {
+    this.#content.forEach((value, key) => void callback(key, value));
+    return true;
+  }
+  /**
+   * Performs a function on each item in registry asynchronously.
+   * @param {(name: string, item) => void} callback Function to perform on each item.
+   */
+  async forEachAsync(callback) {
+    this.#content.forEach(
+      async (value, key) => await void callback(key, value)
+    );
+  }
+  /**
+   *
+   * @param {int} index Zero-based index of the item to get.
+   * @returns The registry item at the index.
+   */
+  at(index) {
+    if (index >= this.#content.size)
+      throw new RangeError(
+        "Index " + index + " out of bounds for registry length " + this.size
+      );
+    return [...this.#content.keys()][index];
+  }
+  static #processName(name) {
+    if (!name) throw new TypeError("Registry name must be defined");
+    if (hasNonAscii(name))
+      throw new TypeError("Registry names may only contain ASCII characters");
+    return name.toString().toLowerCase();
+  }
+  static isValidName(name) {
+    try {
+      this.#processName(name);
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+  /**
+   * Constructs an item from this registry, using a type from another registry.
+   * @param {string} name Name of item to construct.
+   * @param {Registry} registry Registry for the type of the item.
+   * @param {Function} [defaultType=Object] Constructor function or class to use if there's no defined type.
+   */
+  create(name, registry, defaultType = Object) {
+    return Registry.#construct(this.get(name), registry, defaultType);
+  }
+  /**
+   * Constructs an item using a type from this registry. Note that this only works with objects.
+   * @param {object} object Object to construct.
+   * @param {Function} [defaultType=Object] Constructor function or class to use if there's no defined type.
+   */
+  construct(object, defaultType = Object) {
+    return Registry.#construct(object, this, defaultType);
+  }
+  static #construct(object, registry, defaultType = Object) {
+    if (!object) return; //Catch accidental calls using null, undefined or similar
+    //Constructs an instance using type from registry, if it exists. If not, throw error.
+    //If type is undefined, use the default.
+    let instantiated = new (
+      object.type ? registry.get(object.type) : defaultType
+    )();
+    let cloned = {};
+    //Clone the object if possible, to copy stuff like bullet drawers, or weapon.shoot.pattern. If it fails, just use the original.
+    try {
+      cloned = structuredClone(object);
+    } catch (error) {
+      cloned = object;
+      console.warn("Could not clone object:", error);
+    }
+    checkForClashingFunctions(cloned, instantiated);
+    instantiated = Object.assign(instantiated, cloned);
+    instantiated.init ? instantiated.init() : {}; //Initialise if possible.
+    return instantiated;
   }
   *[Symbol.iterator]() {
     for (let item of this.#content.values()) {
@@ -163,14 +200,18 @@ class Registry {
   }
 }
 
-function checkForClashingFunctions(source, target){
-  for(let prop in source){
-    if(prop in target){
-      if(typeof target[prop] === "function"){
-        throw new SyntaxError("Property '"+prop+"' clashes with a class method!")
+let hasNonAscii = (str) => [...str].some((char) => char.charCodeAt(0) > 127);
+
+function checkForClashingFunctions(source, target) {
+  for (let prop in source) {
+    if (prop in target) {
+      if (typeof target[prop] === "function") {
+        throw new SyntaxError(
+          "Property '" + prop + "' clashes with a class method!"
+        );
       }
     }
   }
 }
 
-export { Registry };
+export { Registry };