CMake AST

Status

Travis CI (Ubuntu)	AppVeyor (Windows)	Coverage	PyPI	Licence

cmake-ast has been tested against every single CMake module that ships with recent versions of CMake. These tests also run in the continuous integration environment on each build. It supports multi-line strings and other corner cases.

Usage

Import cmakeast and ASTify the contents of a cmake file with cmakeast.ast.parse(contents). You can also pass it a list of tokens obtained by tokenization with the tokens keyword argument. The return will be a toplevel node, with node descriptions as follows:

Word

• (One) Type type: Variable | String | Number | CompoundLiteral | VariableDereference
• (One) String contents

Body

• (Many) (FunctionCall, IfStatement, ForeachStatement, WhileStatement)

FunctionCall

• (One) Word name
• (Many) Word arguments

FunctionDefinition

• (One) FunctionCall header
• (One) Body body
• (One) FunctionCall footer

MacroDefinition

• (One) FunctionCall header
• (One) Body body
• (One) FunctionCall footer

IfStatement

• (One) FunctionCall header
• (One) Body body

ElseIfStatement

• (One) FunctionCall header
• (One) Body body

ElseStatement

• (One) FunctionCall header
• (One) Body body

IfBlock

• (One) IfStatement if_statement
• (Many) ElseIfStatement else_ifs
• (One Optional) ElseStatement else_statement
• (One) FunctionCall footer

ForeachStatement

• (One) FunctionCall foreach_function
• (One) Body body
• (One) FunctionCall footer

WhileStatement

• (One) FunctionCall while_function
• (One) Body body
• (One) FunctionCall footer

Each node also has a line and col member to indicate where it can be found in the source file.

Word type aliases are stored in WordType inside ast.

Traversing the AST

CMake-AST provides a helper module ast_visitor to make traversing the AST less verbose. It will traverse every single node by default. Listeners matching the signature def handler (name, node, depth) can be passed as the following keyword arguments to recurse (body, **kwargs):

Keyword	Handles Node Type
toplevel	ToplevelBody
while_stmnt	WhileStatement
foreach	ForeachStatement
function_def	FunctionDefinition
macro_def	MacroDefinition
if_block	IfBlock
if_stmnt	IfStatement
elseif_stmnt	ElseIfStatement
else_stmnt	ElseStatement
function_call	FunctionCall
word	Word

Dumping the AST of a CMake file

If you wish to dump the AST of a cmake file, the cmake-print-ast tool is also provided. Pass a single filename to dump the AST of to it on the command line

Tokenization

To get an even lower level representation, use cmakeast.ast.tokenize(contents) which divides the file only into tokens. Aliases are stored in the TokenType class in ast. Tokens correspond as follows:

Token Type	Description
QuotedLiteral	Something in quotes
LeftParen	(
RightParen	)
Word	Alphanumeric Sequence
Number	Numeric-Only Sequence
Deref	Alphanumeric Sequence inside ${}
RST	Documentation Comment
Comment	Comment
UnquotedLiteral	Any character sequence, punctuation included