recogn-parse/README.md

recogn-parse 提供了 识别--解析 的机制，使用者只需要添加识别器 和 解析器，然后就可以对事件进行识别和解析，适合用所有具备 识别--解析 流程的场景中，如：加载并显示各种模型、预览文件等

[教程]: ./doc/教程.md
[API接口文档]: ./doc/api/index.md
[设计与机制]: ./doc/设计与机制.md

[GitHub仓库]: https://github.com/GuoBinyong/recogn-parse
[发行地址]: https://github.com/GuoBinyong/recogn-parse/releases
[issues]: https://github.com/GuoBinyong/recogn-parse/issues

[码云仓库]: https://gitee.com/guobinyong/recogn-parse



[识别解析机制_简图]: ./doc/assets/识别解析机制_简图.png


**目录**

<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->

<!-- code_chunk_output -->

- [1. 背景](#1-背景)
  - [1.1 问题](#11-问题)
  - [1.2 解决方案](#12-解决方案)
- [2. 简介](#2-简介)
- [3. 安装方式](#3-安装方式)
  - [3.1. 方式1：通过 npm 安装](#31-方式1通过-npm-安装)
  - [3.2. 方式3：通过`<script>`标签引入](#32-方式3通过script标签引入)
- [4. 教程](#4-教程)
- [5. 设计与机制](#5-设计与机制)
- [6. API接口文档](#6-api接口文档)

<!-- /code_chunk_output -->



----------

# 1. 背景

## 1.1 问题
假如我们需要开发一个文件查看的 SDK，因为不同的文件有不同的解析规则和查看交互方式，所以我们要为每类甚至每种文件都要写一套解析 和 查看的逻辑。一种简单的思路是：为每种类型的文件写一个对应的查看方法，如 `viewImage()`、`viewText` 等等。但这样做有以下缺点：
- **用户负担大**：用户需要自己判断文件的类型，然后再根据类型调用对应的方法。
- **入口难统一**：对于多个文件的输入口的场景，比如：网络请求、文件拖拽、文件层级树 等等，很难把这些入口合并。因为网络请求入口输入的大多是 url，需要网络请求才能使到具体的文件内容，而文件拖拽入口输入的是文件对象，与网络请求获取到结果的格式也不一样，而文件层级树 是树形结构，与 网络请求 和 文件拖拽的 扁平结构也不一样。
- **维护成本高**：用户需要在每个文件入口处写很多文件类型的判断 `if...else...`，然后调用对应的查看方法。如果将来新增了文件查看类型，就需要在每一个入口处增加对应的逻辑判断。
- **代码复用性低**：有很多后缀名一样，但却是不同类型的资源，比如：`gltf`、`GeoJson`、`3DTiles` 等等 都是 `.json` 后缀名，但却分别表示：3d模型、失量图形、3D瓦片，但在每个资源对应的查看方法  `viewGltf()`、`viewGeoJson()`、`view3DTiles()` 中都会有 从 url 到 json 对象 的解析逻辑，其实这部分完全是可以共用的。
- **不支持一进多出的操作**：如果一个文件有多个查看窗口，比如：对于 `.json` 格式的 `GeoJson` 文件 可以同时展示两个视图，一个是查看 `json` 文件的视图，一个是查看失量图的视图，原来这两个视图是分别通过方法 `viewJson()` 和 `viewGeoJson()` 来查看的，如果想调用一个方法，同时显示这两个视图，就需要重新实现了。

## 1.2 解决方案
而更好的设计是：提供一种识别解析的机制，如下图：

![识别解析机制_简图][]

使用该机制之前，需要先针对不同的输入资源添加对应的识别器 和 解析器。在使用该机制时，先识别器用于将杂乱的输入资源识别成规整的类型，并输出格式化后的参数，然后根据识别出的类型去调用对应的解析器，解析器根据识别器提供的格式化参数对资源进行解析，在本例中解析负责的就是资源的查看操作。

其实 `识别——解析` 机制是一种比较通用的机制，它不但可以用于 文件查看，还可以用于其它很多场景，比如：
- 3D模型文件解析。
- 右键上下文菜单：根据不同的上下文，展示不同的右键菜单。

总之，适用于一切需要根据不同的条件执行不同的策略的场景。

而 `recogn-parse` 就是这种机制的一个实现，巧妙的设计使得 `recogn-parse` 不但可以解决上述问题，而且更具通用性、扩展性、复用性、易用性。


# 2. 简介
`recogn-parse` 是一个 `识别—解析` 工具，用户可以添加识别器 和 解析器，对于输入资源，它会先用用添加的识别器进行识别，识别出类型之后，再调用用户添加的对应类型的解析器进行解析，这是它的基本机制，同时它具备一些更具通用性、扩展性、复用性 和 易用性 的机制，比如：支持前置识别器、后置识别器、前置解析器、后置解析器、一进多出、异步识别、异步解析 等等。合用所有具备 识别--解析 流程的场景中，如：加载并显示各种模型、预览文件、右键菜单等。

**具有以下特性：**  
- **识别—解析机制**
- **支持异步识别、异步解析**
- **支持串行识别器**：用户可以将几个独立的识别逻辑组成一个整体作为一个识别器，当执行该识别器时会串行执行被组合的几个识别逻辑。这可以让用户更细粒度的拆分、复用识别逻辑。
- **支持串行解析器**：用户可以将几个独立的解析逻辑组成一个整体作为一个解析器，当执行该解析器时会串行执行被组合的几个解析逻辑。这可以让用户更细粒度的拆分、复用解析逻辑。
- **支持前置和后置识别器**：用户可以把所有识别器共同的前置和后置逻辑放在前置和后置识别器中，这样可以提高复用性 和 执行效率。
- **支持前置和后置解析器**：用户可以把所有解析器共同的前置和后置逻辑放在前置和后置解析器中，这样可以提高复用性 和 执行效率。
- **支持一进多出**：支持对一次输入识别成多个类型，然后触发多个解析器。


**详情请看：**  
- 主页：<https://github.com/GuoBinyong/recogn-parse>
- [GitHub仓库][]
- [码云仓库][]
- [教程][]
- [设计与机制][]
- [API接口文档][]


**如果您在使用的过程中遇到了问题，或者有好的建议和想法，您都可以通过以下方式联系我，期待与您的交流：**
- 给该仓库提交 [issues][]
- 给我 Pull requests
- 邮箱：<guobinyong@qq.com>
- 微信：keyanzhe





# 3. 安装方式
目前，安装方式有以下几种：


## 3.1. 方式1：通过 npm 安装
通过 npm （或 yarn、pnpm 等包管理器）安装
```shell
npm install recogn-parse
```



## 3.2. 方式3：通过`<script>`标签引入
您可直接从项目的 [发行地址][] 中下载以 `.iife.js` 作为缀的文件，然后使用如下代码引用 和 使用 recogn-parse：


1. 引用 recogn-parse
   ```html
   <script src="path/to/package/recogn-parse.iife.js"></script>
   ```
   
2. 使用全局的 `RecognParse`
   ```html
   <script>
   // 使用全局的 RecognParse
   </script>
   ```

# 4. 教程
详情跳转至[教程][]

# 5. 设计与机制
详情跳转至[设计与机制][]

# 6. API接口文档
详情跳转至[API接口文档][]