s2/vanillajs-seed
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update node modules

Browse Source
This commit is contained in:
s2
2020-07-20 16:20:39 +02:00
parent dcb748f037
commit f9fb05e4db
906 changed files with 124011 additions and 93468 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
node_modules/saxes/README.md generated vendored
View File

@@ -8,7 +8,7 @@ of sax in this project's documentation are references to sax 1.2.4.
Designed with [node](http://nodejs.org/) in mind, but should work fine in the
browser or other CommonJS implementations.
Saxes does not support Node versions older than 8.
Saxes does not support Node versions older than 10.
## Notable Differences from Sax.
@@ -16,11 +16,10 @@ Saxes does not support Node versions older than 8.
well-formedness. Sax, even in its so-called "strict mode", is not strict. It
silently accepts structures that are not well-formed XML. Projects that need
better compliance with well-formedness constraints cannot use sax as-is.
Saxes aims for conformance with [XML 1.0 fifth
edition](https://www.w3.org/TR/2008/REC-xml-20081126/) and [XML Namespaces 1.0
third edition](http://www.w3.org/TR/2009/REC-xml-names-20091208/).
Consequently, saxes does not support HTML, or pseudo-XML, or bad XML.
Consequently, saxes does not support HTML, or pseudo-XML, or bad XML. Saxes
will report well-formedness errors in all these cases but it won't try to
extract data from malformed documents like sax does.
* Saxes is much much faster than sax, mostly because of a substantial redesign
of the internal parsing logic. The speed improvement is not merely due to
@@ -45,46 +44,43 @@ Saxes does not support Node versions older than 8.
* Saxes does not have facilities for limiting the size the data chunks passed to
event handlers. See the FAQ entry for more details.
## Conformance
Saxes supports:
* [XML 1.0 fifth edition](https://www.w3.org/TR/2008/REC-xml-20081126/)
* [XML 1.1 second edition](https://www.w3.org/TR/2006/REC-xml11-20060816/)
* [Namespaces in XML 1.0 (Third Edition)](https://www.w3.org/TR/2009/REC-xml-names-20091208/).
* [Namespaces in XML 1.1 (Second Edition)](https://www.w3.org/TR/2006/REC-xml-names11-20060816/).
## Limitations
This is a non-validating parser so it only verifies whether the document is
well-formed. We do aim to raise errors for all malformed constructs encountered.
However, this parser does not parse the contents of DTDs. So malformedness
errors caused by errors in DTDs cannot be reported.
Also, the parser continues to parse even upon encountering errors, and does its
best to continue reporting errors. You should heed all errors
well-formed. We do aim to raise errors for all malformed constructs
encountered. However, this parser does not thorougly parse the contents of
DTDs. So most malformedness errors caused by errors **in DTDs** cannot be
reported.
**HOWEVER, ONCE AN ERROR HAS BEEN ENCOUNTERED YOU CANNOT RELY ON THE DATA
PROVIDED THROUGH THE OTHER EVENT HANDLERS.**
After an error, saxes tries to make sense of your document, but it may interpret
it incorrectly. For instance ``<foo a=bc="d"/>`` is invalid XML. Did you mean to
have ``<foo a="bc=d"/>`` or ``<foo a="b" c="d"/>`` or some other variation?
Saxes takes an honest stab at figuring out your mangled XML. That's as good as
it gets.
## Regarding `<!DOCTYPE`s and `<!ENTITY`s
## Regarding `<!DOCTYPE` and `<!ENTITY`
The parser will handle the basic XML entities in text nodes and attribute
values: `&amp; &lt; &gt; &apos; &quot;`. It's possible to define additional
entities in XML by putting them in the DTD. This parser doesn't do anything with
that. If you want to listen to the `ondoctype` event, and then fetch the
that. If you want to listen to the `doctype` event, and then fetch the
doctypes, and read the entities and add them to `parser.ENTITIES`, then be my
guest.
## Documentation
The source code contains JSDOC comments. Use them.
The source code contains JSDOC comments. Use them. What follows is a brief
summary of what is available. The final authority is the source code.
**PAY CLOSE ATTENTION TO WHAT IS PUBLIC AND WHAT IS PRIVATE.**
The elements of code that do not have JSDOC documentation, or have documentation
with the ``@private`` tag, are private.
The move to TypeScript makes it so that everything is now formally private,
protected, or public.
If you use anything private, that's at your own peril.
If you use anything not public, that's at your own peril.
If there's a mistake in the documentation, raise an issue. If you just assume,
you may assume incorrectly.
@@ -97,39 +93,39 @@ you may assume incorrectly.
var saxes = require("./lib/saxes"),
parser = new saxes.SaxesParser();
parser.onerror = function (e) {
parser.on("error", function (e) {
// an error happened.
};
parser.ontext = function (t) {
});
parser.on("text", function (t) {
// got some text. t is the string of text.
};
parser.onopentag = function (node) {
});
parser.on("opentag", function (node) {
// opened a tag. node has "name" and "attributes"
};
parser.onend = function () {
});
parser.on("end", function () {
// parser stream is done, and ready to have more stuff written to it.
};
});
parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close();
```
### Constructor Arguments
Pass the following arguments to the parser function. All are optional.
`opt` - Object bag of settings regarding string formatting.
Settings supported:
* `xmlns` - Boolean. If `true`, then namespaces are supported. Default
is `false`.
* `position` - Boolean. If `false`, then don't track line/col/position. Unset is
treated as `true`. Default is unset.
treated as `true`. Default is unset. Currently, setting this to `false` only
results in a cosmetic change: the errors reported do not contain position
information. sax-js would literally turn off the position-computing logic if
this flag was set to false. The notion was that it would optimize
execution. In saxes at least it turns out that continually testing this flag
causes a cost that offsets the benefits of turning off this logic.
* `fileName` - String. Set a file name for error reporting. This is useful only
when tracking positions. You may leave it unset, in which case the file name
in error messages will be `undefined`.
when tracking positions. You may leave it unset.
* `fragment` - Boolean. If `true`, parse the XML as an XML fragment. Default is
`false`.
@@ -138,10 +134,32 @@ Settings supported:
namespaces known before parsing the XML file. It is not legal to pass
bindings for the namespaces `"xml"` or `"xmlns"`.
* `defaultXMLVersion` - The default version of the XML specification to use if
the document contains no XML declaration. If the document does contain an XML
declaration, then this setting is ignored. Must be `"1.0"` or `"1.1"`. The
default is `"1.0"`.
* `forceXMLVersion` - Boolean. A flag indicating whether to force the XML
version used for parsing to the value of ``defaultXMLVersion``. When this flag
is ``true``, ``defaultXMLVersion`` must be specified. If unspecified, the
default value of this flag is ``false``.
Example: suppose you are parsing a document that has an XML declaration
specifying XML version 1.1.
If you set ``defaultXMLVersion`` to ``"1.0"`` without setting
``forceXMLVersion`` then the XML declaration will override the value of
``defaultXMLVersion`` and the document will be parsed according to XML 1.1.
If you set ``defaultXMLVersion`` to ``"1.0"`` and set ``forceXMLVersion`` to
``true``, then the XML declaration will be ignored and the document will be
parsed according to XML 1.0.
### Methods
`write` - Write bytes onto the stream. You don't have to do this all at
once. You can keep writing as much as you want.
`write` - Write bytes onto the stream. You don't have to pass the whole document
in one `write` call. You can read your source chunk by chunk and call `write`
with each chunk.
`close` - Close the stream. Once closed, no more data may be written until it is
done processing the buffer, which is signaled by the `end` event.
@@ -150,8 +168,10 @@ done processing the buffer, which is signaled by the `end` event.
The parser has the following properties:
`line`, `column`, `position` - Indications of the position in the XML document
where the parser currently is looking.
`line`, `column`, `columnIndex`, `position` - Indications of the position in the
XML document where the parser currently is looking. The `columnIndex` property
counts columns as if indexing into a JavaScript string, whereas the `column`
property counts Unicode characters.
`closed` - Boolean indicating whether or not the parser can be written to. If
it's `true`, then wait for the `ready` event to write again.
@@ -168,6 +188,27 @@ generated by the parser happens, the declaration has been processed if present
at all. Otherwise, you have a malformed document, and as stated above, you
cannot rely on the parser data!
### Error Handling
The parser continues to parse even upon encountering errors, and does its best
to continue reporting errors. You should heed all errors reported. After an
error, however, saxes may interpret your document incorrectly. For instance
``<foo a=bc="d"/>`` is invalid XML. Did you mean to have ``<foo a="bc=d"/>`` or
``<foo a="b" c="d"/>`` or some other variation? For the sake of continuing to
provide errors, saxes will continue parsing the document, but the structure it
reports may be incorrect. It is only after the errors are fixed in the document
that saxes can provide a reliable interpretation of the document.
That leaves you with two rules of thumb when using saxes:
* Pay attention to the errors that saxes report. The default `onerror` handler
throws, so by default, you cannot miss errors.
* **ONCE AN ERROR HAS BEEN ENCOUNTERED, STOP RELYING ON THE EVENT HANDLERS OTHER
THAN `onerror`.** As explained above, when saxes runs into a well-formedness
problem, it makes a guess in order to continue reporting more errors. The guess
may be wrong.
### Events
To listen to an event, override `on<eventname>`. The list of supported events
@@ -201,6 +242,42 @@ namespaces is onerous.
Note that you can use `additionalNamespaces` and `resolvePrefix` together if you
want. `additionalNamespaces` applies before `resolvePrefix`.
The options `additionalNamespaces` and `resolvePrefix` are really meant to be
used for parsing fragments. However, saxes won't prevent you from using them
with `fragment: false`. Note that if you do this, your document may parse
without errors and yet be malformed because the document can refer to namespaces
which are not defined *in* the document.
Of course, `additionalNamespaces` and `resolvePrefix` are used only if `xmlns`
is `true`. If you are parsing a fragment that does not use namespaces, there's
no point in setting these options.
### Performance Tips
* saxes works faster on files that use newlines (``\u000A``) as end of line
markers than files that use other end of line markers (like ``\r`` or
``\r\n``). The XML specification requires that conformant applications behave
as if all characters that are to be treated as end of line characters are
converted to ``\u000A`` prior to parsing. The optimal code path for saxes is a
file in which all end of line characters are already ``\u000A``.
* Don't split Unicode strings you feed to saxes across surrogates. When you
naively split a string in JavaScript, you run the risk of splitting a Unicode
character into two surrogates. e.g. In the following example ``a`` and ``b``
each contain half of a single Unicode character: ``const a = "\u{1F4A9}"[0];
const b = "\u{1F4A9}"[1]`` If you feed such split surrogates to versions of
saxes prior to 4, you'd get errors. Saxes version 4 and over are able to
detect when a chunk of data ends with a surrogate and carry over the surrogate
to the next chunk. However this operation entails slicing and concatenating
strings. If you can feed your data in a way that does not split surrogates,
you should do it. (Obviously, feeding all the data at once with a single write
is fastest.)
* Don't set event handlers you don't need. Saxes has always aimed to avoid doing
work that will just be tossed away but future improvements hope to do this
more aggressively. One way saxes knows whether or not some data is needed is
by checking whether a handler has been set for a specific event.
## FAQ
Q. Why has saxes dropped support for limiting the size of data chunks passed to