init

Author: Cactusinhand

README.md

@@ -0,0 +1,191 @@
+# 从零开始的 JSON 库教程 (Go语言版)
+
+* 基于 Milo Yip 的 C语言JSON教程改编
+* 2025年
+
+这是一个使用Go语言实现的JSON库教程，基于[《从零开始的 JSON 库教程》](https://github.com/miloyip/json-tutorial)改编。本教程保持原教程的章节结构和渐进式开发方法，但根据Go语言的特性进行了适当调整。
+
+## 对象与目标
+
+教程对象：学习过基本Go语言编程的同学。
+
+通过这个教程，同学可以了解如何从零开始写一个Go语言版本的JSON库，其特性如下：
+
+* 符合标准的JSON解析器和生成器
+* 使用Go语言的递归下降解析器（recursive descent parser）
+* 跨平台（如Windows/Linux/macOS）
+* 支持UTF-8 JSON文本
+* 使用Go语言内置类型存储JSON数据
+* 解析器和生成器的代码简洁高效
+* 提供丰富的访问和修改API
+
+除了围绕JSON作为例子，希望能在教程中讲述一些课题：
+
+* 测试驱动开发（test driven development, TDD）
+* Go语言编程风格
+* 数据结构
+* API设计
+* 错误处理
+* Unicode
+* 浮点数
+* Go模块、单元测试等工具和实践
+
+## 项目结构
+
+教程按照章节组织，每个章节对应一个子目录：
+
+1. tutorial01: 基础结构、解析null/true/false
+2. tutorial02: 解析数字
+3. tutorial03: 解析字符串
+4. tutorial04: Unicode支持
+5. tutorial05: 解析数组
+6. tutorial06: 解析对象
+7. tutorial07: 生成器
+8. tutorial08: 访问与其他功能
+9. tutorial09: 增强的错误处理
+
+## 当前进度
+
+当前已经完成了所有教程的实现，包括：
+
+* null、true、false等字面值
+* 数字（包括整数、浮点数、科学计数法）
+* 字符串（支持转义序列和Unicode）
+* 数组（支持嵌套）
+* 对象（支持嵌套）
+* JSON生成器 - 将JSON值转换为文本
+* 高级功能:
+  * 对象键值查询
+  * JSON值比较
+  * 深度复制、移动和交换
+  * 动态数组和对象操作
+  * 高效内存管理
+* 增强错误处理:
+  * 详细的错误信息与位置
+  * 错误恢复能力
+  * 自定义解析选项
+  * 支持JSON注释
+
+## 安装与使用
+
+要使用这个库，你需要Go语言环境（推荐Go 1.16或更高版本）。克隆该仓库后，可以直接导入使用：
+
+```go
+import "github.com/Cactusinhand/go-json-tutorial/tutorial08"
+// 或使用增强错误处理版本
+import "github.com/Cactusinhand/go-json-tutorial/tutorial09"
+
+func main() {
+    // 基本解析JSON
+    v := leptjson.Value{}
+    if err := leptjson.Parse(&v, `{"name": "John", "age": 30}`); err != leptjson.PARSE_OK {
+        // 处理错误
+    }
+    
+    // 使用增强错误处理
+    options := leptjson.ParseOptions{
+        RecoverFromErrors: true,  // 启用错误恢复
+        AllowComments: true,      // 允许JSON注释
+        MaxDepth: 1000            // 设置最大嵌套深度
+    }
+    if err := leptjson.ParseWithOptions(&v, `{"name": "John", /* 这是注释 */ "age": 30}`, options); err != leptjson.PARSE_OK {
+        // 错误处理但仍能继续解析
+        fmt.Println("解析遇到错误但已恢复:", err)
+    }
+    
+    // 访问解析后的数据
+    name := leptjson.GetString(leptjson.GetObjectValueByKey(&v, "name"))
+    age := leptjson.GetNumber(leptjson.GetObjectValueByKey(&v, "age"))
+    
+    // 使用FindObjectKey快速访问
+    if value, found := leptjson.FindObjectKey(&v, "name"); found {
+        name = leptjson.GetString(value)
+    }
+    
+    // 修改JSON数据
+    newPerson := &leptjson.Value{}
+    leptjson.SetObject(newPerson)
+    nameValue := leptjson.SetObjectValue(newPerson, "name")
+    leptjson.SetString(nameValue, "Alice")
+    
+    // 动态数组操作
+    arr := &leptjson.Value{}
+    leptjson.SetArray(arr, 0)
+    elem := leptjson.PushBackArrayElement(arr)
+    leptjson.SetNumber(elem, 42)
+    
+    // 生成JSON字符串
+    jsonStr, _ := leptjson.Stringify(newPerson)
+}
+```
+
+## 关键API说明
+
+### 解析和生成
+* `Parse(&v, json)`: 解析JSON文本到Value结构
+* `ParseWithOptions(&v, json, options)`: 使用自定义选项解析JSON文本
+* `Stringify(&v)`: 将Value结构转换为JSON文本
+
+### 类型和值访问
+* `GetType(&v)`: 获取JSON值的类型
+* `GetBoolean(&v)`, `SetBoolean(&v, b)`: 获取/设置布尔值
+* `GetNumber(&v)`, `SetNumber(&v, n)`: 获取/设置数字值
+* `GetString(&v)`, `SetString(&v, s)`: 获取/设置字符串值
+
+### 数组操作
+* `GetArraySize(&v)`: 获取数组大小
+* `GetArrayElement(&v, index)`: 获取数组元素
+* `SetArray(&v, capacity)`: 设置为数组类型
+* `PushBackArrayElement(&v)`: 添加数组元素
+* `PopBackArrayElement(&v)`: 移除最后一个元素
+* `InsertArrayElement(&v, index)`: 插入元素
+* `EraseArrayElement(&v, index, count)`: 删除元素
+* `ClearArray(&v)`: 清空数组
+
+### 对象操作
+* `GetObjectSize(&v)`: 获取对象大小
+* `GetObjectKey(&v, index)`: 获取对象键
+* `GetObjectValue(&v, index)`: 获取对象值
+* `GetObjectValueByKey(&v, key)`: 根据键获取对象值
+* `FindObjectKey(&v, key)`: 查找键并返回值
+* `SetObject(&v)`: 设置为对象类型
+* `SetObjectValue(&v, key)`: 设置对象键值
+* `RemoveObjectValue(&v, index)`: 移除成员
+* `ClearObject(&v)`: 清空对象
+
+### 内存和资源管理
+* `Copy(dst, src)`: 深度复制JSON值
+* `Move(dst, src)`: 移动JSON值
+* `Swap(lhs, rhs)`: 交换两个JSON值
+* `Free(&v)`: 释放资源
+
+### 比较和其他
+* `Equal(lhs, rhs)`: 比较两个JSON值是否相等
+
+### 增强错误处理
+* `ParseOptions`: 定义解析选项的结构体，包含错误恢复、注释支持和最大深度等选项
+* `EnhancedError`: 提供详细的错误信息，包括行号、列号、上下文和错误位置指示
+* `GetErrorMessage(code)`: 获取特定错误码的错误描述信息
+
+## 测试
+
+每个章节都包含完整的测试用例，测试覆盖了各种正常和边缘情况。运行测试：
+
+```bash
+go test ./tutorial08
+```
+
+## 注意事项
+
+* 处理Unicode时，需要特别注意UTF-16代理对的处理
+* 数字解析需要考虑各种边缘情况，如前导零、溢出等
+* 字符串解析需要正确处理所有转义序列
+* 数组和对象解析需要处理嵌套和边界情况
+* 在使用动态数组和对象函数时，注意内存管理和资源释放
+
+## 参考资料
+
+* [JSON官方规范](https://www.json.org/)
+* [原始C语言教程](https://github.com/miloyip/json-tutorial)
+* [RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc7159)
+* [RFC 3629: UTF-8, a transformation format of ISO 10646](https://tools.ietf.org/html/rfc3629)

go.mod

@@ -0,0 +1,3 @@
+module github.com/Cactusinhand/go-json-tutorial
+
+go 1.16

plan.md

@@ -0,0 +1,55 @@
+对于 JSON 库的未来计划和可能的扩展特性，我想提出以下几个方向：
+
+## 未来计划与潜在新特性
+
+1. **性能优化**：
+   - 使用更高效的内存分配策略，减少垃圾回收压力
+   - 实现流式解析，处理超大 JSON 文件而不必一次性载入内存
+   - 采用并发解析技术处理大型 JSON 数据
+
+2. **功能扩展**：
+   - **JSON Path 支持**：实现类似 XPath 的查询语言，方便从复杂 JSON 结构中提取数据
+   - **JSON Schema 验证**：支持根据 JSON Schema 验证 JSON 数据的结构和内容
+   - **JSON Patch 操作**：实现 RFC 6902 的 JSON Patch 标准，支持增量修改
+   - **JSON Merge Patch**：实现 RFC 7396 的 JSON Merge Patch 标准，提供更简单的更新方式
+
+3. **错误处理增强**：
+   - 提供更详细的错误信息，包括行号、列号和上下文
+   - 支持错误恢复，在某些错误情况下尝试继续解析
+
+4. **工具与集成**：
+   - 提供命令行工具进行 JSON 格式化、验证和转换
+   - 提供对其他数据格式的转换支持，如 YAML、TOML、XML 等
+   - 与数据库序列化/反序列化集成
+   - 支持 struct tag 映射，自动转换 Go 结构体与 JSON
+
+5. **特殊需求支持**：
+   - 支持 JSON5 和 JSON Lines 等 JSON 扩展格式
+   - 支持注释处理
+   - 支持更大范围的数值类型，如大整数
+   - 支持自定义格式化输出样式
+
+6. **高级数据结构**：
+   - 实现 JSON 指针（JSON Pointer）
+   - 支持循环引用检测和处理
+   - 实现 JSON-LD (JSON for Linked Data) 支持
+
+7. **文档与示例**：
+   - 编写更详细的使用文档和 API 参考
+   - 提供更多实际应用场景的示例代码
+   - 性能基准测试和与其他库的对比
+
+8. **跨平台与兼容性**：
+   - 实现 WebAssembly 支持，使库可在浏览器环境中使用
+   - 提供对较老 Go 版本的兼容性支持
+
+9. **安全性增强**：
+   - 添加防止 DoS 攻击的机制（如递归深度限制、输入大小限制）
+   - 提供安全的序列化/反序列化方法，防止数据注入攻击
+
+10. **教学扩展**：
+    - 添加详细的算法解释和设计思想文档
+    - 开发互动式教程，帮助理解 JSON 处理原理
+    - 拓展到其他格式的解析器实现，如 YAML、XML 等
+
+这些计划可以根据实际需求和用户反馈进行优先级排序。最重要的是保持库的简洁性和易用性，在添加新功能的同时不影响核心功能的性能和稳定性。未来的发展可以考虑将核心库保持简单，然后通过扩展模块提供高级功能。

prompt

@@ -0,0 +1,15 @@
+
+请以第一章和第二章第三章为最佳实践，请完成剩余的章节。
+一切按照第一第二第三章节的最佳实践进行，同时与原C项目的章节内容保持一一对应，各章节之间保持连贯，README文档也要保持如此，接口测试，单元测试，基准测试都不能少，
+只需要按照每个功能点，依据最佳测试实践原则，测试驱动原则，一一进行充分测试即可。
+
+
+我想与一位精通Go和C语言的JSON解析专家交谈，他是高效率的并发编程大师和接口设计师，深入理解内存管理和标准库。
+我正在开发一个JSON解析器的教学项目，同时包含C和Go两种实现，需要遵循测试驱动开发的最佳实践。
+希望这位专家能帮我设计清晰的API接口，实现高性能的JSON解析和生成功能，并编写全面的单元测试、基准测试和文档。
+请分享如何在保持两种语言实现一致性的同时，充分发挥各自语言特性的经验
+
+
+现在为了让我们的代码更加健壮，需要适当增加更多测试用例，请参照 tutorial06 中的实践，
+分别给tutorial01, tutorial02, tutorial03, tutorial04, tutorial05  增加更多 edge case, complex case，
+当然这些并不是必须的，你可以根据各个章节的实际内容进行分析，该需要补充测试用例的就补充，没必要补充的就不补充。