Rust Erlang词法分析库erl_tokenize的使用指南

介绍

erl_tokenize是一个用Rust编写的Erlang源代码词法分析库，它能够高效地将Erlang源代码分解为一系列标记(tokens)，为后续的语法分析和编译提供基础。

该库的主要特点包括：

• 完整的Erlang词法支持
• 高性能的解析能力
• 准确的源代码位置跟踪
• 良好的错误处理机制

安装

在Cargo.toml中添加依赖：

[dependencies]
erl_tokenize = "0.3"

基本使用方法

1. 简单的词法分析

use erl_tokenize::{Lexer, Token};

fn main() {
    let src = r#"io:format("Hello, ~s!~n", ["World"])"#;
    let mut lexer = Lexer::new(src);
    
    while let Some(token) = lexer.next().unwrap() {
        println!("{:?}", token);
    }
}

2. 处理模块定义

use erl_tokenize::{Lexer, Token};

fn tokenize_module(module_src: &str) {
    let mut lexer = Lexer::new(module_src);
    while let Some(token) = lexer.next().unwrap() {
        match token.value() {
            erl_tokenize::values::Atom(atom) if atom == "module" => {
                println!("Found module declaration");
            }
            _ => {}
        }
    }
}

fn main() {
    let src = r#"
        -module(hello).
        -export([greet/0]).
        
        greet() -> io:format("Hello world!~n").
    "#;
    tokenize_module(src);
}

3. 获取标记位置信息

use erl_tokenize::{Lexer, Position};

fn print_token_positions(src: &str) {
    let mut lexer = Lexer::new(src);
    while let Some(token) = lexer.next().unwrap() {
        let start = token.start_position();
        let end = token.end_position();
        println!(
            "Token '{}' at {}:{} to {}:{}",
            token.text(),
            start.line(),
            start.column(),
            end.line(),
            end.column()
        );
    }
}

fn main() {
    let src = r#"
        add(X, Y) ->
            X + Y.
    "#;
    print_token_positions(src);
}

高级用法

1. 自定义错误处理

use erl_tokenize::{Lexer, Error};

fn tokenize_with_error_handling(src: &str) {
    let mut lexer = Lexer:: new(src);
    loop {
        match lexer.next() {
            Ok(Some(token)) => println!("Token: {:?}", token),
            Ok(None) => break, // 输入结束
            Err(e) => {
                eprintln!("Lexical error at {}:{} - {}",
                    e.position().line(),
                    e.position().column(),
                    e.kind()
                );
                // 尝试从错误中恢复
                lexer.recover();
            }
        }
    }
}

fn main() {
    let src = r#"
        test() ->
            1 + $%  % 非法字符
    "#;
    tokenize_with_error_handling(src);
}

2. 过滤特定标记

use erl_tokenize::{Lexer, Token};

fn find_function_calls(src: &str) {
    let mut lexer = Lexer::new(src);
    let mut tokens: Vec<Token> = lexer.collect::<Result<_, _>>().unwrap();
    
    // 查找函数调用模式: Atom:Atom( 或 Atom(
    for window in tokens.windows(3) {
        if let (Some(module), Some(colon), Some(func)) = (&window[0], &window[1], &window[2]) {
            if colon.text() == ":" {
                if let (Some(module_name), Some(func_name)) = 
                    (module.as_atom(), func.as_atom()) 
                {
                    println!("Found remote call: {}:{}", module_name, func_name);
                }
            }
        }
        
        if let Some(func) = &window[0] {
            if let Some(func_name) = func.as_atom() {
                if let Some(next) = &window[1] {
                    if next.text() == "(" {
                        println!("Found local call: {}", func_name);
                    }
                }
            }
        }
    }
}

fn main() {
    let src = r#"
        main() ->
            io:format("Hello"),
            local_func().
    "#;
    find_function_calls(src);
}

实际应用示例

统计Erlang模块中的函数定义

use erl_tokenize::{Lexer, Token};

fn count_functions(src: &str) -> usize {
    let mut lexer = Lexer::new(src);
    let mut count = 0;
    let mut tokens: Vec<Token> = lexer.collect::<Result<_, _>>().unwrap();
    
    // 查找模式: Atom( -> ... ) ->
    for window in tokens.windows(4) {
        if let (Some(name), Some(lparen), _, Some(rarrow)) = 
            (&window[0], &window[1], &window[2], &window[3]) 
        {
            if name.as_atom().is_some() && 
               lparen.text() == "(" && 
               rarrow.text() == "->" 
            {
                count += 1;
            }
        }
    }
    
    count
}

fn main() {
    let src = r#"
        -module(sample).
        
        func1() -> ok.
        func2(X) -> {ok, X}.
        func3(X, Y) when is_integer(X), is_integer(Y) -> X + Y.
    "#;
    
    println!("Found {} functions", count_functions(src));
}

性能提示

1. 对于大型文件，考虑使用Lexer::with_offset来处理文件片段
2. 重用Lexer实例可以减少分配
3. 如果不需要位置信息，可以禁用位置跟踪以提高性能

use erl_tokenize::{Lexer, LexerBuilder};

fn fast_tokenize(src: &str) {
    let lexer = LexerBuilder::new()
        .track_positions(false)  // 禁用位置跟踪
        .build(src);
    
    // 处理标记...
}

完整示例

下面是一个整合了多个功能的完整示例，展示如何使用erl_tokenize进行Erlang代码分析：

use erl_tokenize::{Lexer, Token, Position, Error, LexerBuilder};
use erl_tokenize::values::Atom;

fn analyze_erlang_code(src: &str) {
    println!("===== Erlang代码分析报告 =====");
    
    // 配置Lexer
    let lexer = LexerBuilder::new()
        .track_positions(true)
        .build(src);
    
    // 1. 显示所有token及其位置
    println!("\n--- 所有Token及其位置 ---");
    let tokens: Vec<Token> = lexer.collect::<Result<_, _>>().unwrap();
    for token in &tokens {
        let pos = token.start_position();
        println!("[{},{}] {}: {:?}", 
            pos.line(), 
            pos.column(),
            token.text(),
            token.value()
        );
    }
    
    // 2. 统计函数数量
    println!("\n--- 函数统计 ---");
    let function_count = tokens.windows(4)
        .filter(|w| {
            matches!(w, 
                [name, lparen, _, rarrow] 
                if name.as_atom().is_some() 
                && lparen.text() == "(" 
                && rarrow.text() == "->"
            )
        })
        .count();
    println!("找到 {} 个函数定义", function_count);
    
    // 3. 查找远程调用
    println!("\n--- 远程函数调用 ---");
    for window in tokens.windows(3) {
        if let [module, colon, func] = window {
            if colon.text() == ":" {
                if let (Some(module_name), Some(func_name)) = 
                    (module.as_atom(), func.as_atom()) 
                {
                    println!("远程调用: {}:{}", module_name, func_name);
                }
            }
        }
    }
}

fn main() {
    let src = r#"
        -module(sample).
        -export([start/0, add/2]).
        
        start() ->
            io:format("Starting...~n"),
            Result = add(1, 2),
            io:format("Result: ~p~n", [Result]).
        
        add(X, Y) when is_integer(X), is_integer(Y) ->
            X + Y;
        add(_, _) ->
            {error, badarg}.
    "#;
    
    analyze_erlang_code(src);
}

这个完整示例展示了：

1. 使用LexerBuilder配置词法分析器
2. 遍历并打印所有token及其位置信息
3. 统计Erlang模块中的函数定义数量
4. 查找所有的远程函数调用

erl_tokenize库为Rust开发者提供了强大的Erlang源代码处理能力，可以用于构建代码分析工具、语法高亮、格式化工具等应用。