如何使用 Python 方便地解析 C 头文件中的注释

我们需要解析一个用 C 语言编写的 .h 文件，从中提取注释和实体名称。这些信息将被进一步写入一个已经开发好的 Word 文档中。源代码注释使用简单的标签式规则格式化。注释标签用于轻松区分不同的实体注释和非文档注释。注释可以是多行形式。每个注释都应该直接放在实体定义之上：

//ENUM My comment bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
//     could be multi-line. Bla bla bla bla bla bla bla bla bla.
enum my_enum
{
    //EITEM My enum item 1.
    //      Just could be multi-line too.
    MY_ENUM_ITEM_1,

    //EITEM My enum item 2
    MY_ENUM_ITEM_2,
};

//STRUCT My struct
struct my_struct {

    //MEMBER struct member 1
    int m_1_;
};

//FUNC my function 1 description.
//     Could be multi-line also.
//INPUT  arg1 - first argument
//RETURN pointer to an allocated my_struct instance.
my_struct* func_1(int arg1);

解析的结果应该是一个代码和注释树。我们希望快速地完成解析，并且不使用第三方库。

2、解决方案

方法一：使用现有工具

一种方法是使用现有的 Python 解析器。这里有一些资源：

• SeeGramWrap：这是一个用 Python 编写的 C 语言解析器。你可以从这里开始。
• Language Parsing：这里列出了其他一些 Python 解析器。
• Python Parsers：这里也列出了一些 Python 解析器。

你还可以下载任何 ANSI C Yacc 语法，并将其重新加工成 PLY 格式，作为跳板使用。

方法二：使用正则表达式

如果你想自己实现一个解析器，可以尝试使用正则表达式。这里有一个快速而简单的方法：

import sys

S_CODE, S_INLINE, S_MULTLINE = range(3)

def parse_comments(filename):
    with open(filename) as f:
        state = S_CODE
        comments = ''
        i = iter(lambda: f.read(1), '')
        while True:
            try:
                c = i.next()
            except StopIteration:
                break
            if state == S_CODE:
                if c == '/':
                    c = i.next()
                    if c == '*':
                        state = S_MULTLINE
                    elif c == '/':
                        state = S_INLINE
            elif state == S_INLINE:
                comments += c
                if c == '\n':
                    state = S_CODE
            elif state == S_MULTLINE:
                if c == '*':
                    c = i.next()
                    if c == '/':
                        comments += '\n'
                        state = S_CODE
                    else:
                        comments += '*%s' % c
                else:
                    comments += c
    return comments


if __name__ == '__main__':
    print(parse_comments(sys.argv[1]))

这个脚本不会处理字符串中的注释，但对于头文件来说应该不是问题。

方法三：使用 shlex 模块

shlex 模块也可以用于解析注释。它是一个更强大的工具，可以处理更复杂的语法。

import shlex

def parse_comments(filename):
    with open(filename) as f:
        lexer = shlex.shlex(f)
        comments = []
        while True:
            token = lexer.get_token()
            if token == '':
                break
            if token[0] == '/':
                comments.append(token)
    return comments


if __name__ == '__main__':
    print(parse_comments(sys.argv[1]))

这个脚本将提取所有注释，包括字符串中的注释。