TODO 库

用于处理 todo.txt 格式 文件的实用工具集合

文件操作

加载待办事项列表

load(文件名: &路径) -> 结果<TaskVec,terr::TodoError>

从给定的文件路径加载待办事项列表。返回加载的待办事项列表或错误。如果文件不存在，该函数返回空列表。

保存待办事项列表

save(任务: &TaskSlice,文件名: &路径) -> 结果<(), terr::TodoError>

将待办事项列表保存到给定的文件路径。如果创建文件或写入失败，则可能返回错误。列表以两步保存

• 将列表保存到同一目录下的临时文件中，文件名为 filename
• 成功后，删除旧文件并将临时文件重命名为 filename

归档已完成的事务

archive(任务: &TaskSlice,文件名: &路径) -> 结果<(), terr::TodoError>

它的工作方式类似于 save，但将任务列表附加到给定的 filename。它不创建临时文件。

过滤

filter(任务: &todo::TaskSlice,c: &Conf) -> todo::IDVec

该函数获取所有待办事项列表和过滤规则，并返回符合规则的待办事项 ID 列表（待办事项的 ID 是待办事项在原始列表中的顺序号）。如果规则与字符串（例如，项目或正则表达式）一起使用，则规则不区分大小写。可用的规则（如果规则为 None，则跳过该规则）

• range - 通过 ID 选择一个待办事项，或在 ID 范围内选择几个待办事项（包含），或选择 ID 列表；
• all - 仅选择所有完成的、仅选择不完整的，或两者都选择；
• pri - 选择具有任何优先级、没有优先级或具有相同/更高/更低优先级（包含）的待办事项；
• regex - 当 use_regex 为 true 时，进行正则表达式模式匹配，否则进行子字符串搜索。注意：它在主题、项目和环境中进行搜索。
• projects - 选择所有包含任意一个projects的任务。此规则允许调用者进行非常基本的模式匹配：在项目名称的开头或结尾添加*分别表示查找以单词结尾或开始的项目的名称，将*添加到两端类似于regex，但只检查项目。*位于单词中间没有特殊含义 - 在这种情况下请使用regex;
• contexts - 选择所有包含任意一个contexts的任务。该规则可以使用与projects相同的方式使用*;
• tags - 选择所有包含任意一个tags的任务。该规则可以使用与projects相同的方式使用*;
• hashtags - 选择所有包含任意一个hashtags的任务。该规则可以使用与projects相同的方式使用*;
• due - 选择所有有截止日期的任务，没有截止日期的任务，截止日期在范围内的任务，或者提前几天内的任务；
• rec - 选择所有周期性任务或所有没有周期性标记的任务。
• thr - 选择所有有阈值日期的任务，没有阈值日期的任务
• tmr - 选择所有活跃的任务 - 那些计时器正在运行的任务
• created - 选择所有有创建日期的任务，没有创建日期的任务，创建日期在范围内的任务
• finished - 选择所有有完成日期的任务，没有完成日期的任务，完成日期在范围内的任务

规则 contexts、projects、hashtags 和 tags 支持特殊值

• none - 过滤没有任何值的任务（contexts=['none'] - 没有任何上下文的任务）
• any - 过滤至少有一个值的任务（project=['any'] - 属于任何项目的任务）

排序

sort(ids: &mut todo::IDVec,todos: &todo::TaskSlice,c: &Conf)

因为sort是应该在filter之后调用的函数，所以它需要一个要排序的选中任务ID列表，整个任务列表（ids中的ID是todos中任务的顺序号）和排序规则。该函数会就地更改ids，排序始终是稳定的 - 它会保持相等任务的ids列表中的顺序。只有两种排序规则

• fields - 是一个由逗号（或冒号）分隔的字段列表，按照排序的重要性排序。如果该向量是空的，则列表保持不变。支持的字段名称（及其缩写）
  • pri 或 priority - 按优先级排序（没有优先级的最后）；
  • due - 按截止日期排序（没有截止日期的任务在底部）；
  • completed 或 finished - 按完成日期排序（未完成的任务在底部）；
  • created 或 create - 按创建日期排序；
  • subject、subj 或 text - 按待办事项的主题排序；
  • done - 顺序：未完成、重复和已完成待办事项；
  • project 或 proj - 按项目名称排序，如果待办事项属于多个项目，则按出现顺序比较，项目列表较短者排在前面；
  • context 或 ctx - 按情境排序，如果待办事项属于多个情境，则按出现顺序比较，情境列表较短者排在前面；
  • thr - 按阈值日期排序（没有阈值日期的待办事项排在底部）；
• rev - 当它为 true 时，在返回结果之前将排序后的列表反转。

编辑

添加新的待办事项

添加(任务: &mut任务向量,c: &Conf) -> usize

该函数获取现有待办事项列表和一个具有非None字段 subject 的 c，然后解析 subject 并将结果待办事项添加到列表中，并返回新待办事项的ID。如果添加失败（例如，subject 为空或解析返回错误）- 函数返回 INVALID_ID。

修改现有待办事项

此类函数接收所有待办事项的列表、待修改的待办事项ID列表以及可选的属性新值。如果 ids 列表为 None，则函数修改所有待办事项。它返回长度与 ids 的长度相等（或长度与 tasks 相等，如果 ids 为 None）的布尔值向量。如果结果向量的某些索引处有 true，则表示 ids 在同一索引处的待办事项已被修改。

完成和取消待办事项

标记待办事项为完成

done_with_config(任务: &mut任务向量,ids: 可选<&IDVec>,completion_config: todotxt::CompletionConfig) ->ChangedVec

使 ids 列表中的所有未完成的待办事项完成。

特殊情况：包含截止日期和/或阈值日期的重复待办事项。它们被标记为完成，并创建新的待办事项，其截止日期和阈值日期移动到未来的下一个日期。

从待办事项中移除完成标记

undone(任务: &mut任务向量,ids: 可选<&IDVec>,模式: todotxt::CompletionMode) ->ChangedVec

从 ids 列表中的所有已完成待办事项中移除完成标记。

特殊情况：重复待办事项。它们不会被更改。

更改特定属性

编辑(任务: &mut任务向量,ids: 可选<&IDVec>,c: &Conf) ->ChangedVec

该函数修改 tasks 中的所有待办事项，其ID位于 ids 列表中。注意：修改主题只修改 ids 列表中的第一个待办事项，因为它没有意义使所有待办事项都相同。

可以修改的内容

• subject - 设置新的主题
• priority - 设置、删除、增加或减少优先级
• due date - 设置或删除 thresold date - 设置或删除
• recurrence - 设置或删除
• projects - 添加、删除或替换
• contexts - 添加、删除或替换
• tags - 添加、删除或替换
• hashtags - 添加、删除或替换

时间跟踪支持

为了计算待办事项花费的时间，添加了两个主要功能

开始和停止时间跟踪

开始(任务: &mut任务向量,ids: 可选<&IDVec>) ->ChangedVec

如果待办事项尚未完成且尚未运行，则将其激活。所有待办事项都将保存它们被激活时的时间戳。

停止(任务: &mut任务向量,ids: 可选<&IDVec>) ->ChangedVec

停止指定待办事项的计时器。待办事项所花费的时间将被更新。

以及两个实用函数

is_timer_on(任务: &todo_txt::任务::扩展) -> 布尔值

如果给定的待办事项是活跃的，则返回 true

已花费时间(任务: &todo_txt::任务::扩展) -> chrono::持续时间

返回给定待办事项所花费的总时间。对于非活跃的待办事项，它返回待办事项的标签 spent 的当前值。对于活跃的待办事项，它返回待办事项的标签 spent 和自待办事项被激活以来经过的时间的总和。