A.12 Using the Mapping API

Org 具备强大的映射遍历能力,可查找满足指定条件的所有条目。该功能内部用于生成日程视图,同时也提供 API,可对每个或筛选后的条目执行任意函数。该 API 的主入口为:

Function: org-map-entries func &optional match scope &rest skip

SCOPE 范围内,对 MATCH 选中的每个标题调用 FUNC

FUNC 为函数或 Lisp 表达式。光标会定位在标题开头,无参数调用该函数。Org 返回所有函数调用的返回值列表。

为不保留光标位置,Org 会在 save-excursion 中执行 FUNC。执行后光标移至刚处理行的行尾,检索从该位置继续。在部分场景下(如当前子树已被归档删除),该行为可能不符合预期,极少数情况下会错误跳过下一条目。如需避免此类问题,可让 FUNC 将变量 org-map-continue-from 设置为指定缓冲区位置。

MATCH 为标签/属性/TODO 匹配条件。Org 仅遍历匹配的标题;若为 nilt ,则遍历所有标题。

SCOPE 决定命令作用范围,可选值:

nil

当前缓冲区,遵循现有限制(如有)。

tree

以光标处条目为起点的子树。

region

活动区域内的条目(如有)。

file

当前缓冲区,无任何限制。

file-with-archives

当前缓冲区及其关联归档文件。

agenda

所有日程文件。

agenda-with-archives

所有日程文件及其关联归档文件。

文件名列表

若为文件名列表,则遍历列表中所有文件。

其余参数用作扫描器的跳过规则,有效参数:

archive

跳过带有 ‘ARCHIVE’ 标签的子树。

comment

跳过带有 COMMENT 关键字的子树。

函数 或 Lisp 形式

作为 org-agenda-skip-function 的值,当函数返回 t 时,对该条目执行 FUNC,并从函数停留位置继续检索。

映射遍历可调用任意函数,包括修改元数据或调用属性 API 的函数(见 Using the Property API)。常用函数如下:

Function: org-todo &optional arg

修改条目的 TODO 状态。参数 ARG 可用值较多,详见函数文档。

Function: org-priority &optional action

修改条目的优先级。ACTION 可用值详见函数文档。

Function: org-toggle-tag tag &optional onoff

切换当前条目的 TAG 标签。将 ONOFF 设为 onoff 不会切换,而是直接开启或关闭标签。

Function: org-promote

提升当前条目层级。

Function: org-demote

降低当前条目层级。

下面示例将所有带有 ‘TOMORROW’ 标签的条目设为 TODO 关键字 ‘UPCOMING’ ,并忽略注释子树和归档子树。

(org-map-entries '(org-todo "UPCOMING")
                 "+TOMORROW" 'file 'archive 'comment)

以下示例统计所有日程文件中 TODO 关键字为 ‘WAITING’ 的条目数量。

(length (org-map-entries t "/+WAITING" 'agenda))