Class: NSFactory

nationscript/factory~NSFactory()

The basic factory class, containing functions for the handling of events emitted by the XML parser on the responses from the NationStates API.

Each factory builds exactly one instance of its configured product. One at a time, the factory targets each property of its product, using events passed by the XML parser to build values from text data by itself, or alternatively passing the events further along to an assigned subFactory, which can use them to build its own product, later to be used by the parent factory as a property.

Data is received from the parser over the following events:

handleOpen
handleClose
handleText
handleCData

Upon receiving an onOpen() call, the factory checks whether its registered tags cover the associated XML node's name. If not, the factory will ignore that XML node, so that no events are acted upon until an onClose() call is received for the ignored node. If the tags cover the node, any associated handler function is executed, with the received attributes as argument.

For a non-ignored node, the factory requires a subFactory for handling. If one is not assigned via the associated tags function(s), the factory will assign itself a "blank" factory - without any tags. While a subFactory is assigned, any and all events passed to a factory will be handed further down to the subFactory.

When an onText() or onCData() event is received, a factory will append the passed text or CDATA to its collected data.

A factory continues to develop its product until an onClose() event is received, and no subFactory exists. At that point, the factory will add any collected text data to its product, after which it is declared to be finalised. From that point on, the factory can deliver the product.

Constructor

new NSFactory()

Class for handling data from events emitted during XML parsing.

Members

(protected) finalised :boolean

true if this factory has received an NSFactory#onClose call for the tag it was originally opened for (and its product should accordingly be considered to be final), otherwise false.

Type:

boolean

(protected) product :*

What this factory is producing. Properties are gradually built up from data contained in events passed to this factory by the XML parser.

Type:

Methods

(protected) addToProduct(val) → {void}

Assigns the given value to the property that is currently being targeted on the product. If an empty name is targeted, the product as a whole is set to val.

Parameters:

Name	Type	Description
`val`	any	Value to assign

Returns:

Type: void

assignSubFactory(subFactory) → {this}

Assigns another factory instance to this factory as a subFactory.

Parameters:

Name	Type	Description
`subFactory`	NSFactory	Sub-factory to assign

Throws:

subFactory must be an instance of an NSFactory.
Type TypeError

Returns:

The factory, for chaining

Type: this

build(name, convert) → {this}

Configures this factory to build the property of the given name on its product next. This also sets the function to convert the calculated value before finally assigning it to the product.

Parameters:

Name	Type	Description
`name`	string	New target `property`
`convert`	DataConverter	New converter function

Returns:

The factory, for chaining

Type: this

deliver() → {ProductType}

Requests this factory to deliver its product. Should it not be finalised yet, the factory will withhold the product.

Throws:

The product must be finalised!
Type ProductWithheldError

Returns:

The product.

Type: ProductType

(protected) emptySubFactory() → {void}

Calls the NSFactory#addToProduct function, passing the product of the currently assigned subFactory as value; then removes that sub-factory assignment.

Returns:

Type: void

(package) get(property) → {any}

Gets the value of the given property on the product.

Parameters:

Name	Type	Description
`property`	string	Name of target property

Returns:

The property on the product; if not set, undefined

Type: any

(package) handleCData(cdata) → {boolean}

Called when a CDATA node is read in the source XML. This simply passes the received data to the NSFactory#handleText function.

Parameters:

Name	Type	Description
`cdata`	string	Text data received

Returns:

true if handled, otherwise false

Type: boolean

(package) handleClose(name) → {boolean}

Called when a tag gets closed in the source XML. If that tag is the one that triggered ignore mode, that gets ended. Otherwise, any collected text data is added to the product, and the factory declares itself finalised.

Parameters:

Name	Type	Description
`name`	string	Name of the source XML tag that is being closed

Returns:

true if handled, otherwise false

Type: boolean

(package) handleError(err)

Called when the XML parser encounters an error. This simply throws a new NSError.

Parameters:

Name	Type	Description
`err`	Error

Throws:

A new NSError, referring back to the passed one
Type NSError

(package) handleOpen(name, attrs) → {boolean}

Called when a new tag gets opened in the source XML. Searches the registered tags for a matching tag name, invoking the associated TagHandlers and assigning a new subFactory for receiving the node content, if not done by one of the registered handlers. If the tags don't cover the tag, ignore mode is activated.

Parameters:

Name	Type	Description
`name`	string	Name of the tag in the source XML
`attrs`	module:nationscript/factory~Attributes	Key-value map of present attributes

Returns:

true if handled, otherwise false

Type: boolean

(package) handleText(text) → {boolean}

Called when a text node is read in the source XML. This appends its text content to the received text data.

Parameters:

Name	Type	Description
`text`	string	Text data received

Returns:

true if handled, otherwise false

Type: boolean

onTag(name, handler) → {this}

Creates a new entry in this factory's tags for the given tag name.

Parameters:

Name	Type	Description
`name`	string	Name of the XML tag to assign the handler to
`handler`	TagHandler	Function to invoke for handling the tag

Returns:

The factory, for chaining multiple tags

Type: this

set(name, value, convert) → {this}

Sets the given value as the given property on the product directly. Shortcut for build(name, convert). addToProduct(value).

Parameters:

Name	Type	Description
`name`	string	Name of target `property`
`value`	any	Value to assign
`convert`	DataConverter	Converter function to apply

Returns:

The factory, for chaining

Type: this