Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

@s4tk/xml-dom

Package Overview
Dependencies
Maintainers
1
Versions
11
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@s4tk/xml-dom - npm Package Compare versions

Comparing version
0.1.2
 to
0.1.3
+7
-1
CHANGELOG.md

@@ -8,5 +8,11 @@ # Changelog

## [0.1.3] - 2022/02/17
### Changed
- Changed type of options in toXml() method to XmlFormattingOptions interface.
### Added
- Added includeProcessingInstructions option to XmlFormattingOptions.
## [0.1.2] - 2022/01/29
### Added
- First release.
- Added `findChild()` method on XmlNode.

@@ -13,0 +19,0 @@ ## [0.1.1] - 2022/01/23

+2
-2
package.json
{
"name": "@s4tk/xml-dom",
"version": "0.1.2",
"version": "0.1.3",
"main": "xml.js",

@@ -9,3 +9,3 @@ "repository": {

},
"homepage": "https://github.com/sims4toolkit/xml-dom#readme",
"homepage": "https://sims4toolkit.com/#/docs/xml-dom",
"bugs": {

@@ -12,0 +12,0 @@ "url": "https://github.com/sims4toolkit/xml-dom/issues"

+1
-318
README.md

@@ -7,4 +7,2 @@ # Sims 4 Toolkit - XML DOM (@s4tk/xml-dom)

**PLEASE NOTE**: Proper documentation for this package will be provided when the Sims 4 Toolkit website has been completed. For now, please reference this README's Documentation section, where the TS declaration file stubs are provided.
## Installation

@@ -26,317 +24,2 @@

### Index
- [interface XmlNode](#interface-xmlnode)
- [class XmlDocumentNode](#class-xmldocumentnode)
- [class XmlElementNode](#class-xmlelementnode)
- [class XmlValueNode](#class-xmlvaluenode)
- [class XmlCommentNode](#class-xmlcommentnode)
### interface XmlNode
An interface for all XML nodes.
#### Importing
```ts
import type { XmlNode } from "@s4tk/xml-dom"; // ESM (TypeScript only)
```
#### Properties
```ts
/**
* Object containing the attributes of this node. Guaranteed to be an object
* if this node is able to have attributes, but if it cannot have attributes
* (e.g. value nodes, comment nodes), it is undefined.
*/
get attributes(): Attributes;
```
```ts
/**
* The first child of this node. If there are no children, it is undefined.
* If this node cannot have children, then an exception is thrown when setting
* this property.
*/
get child(): XmlNode;
set child(child: XmlNode);
```
```ts
/**
* The children of this node. This is guaranteed to be an array if this node
* can have children (e.g. a document or an element), but is undefined if it
* cannot (e.g. values or comments).
*/
get children(): XmlNode[];
```
```ts
/** Whether or not this node has an array for children. */
get hasChildren(): boolean;
```
```ts
/**
* Shorthand for the `s` attribute. If this node cannot have attributes, an
* exception is thrown when setting this property.
*/
get id(): string | number | bigint;
set id(id: string | number | bigint);
```
```ts
/**
* The value of this node's first child, if it has one. If this node cannot
* have children, or if its first child cannot have a value, an exception is
* thrown when setting this property.
*/
get innerValue(): XmlValue;
set innerValue(value: XmlValue);
```
```ts
/**
* Shorthand for the `n` attribute. If this node cannot have attributes, an
* exception is thrown when setting this property.
*/
get name(): string;
set name(name: string);
```
```ts
/** The number of children on this node. */
get numChildren(): number;
```
```ts
/**
* The tag of this node. If this node is not an element or if the given tag is
* not a non-empty string, an exception is thrown when setting this property.
*/
get tag(): string;
set tag(tag: string);
```
```ts
/**
* Shorthand for the `t` attribute. If this node cannot have attributes, an
* exception is thrown when setting this property.
*/
get type(): string;
set type(type: string);
```
```ts
/**
* The value of this node. If this node cannot have a value (i.e. it has
* children instead), an exception is thrown when setting this property.
*/
get value(): XmlValue;
set value(value: XmlValue);
```
#### Methods
```ts
/**
* Adds the given children to this node by object reference. If you are adding
* these children to multiple nodes and plan on mutating them, it is
* recommended that you use `addClones()` instead.
*
* @param children Child nodes to append to this one
* @throws If this node cannot have children
*/
addChildren(...children: XmlNode[]): void;
```
```ts
/**
* Adds the given children to this node by value. All children are cloned
* prior to being added.
*
* @param children Child nodes to append to this one
* @throws If this node cannot have children
*/
addClones(...children: XmlNode[]): void;
```
```ts
/**
* Returns a deep copy of this node.
*/
clone(): XmlNode;
```
```ts
/**
* Calls the `sort()` method on this node and all of its descendants.
*
* @param compareFn Function used to determine the order of the elements. It
* is expected to return a negative value if first argument is less than
* second argument, zero if they're equal and a positive value otherwise. If
* omitted, the elements are sorted in ascending, ASCII character order.
* [Copied from `Array.sort()` documentation]
* @throws If this node cannot have children
*/
deepSort(compareFn?: (a: XmlNode, b: XmlNode) => number): void;
```
```ts
/**
* Sorts the children of this node using the provided function. If no function
* is given, they are sorted in ascending alphanumeric order by their `n`
* attribute (their name). Children without names will retain their order
* relative to one another and will appear at the end.
*
* @param compareFn Function used to determine the order of the elements. It
* is expected to return a negative value if first argument is less than
* second argument, zero if they're equal and a positive value otherwise. If
* omitted, the elements are sorted in ascending, ASCII character order.
* [Copied from `Array.sort()` documentation]
* @throws If this node cannot have children
*/
sort(compareFn?: (a: XmlNode, b: XmlNode) => number): void;
```
```ts
/**
* Serializes this node and all of its descendants as XML code.
*
* Options
* - `indents`: Number of times to indent this node. This will increase by 1
* for each recursive call. (Default = 0)
* - `spacesPerIndent`: Number of spaces to use per indent. (Default = 2)
*
* @param options Object containing options for serializing
*/
toXml(options?: { indents?: number; spacesPerIndent?: number; }): string;
```
### class XmlDocumentNode
A node for an entire XML document. This document _can_ have multiple children, but one is recommended.
See [XmlNode](#interface-xmlnode) for properties and methods.
#### Importing
```ts
import { XmlDocumentNode } from "@s4tk/xml-dom"; // ESM
const { XmlDocumentNode } = require("@s4tk/xml-dom"); // CJS
```
#### Initialization
```ts
/**
* Creates a new XmlDocumentNode from the given root node. If no root node
* is given, then this document is empty.
*
* @param root Optional node to use at the root of this document
*/
constructor(root?: XmlNode);
```
```ts
/**
* Parses and returns either a string or a buffer containing XML code as a
* XmlDocumentNode, if possible.
*
* Options
* - `allowMultipleRoots`: Whether or not the document should still be created
* if it will have multiple roots. If false, an exception will be thrown if
* there is more than one root element. (Default = false)
* - `ignoreComments`: Whether or not comments should be ignored. If false,
* comments will be parsed. (Default = false)
*
* @param xml XML document to parse as a node
* @param options Optional object containing options
*/
static from(xml: string | Buffer, options?: {
allowMultipleRoots?: boolean;
ignoreComments?: boolean;
}): XmlDocumentNode;
```
### class XmlElementNode
A node that can have a tag, attributes, and children.
See [XmlNode](#interface-xmlnode) for properties and methods.
#### Importing
```ts
import { XmlElementNode } from "@s4tk/xml-dom"; // ESM
const { XmlElementNode } = require("@s4tk/xml-dom"); // CJS
```
#### Initialization
```ts
/**
* Creates a new XmlElementNode with the given tag, attributes, and children.
*
* Arguments:
* - `tag`: Required. The tag to use for this node.
* - `attributes`: An object for the attributes of this node. (Default = {})
* - `children`: An array for the children of this node. (Default = [])
*
* @param args Arguments for construction
*/
constructor(args: {
tag: string;
attributes?: Attributes;
children?: XmlNode[];
});
```
### class XmlValueNode
A node that can have an inner value.
See [XmlNode](#interface-xmlnode) for properties and methods.
#### Importing
```ts
import { XmlValueNode } from "@s4tk/xml-dom"; // ESM
const { XmlValueNode } = require("@s4tk/xml-dom"); // CJS
```
#### Initialization
```ts
/**
* Creates a new XmlValueNode with the given value.
*
* @param value Optional value of this node.
*/
constructor(value?: XmlValue);
```
### class XmlCommentNode
A node that can have a comment value.
See [XmlNode](#interface-xmlnode) for properties and methods.
#### Importing
```ts
import { XmlCommentNode } from "@s4tk/xml-dom"; // ESM
const { XmlCommentNode } = require("@s4tk/xml-dom"); // CJS
```
#### Initialization
```ts
/**
* Creates a new XmlCommentNode with the given value.
*
* @param value Optional value of this comment node.
*/
constructor(value?: string);
```
Visit [the webpage](https://sims4toolkit.com/#/docs/xml-dom) for documentation.
+21
-13
xml.d.ts

@@ -8,2 +8,21 @@ /// <reference types="node" />

declare type XmlValue = number | bigint | boolean | string;
/**
* Options to use when writing a node as an XML string.
*/
interface XmlFormattingOptions {
/**
* Whether or not to include the XML processing instruction tag at the top of
* this output. Only applicable to document nodes. (Default = true)
*/
includeProcessingInstructions?: boolean;
/**
* Number of times to indent this node. This will increase by 1 for each
* recursive call. (Default = 0)
*/
indents?: number;
/**
* Number of spaces to use per indent. (Default = 2)
*/
spacesPerIndent?: number;
}
/** A node in an XML DOM. */

@@ -129,13 +148,5 @@ export interface XmlNode {

*
* Options
* - `indents`: Number of times to indent this node. This will increase by 1
* for each recursive call. (Default = 0)
* - `spacesPerIndent`: Number of spaces to use per indent. (Default = 2)
*
* @param options Object containing options for serializing
*/
toXml(options?: {
indents?: number;
spacesPerIndent?: number;
}): string;
toXml(options?: XmlFormattingOptions): string;
}

@@ -215,6 +226,3 @@ /** A base implementation of XmlNode. */

clone(): XmlDocumentNode;
toXml({ indents, spacesPerIndent }?: {
indents?: number;
spacesPerIndent?: number;
}): string;
toXml({ includeProcessingInstructions, indents, spacesPerIndent }?: XmlFormattingOptions): string;
}

@@ -221,0 +229,0 @@ /** A node with a tag, attributes, and children. */

+4
-2
xml.js

@@ -191,5 +191,7 @@ "use strict";

}
toXml({ indents = 0, spacesPerIndent = 2 } = {}) {
toXml({ includeProcessingInstructions = true, indents = 0, spacesPerIndent = 2 } = {}) {
const spaces = " ".repeat(indents * spacesPerIndent);
const lines = [`${spaces}${XML_DECLARATION}`];
const lines = [];
if (includeProcessingInstructions)
lines.push(`${spaces}${XML_DECLARATION}`);
this.children.forEach(child => {

@@ -196,0 +198,0 @@ lines.push(child.toXml({ indents, spacesPerIndent }));