js2xmlparser

  • Version 5.0.0
  • Published
  • 59.9 kB
  • 1 dependency
  • Apache-2.0 license

Install

npm i js2xmlparser
yarn add js2xmlparser
pnpm add js2xmlparser

Overview

Parses JavaScript objects into XML

Index

Functions

function parse

parse: (root: string, object: unknown, options?: IOptions) => string;
  • Returns a XML string representation of the specified object using the specified options.

    root is the name of the root XML element. When the object is converted to XML, it will be a child of this root element.

function parseToExistingElement

parseToExistingElement: (
element: XmlElement<unknown>,
object: unknown,
options?: IOptions
) => void;
  • Converts the specified object to XML and adds the XML representation to the specified XmlElement object using the specified options.

    This function does not add a root element. In addition, it does not add an XML declaration or DTD, and the associated options in IOptions are ignored. If desired, these must be added manually.

Classes

class Absent

class Absent {}
  • Indicates that an object of a particular type should be suppressed from the XML output.

    See the typeHandlers property in IOptions for more details.

property instance

static readonly instance: Absent;
  • Returns the sole instance of Absent.

Interfaces

interface IDeclarationOptions

interface IDeclarationOptions {}
  • The options associated with the XML declaration. An example of an XML declaration is as follows:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

property encoding

encoding?: string;
  • The encoding attribute to be included in the declaration. If defined, this value must be a valid encoding. By default, no encoding attribute is included.

property include

include?: boolean;
  • Whether to include a declaration in the generated XML. By default, one is included.

property standalone

standalone?: string;
  • The value of the standalone attribute to be included in the declaration. If defined, this value must be "yes" or "no". By default, no standalone attribute is included.

property version

version?: string;
  • The XML version to be included in the declaration. If defined, this value must be a valid XML version number. Defaults to "1.0".

interface IDtdOptions

interface IDtdOptions {}
  • The options associated with the XML document type definition (DTD). An example of a DTD is as follows:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

property include

include?: boolean;
  • Whether to include a DTD in the generated XML. By default, no DTD is included.

property name

name?: string;
  • The name of the DTD. This value cannot be left undefined if include is true.

property pubId

pubId?: string;
  • The public identifier of the DTD, excluding quotation marks. If a public identifier is provided, a system identifier must be provided as well. By default, no public identifier is included.

property sysId

sysId?: string;
  • The system identifier of the DTD, excluding quotation marks. By default, no system identifier is included.

interface IFormatOptions

interface IFormatOptions {}
  • The options associated with the formatting of the XML document.

property doubleQuotes

doubleQuotes?: boolean;
  • Whether double quotes or single quotes should be used in XML attributes. By default, single quotes are used.

property indent

indent?: string;
  • The indent string used for pretty-printing. The default indent string is four spaces.

property newline

newline?: string;
  • The newline string used for pretty-printing. The default newline string is "\n".

property pretty

pretty?: boolean;
  • Whether pretty-printing is enabled. By default, pretty-printing is enabled.

interface IOptions

interface IOptions {}
  • The options associated with parsing an object and formatting the resulting XML.

property aliasString

aliasString?: string;
  • If an object or map contains a key that, when converted to a string, is equal to the value of aliasString, then the name of the XML element containing the object will be replaced with the value associated with said key.

    For example, if aliasString is "=", then the following object:

    {
    "abc": {
    "=": "def"
    "#": "ghi"
    }
    }

    will result in the following XML for a root element named "root":

    <root>
    <def>ghi</def>
    </root>

    The handlers in typeHandlers are not applied to the value.

    The default alias string is "=".

property attributeString

attributeString?: string;
  • If an object or map contains a key that, when converted to a string, begins with the value of attributeString, then the value mapped by said key will be interpreted as attributes for the XML element for that object.

    The keys of the value of attributeString are interpreted as attribute names, while the values mapping to those keys are interpreted as attribute values.

    For example, if attributeString is "@", then the following object:

    {
    "abc": {
    "@1": {
    "ghi": "jkl",
    "mno": "pqr"
    },
    "stu": "vwx",
    "@2": {
    "yza": "bcd"
    },
    }
    }

    will result in the following XML for a root element named "root":

    <root>
    <abc ghi='jkl' mno='pqr' yza='bcd'>
    <stu>vwx</stu>
    </abc>
    </root>

    The handlers in typeHandlers are applied to the values.

    The default attribute string is "@".

property cdataInvalidChars

cdataInvalidChars?: boolean;
  • Whether to enclose any text containing the characters < or & in CDATA sections. If this is false, these characters shall be replaced with XML escape characters instead.

    By default, this is disabled.

property cdataKeys

cdataKeys?: string[];
  • If an object or map contains a key that, when converted to a string, is equal to an item in cdataKeys, then the value mapped by said key will be enclosed in a CDATA section.

    For example, if cdataKeys is:

    [
    "abc"
    ]

    then the following object:

    {
    "abc": "def&",
    "ghi": "jkl",
    "mno": "pqr<"
    }

    will result in the following XML for a root element named "root":

    <root>
    <abc><![CDATA[def&]]></ghi>
    <ghi>jlk</ghi>
    <mno>pqr&lt;</mno>
    </root>

    If cdataKeys has a key named "*", then that entry will match all keys.

    By default, this is an empty array.

property declaration

declaration?: IDeclarationOptions;
  • The options associated with the XML declaration.

property dtd

dtd?: IDtdOptions;
  • The options associated with the XML document type definition.

property format

format?: IFormatOptions;
  • The options associated with the formatting of the XML document.

property replaceInvalidChars

replaceInvalidChars?: boolean;
  • Whether to replace any characters that are not valid in XML in particular contexts with the Unicode replacement character, U+FFFD.

    At present this is limited to attribute names and values; element names and character data; CDATA sections; and comments. This may be extended in future.

    By default, this is disabled.

property typeHandlers

typeHandlers?: ITypeHandlers;
  • If a value has a type (as defined by calling Object.prototype.toString on the value) equal to a key in typeHandlers, then said value will be replaced by the return value of the function mapped to by the key in typeHandlers. This function is called with the value as a parameter.

    If one of these functions returns the sole instance of Absent, then the value will be suppressed from the XML output altogether.

    For example, if typeHandlers is:

    {
    "[object Date]": function(value) {
    return value.getYear();
    },
    "[object Null]": function(value) {
    return Absent.instance;
    }
    }

    then the following object:

    {
    "abc": new Date(2012, 10, 31),
    "def": null
    }

    will result in the following XML for a root element named "root":

    <root>
    <abc>2012</abc>
    </root>

    If typeHandlers has a key named "*", then that entry will match all values, unless there is a more specific entry.

    Note that normal parsing still occurs for the value returned by the function; it is not directly converted to a string.

    The default value is an empty object.

property useSelfClosingTagIfEmpty

useSelfClosingTagIfEmpty?: boolean;
  • Whether to use a self-closing tag for empty elements.

    For example, the following element will be used:

    <element/>

    instead of:

    <element></element>

    By default, this is enabled.

property validation

validation?: boolean;
  • Whether to throw an exception if basic XML validation fails while building the document.

    By default, this is enabled.

property valueString

valueString?: string;
  • If an object or map contains a key that, when converted to a string, begins with the value of valueString, then the value mapped by said key will be represented as bare text within the XML element for that object.

    For example, if valueString is "#", then the following object:

    new Map([
    ["#1", "abc"],
    ["def", "ghi"],
    ["#2", "jkl"]
    ])

    will result in the following XML for a root element named "root":

    <root>
    abc
    <def>ghi</def>
    jkl
    </root>

    The handlers in typeHandlers are applied to the value.

    The default value is "#".

property wrapHandlers

wrapHandlers?: IWrapHandlers;
  • If an object or map contains a key that, when converted to a string, is equal to a key in wrapHandlers, and the key in said object or map maps to an array or set, then all items in the array or set will be wrapped in an XML element with the same name as the key.

    The key in wrapHandlers must map to a function that is called with the key name, as well as the array or set, as parameters. This function must return a string or value that can be converted to a string, which will become the name for each XML element for each item in the array or set. Alternatively, this function may return null to indicate that no wrapping should occur.

    For example, if wrapHandlers is:

    {
    "abc": function(key, value) {
    return "def";
    }
    }

    then the following object:

    {
    "ghi": "jkl",
    "mno": {
    "pqr": ["s", "t"]
    },
    "uvw": {
    "abc": ["x", "y"]
    }
    }

    will result in the following XML for a root element named "root":

    <root>
    <ghi>jkl</ghi>
    <mno>
    <pqr>s</pqr>
    <pqr>t</pqr>
    </mno>
    <uwv>
    <abc>
    <def>x</def>
    <def>y</def>
    </abc>
    </uwv>
    </root>

    If wrapHandlers has a key named "*", then that entry will match all arrays and sets, unless there is a more specific entry.

    The default value is an empty object.

interface ITypeHandlers

interface ITypeHandlers {}
  • Map for the typeHandlers property in the IOptions interface.

index signature

[type: string]: (value: any) => unknown;
  • Mapping between the type of a value in an object to a function taking this value and returning a replacement value.

interface IWrapHandlers

interface IWrapHandlers {}
  • Map for the wrapHandlers property in the IOptions interface.

index signature

[key: string]: (key: string, value: any) => string | null;
  • Mapping between the string version of a key in an object or map with a value that is an array or set to a function taking the string version of that key, as well as that array or set.

    This function returns either a string that will become the name for each XML element for each item in the array or set, or null to indicate that wrapping should not occur.

Package Files (2)

Dependencies (1)

Dev Dependencies (11)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/js2xmlparser.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/js2xmlparser)
  • HTML
    <a href="https://www.jsdocs.io/package/js2xmlparser"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>