Crate oak_j 

馃洜锔?J Parser Developer Guide

This guide is designed to help you quickly get started with developing and integrating oak-J.

馃殾 Quick Start

Basic Parsing Example

The following is a standard workflow for parsing an J package specification:

use oak_j::{JParser, JLanguage};
use oak_core::{SourceText, Parser, parser::ParseSession};

fn main() {
    // 1. 准备源代码
    let code = "a =: 1 + 2";
    let source = SourceText::new(code);

    // 2. 初始化解析器
    let config = JLanguage::default();
    let parser = JParser::new(&config);

    // 3. 执行解析
    let mut session = ParseSession::new(1024);
    let result = parser.parse(&source, &[], &mut session);

    // 4. 处理结果
    if result.result.is_ok() {
        println!("解析成功！");
    }
}

🔍 核心 API 用法

1. 语法树遍历

解析成功后，你可以使用内置的访问者模式或手动遍历 Green/Red Tree。

2. 增量解析

当源代码发生微小变化时，无需重新解析整个文档：

use oak_j::{JParser, JLanguage};
use oak_core::{SourceText, Parser, parser::ParseSession};

// 假设已经有了解析器实例 parser
// 假设你已经有了旧的解析结果 result 和新的源代码 new_source
let mut session = ParseSession::new(1024);
// 在实际场景中，session 会保留旧的树用于增量对比
let new_result = parser.parse(&new_source, &[], &mut session);

3. 诊断信息 (Diagnostics)

oak-j 提供了丰富的错误上下文：

for diag in result.diagnostics {
    println!("{:?}", diag);
}

馃彈锔?Architecture Overview

• Lexer: Tokenizes J source text into a stream of tokens, handling keywords (case-insensitive), operators, and numeric literals.
• Parser: Syntax analyzer based on the Pratt parsing algorithm to handle J’s structural declarations and expression precedence.
• AST: A strongly-typed syntax abstraction layer designed for building high-performance J analysis tools and IDEs.

馃敆 Advanced Resources

• Full Examples: Check the examples/ folder in the project root.
• API Documentation: Run cargo doc --open for detailed type definitions.
• Test Cases: See tests/ for handling of various J edge cases and language versions. J support for the Oak language framework.

Re-exports

pub use language::JLanguage;

pub use lexer::JLexer;

pub use lexer::JTokenType;

pub use parser::JElementType;

pub use parser::JParser;

pub use crate::lsp::highlighter::JHighlighter;

pub use crate::lsp::JLanguageService;

pub use crate::lsp::formatter::JFormatter;

pub use crate::mcp::serve_j_mcp;

Modules

ast

AST module.

builder

Builder module.

language

Type definitions module. Language configuration module.

lexer

Lexer module.

lsp

LSP module.

mcp

MCP module.

parser

Parser module.

Traits

ElementType

Element type definitions for nodes in the parsed tree.

Language

Language definition trait that coordinates all language-related types and behaviors.

TokenType

Token type definitions for tokens in the parsing system.