Import Cobalt 19.master.0.203780
Includes the following patches:
https://cobalt-review.googlesource.com/c/cobalt/+/5210
by errong.leng@samsung.com
https://cobalt-review.googlesource.com/c/cobalt/+/5270
by linus.wang@samsung.com
diff --git a/src/third_party/web_platform_tests/resources/webidl2/README.md b/src/third_party/web_platform_tests/resources/webidl2/README.md
new file mode 100644
index 0000000..f7d03fc
--- /dev/null
+++ b/src/third_party/web_platform_tests/resources/webidl2/README.md
@@ -0,0 +1,760 @@
+
+# WebIDL 2
+
+[](http://badge.fury.io/js/webidl2)
+
+Purpose
+=======
+
+This is a parser for the [WebIDL](http://dev.w3.org/2006/webapi/WebIDL/) language. If
+you don't know what that is, then you probably don't need it. It is meant to be used
+both in Node and in the browser (the parser likely works in other JS environments, but
+not the test suite).
+
+What of v1?
+-----------
+There was a previous incarnation of this project. I had written it in the most quick
+and dirty manner that was handy because I required it as a dependency in an experiment.
+As these things tend to happen, some people started using that, which then had to be
+maintained. But since it was not built on solid foundations, it was painful to keep
+up to date with the specification, which is a bit of a moving target.
+
+So I started from scratch. Compared to the previous version (which used a parser generator)
+this one is about 6x less code (which translates to 4x smaller minified or 2x smaller
+minizipped) and 4x faster. The test suite is reasonably complete (95% coverage), much more
+than previously. This version is up to date with WebIDL, rather than a couple years' behind.
+It also has *far* better error reporting.
+
+The AST you get from parsing is very similar to the one you got in v1, but some adjustments
+have been made in order to be more systematic, and to map better to what's actually in the spec
+now. If you used v1, you will need to tweak your code but the result ought to be simpler and
+you ought to be able to be a fair bit less defensive against irregularities in the way
+information is represented.
+
+Installation
+============
+
+Just the usual. For Node:
+
+ npm install webidl2
+
+In the browser:
+
+ <script src='webidl2.js'></script>
+
+Documentation
+=============
+
+The API to WebIDL2 is trivial: you parse a string of WebIDL and it returns a syntax tree.
+
+Parsing
+-------
+In Node, that happens with:
+
+ var WebIDL2 = require("webidl2");
+ var tree = WebIDL2.parse("string of WebIDL");
+
+In the browser:
+
+ <script src='webidl2.js'></script>
+ <script>
+ var tree = WebIDL2.parse("string of WebIDL");
+ </script>
+
+Advanced Parsing
+----------------
+
+`parse()` can optionally accept a second parameter, an options object, which can be used to
+modify parsing behavior.
+
+The following options are recognized:
+```javascript
+{
+ allowNestedTypedefs: false #
+}
+```
+And their meanings are as follows:
+
+* `allowNestedTypedefs`: Boolean indicating whether the parser should accept `typedef`s as valid members of `interface`s. This is non-standard syntax and therefore the default is `false`.
+
+Errors
+------
+When there is a syntax error in the WebIDL, it throws an exception object with the following
+properties:
+
+* `message`: the error message
+* `line`: the line at which the error occurred.
+* `input`: a short peek at the text at the point where the error happened
+* `tokens`: the five tokens at the point of error, as understood by the tokeniser
+ (this is the same content as `input`, but seen from the tokeniser's point of view)
+
+The exception also has a `toString()` method that hopefully should produce a decent
+error message.
+
+AST (Abstract Syntax Tree)
+--------------------------
+The `parse()` method returns a tree object representing the parse tree of the IDL.
+Comment and white space are not represented in the AST.
+
+The root of this object is always an array of definitions (where definitions are
+any of interfaces, exceptions, callbacks, etc. — anything that can occur at the root
+of the IDL).
+
+### IDL Type
+
+This structure is used in many other places (operation return types, argument types, etc.).
+It captures a WebIDL type with a number of options. Types look like this and are typically
+attached to a field called `idlType`:
+
+ {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "void"
+ }
+
+Where the fields are as follows:
+
+* `sequence`: Boolean indicating whether this is a sequence or not. Deprecated. Use
+ `generic` instead.
+* `generic`: String indicating the generic type (e.g. "Promise", "sequence"). `null`
+ otherwise.
+* `nullable`: Boolean indicating whether this is nullable or not.
+* `array`: Either `false` to indicate that it is not an array, or a number for the level of
+ array nesting.
+* `union`: Boolean indicating whether this is a union type or not.
+* `idlType`: Can be different things depending on context. In most cases, this will just
+ be a string with the type name. But the reason this field isn't called "typeName" is
+ because it can take more complex values. If the type is a union, then this contains an
+ array of the types it unites. If it is a generic type, it contains the IDL type
+ description for the type in the sequence, the eventual value of the promise, etc.
+
+#### Interactions between `nullable` and `array`
+
+A more complex data model for our AST would likely represent `Foo[][][]` as a series of
+nested types four levels deep with three anonymous array types eventually containing a
+`Foo` type. But experience shows that such structures are cumbersome to use, and so we
+have a simpler model in which the depth of the array is specified with the `array` field.
+
+This is all fine and well, and in the vast majority of cases is actually simpler. But it
+does run afoul of cases in which it is necessary to distinguish between `Foo[][][]?`,
+`Foo?[][][]`, `Foo[][]?[]`, or even `Foo?[]?[]?[]?`.
+
+For this, when a type is an array type an additional `nullableArray` field is made available
+that captures which of the arrays contain nullable elements. It contains booleans that are
+true if the given array depth contains nullable elements, and false otherwise (mapping that to
+the syntax, and item is true if there is a `?` preceding the `[]`). These examples ought to
+clarify the model:
+
+ Foo[][][]?
+ -> nullable: true
+ -> nullableArray: [false, false, false]
+ Foo?[][][]
+ -> nullable: false
+ -> nullableArray: [true, false, false]
+ Foo[][]?[]
+ -> nullable: false
+ -> nullableArray: [false, false, true]
+ Foo?[]?[]?[]?
+ -> nullable: true
+ -> nullableArray: [true, true, true]
+
+Of particular importance, please note that the overall type is only `nullable` if there is
+a `?` at the end.
+
+### Interface
+Interfaces look like this:
+
+ {
+ "type": "interface",
+ "name": "Animal",
+ "partial": false,
+ "members": [...],
+ "inheritance": null,
+ "extAttrs": [...]
+ },
+ {
+ "type": "interface",
+ "name": "Human",
+ "partial": false,
+ "members": [...],
+ "inheritance": "Animal",
+ "extAttrs": [...]
+ }
+
+The fields are as follows:
+
+* `type`: Always "interface".
+* `name`: The name of the interface
+* `partial`: A boolean indicating whether it's a partial interface.
+* `members`: An array of interface members (attributes, operations, etc.). Empty if there are none.
+* `inheritance`: A string giving the name of an interface this one inherits from, `null` otherwise.
+ **NOTE**: In v1 this was an array, but multiple inheritance is no longer supported so this didn't make
+ sense.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Callback Interfaces
+
+These are captured by the same structure as [Interfaces](#interface) except that
+their `type` field is "callback interface".
+
+### Callback
+
+A callback looks like this:
+
+ {
+ "type": "callback",
+ "name": "AsyncOperationCallback",
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "void"
+ },
+ "arguments": [...],
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "callback".
+* `name`: The name of the callback.
+* `idlType`: An [IDL Type](#idl-type) describing what the callback returns.
+* `arguments`: A list of [arguments](#arguments), as in function paramters.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Dictionary
+
+A dictionary looks like this:
+
+ {
+ "type": "dictionary",
+ "name": "PaintOptions",
+ "partial": false,
+ "members": [
+ {
+ "type": "field",
+ "name": "fillPattern",
+ "required": false,
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": true,
+ "array": false,
+ "union": false,
+ "idlType": "DOMString"
+ },
+ "extAttrs": [],
+ "default": {
+ "type": "string",
+ "value": "black"
+ }
+ }
+ ],
+ "inheritance": null,
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "dictionary".
+* `name`: The dictionary name.
+* `partial`: Boolean indicating whether it's a partial dictionary.
+* `members`: An array of members (see below).
+* `inheritance`: A string indicating which dictionary is being inherited from, `null` otherwise.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+All the members are fields as follows:
+
+* `type`: Always "field".
+* `name`: The name of the field.
+* `required`: Boolean indicating whether this is a [required](https://heycam.github.io/webidl/#required-dictionary-member) field.
+* `idlType`: An [IDL Type](#idl-type) describing what field's type.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+* `default`: A [default value](#default-and-const-values), absent if there is none.
+
+### Exception
+
+An exception looks like this:
+
+ {
+ "type": "exception",
+ "name": "HierarchyRequestError",
+ "members": [
+ {
+ "type": "field",
+ "name": "code",
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "unsigned short"
+ },
+ "extAttrs": []
+ }
+ ],
+ "inheritance": "DOMException",
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "exception".
+* `name`: The exception name.
+* `members`: An array of members (constants or fields, where fields are described below).
+* `inheritance`: A string indicating which exception is being inherited from, `null` otherwise.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+Members that aren't [constants](#constants) have the following fields:
+
+* `type`: Always "field".
+* `name`: The field's name.
+* `idlType`: An [IDL Type](#idl-type) describing what field's type.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Enum
+
+An enum looks like this:
+
+ {
+ "type": "enum",
+ "name": "MealType",
+ "values": [
+ "rice",
+ "noodles",
+ "other"
+ ],
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "enum".
+* `name`: The enum's name.
+* `value`: An array of values (strings).
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Typedef
+
+A typedef looks like this:
+
+ {
+ "type": "typedef",
+ "typeExtAttrs": [],
+ "idlType": {
+ "sequence": true,
+ "generic": "sequence",
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "Point"
+ }
+ },
+ "name": "PointSequence",
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "typedef".
+* `name`: The typedef's name.
+* `idlType`: An [IDL Type](#idl-type) describing what typedef's type.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+* `typeExtAttrs`: A list of [extended attributes](#extended-attributes) that apply to the
+type rather than to the typedef as a whole.
+
+### Implements
+
+An implements definition looks like this:
+
+ {
+ "type": "implements",
+ "target": "Node",
+ "implements": "EventTarget",
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "implements".
+* `target`: The interface that implements another.
+* `implements`: The interface that is being implemented by the target.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Operation Member
+
+An operation looks like this:
+
+ {
+ "type": "operation",
+ "getter": false,
+ "setter": false,
+ "creator": false,
+ "deleter": false,
+ "legacycaller": false,
+ "static": false,
+ "stringifier": false,
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "void"
+ },
+ "name": "intersection",
+ "arguments": [
+ {
+ "optional": false,
+ "variadic": true,
+ "extAttrs": [],
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "long"
+ },
+ "name": "ints"
+ }
+ ],
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "operation".
+* `getter`: True if a getter operation.
+* `setter`: True if a setter operation.
+* `creator`: True if a creator operation.
+* `deleter`: True if a deleter operation.
+* `legacycaller`: True if a legacycaller operation.
+* `static`: True if a static operation.
+* `stringifier`: True if a stringifier operation.
+* `idlType`: An [IDL Type](#idl-type) of what the operation returns. If a stringifier, may be absent.
+* `name`: The name of the operation. If a stringifier, may be `null`.
+* `arguments`: An array of [arguments](#arguments) for the operation.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Attribute Member
+
+An attribute member looks like this:
+
+ {
+ "type": "attribute",
+ "static": false,
+ "stringifier": false,
+ "inherit": false,
+ "readonly": false,
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "RegExp"
+ },
+ "name": "regexp",
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "attribute".
+* `name`: The attribute's name.
+* `static`: True if it's a static attribute.
+* `stringifier`: True if it's a stringifier attribute.
+* `inherit`: True if it's an inherit attribute.
+* `readonly`: True if it's a read-only attribute.
+* `idlType`: An [IDL Type](#idl-type) for the attribute.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Constant Member
+
+A constant member looks like this:
+
+ {
+ "type": "const",
+ "nullable": false,
+ "idlType": "boolean",
+ "name": "DEBUG",
+ "value": {
+ "type": "boolean",
+ "value": false
+ },
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always "const".
+* `nullable`: Whether its type is nullable.
+* `idlType`: The type of the constant (a simple type, the type name).
+* `name`: The name of the constant.
+* `value`: The constant value as described by [Const Values](#default-and-const-values)
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Serializer Member
+
+Serializers come in many shapes, which are best understood by looking at the
+examples below that map the IDL to the produced AST.
+
+ // serializer;
+ {
+ "type": "serializer",
+ "extAttrs": []
+ }
+
+ // serializer DOMString serialize();
+ {
+ "type": "serializer",
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "DOMString"
+ },
+ "operation": {
+ "name": "serialize",
+ "arguments": []
+ },
+ "extAttrs": []
+ }
+
+ // serializer = { from, to, amount, description };
+ {
+ "type": "serializer",
+ "patternMap": true,
+ "names": [
+ "from",
+ "to",
+ "amount",
+ "description"
+ ],
+ "extAttrs": []
+ }
+
+ // serializer = number;
+ {
+ "type": "serializer",
+ "name": "number",
+ "extAttrs": []
+ }
+
+ // serializer = [ name, number ];
+ {
+ "type": "serializer",
+ "patternList": true,
+ "names": [
+ "name",
+ "number"
+ ],
+ "extAttrs": []
+ }
+
+The common fields are as follows:
+
+* `type`: Always "serializer".
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+For a simple serializer, that's all there is. If the serializer is an operation, it will
+have:
+
+* `idlType`: An [IDL Type](#idl-type) describing what the serializer returns.
+* `operation`: An object with the following fields:
+ * `name`: The name of the operation.
+ * `arguments`: An array of [arguments](#arguments) for the operation.
+
+If the serializer is a pattern map:
+
+* `patternMap`: Always true.
+* `names`: An array of names in the pattern map.
+
+If the serializer is a pattern list:
+
+* `patternList`: Always true.
+* `names`: An array of names in the pattern list.
+
+Finally, if the serializer is a named serializer:
+
+* `name`: The serializer's name.
+
+### Iterator Member
+
+Iterator members look like this
+
+ {
+ "type": "iterator",
+ "getter": false,
+ "setter": false,
+ "creator": false,
+ "deleter": false,
+ "legacycaller": false,
+ "static": false,
+ "stringifier": false,
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "Session2"
+ },
+ "iteratorObject": "SessionIterator",
+ "extAttrs": []
+ }
+
+* `type`: Always "iterator".
+* `iteratorObject`: The string on the right-hand side; absent if there isn't one.
+* the rest: same as on [operations](#operation-member).
+
+### Arguments
+
+The arguments (e.g. for an operation) look like this:
+
+ "arguments": [
+ {
+ "optional": false,
+ "variadic": true,
+ "extAttrs": [],
+ "idlType": {
+ "sequence": false,
+ "generic": null,
+ "nullable": false,
+ "array": false,
+ "union": false,
+ "idlType": "long"
+ },
+ "name": "ints"
+ }
+ ]
+
+The fields are as follows:
+
+* `optional`: True if the argument is optional.
+* `variadic`: True if the argument is variadic.
+* `idlType`: An [IDL Type](#idl-type) describing the type of the argument.
+* `name`: The argument's name.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+### Extended Attributes
+
+Extended attributes are arrays of items that look like this:
+
+ "extAttrs": [
+ {
+ "name": "TreatNullAs",
+ "arguments": null,
+ "rhs": {
+ "type": "identifier",
+ "value": "EmptyString"
+ }
+ }
+ ]
+
+The fields are as follows:
+
+* `name`: The extended attribute's name.
+* `arguments`: If the extended attribute takes arguments (e.g. `[Foo()]`) or if
+ its right-hand side does (e.g. `[NamedConstructor=Name(DOMString blah)]`) they
+ are listed here. Note that an empty arguments list will produce an empty array,
+ whereas the lack thereof will yield a `null`. If there is an `rhs` field then
+ they are the right-hand side's arguments, otherwise they apply to the extended
+ attribute directly.
+* `rhs`: If there is a right-hand side, this will capture its `type` (which can be
+ "identifier" or "identifier-list") and its `value`.
+* `typePair`: If the extended attribute is a `MapClass` this will capture the
+ map's key type and value type respectively.
+
+### Default and Const Values
+
+Dictionary fields and operation arguments can take default values, and constants take
+values, all of which have the following fields:
+
+* `type`: One of string, number, boolean, null, Infinity, NaN, or sequence.
+
+For string, number, boolean, and sequence:
+
+* `value`: The value of the given type. For sequence, the only possible value is `[]`.
+
+For Infinity:
+
+* `negative`: Boolean indicating whether this is negative Infinity or not.
+
+### `iterable<>`, `legacyiterable<>`, `maplike<>`, `setlike<>` declarations
+
+These appear as members of interfaces that look like this:
+
+ {
+ "type": "maplike", // or "legacyiterable" / "iterable" / "setlike"
+ "idlType": /* One or two types */,
+ "readonly": false, // only for maplike and setlike
+ "extAttrs": []
+ }
+
+The fields are as follows:
+
+* `type`: Always one of "iterable", "legacyiterable", "maplike" or "setlike".
+* `idlType`: An [IDL Type](#idl-type) (or an array of two types) representing the declared type arguments.
+* `readonly`: Whether the maplike or setlike is declared as read only.
+* `extAttrs`: A list of [extended attributes](#extended-attributes).
+
+
+Testing
+=======
+
+In order to run the tests you need to ensure that the widlproc submodule inside `test` is
+initialised and up to date:
+
+ git submodule init
+ git submodule update
+
+Running
+-------
+The test runs with mocha and expect.js. Normally, running mocha in the root directory
+should be enough once you're set up.
+
+Coverage
+--------
+Current test coverage, as documented in `coverage.html`, is 95%. You can run your own
+coverage analysis with:
+
+ jscoverage lib lib-cov
+
+That will create the lib-cov directory with instrumented code; the test suite knows
+to use that if needed. You can then run the tests with:
+
+ JSCOV=1 mocha --reporter html-cov > coverage.html
+
+Note that I've been getting weirdly overescaped results from the html-cov reporter,
+so you might wish to try this instead:
+
+ JSCOV=1 mocha --reporter html-cov | sed "s/</</g" | sed "s/>/>/g" | sed "s/"/\"/g" > coverage.html
+
+Browser tests
+-------------
+In order to test in the browser, get inside `test/web` and run `make-web-tests.js`. This
+will generate a `browser-tests.html` file that you can open in a browser. As of this
+writing tests pass in the latest Firefox, Chrome, Opera, and Safari. Testing on IE
+and older versions will happen progressively.
+
+TODO
+====
+
+* add some tests to address coverage limitations
+* add a push API for processors that need to process things like comments
