MYDICTIONARY是一个golang库。
该库提供为开发者提供一组API，以帮助他们构建基于Excel表格与在线内容的词典应用程序。
词条 包括词汇、释义、笔记和其他必要信息。
从这里获取更多信息。
MYDICTIONARY能够从网站获取页面、提取信息并构建词条。这个过程称为在线服务。这使我们能够获得生词本或离线词典中没有的词条。
MYDICTIONARY目前提供下列在线服务：
- 必应词典
- 金山词霸-柯林斯词典
- 韦氏词典
声明:
- 上述网站中一切信息的版权属于相应的公司。
- 上述信息禁止用于一切形式的商业用途。
- 滥用上述信息产生的一切后果与本人无关。
从这里获取更多信息。
词典应用程序需要利用文件存储词汇和释义。据我所知，这些文件一般都是特别设计的，用户不能自行查看或编辑。这曾经让我十分困惑。因此，在设计MYDICTIONARY的时候，我选择将数据存储在“.xlsx”文件中，这意味着用户能够方便地利用Microsoft Excel或WPS表格进行读写操作。
所以符合下列条件“.xlsx”文件都能够作为 生词本文件 或 离线词典文件 。
- 至少包含一个工作表。
- 第一个工作表的首行包含下列单元格：“SN”（序号）、“Word”（词汇）、“Definition”（释义）、“Note”（笔记）、“QC”（查询次数）和“QT”（上次查询时间）。
例如：
- 生词本文件
bing-dictionary.xlsx
- 离线词典文件
animal.xlsx
生词本 和 离线词典 都是词条的集合。它们分别是生词本文件和离线词典文件的内存映像。生词本文件或离线词典文件中的一行会被转化为生词本或离线词典中的一个词条。
生词本与离线词典具有相似的结构，它们的不同之处在于：
-
对于离线词典，在查询时，MYDICTIONARY能够更新现存词条的
QC和QT（为QC加1，将QT设定为当前时间）。 -
生词本的主要功能是记录满足下列全部条件的词条
- 从在线服务中获得的
- 不存在与任何生词本和离线词典中的
因此，对于生词本，在查询时，MYDICTIONARY不仅能更新现存词条的
QC和QT，还能新增的词条。
上述更新和/或新增操作称为记录。
MYDICTIONARY需要下列路径（目录）：
- 工作路径 ：存放配置文件。
- 文档路径 ：存放所有生词本文件和离线词典文件。
- 缓存路径 ：存放所有在线服务的缓存文件。
配置文件 mydictionary.setting.json必须被放置在工作路径。
示例：
{
"collection": [
{
"name": "bing-dictionary",
"fileName": "bing-dictionary.xlsx",
"readable": true,
"writable": true,
"onlineSource": "Bing Dictionary"
},
{
"name": "iciba-collins",
"fileName": "iciba-collins.xlsx",
"readable": true,
"writable": true,
"onlineSource": "iCIBA Collins"
},
{
"name": "merriam-webster",
"fileName": "merriam-webster.xlsx",
"readable": true,
"writable": true,
"onlineSource": "Merriam Webster"
}
],
"dictionary": [
{
"name": "animal",
"fileName": "animal.xlsx",
"readable": true,
"writable": true
},
{
"name": "fruit",
"fileName": "fruit.xlsx",
"readable": true,
"writable": true
}
],
"online": {
"mode": 3,
"service": {
"Bing Dictionary": true,
"iCIBA Collins": true,
"Merriam Webster": true
},
"cache": {
"enable": true,
"shelfLifeDay": 7
},
"debug": false
}
}配置 中有3个结构体："collection"、"dictionary"和"online" 。
"collection"是一个数组，它的每一项具有下列成员：
- 字符串
"name"：生词本的名称。 - 字符串
"fileName"：生词本文件的名称，位于文档路径下。 - 布尔型
"readable"：如果设为false，那么生词本将被MYDICTIONARY忽略。通过这项设置，我们可以在不移除整个数组项的情况下，停用生词本。 - 布尔型
"writable"：如果设为true，那么允许MYDICTIONARY在查询的时候将-词条-记录-到生词本。 - 字符串
"onlineSource"：每个生词本只能从一个在线服务中记录-词条，但是MYDICTIONARY能够从多个不同的在线服务中获得词条。因此，我们需要该成员来记录生词本与在线服务之间的对应关系。该成员需要与online.service中的键名精确匹配。
"dictionary"是一个数组，它的每一项具有下列成员：
- 字符串
"name"：离线词典的名称。 - 字符串
"fileName"：离线词典文件的名称，位于文档路径下。 - 布尔型
"readable"：如果设为false，那么离线词典将被MYDICTIONARY忽略。通过这项设置，我们可以在不移除整个数组项的情况下，停用离线词典。 - 布尔型
"writable"：如果设为true，那么允许MYDICTIONARY在查询的时候将-词条-记录-到离线词典。
"online"是一个结构体，具有下列成员：
"mode"是个整数，它决定了在什么样的情况下，MYDICTIONARY会从在线服务获取词条（联网查询）。
取值如下：
0：MYDICTIONARY从不执行联网查询。1：如果用户需要，那么MYDICTIONARY执行联网查询。2：如果词条不存在所有的生词本和离线词典中，那么MYDICTIONARY执行联网查询。3：如果用户需要，或者词条不存在所有的生词本和离线词典中，那么MYDICTIONARY执行联网查询。4：MYDICTIONARY总是执行联网查询。
如果难以理解以上描述，将"mode"设定为默认值3即可。
"service"是一个数组，每项的键-值对（字符串-布尔型）决定了是否启用该在线服务。
如果"enable"设定为true，那么MYDICTIONARY将缓存从在线服务获得的查询结果若干天（取决于"shelfLifeDay"）。这会显著增加联网查询的速度。
每个在线服务的缓存会对应一个同名缓存文件。缓存文件位于缓存路径下。
"debug"决定了MYDICTIONARY是否处于调试模式。默认值为false。非开发者请勿更改。
func Initialize(path []string) (success bool, information string)该函数用于初始化MYDICTIONARY。
path是一个包含1-3个成员的切片：
- 如果
path的长度为1，那么工作路径、文档路径和缓存路径均为path[0]。 - 如果
path的长度为2，那么工作路径为path[0]，文档路径为path[1]，缓存路径为path[0]。 - 如果
path的长度为3，那么工作路径为path[0]，文档路径为path[1]，缓存路径为path[2]。
函数执行的过程如下：
- 设定路径。
- 读取配置文件，生成并解析配置。
- 读取生词本文件，生成生词本。
- 读取离线词典文件，生成离线词典。
- 加载在线服务的缓存文件。
该函数应该在任何其他函数前调用。
返回值：
- 如果成功，那么
success为true。同时，配置的内容通过information返回。 - 如果失败，那么
success为false。同时，错误信息通过information返回。
func CheckNetwork() (success bool, information string)该函数通过请求百度来检查网络。
返回值：
- 如果百度可达，那么
success为true。 - 否则，那么
success为false。 information将会提供更多的信息。
func Query(vocabularyAsk VocabularyAskStruct) (success bool, vocabularyResult VocabularyResultStruct)该函数是MYDICTIONARY的核心。
过程如下：
- 在所有的生词本和离线词典中查询
vocabularyAsk中的词汇，记录离线查询的结果。 - 根据配置中的
online.mode、vocabularyAsk中的选项以及离线查询的结果，决定是否进行在线查询。 - 如果第2步的答案为”是“，那么执行在线查询并记录结果。由于使用了goroutines，MYDICTIONARY将会同时查询所有的在线服务，这就意味着查询时间取决于响应时间最长的在线服务。
- 通过
vocabularyResult返回所有结果。
Return values:
- 如果成功，那么
success为true，结果会通过vocabularyResult返回。 - 如果MYDICTIONARY还未被初始化，那么
success为false。
func Save() (success bool, information string)该函数用于：
- 将生词本写回对应的生词本文件
- 将离线词典写回对应的离线词典文件
- 保存在线服务的缓存
返回值：
- 如果所有文件均写回成功，那么
success为true。 - 否则，那么
success为false。 information将会提供更多的信息。
func Edit(vocabularyEdit VocabularyEditStruct) (success bool, information string)该函数用于编辑生词本或离线词典中词条的释义和笔记。该函数不受配置中"writable"的制约。
返回值：
- 如果成功，那么
success为true。 - 如果失败，那么
success为false。 information将会提供更多的信息。
- 感谢excelize的提供者xuri。
- 感谢goquery的提供者PuerkitoBio。
- 所以代码文件是用Atom编写的。
- 所有".md"文件是用Typora编写的。
- 所有".md"文件的风格是Github Flavored Markdown。
- 各行以LF（Linux）结尾。