Abstract
Unicorn XML Processor is a stand-alone ECMAScript interpreter that supports a rich set of built-in extension objects. These objects implement various XML-related features:
- non-validating XML parser
- XML writer supporting XML, HTML and text output methods
- SAX2 (Simple API for XML version 2.0) interface
- DOM (Document Object Model) Level 1
- XPath expressions and node-sets
- XSLT processor and XSLT pattern matching facility
In addition, the following general-purpose features are supported:
- regular expressions
- I/O operations for text files
The XSLT processor, which forms an integral part of the product, supports various XSLT extensions:
- Object-based extensions
- Report generation extensions
- Text input extensions
Status of this document
THE DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
IN NO EVENT WILL UNICORN ENTERPRISES BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES FOR ANY USE OF THE DOCUMENTATION INCLUDING, WITHOUT LIMITATION, ANY LOST PROFITS, BUSINESS INTERRUPTION, LOSS OF PROGRAMS OR OTHER DATA ON YOUR COMPUTER SYSTEM OR OTHERWISE, EVEN IF WE ARE EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Table of contents
1 Introduction
Unicorn XML Processor is a stand-alone ECMAScript interpreter that supports a rich set of built-in extension objects. These objects implement various XML-related features:
- non-validating XML parser
- XML writer supporting XML, HTML and text output methods
- SAX2 (Simple API for XML version 2.0) interface
- DOM (Document Object Model) Level 1
- XPath expressions and node-sets
- XSLT processor and XSLT pattern matching facility
In addition, the following general-purpose features are supported:
- regular expressions
- I/O operations for text files
The XSLT processor, which forms an integral part of the product, supports various XSLT extensions:
- Object-based extensions
- Report generation extensions
- Text input extensions
2 Conventions
The product supports, with few limitations, the ECMAScript language as specified in ECMA-262 standard (2nd Edition). Known limitations are listed in Appendix B of this document.
The following chapters contain description of extension objects specific to the product. Whenever possible, terms and conventions of the original ECMA-262 specifications are used.
3 ECMAScript Extensions
ECMAScript implementation for Unicorn XML Processor is provided by Unicorn ECMAScript Interpreter (UESI) engine, which is an integral part of the product.
UESI supports ECMAScript language as specified in ECMA-262 standard (2nd Edition). In addition, the rich set of extension objects is supported. These extensions are described in the following sections.
3.1 XML Objects
XML extensions provide built-in ECMAScript objects that support basic XML processing interfaces.
Many object categories provide functionality specified by SAX2: Simple API for XML, effectively implementing ECMAScript bindings for SAX2. Few other objects, that have no counterparts in SAX2, were introduced to support integration of various XML-enabling ECMAScript extensions available in UESI (e.g., DOM and XSLT), and to provide sophisticated XML output facility (XML Writer) designed to represent XML documents in XML, HTML and text formats.
Attributes objects represent lists of XML attributes. They implement functionality similar to that of the Attributes interface and AttributesImpl class specified by SAX2.
ContentHandler objects are used to receive notifications of the logical content of documents. They implement functionality similar to that of the ContentHandler interface specified by SAX2.
DTDHandler objects are used to receive notifications of basic DTD-related events. They implement functionality similar to that of the DTDHandler interface specified by SAX2.
EntityResolver objects provide basic interface for resolving entities. They implement functionality similar to that of the EntityResolver interface specified by SAX2.
ErrorHandler objects provide basic interface for XML Reader error handlers. They implement functionality similar to that of the ErrorHandler interface specified by SAX2.
InputSource objects represent input sources for XML entities. They implement functionality similar to that of the InputSource class specified by SAX2.
Locator objects represent interface for associating XML Stream events with document locations. They implement functionality similar to that of the Locator interface and LocatorImpl class specified by SAX2.
NamespacesSupport objects encapsulate namespace logic. They implement functionality similar to that of the NamespaceSupport class specified by SAX2.
Exception objects are used to encapsulate general XML errors and warnings. They implement functionality similar to that of the SAXException class specified by SAX2.
NotSupportedException objects are used for unsupported operations. They implement functionality similar to that of the SAXNotSupportedException class specified by SAX2.
NotRecognizedException objects are used for unrecognized identifiers. They implement functionality similar to that of the SAXNotRecognizedException class specified by SAX2.
ParseException objects are used to encapsulate XML parse errors and warnings. They implement functionality similar to that of the SAXParseException class specified by SAX2.
Stream objects represent interfaces for reading content of XML documents. Every stream object generates a sequence of events. Each event represents a piece of XML content. Stream objects are normally associated with ContentHandler objects. The latter implement the ContentHandler interface and are used to process events generated by Streams. There is no direct counterpart for Stream objects in SAX2. In UESI, Stream represents more primitive object type than the interface XMLReader recommended by SAX2, since it does not provide DTD handling, entity resolving and handling for parse errors.
Processor objects combine functionality provided by Stream and ContentHandler objects. The Processor instance is like a Stream, except that it obtains its events from another Stream rather than a primary source. Processors can modify a stream of events as they pass on to their associated content handlers. Processor objects can be used to implement pipelines of XML processing components. The Processor objects have no direct counterparts in SAX2. In UESI, the Stream and Processor objects have relation similar to that of interfaces XMLReader and XMLFilter specified by SAX2.
Reader objects implement interface for reading XML documents using callbacks. They implement functionality similar to that of the XMLReader interface specified by SAX2.
Filter objects implement interface for XML filters. They implement functionality similar to that of the XMLFilterImpl class specified by SAX2. Filter objects combine functionality provided by Reader, DTDHandler, ContentHandler, EntityResolver and ErrorHandler objects. The Filter instance is like Reader, except that it obtains its events from another Reader rather than a primary source. Filters can modify a stream of events as they pass on to the final destination.
Writer objects implement interface for writing XML documents using XML, HTML and text output methods. Writer objects have no counterparts in core SAX2. The functionality of Writer objects is modelled after the output facility of XSL Transformations (XSLT), version 1.0.
Stream and ContentHandler objects play an important role for integration of various XML-enabling ECMAScript extensions implemented by UESI. Stream objects generate sequences of events representing content of XML documents, while ContentHandler objects act as consumers (processors) of these events. Some objects may act as both streams and content handlers. By linking streams and content handlers together, various UESI XML-enabling components can be integrated to provide the desired XML processing functonality.
Many objects supported by other ECMAScript extension packages available in UESI (e.g., DOM and XSLT) implement interfaces of Stream or ContentHandler, and therefore can be integrated using the common basic concept.
The detailed description of XML Extensions can be found in a separate document, Unicorn ECMAScript Interpreter Reference Manual. XML Extensions, Version 2.0.
3.2 DOM Objects
DOM extensions provide built-in ECMAScript objects that implement ECMAScript bindings for interfaces defined in DOM Level 1.
Node objects implement bindings for Node interface specified by DOM.
NodeList objects implement bindings for NodeList interface specified by DOM.
NamedNodeMap objects implement bindings for NamedNodeMap interface specified by DOM.
DOMImplementation objects implement bindings for DOMImplementation interface specified by DOM.
DocumentFragment objects implement bindings for DocumentFragment interface specified by DOM.
Document objects implement bindings for Document interface specified by DOM.
CharacterData objects implement bindings for CharacterData interface specified by DOM.
Attr objects implement bindings for Attr interface specified by DOM.
Element objects implement bindings for Element interface specified by DOM.
Text objects implement bindings for Text interface specified by DOM.
Comment objects implement bindings for Comment interface specified by DOM.
CDATASection objects implement bindings for CDATASection interface specified by DOM.
EntityReference objects implement bindings for EntityReference interface specified by DOM.
ProcessingInstruction objects implement bindings for ProcessingInstruction interface specified by DOM.
Reader objects are designed to traverse the DOM subtree in the document order, generating the appropriate stream of SAX2 events. Reader objects implement XML Stream interface and can be used in any context where XML Stream is required. Reader objects do not implement any specific DOM interface.
Writer objects are designed process the stream of SAX2 events, creating a set of DOM nodes and appending these nodes to the children list of a given root node. Writer objects implement XML ContentHandler interface and can be used in any context where XML ContentHandler is required. Writer objects do not implement any specific DOM interface.
The detailed description of DOM Extensions can be found in a separate document, Unicorn ECMAScript Interpreter Reference Manual. DOM Extensions, Version 2.0.
3.3 XPath Objects
XPath extensions provide built-in ECMAScript objects that support XPath expressions and node-sets. XPath extensions are built on the top of XML extensions and DOM extensions implemented by UESI.
NodeSet objects represent XPath node-sets.
Expr objects represent XPath expressions.
The detailed description of XPath Extensions can be found in a separate document, Unicorn ECMAScript Interpreter Reference Manual. XPath Extensions, Version 2.0.
3.4 XSLT Objects
XSLT extensions provide built-in ECMAScript objects that support XSLT transformations. XSLT extensions are built on the top of XML extensions and DOM extensions implemented by UESI.
Processor objects represent XSLT processors.
Stylesheet objects represent XSLT stylesheets.
Pattern objects are used to represent XSLT paterns and to implement the XSLT pattern matching facility.
The detailed description of XSLT Extensions can be found in a separate document, Unicorn ECMAScript Interpreter Reference Manual. XSLT Extensions, Version 2.0.
3.5 Regular Expressions
UESI supports the regular expression facility specified by the third edition of the ECMA-262 Standard. (Note that basically UESI implements only the features specified by the previous, second edition of ECMA-262).
The RegExp objects are supported as specified in the section 15.10 RegExp (Regular Expressions) of the ECMA-262 Standard, 3rd Edition.
Furthermore, functions String.prototype.match, String.prototype.replace and String.prototype.search of the String prototype are supported as specified in sections 15.5.4.10, 15.5.4.11 and 15.5.4.12 of the ECMA-262 Standard, 3rd Edition.
Regular expression literals are not supported.
3.6 File Objects
File objects are designed to provide access to Unicode text files. Content of text files may be encoded using various encoding algorithms. The encoding name may be specified as an optional argument of a file open function. If the encoding name is not specified, the file is open using the implicit encoding, and the ISO-8859-1 encoding algorithm is assumed. Certain access functions are applicable only to files that are open using the implicit encoding.
Several file access functions require path values as their arguments. The path value may be represented as either a path name recognized by the local file system, or as a file URI. Currently supported URI syntax rules are described in Appendix D . Path values conforming to these rules are interpreted as URI, all other values are interpreted as local file system path values. Only absolute URI are currently supported. Relative path values are interpreted as the local file system path values and are resolved using the current directory path of the interpreter application.
In general, file objects follow the same conventions as specified for ECMAScript standard built-in objects. Every built-in file function has the length property that specifies maximum number of function arguments. This property has the attribute set { ReadOnly, DontDelete, DontEnum }. Other file properties have the attribute set { DontEnum } unless otherwise specified. Every function accepts arguments of certain types. If the argument provided by the caller have different type, the standard type conversion is performed. If the argument is missing, the undefined value is used.
3.6.1 The File Constructor
The file constructor object is accessible as initial property of the global object. The property name is File.
The File object cannot be called as a function.
When File is called as part of new expression, it is treated as a constructor: it creates a new file object.
3.6.1.1 new File()
The new file object is constructed. The constructor does not open any file. To open the file, the separate function File.prototype.open should be used.
The [[Prototype]] property of the newly created file object is set to the original File prototype object - the initial value of File.prototype.
The [[Class]] property is set to "File".
3.6.2 Properties of the File Constructor
3.6.2.2 File.stdin
The value of File.stdin is the file object attached to the application standard input stream. This property has the attribute set { ReadOnly, DontEnum, DontDelete }.
This property can be used to read data from the standard input. The standard input is accessed using the implicit encoding.
3.6.2.3 File.stdout
The value of File.stdout is the file object attached to the application standard output stream. This property has the attribute set { ReadOnly, DontEnum, DontDelete }.
This property can be used to write data to the standard output. The standard output is accessed using the implicit encoding.
3.6.2.4 File.stderr
The value of File.stderr is the file object attached to the application standard error output stream. This property has the attribute set { ReadOnly, DontEnum, DontDelete }.
This property can be used to write data to the standard error output. The standard error output is accessed using the implicit encoding.3.6.2.5 File.FROM_BEGIN
The value of File.FROM_BEGIN is a numeric constant 0. This constant can be used as the value of the argument of File.prototype.setPosition function. This property has the attribute set { ReadOnly, DontEnum, DontDelete }.
3.6.2.6 File.FROM_CURRENT
The value of File.FROM_CURRENT is a numeric constant 1. This constant can be used as the value of the argument of File.prototype.setPosition function. This property has the attribute set { ReadOnly, DontEnum, DontDelete }.
3.6.2.7 File.FROM_END
The value of File.FROM_END is a numeric constant 2. This constant can be used as the value of the argument of File.prototype.setPosition function. This property has the attribute set { ReadOnly, DontEnum, DontDelete }.
3.6.2.8 File.exists(path)
This function tests existence of the file referenced by the argument. The argument is a string value that specifies the file path. Both URI and local file system path notations are supported as described above .
The function returns the boolean value of true if the specified file exists and the value of false otherwise.
3.6.2.9 File.remove(path)
This function removes the file referenced by the argument. The argument is a string value that specifies the file path. Both URI and local file system path notations are supported as described above .
The function returns the boolean value of true if operation was successful and the value of false otherwise.
3.6.2.10 File.rename(oldPath, newPath)
This function renames the file referenced by the argument, giving it the new name specified by the argument. The arguments are strings that specify the file path values. Both URI and local file system path notations are supported as described above .
The function returns the boolean value of true if operation was successful and the value of false otherwise.
3.6.3 Properties of the File Prototype Object
The File prototype object is itself a file object. Its [[Class]] property is "File".
The value of internal prototype object is the Object prototype object.
3.6.3.1 File.prototype.constructor
The initial value of File.prototype.constructor is built-in File constructor.
3.6.3.2 File.prototype.clearError()
This function clears the file error and end-of-file status. It returns the undefined value.
3.6.3.3 File.prototype.close()
This function closes the file associated with the object. It returns the boolean value of true on success, and the value of false otherwise.
3.6.3.4 File.prototype.eof()
This function tests the end-of-file status of the file. It returns the boolean value of true if the file pointer is at end of file and the value of false otherwise.
3.6.3.5 File.prototype.error()
This function tests the code of last error occurred as the result of file I/O operation. It returns the numeric value of 0 if there is no error status, or non-zero numeric value otherwise.
Each File.prototype function call, if unsuccessful, may set the new error code.
The error codes are platform-specific and usually correspond to the values of errno variable implemented by the underlying C language run-time library.
Large numbers represent error codes corresponding to errors generated by the interpreter itself. The following values are currently supported:
10001 File is not open
10002 File is already open
10003 Invalid file path
10004 Invalid file open mode
10005 Function is not supported for given file access mode
3.6.3.6 File.prototype.flush()
This function flushes the run-time system buffer associated with the file. (NOTE: the run-time system buffer may be written to the operating system buffer rather than to the disk, so using this function does not guarantee that the critical data will be really written to the disk on the completion of the function.)
The function returns the boolean value of true on success, and the value of false otherwise.
3.6.3.7 File.prototype.getLength()
This function returns the length, in bytes, of the file associated with the given file object. The function determines the number of bytes in a file rather than the number of Unicode characters.
The return value is a number that specifies file length, or numeric value of -1 on error.
3.6.3.8 File.prototype.getPosition()
This function returns the current position of the file I/O pointer. The return value is a number that specifies the position, or numeric value of -1 on error.
This function is supported only for files that are open using the implicit encoding.
3.6.3.9 File.prototype.open(path, mode, encoding)
This function opens that file and associates file I/O stream with the current file object.
The argument is a string value that specifies the file path. The path value may be represented as either a path name recognized by the local file system, or as a file URI. Currently supported URI syntax rules are described in Appendix D . Path values conforming to these rules are interpreted as URI, all other values are interpreted as local file system path values. Only absolute URI are currently supported. Relative path values are interpreted as the local file system path values and are resolved using the current directory path of the interpreter application.
The argument is a string value that specifies the file open mode. The following modes are supported:
- "r"
- Open an existing file for reading. Error is generated if the file does not exist.
- "w"
- Create a new file for writing.
- "a"
- Open an existing file for writing at the end of file. Create the file first if it does not exist.
- "r+"
- Open an existing file for both reading and writing. Error is generated if the file does not exist.
- "w+"
- Create a new file for both reading and writing.
- "a+"
- Open an existing file for both reading and writing (writing occurs only at end of file). Create the file first if it does not exist.
The three last modes (which include "+") are supported only for files that are open using the implicit encoding.
The file may be open in either text or binary mode. If the file is open in a text mode, then platform-specific end-of-line markers (e.g., the "carriage return"/"line feed" pairs for Windows-based platforms) will be translated to a single "line feed" (decimal code 10) character by input functions. The "line feed" characters will be translated to the platform-specific end-of-line markers by the output functions. The text mode is applicable only to files open using the implicit encoding. Files using the explicit encoding are always accessed in binary mode.
If the file is to be open using the implicit encoding, the argument may contain additional character "b" ("rb", "wb", "ab", "r+b", "w+b" and "a+b"). In this case the file is open in a binary mode. Otherwise the file is open in a text mode.
The optional argument specifies the file encoding.
If this argument is not supplied, the file is open using the implicit encoding, and the ISO-8859-1 encoding algorithm is assumed. Certain access functions are applicable only to files that are open using the implicit encoding.
If the argument is supplied, the file is accessed using the explicit encoding. Content of the file is mapped to Unicode by I/O procedures according to the specified encoding algorithm. Currently, the values "ISO-8859-1", "UTF-8" and "UTF-16" are supported. Encoding names are interpreted case-insensitive.
Files encoded using UTF-16 may use the leading "Byte order mark" (BOM) character (hexadecimal FEFF) to specify the byte order. This character is not generated automatically for newly created files. If needed, it should be written explicitly by the script.
The File.prototype.open function returns the boolean value of true on success, and the value of false otherwise.
3.6.3.10 File.prototype.read()
This function reads specified number of characters from a file stream. The argument is the numeric value that specifies the desired number of characters. The reading is not stopped at line boundaries.
The platform-specific end-of-line markers are translated to "line feed" characters if the file is accessed in a text mode.
The function returns the string value that contains all characters read. If there were no characters to read (I/O position was at end of file), then the empty string is returned.
The number of characters actually read may be determined querying the length property of the result string.
3.6.3.11 File.prototype.read(count)
This function reads specified number of characters from a file stream. The argument is the numeric value that specifies the desired number of characters. The reading is not stopped at line boundaries.
The platform-specific end-of-line markers are translated to "line feed" characters if the file is accessed in a text mode.
The function returns the string value that contains all characters read. If there were no characters to read (I/O position was at end of file), then the empty string is returned.
The number of characters actually read may be determined querying the length property of the result string.
3.6.3.12 File.prototype.setPosition(position, from)
This function sets current I/O position on a stream associated with the file. The argument is the numeric value that specifies the desired file position.
The optional argument is the numeric value that specifies the origin and may be equal to one of the following constants:
File.FROM_BEGIN 0 Beginning of file
File.FROM_CURRENT 1 Current I/O position
File.FROM_END 2 End of file
The new I/O pointer is positioned relative to the origin specified, while the value of argument defines number of bytes between the origin and the new I/O position.
If the argument is not specified, then the beginning of file is used as the origin.
If the file is open in a text mode, certain limitations apply to the argument values. If the value of is File.FROM_BEGIN, then only values returned by the preceding calls to File.prototype.getPosition may be specified for the argument. If the value of is File.FROM_CURRENT or File.FROM_END, then should be the 0. Other combinations of argument values may cause unpredictable results.
This function is supported only for files that are open using the implicit encoding.
The function returns the boolean value of true on success, and the value of false otherwise.
3.6.3.13 File.prototype.write(data)
This function writes characters to the file. The string argument contains characters to write.
The "line feed" characters are translated to platform-specific end-of-line markers if the file is accessed in a text mode.
The function returns the boolean value of true on success, and the value of false otherwise.
3.6.4 Properties of File Instances
File instances inherit properties from the File prototype object.
3.6.5 Example
The following ECMAScript code fragment opens the input file using the implicit encoding, creates the output file using the UTF-16 encoding and copies input to output.
var BOM = String.fromCharCode(0xFEFF);
var finp = new File();
var fout = new File();
finp.open("test.txt", "r");
fout.open("test.u16", "w", "UTF-16");
fout.write(BOM); // BOM should be written explicitly
while (!finp.eof()) {
var line = finp.read();
fout.write(line);
}
fout.close();
finp.close();
3.7 Miscellaneous Functions
One miscellaneous function is implemented as initial property of the global object. This function has the name print. It accepts the single argument, converts it to string and prints the result to the application standard output. The "line feed" character is added to the end of printed text. The function returns undefined value.
This function is provided mainly for diagnostic and debugging purposes.
4 XSLT Extensions
XSLT implementation for Unicorn XML Processor is provided by Unicorn XSLT Processor (UXT) engine, which is an integral part of the product.
UXT supports XSLT as specified in XSL Transformations (XSLT) Version 1.0. W3C Recommendation 16 November 2024. In addition, the rich set of extensions is supported. These extensions are described in the following sections.
4.1 Object-based Extensions
Object-based XSLT extensions are designed to access, in the platform-independent way, programming resources implemented using various object-based technologies. These extensions are integrated into XSLT transformation environment using the extension mechanism specified in W3C XSLT recommendation.
Only ECMAScript object world is supported by Unicorn XML Processor.
The detailed description of object-based XSLT extensions can be found in a separate document, Object-Based Extensions in XSL Transformations, Version 1.0 .
4.2 Report Generation Extensions
Report generation XSLT extensions are designed to implement features usually provided by traditional report generation tools. These extensions are integrated into XSLT transformation environment using the extension mechanism specified in W3C XSLT recommendation.
The detailed description of report generation XSLT extensions can be found in a separate document, Report Generation Extensions in XSL Transformations, Version 1.0 .
4.3 Text Input Extensions
Text input XSLT extensions are designed to implement processing of source data represented in text format. These extensions are integrated into XSLT transformation environment using the extension mechanism specified in W3C XSLT recommendation.
The detailed description of text input XSLT extensions can be found in a separate document, Text Input Extensions in XSL Transformations, Version 1.0 .
A References
B Known limitations in ECMAScript implementation
The following implementation-specific limitations are known. They might be resolved in the future releases of the product.
- Large sparse arrays are not supported. ECMAScript allows usage of large sparse arrays, i.e., arrays that have very big length. but only few items with defined values. The current ECMAScript implementation represents each array as a contiguous memory block with the size proportional to the array length, therefore large sparse arrays cannot be supported.
- Number to string conversion provides results which are mathematically correct, but in some cases do not conform to ECMA-262 specification.
- Functions String.prototype.toLowerCase and String.prototype.toUpperCase recognize only ASCII letters.
- Dates earlier than 01-Jan-1601 are not supported. Current implementation relies on the Win32 date manipulation functions which do not support earlier dates.
C Known limitations in DOM implementation
The following implementation-specific limitations are known. They might be resolved in the future releases of the product.
- default attribute values specified in DTD are not assigned automatically as required by the DOM specification;
- the doctype property of Document object is always null, therefore DocumentType, Notation and Entity objects are not accessible;
- method getElementsByTagName of Document object is not implemented;
- method isSpecified of Attr object always returns true;
- method getElementsByTagName of Element object is not implemented;
- method normalize of Element object is not implemented;
- the special semantics for child lists of EntityReference nodes and the read-only property for descendants of EntityReference nodes are not implemented.
D URI Support
Current release supports only URI related to the Win32 local file system. The syntax is
file://localhost/<drive>/<directory1>/.../<directoryN>/<filename>
For example, the file
d:\unicorn\uxsl\samples\test.xml
may be described using the URI
file://localhost/d/unicorn/uxsl/samples/test.xml
Relative URI and fragment identifiers are not supported.
The URI syntax described in RFC 2396 does not allow certain characters in the URI. Such characters should be always escaped when the URI is referenced within a script.
In particular, if the Win32 path name of the resource contains space characters, these space characters should be replaced by their escaped equivalent %20 in the corresponding URI reference.
For example, the file
d:\unicorn\my documents\test.xml
should be described using the URI
file://localhost/d/unicorn/my%20documents/test.xml