# README
ap -- auto-pager
ap 是一个 shell 工具，可以让其它 shell 命令的输出能够自动进入交互翻页模式。
ap 由两部分组成，一个 Go 语言编写的二进制程序，负责捕获命令的输出并支持翻页， 和一组 shell 脚本，负责为用户指定的命令清单创建与之同名的 wrapper。
经过 wrap 之后的命令用法与原来相同，不应当改变用户操作习惯，不会给用户造成困扰。
安装
go install github.com/flw-cn/ap@master
配置
bash
在你的 ~/.bashrc 里加入下面内容：
eval "$(ap --bash)"
ap 默认 wrap 了一批命令。如果你不满意，可以通过环境变量重新定制：
AUTO_PAGER_CMDS=(go cargo make)
eval "$(ap --bash)"
或者也可只在默认清单之上增加新的命令：
AUTO_PAGER_CMDS_EXTRA=(ps last)
eval "$(ap --bash)"
另外，ap 也可以和 grc 一起工作，在 macOS 下可以使用 Homebrew 安装 grc:
brew install grc
ap + grc 默认 wrap 了一批命令。如果你不满意，可以通过环境变量重新定制：
AUTO_PAGER_CMDS_WITH_GRC=(ps last dig diff)
eval "$(ap --bash)"
或者也可只在默认清单之上增加新的命令：
AUTO_PAGER_CMDS_WITH_GRC_EXTRA=(ps last)
eval "$(ap --bash)"
另外，环境变量 $AUTO_PAGER_MIN_HEIGHT 可以控制开始分页的最小行数：
AUTO_PAGER_MIN_HEIGHT=30 # 输出超过 30 行时才开始分页
eval "$(ap --bash)"
如果配置为负数，则代表终端窗口高度的百分比：
AUTO_PAGER_MIN_HEIGHT='-50' # 输出超过终端窗口高度的 50% 时才开始分页
eval "$(ap --bash)"
如果不指定 AUTO_PAGER_MIN_HEIGHT，默认为 -80，即 80%。
fish
在你的 ~/.config/fish/config.fish 里加入下面内容：
ap --fish | source
ap 默认 wrap 了一批命令。如果你不满意，可以通过环境变量重新定制：
set AUTO_PAGER_CMDS go cargo make
ap --fish | source
或者也可只在默认清单之上增加新的命令：
set AUTO_PAGER_CMDS_EXTRA ps last
ap --fish | source
另外，ap 也可以和 grc 一起工作，在 macOS 下可以使用 Homebrew 安装 grc:
brew install grc
ap + grc 默认 wrap 了一批命令。如果你不满意，可以通过环境变量重新定制：
set AUTO_PAGER_CMDS_WITH_GRC ps last dig diff
ap --fish | source
或者也可只在默认清单之上增加新的命令：
set AUTO_PAGER_CMDS_WITH_GRC_EXTRA ps last
ap --fish | source
另外，环境变量 $AUTO_PAGER_MIN_HEIGHT 可以控制开始分页的最小行数：
set AUTO_PAGER_MIN_HEIGHT 30 # 输出超过 30 行时才开始分页
ap --fish | source
如果配置为负数，则代表终端窗口高度的百分比：
set AUTO_PAGER_MIN_HEIGHT -50 # 输出超过终端窗口高度的 50% 时才开始分页
ap --fish | source
如果不指定 AUTO_PAGER_MIN_HEIGHT，默认为 -80，即 80%。
zsh
在你的 ~/.zshrc 里加入下面内容：
eval "$(ap --zsh)"
ap 默认 wrap 了一批命令。如果你不满意，可以通过环境变量重新定制：
AUTO_PAGER_CMDS=(go cargo make)
eval "$(ap --zsh)"
或者也可只在默认清单之上增加新的命令：
AUTO_PAGER_CMDS_EXTRA=(ps last)
eval "$(ap --zsh)"
另外，ap 也可以和 grc 一起工作，在 macOS 下可以使用 Homebrew 安装 grc:
brew install grc
ap + grc 默认 wrap 了一批命令。如果你不满意，可以通过环境变量重新定制：
AUTO_PAGER_CMDS_WITH_GRC=(ps last dig diff)
eval "$(ap --zsh)"
或者也可只在默认清单之上增加新的命令：
AUTO_PAGER_CMDS_WITH_GRC_EXTRA=(ps last)
eval "$(ap --zsh)"
另外，环境变量 $AUTO_PAGER_MIN_HEIGHT 可以控制开始分页的最小行数：
AUTO_PAGER_MIN_HEIGHT=30 # 输出超过 30 行时才开始分页
eval "$(ap --zsh)"
如果配置为负数，则代表终端窗口高度的百分比：
AUTO_PAGER_MIN_HEIGHT='-50' # 输出超过终端窗口高度的 50% 时才开始分页
eval "$(ap --zsh)"
如果不指定 AUTO_PAGER_MIN_HEIGHT，默认为 -80，即 80%。
使用
经过 ap wrap 过的命令只需要像往常一样使用就可以了。
如果输出内容过多，会自动调用环境变量 $PAGER 所指定的分页器进行分页。
如果你的 $PAGER 变量比较特殊，无法与 ap 适配，你也可以通过环境变量 $AP_PAGER
为 ap 单独设置分页器。
如果 $AP_PAGER 和 $PAGER 都没有指定，那么将使用 less -Fr。
以下情况并不会启动分页器：
- 输出内容过少时，参见
$AUTO_PAGER_MIN_HEIGHT。 - 当 ap 检测到命令输出中包含
ESC [?1049h序列时，此时命令被判定为全荧幕应用。 - 当命令尚未执行完成时。分页器只有命令执行完成后才会启动。
ping和tcpdump等此类命令需要先按Ctrl-C终止命令后才会启动分页。python和gdb等此类命令需要先等待命令退出后才会启动分页。
常见问题
- 会影响命令的彩色输出吗？
- 不会。
- 有的命令会检测终端，并为终端模式和非终端模式提供不同的输出，会改变它的输出吗？
- 不会。
- 如果我怀疑 ap 影响了命令的输出，如何诊断？
- 你可以用
command foo来执行foo，这样就不会调用 ap。
- 你可以用
- 如果我习惯性地在 ap 过的命令后面加了
| less，会出问题吗？- 不会。
- ap 过的命令还可以重定向它的输出吗？
- 可以。
- ap 过的命令的自动补全会被破坏吗？
- 不会。
- ap 支持像
python、gdb这样的交互式应用吗？- 支持。但是由于这些应用会输出一些控制字符，所以分页后看到的内容可能会有点乱。
- ap 支持像
htop、vim这样的全荧幕应用吗？- 怎么说呢，反正不会出错，但我想不明白把 ap 和它们搭配在一起有什么实际意义。