Skip to content

Latest commit

 

History

History
453 lines (329 loc) · 27.9 KB

API_JSDOC.md

File metadata and controls

453 lines (329 loc) · 27.9 KB

xml-csharp-cereal

Node.js XML serializer with an eye toward limited C# XmlSerializer compatibility

License: (Unlicense OR Apache-2.0) DISCLAIMER: Authors and contributors assume no liability or warranty. Use at your own risk.

xml-csharp-cereal~XmlSerializerError

Extend standard Error object with additional information from XML serialization process

Kind: inner class of xml-csharp-cereal

new XmlSerializerError(msg, [opts], [_state])

Creates an instance of XmlSerializerError

Param Type Default Description
msg Error | string Error object or error message string
[opts] Object Options object that was used at time of the error
[_state] Object Internal state object at time of the error

xml-csharp-cereal~XmlTemplateItem

Class representing the XML template for a given property.

Kind: inner class of xml-csharp-cereal

new XmlTemplateItem(prop_name, class_name, [arr_levels], [arr_namespace], [isNullable], [hasExplicitTypeTag], [isFlatArray])

Creates an instance of XmlTemplateItem.

Param Type Default Description
prop_name string Property Name
class_name string Class or Type Name
[arr_levels] ?Array.<string> | number XML tag names for array levels or number of dimensions (if not defined, assumes not an array)
[arr_namespace] string XML namespace for array, if any
[isNullable] boolean false If simple type should be flagged as nullable
[hasExplicitTypeTag] boolean false If true this prop uses an explicit type tag (somewhat like an array without being one)
[isFlatArray] booleab false If true and this prop is array, treat it as 'flat' or 'headless'

xmlTemplateItem.nullable() ⇒ XmlTemplateItem

Mark XmlTemplateItem as nullable

Kind: instance method of XmlTemplateItem
Returns: XmlTemplateItem - This XmlTemplateItem instance

xmlTemplateItem.attr() ⇒ XmlTemplateItem

Mark XmlTemplateItem as an XML attribute

Kind: instance method of XmlTemplateItem
Returns: XmlTemplateItem - This XmlTemplateItem instance

xmlTemplateItem.explicitTypeTag() ⇒ XmlTemplateItem

Mark XmlTemplateItem as having an explicit type tag

Kind: instance method of XmlTemplateItem
Returns: XmlTemplateItem - This XmlTemplateItem instance

xmlTemplateItem.flatArr() ⇒ XmlTemplateItem

Mark XmlTemplateItem as having a flat or headless XML array

Kind: instance method of XmlTemplateItem
Returns: XmlTemplateItem - This XmlTemplateItem instance

xml-csharp-cereal~XmlTemplate

The XmlTemplate class stores info of how a class's properties are to be serialized.

Kind: inner class of xml-csharp-cereal

new XmlTemplate(class_constructor, [constructor_args], [class_name])

Creates an instance of XmlTemplate.

Param Type Default Description
class_constructor function Class function (essentially the constructor)
[constructor_args] Array.<any> Arguments to feed constructor when creating a new instance
[class_name] string null An alternative class name or alias to use in place of the constructor's name

xmlTemplate.getName([full]) ⇒ string

Gets the name of the class being mapped by this XML template.

Kind: instance method of XmlTemplate
Returns: string - Name of the class that this template maps

Param Type Default Description
[full] boolean false If true, include any class name qualifiers

xmlTemplate.hasAlias() ⇒ boolean

Checks if this template is using a class name alias

Kind: instance method of XmlTemplate
Returns: boolean - True if this template uses a class name alias

xmlTemplate.extend(class_constructor, [constructor_args], [class_name]) ⇒ XmlTemplate

Converts the current template into a template for the given derived class

Kind: instance method of XmlTemplate
Returns: XmlTemplate - The current modified template (not a copy)

Param Type Default Description
class_constructor function Class function (essentially the constructor)
[constructor_args] Array.<any> Arguments to feed constructor when creating a new instance
[class_name] string null An alternative class name to use in place of the constructor's name

xmlTemplate.clone([class_constructor], [constructor_args], [class_name]) ⇒ XmlTemplate

Makes a shallow copy of this template. You can specify a different class or constructor args if you want.

Kind: instance method of XmlTemplate
Returns: XmlTemplate - The shallow clone of this

Param Type Description
[class_constructor] function Class function (essentially the constructor)
[constructor_args] Array.<any> Arguments to feed constructor when creating a new instance
[class_name] string An alternative class name to use in place of the constructor's name

xmlTemplate.newObj(...constructor_args) ⇒ Object

Returns a new instance of the class associated with this template.

Kind: instance method of XmlTemplate
Returns: Object - New instance of ClassConstructor (using ConstructorArgs if any)

Param Type Description
...constructor_args any If parameters given, they are passed to constructor; otherwise any stored ConstructorArgs are used.

xmlTemplate.add(prop_name, class_name, [arr_levels], [arr_namespace], [isNullable], [hasExplicitTypeTag], [isFlatArray]) ⇒ XmlTemplateItem

Add property to this class XML template.

Kind: instance method of XmlTemplate
Returns: XmlTemplateItem - Instance of the new XML template item that was added for this property

Param Type Default Description
prop_name string | XmlTemplateItem Property Name or instance of Property XML template. If passing full item template, other parameters are ignored.
class_name string | function | Object Class Name or Class instance or Class function of the property.
[arr_levels] number | Array.<string> 0 Number of dimensions or array of tag names (if not defined, assumes no array)
[arr_namespace] string XML namespace for array, if any
[isNullable] boolean false If simple type should be flagged as nullable
[hasExplicitTypeTag] boolean false If true this prop uses an explicit type tag (somewhat like an array without being one)
[isFlatArray] booleab false If true and this prop is array, treat it as 'flat' or 'headless'

xmlTemplate.sortByName([skip_inherited]) ⇒ XmlTemplate

Sorts the properties list by property names

Kind: instance method of XmlTemplate
Returns: XmlTemplate - This instance

Param Type Default Description
[skip_inherited] boolean false If true, any inherited props are ignored and put at top of the list in the order they are encounted.

xmlTemplate.setXmlNameSpace(xml_namespace) ⇒ XmlTemplate

Sets the XML namespace for this class template

Kind: instance method of XmlTemplate
Returns: XmlTemplate - This instance

Param Type Description
xml_namespace string The full XML namespace to use for this class

xml-csharp-cereal~XmlTemplateFactory

The XmlTemplateFactory class stores a collection of XmlTemplate instances for serializing them into/out-of XML.

Kind: inner class of xml-csharp-cereal

new XmlTemplateFactory([...templates])

Creates an instance of XmlTemplateFactory.

Param Type Description
[...templates] function | XmlTemplate Variable number of class functions (with static getXmlTemplate), or XmlTemplate's, or arrays of either.

xmlTemplateFactory.setSimpleCodec(type_names, [decode_func], [encode_func], [type_namespace]) ⇒ XmlTemplateFactory

Sets the given simple type decoder or encoder for this factory

Kind: instance method of XmlTemplateFactory
Returns: XmlTemplateFactory - This factory instance

Param Type Default Description
type_names string | Array.<string> Simple type name(s) being set
[decode_func] DecoderCallback Function to decode XML node string into JS property value
[encode_func] EncoderCallback Function to encode JS property value into XML node string
[type_namespace] string null XML namespace to use for this simple type

xmlTemplateFactory.add(xml_template) ⇒ XmlTemplateFactory

Add a class XML template to the factory.

Kind: instance method of XmlTemplateFactory
Returns: XmlTemplateFactory - This factory instance

Param Type Description
xml_template function | XmlTemplate Class function (with static getXmlTemplate) or XmlTemplate instance.

xmlTemplateFactory.addEnum(enum_name, enum_obj, [enum_namespace]) ⇒ XmlTemplateFactory

Adds an enum type description

Kind: instance method of XmlTemplateFactory
Returns: XmlTemplateFactory - This factory instance

Param Type Default Description
enum_name string Name of the enum
enum_obj Object Simple object representation of the enum, or object providing getEnumValue and getEnumName functions
[enum_namespace] string null XML namespace of the enum

xmlTemplateFactory.addDict(class_name, pair_name, key_prop, value_prop, [dict_namespace], [hasExplicitTypeTags]) ⇒ XmlTemplateFactory

Adds an implicit dictionary description

Kind: instance method of XmlTemplateFactory
Returns: XmlTemplateFactory - This factory instance

Param Type Default Description
class_name string Name of dictionary class
pair_name string Name of key-value pair
key_prop XmlTemplateItem | Array.<any> Property info for the key (if given array, it is passed to XmlTemplateItem constructor)
value_prop XmlTemplateItem | Array.<any> Property info for the value (if given array, it is passed to XmlTemplateItem constructor)
[dict_namespace] string null XML namespace of the dictionary
[hasExplicitTypeTags] boolean false If true, this dictionary uses type tags within key and value tags

xmlTemplateFactory.addDictQuick(class_name, value_prop, [dict_namespace], [hasExplicitTypeTags]) ⇒ XmlTemplateFactory

Adds an implicit dictionary description assuming 'KeyValuePair' with string 'Key'

Kind: instance method of XmlTemplateFactory
Returns: XmlTemplateFactory - This factory instance

Param Type Default Description
class_name string Name of dictionary class
value_prop string | XmlTemplateItem | Array.<any> Value class name or property info (if given array, it is passed to XmlTemplateItem constructor)
[dict_namespace] string null Class namespace of the dictionary
[hasExplicitTypeTags] boolean false If true, this dictionary uses type tags within key and value tags

xmlTemplateFactory.find(class_name) ⇒ XmlTemplate

Finds a class XML template from the factory's collection.

Kind: instance method of XmlTemplateFactory
Returns: XmlTemplate - Returns the XML template if found, otherwise returns null

Param Type Description
class_name string | Object | function Name, instance, or class function of the XML class template to find

xmlTemplateFactory.applyDataContractNameSpaces(default_namespace) ⇒ XmlTemplateFactory

Loops all the templates and attempts to add XML namespaces where they are not already defined based on DataContract style XML.

Kind: instance method of XmlTemplateFactory
Returns: XmlTemplateFactory - This factory instance

Param Type Description
default_namespace string Typically the root namespace. Basically applied to all templates without an existing namespace

xmlTemplateFactory.from_xmldom(xmldom_obj, [options]) ⇒ Object

Creates a new class instance of the root object from xmldom XMLDocument.

Kind: instance method of XmlTemplateFactory
Returns: Object - An instance of the root object deserialized from the XML root.

Param Type Description
xmldom_obj Object XmlDocument object produced by xmldom from XML.
[options] Object Object of options to use for deserialization (specific to this function).

xmlTemplateFactory.to_xmldom(root_obj, [options]) ⇒ Object

Creates a new xmldom XMLDocument from given instance of a known class.

Kind: instance method of XmlTemplateFactory
Returns: Object - XmlDocument object that xmldom can use to generate XML.

Param Type Description
root_obj Object Instance of a class known to this factory to be serialized.
[options] Object Object of options to use for serialization (specific to this function).

xmlTemplateFactory.from_xml2js(xml2js_obj, [options]) ⇒ Object

Creates a new class instance of the root object from the given xml2js object.

Kind: instance method of XmlTemplateFactory
Returns: Object - An instance of the root object deserialized from the XML root.

Param Type Description
xml2js_obj Object Object produced by xmldom from XML.
[options] Object Object of options to use for deserialization (specific to this function).

xmlTemplateFactory.to_xml2js(root_obj, [options]) ⇒ Object

Creates a new xml2js object from given instance of a known class.

Kind: instance method of XmlTemplateFactory
Returns: Object - Object that xml2js can use to generate XML.

Param Type Description
root_obj Object Instance of a class known to this factory to be serialized.
[options] Object Object of options to use for serialization (specific to this function).

xml-csharp-cereal~DecoderCallback ⇒ any

This callback takes value from XML and decodes it into appropriate value for object.

Kind: inner typedef of xml-csharp-cereal
Returns: any - the decoded JS property value

Param Type Description
val any the XML node string to decode

xml-csharp-cereal~EncoderCallback ⇒ string

This callback takes value from object and encodes it into appropriate value for XML.

Kind: inner typedef of xml-csharp-cereal
Returns: string - the encoded XML node string

Param Type Description
val any the JS property value to encode