solc-ast

用于探索由solc编译器生成的Solidity抽象语法树的工具。

安装

您可以通过pip安装最新版本

$ pip install py-solc-ast

或者克隆仓库并使用setuptools

$ python setup.py install

用法

首先，使用py-solc-x将您的合约编译成标准JSON输出格式。

>>> import json
>>> import solcx
>>> input_json = json.load(open('input.json'))
>>> output_json = solcx.compile_standard(input_json)

然后，导入solcast并使用from_standard_output_json或from_standard_output初始化。这返回一个SourceUnit对象列表，每个对象代表Solidity源文件中的基本AST节点。

>>> import solcast
>>> nodes = solcast.from_standard_output(output_json)
>>> nodes
[<SourceUnit iterable 'contracts/Token.sol'>, <SourceUnit iterable 'contracts/SafeMath.sol'>]

您也可以直接从该源代码的AST生成单个SourceUnit

>>> import solcast
>>> node = solcast.from_ast(output_json["sources"]["contracts/Token.sol"]["ast"])
>>> node
<SourceUnit iterable 'contracts/Token.sol'>

与节点交互

每个节点都有以下属性

>>> node
<FunctionDefinition iterable 'mul'>

>>> node.depth  # Number of nodes between this node and the SourceUnit
2

>>> node.offset  # Absolute source offsets as a (start, stop) tuple
(1693, 2151)

>>> node.contract_id  # Contract ID as given by the standard compiler JSON
2

>>> node.fields  # List of fields for this node
['baseNodeType', 'documentation', 'id', 'implemented', 'kind', 'modifiers', 'name', 'nodeType', 'nodes', 'parameters', 'returnParameters', 'scope', 'src', 'stateMutability', 'superFunction', 'visibility']

字段主要遵循预期的AST语法。一个显著的区别：Block节点被省略，每个Block的体在其父节点中作为属性nodes可用。包含体的节点是可迭代的，可以使用列表语法访问。此外，任何具有name字段的子节点都可以使用字典语法访问。

以下附加字段也可用

• 大多数节点都有一个定义在grammar.py中的baseNodeType字段。
• ContractDefinition节点具有指向相关ContractDefition节点的dependencies和libraries字段。

一些示例

>>> source_node
<SourceUnit iterable 'contracts/math/SafeMath.sol'>

>>> source_node.keys()
['absolutePath', 'children', 'contract_id', 'depth', 'exportedSymbols', 'id', 'is_child_of', 'is_parent_of', 'keys', 'nodeType', 'nodes', 'offset', 'parent', 'parents', 'src']

>>> source_node.nodes
[<PragmaDirective object>, <ContractDefinition iterable 'SafeMath'>]

>>> source_node[1]
<ContractDefinition iterable 'SafeMath'>

>>> source_node['SafeMath']
<ContractDefinition iterable 'SafeMath'>

>>> source_node['SafeMath'].keys()
['baseContracts', 'children', 'contractDependencies', 'contractKind', 'contract_id', 'dependencies', 'depth', 'documentation', 'fullyImplemented', 'id', 'is_child_of', 'is_parent_of', 'keys', 'libraries', 'linearizedBaseContracts', 'name', 'nodeType', 'nodes', 'offset', 'parent', 'parents', 'scope', 'src']

>>> source_node['SafeMath'].nodes
[<FunctionDefinition iterable 'add'>, <FunctionDefinition iterable 'sub'>, <FunctionDefinition iterable 'mul'>, <FunctionDefinition iterable 'div'>, <FunctionDefinition iterable 'mod'>]

>>> source_node['SafeMath']['mul']
<FunctionDefinition iterable 'mul'>

>>> source_node['SafeMath']['mul']
[<IfStatement object>, <VariableDeclarationStatement object>, <FunctionCall object>, <Return object>]

探索树

使用Node.children()方法来搜索和过滤给定节点的子节点。它接受以下任一关键字参数：

• depth：要遍历的子节点级别的数量。返回值为0时仅返回此节点。
• include_self：将此节点包含在结果中。
• include_parents：当这些节点匹配且它们也有匹配的子节点时，将匹配的节点包含在结果中。
• include_children：如果为True，一旦找到匹配项，则不会将匹配项的子节点包含在搜索中。
• required_offset：仅匹配具有包含此偏移量的源偏移量的节点。
• offset_limits：仅当它们的源偏移量包含在此源偏移量内时，才匹配节点。
• filters：表示{'attribute': "value"}的字典，子节点必须匹配。也可以作为字典列表提供，匹配任何字典的子节点将被返回。
• exclude_filter：表示{'attribute': "value"}的字典，子节点不能匹配。

>>> node = s['Token']['transfer']
>>> node.children(
    include_children=False,
    filters={'nodeType': "FunctionCall", "expression.name": "require"}
)
[<FunctionCall>]

Node.parent()和Node.parents()用于向上遍历树。它们接受以下参数：

• depth：深度限制。如果给定负值，则从该对象的深度中减去。
• filters：表示{'attribute': "value"}的字典，必须匹配父节点。

Node.parent()返回一个结果，Node.parents()返回一个匹配项列表。

>>> node.parents()
[<ContractDefinition iterable 'Token'>, <SourceUnit iterable object 'contracts/Token.sol'>]

测试

运行测试套件

$ tox

开发

欢迎评论、提问、批评和pull requests！如果您遇到问题或想建议新功能，请随时提交issue。

许可协议

本项目遵循MIT许可。