From 44e31ef235402a8e3bbe6fe387963ddcd195b366 Mon Sep 17 00:00:00 2001 From: s97712 Date: Sun, 24 Aug 2025 08:55:52 +0800 Subject: [PATCH] Add README files to NuGet packages and reorganize documentation - Add PackageReadmeFile property to Directory.Build.props - Include README.md files in both TypeScriptParser and TypeScriptParser.Native packages - Restructure main README with improved quick start guide and clearer project organization - Move detailed build instructions under development section --- Directory.Build.props | 1 + README.md | 74 +++------ .../TypeScriptParser.Native.csproj | 5 + TypeScriptParser/README.md | 155 ++++++++++++++++++ TypeScriptParser/TypeScriptParser.csproj | 5 + 5 files changed, 192 insertions(+), 48 deletions(-) create mode 100644 TypeScriptParser/README.md diff --git a/Directory.Build.props b/Directory.Build.props index 16d4d66..2acf585 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -14,6 +14,7 @@ https://github.com/your-org/csharp-tree-sitter https://github.com/your-org/csharp-tree-sitter git + README.md 基于Tree-sitter的TypeScript解析器 - 支持跨平台Native库自动管理 diff --git a/README.md b/README.md index 9f70615..9e0a9dc 100644 --- a/README.md +++ b/README.md @@ -2,30 +2,46 @@ 基于Tree-sitter的TypeScript解析器 - .NET绑定 -## 构建步骤 +## 快速开始 ```bash -# 1. 复制运行时文件 +# 1. 构建native库 (cd tree-sitter/ && make clean && make) +# 2. 复制运行时文件 RID=$(dotnet --info | grep "RID:" | awk '{print $2}') mkdir -p TypeScriptParser.Native/runtimes/$RID/native cp -r tree-sitter/dist/* TypeScriptParser.Native/runtimes/$RID/native/ -# 2. 恢复依赖 +# 3. 构建和测试 dotnet restore - -# 3. 构建项目 dotnet build -c Release +dotnet test --configuration Release -# 4. 运行测试 -dotnet test --configuration Release --no-build +# 4. 打包NuGet包 +dotnet pack -c Release -o ./artifacts +``` + +## 项目结构 -# 5. 打包NuGet包 -dotnet pack -c Release --no-build -o ./artifacts +- [`TypeScriptParser/`](TypeScriptParser/) - 主要的.NET绑定库 +- [`TypeScriptParser.Native/`](TypeScriptParser.Native/) - 跨平台Native库包 +- [`TypeScriptParser.Tests/`](TypeScriptParser.Tests/) - 单元测试 + +## 开发指南 + +### Debug模式构建 +```bash +dotnet build -c Debug +dotnet test --configuration Debug ``` -## 自动化构建 +### 支持平台 +- Linux x64 +- macOS ARM64 +- Windows x64 + +## CI/CD流程 ### 开发流程 1. 创建功能分支 @@ -36,41 +52,3 @@ dotnet pack -c Release --no-build -o ./artifacts 1. 创建版本标签：`git tag v1.2.0 && git push origin v1.2.0` 2. 自动构建测试发布到NuGet.org 3. 版本号格式：`1.2.0.{构建号}` - -## 手动构建 - -```bash -# 1. 构建native库 -(cd tree-sitter/ && make clean && make) - -# 2. 复制运行时文件 -RID=$(dotnet --info | grep "RID:" | awk '{print $2}') -mkdir -p TypeScriptParser.Native/runtimes/$RID/native -cp -r tree-sitter/dist/* TypeScriptParser.Native/runtimes/$RID/native/ - -# 3. .NET构建 -dotnet restore -dotnet build -c Release -dotnet test --configuration Release --no-build -dotnet pack -c Release --no-build -o ./artifacts -``` - -## 开发构建 - -```bash -# Debug模式构建和测试 -dotnet build -c Debug -dotnet test --configuration Debug --no-build -``` - -## 项目结构 - -- `TypeScriptParser/` - 主要的.NET绑定库 -- `TypeScriptParser.Native/` - 跨平台Native库包 -- `TypeScriptParser.Tests/` - 单元测试 - -## 支持平台 - -- Linux x64 -- macOS ARM64 -- Windows x64 diff --git a/TypeScriptParser.Native/TypeScriptParser.Native.csproj b/TypeScriptParser.Native/TypeScriptParser.Native.csproj index 2c4f9c6..a266213 100644 --- a/TypeScriptParser.Native/TypeScriptParser.Native.csproj +++ b/TypeScriptParser.Native/TypeScriptParser.Native.csproj @@ -10,6 +10,11 @@ $(NoWarn);NU5128 + + + + + diff --git a/TypeScriptParser/README.md b/TypeScriptParser/README.md new file mode 100644 index 0000000..123229b --- /dev/null +++ b/TypeScriptParser/README.md @@ -0,0 +1,155 @@ +# TypeScriptParser + +基于Tree-sitter的TypeScript解析器.NET绑定库，提供高性能的TypeScript代码解析功能。 + +## 安装 + +```bash +dotnet add package TypeScriptParser +``` + +## 快速开始 + +```csharp +using System; +using TreeSitter.TypeScript; +using GitHub.TreeSitter; + +// 创建解析器实例 +using var parser = new TypeScriptParser(); + +// 解析TypeScript代码 +string code = @" +function greet(name: string): string { + return `Hello, ${name}!`; +} +"; + +using var tree = parser.ParseString(code); +var rootNode = tree.root_node(); + +// 遍历语法树 +Console.WriteLine($"语法树类型: {rootNode.type()}"); +Console.WriteLine($"子节点数量: {rootNode.child_count()}"); + +// 获取源码文本 +Console.WriteLine($"源码内容: {rootNode.text(code)}"); +``` + +## 主要功能 + +- ✅ 完整的TypeScript语法支持 +- ✅ 高性能的增量解析 +- ✅ 跨平台支持 (Windows, Linux, macOS) +- ✅ 详细的语法错误信息 +- ✅ 语法树遍历和查询 + +## API 参考 + +### TypeScriptParser 类 + +位于 `TreeSitter.TypeScript` 命名空间。 + +#### 构造函数 +```csharp +var parser = new TypeScriptParser(); +``` + +#### 主要方法 + +**ParseString(string sourceCode)** +- 解析TypeScript源代码字符串 +- 返回: `TSTree` - 解析后的语法树 + +```csharp +var tree = parser.ParseString("const x = 42;"); +``` + +**CreateCursor(TSTree tree)** +- 创建语法树游标用于高效遍历 +- 返回: `TSCursor` - 语法树游标对象 + +```csharp +using var cursor = parser.CreateCursor(tree); +``` + +#### 属性 + +**Language** +- 获取TypeScript语言对象 +- 类型: `TSLanguage` + +**IsAvailable** +- 检查解析器是否可用 +- 类型: `bool` + +### TSTree 类 (来自 GitHub.TreeSitter) + +**主要方法:** +- `root_node()` - 获取根节点 +- `copy()` - 复制语法树 +- `edit(TSInputEdit edit)` - 编辑语法树 + +### TSNode 结构 (来自 GitHub.TreeSitter) + +**主要方法:** +- `type()` - 获取节点类型名称 +- `child_count()` - 获取子节点数量 +- `child(uint index)` - 获取指定索引的子节点 +- `start_point()` / `end_point()` - 获取节点位置 +- `text(string sourceCode)` - 获取节点对应的源码文本 + +## 语法树遍历示例 + +```csharp +using var parser = new TypeScriptParser(); +var tree = parser.ParseString(@" +class Calculator { + add(a: number, b: number): number { + return a + b; + } +} +"); + +var root = tree.root_node(); + +// 递归遍历所有节点 +void TraverseNode(TSNode node, string source, int depth = 0) +{ + var indent = new string(' ', depth * 2); + Console.WriteLine($"{indent}{node.type()}: {node.text(source)}"); + + for (uint i = 0; i < node.child_count(); i++) + { + TraverseNode(node.child(i), source, depth + 1); + } +} + +TraverseNode(root, code); +``` + +## 错误处理 + +```csharp +using var parser = new TypeScriptParser(); +var tree = parser.ParseString("const x = ;"); // 语法错误 + +var root = tree.root_node(); +if (root.has_error()) +{ + Console.WriteLine("语法树包含错误"); +} +``` + +## 系统要求 + +- .NET 9.0 或更高版本 +- 支持的平台：Windows (x64), Linux (x64), macOS (ARM64/x64) + +## 相关包 + +- `TypeScriptParser.Native` - 包含跨平台原生库的运行时包 + +## 许可证 + +本项目基于MIT许可证开源。 \ No newline at end of file diff --git a/TypeScriptParser/TypeScriptParser.csproj b/TypeScriptParser/TypeScriptParser.csproj index 35629bf..9a8a83f 100644 --- a/TypeScriptParser/TypeScriptParser.csproj +++ b/TypeScriptParser/TypeScriptParser.csproj @@ -11,6 +11,11 @@ $(NoWarn);CS1591 + + + + +