gtac-types 0.0.1

package/src/types/xml.d.ts

@@ -0,0 +1,232 @@
+/**
+ * GTAC XML and File I/O Type Definitions
+ *
+ * Defines the types for XML document manipulation and file I/O operations.
+ * The `xml` global provides a DOM-like API for creating, loading, saving,
+ * and traversing XML documents. `FileObject` is the handle type used by
+ * the file I/O functions (`fileOpen`, `fileRead`, `fileWrite`, etc.).
+ *
+ * All declarations are global — no import required.
+ *
+ * @module types/xml
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Load an XML file and read its contents
+ * const doc = xml.loadFile("data/config.xml");
+ * if (doc) {
+ *     const root = xml.documentElement;
+ *     const settings = xml.findChild(root, "settings");
+ *     if (settings) {
+ *         const value = xml.getAttribute(settings, "difficulty");
+ *         console.log("Difficulty: " + value);
+ *     }
+ * }
+ *
+ * @example
+ * // Create a new XML document and save it
+ * const doc = xml.createDocument("root");
+ * const child = xml.createElement("item");
+ * xml.setAttribute(child, "id", "1");
+ * xml.setText(child, "Hello World");
+ * xml.appendChild(xml.documentElement, child);
+ * xml.saveFile("data/output.xml");
+ */
+
+// ===== XML =====
+
+/**
+ * An XML document handle (opaque type).
+ *
+ * Represents a parsed or created XML document. Use the `xml` API to create,
+ * load, and save documents. The internal structure is engine-defined.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+type XmlDocument = {}
+
+/**
+ * An XML element node handle (opaque type).
+ *
+ * Represents a single element node in an XML document tree. Elements have
+ * a name, text content, attributes, parent, and children. Use the `xml` API
+ * to navigate and manipulate the tree.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ */
+type XmlElement = {}
+
+/**
+ * XML document manipulation API.
+ *
+ * Provides a complete set of DOM-like functions for creating, loading,
+ * saving, and traversing XML documents. The API is stateful: `loadFile()`
+ * and `createDocument()` set the current `documentElement` which is used
+ * implicitly by other functions.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Create a simple XML structure
+ * xml.createDocument("players");
+ * xml.saveFile("players.xml");
+ */
+declare var xml: {
+    /**
+     * Creates a new, empty XML document with the specified root element name.
+     * The root element becomes the current `documentElement`.
+     *
+     * @param rootName - The tag name for the root element (e.g. `"settings"`).
+     * @returns A new `XmlDocument` handle.
+     */
+    createDocument(rootName: string): XmlDocument;
+
+    /**
+     * Loads an XML file from the filesystem.
+     * On success, the document's root element becomes the current `documentElement`.
+     *
+     * @param path - File path to the XML file (relative to resource root).
+     * @returns The loaded `XmlDocument`, or `null` if the file could not be loaded.
+     */
+    loadFile(path: string): XmlDocument | null;
+
+    /**
+     * The root element of the currently loaded or created XML document.
+     * This is set automatically by `loadFile()` and `createDocument()`.
+     */
+    documentElement: XmlElement;
+
+    /**
+     * Saves the current XML document to a file on disk.
+     *
+     * @param path - Output file path (relative to resource root).
+     * @returns `true` if the file was saved successfully, `false` on error.
+     */
+    saveFile(path: string): boolean;
+
+    /**
+     * Creates a new, unattached XML element node.
+     * The element is not added to any document until `appendChild()` is called.
+     *
+     * @param name - The tag name for the new element (e.g. `"entry"`).
+     * @returns A new `XmlElement` handle.
+     */
+    createElement(name: string): XmlElement;
+
+    /**
+     * Appends a child element to a parent element.
+     * The child becomes the last child of the parent.
+     *
+     * @param parent - The parent `XmlElement` to append to.
+     * @param child - The `XmlElement` to add as a child.
+     */
+    appendChild(parent: XmlElement, child: XmlElement): void;
+
+    /**
+     * Removes a child element from its parent.
+     * The child is detached but not destroyed; it can be re-added elsewhere.
+     *
+     * @param parent - The parent `XmlElement`.
+     * @param child - The `XmlElement` to remove.
+     */
+    removeChild(parent: XmlElement, child: XmlElement): void;
+
+    /**
+     * Gets the value of an attribute on an element.
+     *
+     * @param element - The `XmlElement` to query.
+     * @param name - The attribute name.
+     * @returns The attribute value as a string, or an empty string if not set.
+     */
+    getAttribute(element: XmlElement, name: string): string;
+
+    /**
+     * Sets an attribute on an element. Creates the attribute if it doesn't exist.
+     *
+     * @param element - The target `XmlElement`.
+     * @param name - The attribute name.
+     * @param value - The attribute value to set.
+     */
+    setAttribute(element: XmlElement, name: string, value: string): void;
+
+    /**
+     * Removes an attribute from an element.
+     *
+     * @param element - The target `XmlElement`.
+     * @param name - The attribute name to remove.
+     */
+    removeAttribute(element: XmlElement, name: string): void;
+
+    /**
+     * Gets all direct child elements of a parent element.
+     * Does not return text nodes or nested children (non-recursive).
+     *
+     * @param element - The parent `XmlElement`.
+     * @returns An array of direct child `XmlElement` handles.
+     */
+    getChildren(element: XmlElement): XmlElement[];
+
+    /**
+     * Gets the text content of an element.
+     *
+     * @param element - The `XmlElement` to read from.
+     * @returns The text content as a string.
+     */
+    getText(element: XmlElement): string;
+
+    /**
+     * Sets the text content of an element.
+     *
+     * @param element - The target `XmlElement`.
+     * @param text - The text string to set.
+     */
+    setText(element: XmlElement, text: string): void;
+
+    /**
+     * Gets the tag name of an element.
+     *
+     * @param element - The `XmlElement` to query.
+     * @returns The element's tag name (e.g. `"entry"`, `"root"`).
+     */
+    getName(element: XmlElement): string;
+
+    /**
+     * Gets the parent element of a given element.
+     *
+     * @param element - The child `XmlElement`.
+     * @returns The parent `XmlElement`, or `null` if this is the root element.
+     */
+    getParent(element: XmlElement): XmlElement | null;
+
+    /**
+     * Finds the first direct child element with a given tag name.
+     * This is a non-recursive search; only immediate children are checked.
+     *
+     * @param element - The parent `XmlElement` to search within.
+     * @param name - The tag name to search for.
+     * @returns The first matching `XmlElement`, or `null` if not found.
+     */
+    findChild(element: XmlElement, name: string): XmlElement | null;
+};
+
+// ===== File =====
+
+/**
+ * An open file handle (opaque type).
+ *
+ * Returned by `fileOpen()` and used with `fileRead()`, `fileWrite()`,
+ * `fileClose()`, `fileGetSize()`, and `fileGetPath()`. The internal
+ * representation is engine-defined.
+ *
+ * @see https://wiki.gtaconnected.com — GTA Connected Wiki
+ *
+ * @example
+ * // Open, read, and close a file
+ * const file = fileOpen("data.txt");
+ * if (file) {
+ *     const content = fileRead(file);
+ *     console.log("File contents: " + content);
+ *     fileClose(file);
+ * }
+ */
+type FileObject = {}

package/templates/meta.xml

@@ -0,0 +1,4 @@
+<meta>
+	<script src="server.js" type="server" />
+	<script src="client.js" type="client" />
+</meta>

package/templates/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"compilerOptions": {
+		"target": "ES2015",
+		"lib": ["ES2015"],
+		"strict": true,
+		"noEmit": true,
+		"skipLibCheck": true,
+		"moduleResolution": "node",
+		"types": ["gtac-types"]
+	},
+	"include": ["src/**/*.ts"]
+}