widlparser

Python中的独立WebIDL解析器。需要Python 3.7+。

按照：http://dev.w3.org/2006/webapi/WebIDL/ (加上一些遗留兼容性项目) 解析WebIDL

此解析器是为了支持一个W3C规范解析器和预处理器而创建的，其API旨在通过名称查找和识别各种WebIDL结构。然而，所有WebIDL源都解析并存储在结构对象中。解析器具有错误恢复功能，并保留整个输入以重新序列化和标记WebIDL结构。

安装

标准的Python包安装

pip install widlparser

使用方法

导入widlparser包并实例化一个解析器。

import widlparser

widl = widlparser.Parser()

要么在构造函数中传递要解析的WebIDL文本，要么调用 Parser.parse(text) 方法。

解析器类

class Parser([text[, ui]])

解析器的构造函数接受两个可选参数，text和ui。如果存在，text是包含要解析的WebIDL文本的字符串。ui.warn()将在解析过程中遇到任何语法错误时被调用（如果实现）。ui.note()将在解析过程中忽略任何遗留WebIDL时被调用（如果实现）。

Parser.constructs

所有顶级WebIDL结构都按源顺序存储在'constructs'属性中。

Parser.complexity_factor

解析的WebIDL中定义的结构相对复杂性的索引。用作规范测试覆盖率的索引很有用。

Parser.parse(text)

解析额外的WebIDL文本。所有解析的结构都将附加到'constructs'属性。

Parser.reset()

清除所有存储的结构。

Parser.find(name)

返回一个命名结构。如果提供了一个单个名称，则通过所有解析的结构执行广度优先搜索。或者，可以通过传递路径（由"/"或"."分隔的名称）来更精确地定位搜索。例如：find("Foo/bar/baz") 在 Interface 'Foo' 中查找 Method 'bar' 内部的 Attribute 'baz'。

Parser.find_all(name)

返回命名结构的列表。接受与 Parser.find(name) 相同的搜索路径。

Parser.normalized_method_name(name [, interface_name=None])

提供一个方法名称的标准化版本，包括所有参数的名称，例如 "drawCircle(long x, long y, long radius)" 变为："drawCircle(x, y, radius)"。如果传递了有效的参数集，则将返回传递的参数名称的标准化形式。否则，将执行匹配先前解析的方法名称的搜索。可以通过传递接口或回调的名称来缩小搜索到特定的接口。

Parser.normalized_method_names(name [, interface_name=None])

返回所有可能的方法名称的列表。如果方法有可选参数，则列表将包含所有可能的参数变体。列表中的第一个项将是 normalized_method_name 返回的值。

Parser.markup(marker)

返回 WebIDL 输入文本的标记版本。传递的 'marker' 对象将被回调以标记 WebIDL 的各个元素。请参阅“标记”部分以获取更多详细信息。

结构

从解析器的 Parser.constructs 属性或从解析器的 find() 方法返回的所有结构都是 Construct 类的子类。基本类提供了以下功能

Construct.name

结构的名称。

Construct.idl_type

包含表示结构类型的字符串。可能的值包括："const"，"enum"，"typedef"，"interface"，"constructor"，"attribute"，"iterable"，"maplike"，"setlike"，"stringifier"，"serializer"，"method"，"argument"，"dictionary"，"dict-member"，"callback"，"implements"，"extended-attribute" 和 "unknown"。

Construct.full_name

结构的名称以及其所有父级的路径形式，例如：'Interface/method_name(argument)/argument'。

Construct.method_name

对于 'method' 结构，包含标准化的方法名称，否则为 None。

Construct.method_names

对于 'method' 结构，包含所有可能的标准化的方法名称的列表，否则为 None。如果方法包含可选参数或可变参数，则方法可能有多个可能的标准化的名称。

Construct.normal_name

对于 'method' 结构，包含标准化的方法名称，否则为结构的名称。

Construct.parent

如果有父级，则为父级结构。如果是源 WebIDL 中的顶级结构，则抛出 KeyError。

Construct.has_parent

一个布尔值，指定结构是否有父级（以及因此访问 .parent 时是否会抛出。）

Construct.extended_attributes

一个扩展属性的列表，或 None。扩展属性存储为结构，形式如下：'identifier'，'identifier=identifier'，'identifier(ArgumentList)'，'identifier=identifier(ArgumentList)'，或 'identifier(Type,Type)' 被解析。第一个标识符存储在 'Construct.attribute' 中，第二个（如果有）存储在 'Construct.name' 中，参数存储在 'Construct.arguments' 中。不符合这些五种形式扩展属性包含一个令牌列表在 'Construct.tokens' 中，其名称设置为 'None'。

Construct.constructors

任何匹配 Constructor 或 LegacyFactoryFunction 形式的扩展属性的列表。任何存在的构造函数将添加到 'interface' 结构的 'members' 属性之前。

Construct.complexity_factor

结构的复杂性的索引。请参阅 Parser.complexity_factor。

Construct.find_member(name)

查找结构的一个成员。对于具有接口的 'callback' 结构，将搜索接口。

Construct.find_members(name)

返回与指定名称匹配的构造函数成员列表。对于具有接口的 'callback' 构造函数，将在接口中进行搜索。

Construct.find_method(name)

在构造函数中查找方法。

Construct.find_methods(name)

返回与指定名称匹配的构造函数中方法列表。

Construct.find_argument(name[, search_members=True])

在构造函数中查找参数。如果 'search_members' 为真，将搜索所有成员。这允许区分回调参数与回调接口方法参数。

Construct.find_arguments(name[, search_members=True])

返回构造函数中与指定名称匹配的参数列表。如果 'search_members' 为真，将搜索所有成员。这允许区分回调参数与回调接口方法参数。

Construct.markup(marker)

返回构造函数 WebIDL 源文本的标记版本。有关信息，请参阅 Parser.markup(marker)。

Construct 子类

每个构造函数都将是一个与 'Construct.idl_type' 对应的 Construct 子类实例。特定的子类提供以下附加属性

Const.type

Const 的类型生成。

Const.value

Const 的 ConstValue 生成。

Enum.values

Enum 的 EnumValueList 生成。

Typedef.type

Typedef 的类型生成。

Argument.type

Argument 的类型生成。

Argument.variadic

符号 "variadic" 或 'None'。

Argument.optional

符号 "optional" 或 'None'。

Argument.default

Argument 的默认生成或 'None'。

InterfaceMember.member

以下之一：Const、Serializer、Stringifier、StaticMember、Iterable、Maplike、Setlike、Attribute、SpecialOperation 或 Operation。

InterfaceMember.arguments

包含任何存在的参数列表或 'None'。

Interface.partial

符号 "partial" 或 'None'。

Interface.inheritance

Interface 的继承生成或 'None'。

Interface.members

InterfaceMembers 列表。

DictionaryMember.type

DictionaryMember 的类型生成。

DictionaryMember.default

DictionaryMember 的默认生成或 'None'。

Dictionary.inheritance

Dictionary 的继承生成或 'None'。

Dictionary.members

DictionaryMembers 列表。

Callback.return_type

Callback 的返回类型生成。

Callback.arguments

包含任何存在的参数列表或 'None'（接口回调）。

Callback.interface

回调的 'interface' 构造函数，或 'None'（函数回调）。

ImplementsStatement.implements

实现了 ImplementsStatement 的类型字符串。

ExtendedAttribute.attribute

ExtendedAttribute 的子类型生成。见下文。以下每个 ExtendedAttribute 子类型也都有一个 '.attribute' 属性，指定 ExtendedAttribute 中的第一个标识符。除了 Constructor 或 LegacyFactoryFunction 类型之外的 ExtendedAttributes 也会将此标识符包含在 '.name' 属性中。

ExtendedAttributeArgList.arguments.

包含任何存在的参数列表或 'None'。

ExtendedAttributeIdent.value

包含 "=" 之后存在的标识符字符串。

ExtendedAttributeNamedArgList.value

包含 "=" 之后存在的标识符字符串。

ExtendedAttributeNamedArgList.arguments

包含任何存在的参数列表或 'None'。

ExtendedAttributeTypePair.key_type

对中的第一个类型生成。

ExtendedAttributeTypePair.value_type

对中的第二个类型生成。

ExtendedAttributeUnknown.tokens

包含不匹配五个基本类型之一的 ExtendedAttributes 中的标记列表。

SyntaxError.tokens

包含不匹配 WebIDL 语法标记的标记列表。

Markup

当调用解析器的'markup(marker)'方法时，传递的'marker'是一个对象，该对象将被调用以帮助生成每个构造、多个生产和编码原始文本的标记。标记和编码调用将按源顺序发生，文本将在标记边界处分割。标记方法将传入构造或原语的纯文本内容和相关构造对象。每个方法都必须返回一个包含两个值的元组（字符串或None），这两个值将被注入到围绕构造或生产的最终标记中。所有标记方法的实现都是可选的。

markup_construct(text, construct)

将为每个构造调用。

markup_name(text, construct)

将为每个构造调用一次，并带有构造的名称。

markup_type(text, construct)

将为每个类型生产调用。注意，类型可能是嵌套的，例如联合、序列等。

markup_primitive_type(text, construct)

将为类型中的每个原语类型生产调用，例如 "unsigned long long"、"float"、"boolean"等。

markup_buffer_type(text, construct)

将为类型中的每个与缓冲区相关的类型生产调用，例如 "ArrayBuffer"、"DataView"、"Int8Array"等。

markup_string_type(text, construct)

将为类型中的每个字符串类型生产调用，例如 "ByteString"、"DOMString"或"USVString"。

markup_object_type(text, construct)

将为类型中的每个对象类型生产调用，例如 "object"或"Error"。

markup_type_name(text, construct)

当引用用户定义的类型名称时将被调用。

markup_keyword(text, construct)

将为每个关键字调用。

markup_enum_value(text, construct)

将为枚举声明中的每个值调用。

encode(text)

将被调用以编码每个文本运行。

注意

解析器本身是可迭代的和可索引的。顶级构造可以通过'in'操作符进行测试，并通过名称或索引通过[]检索。也可以使用str()函数在解析器上重新序列化解析的WebIDL。序列化输出是中性的，即str(parser.Parser(text)) == text

构造也是可迭代的和可索引的，以便访问成员。此外，构造可以通过str()函数重新序列化为有效的WebIDL。

所有其他WebIDL输入都存储在各种构造中作为生产对象。有关详细信息，请参阅productions.py源文件。生产可以通过str()函数重新序列化为它们的源WebIDL。