(这是 hledger 仓库 bin/ 目录中的 README，也发布在 hledger.org 的 脚本和附加组件 页面上。)
脚本 是一种您可以立即运行的程序，而无需先编译。它们通常很小，并定义在单个文件、shell 别名或 shell 函数中。您可以创建自己的简单或复杂脚本，以增强 hledger。例如，您可能会编写一个复杂的报告脚本，这样您就不必记住详细的命令。
一个 hledger 附加命令 是任何名称以 "hledger-" 开头的程序。在 PATH 中找到的附加命令将出现在命令列表中（当你运行 hledger 而不带参数时显示）。下面的一些脚本是附加命令。一些附加命令是用 Haskell 编写的，可以使用 hledger 的全部功能，就像内置命令一样。
以下是一些您可以使用或学习的现有脚本。这些大多数都收集在 hledger 的 bin/ 目录 中，您可以通过 克隆 hledger 源代码来获取。编译的附加组件也在下面列出，单独成节。
请注意，如果您是 hledger 的新手，您不需要任何这些额外的功能 - 除非可能需要 hledger-ui 和 hledger-web，这在开始时可能会很有用。
这里有一些脚本，它们并不直接使用 hledger，但可能对 hledger 用户有用。（更多信息，请参见：plaintextaccounting.org > 软件）。
'pricehist 对于下载市场价格/汇率非常有用；推荐使用。并且 hledger-pricehist 是一个小脚本，可以使其出现在 hledger 命令列表中。'
paypaljson 下载最近30天的Paypal交易（需要一个免费的开发者账户和API密钥）。
paypaljson2csv (python) 将 paypaljson 的输出转换为 CSV，格式类似于 Paypal 手动下载的 CSV。
这些脚本使用 hledger 的命令行接口，或处理其输出格式之一。
bashrc 包含许多示例 bash 别名和函数。安装 bin 脚本后：作为一个 bash 用户，
# 自定义 FINDIR 和 LEDGER_FILE 在 bin/bashrc 的顶部
$ . bin/bashrc
$ fin # 列出可用的脚本
$ alias f=~/src/hledger/bin/ft
$ f
--------------------------------------------------------------------------------"; }
ft - 财务工具: 运行财务报告和与财务相关的脚本
用法: ft [命令 [参数]]
命令:
help 显示此帮助
get-csv 下载可自动下载的CSV（paypal）
import-dry 将新下载的交易导入日记，干运行
import 将新下载的交易导入日记，记录并不打印错误
get-prices [价格历史获取选项] - 下载主要商品的价格（默认: 今天的）
bs 显示资产负债表
is 显示收入报表
a 显示资产
r 显示收入
x 显示支出
ab 显示资产柱状图
rb 显示收入柱状图
xb 显示支出柱状图
al 显示资产折线图
rl 显示收入折线图
xl 显示支出折线图
forecast 打印从上周开始根据预测规则预测的交易
household 显示上个月的草稿月末家庭调整交易
consulting 显示咨询收入
bin [PAT] 显示$DIR/bin/[bashrc]中的所有脚本（默认: ~/finance/）
OTHERCMD [参数] 在默认日记上运行其他hledger命令
添加 hledger 选项以自定义报告。
tt 是一个类似的 bash 多脚本，用于时间报告。
$ alias t=~/src/hledger/bin/tt
$ t
--------------------------------------------------------------------------------
tt - 时间工具：运行时间报告和与时间相关的脚本
用法：tt [命令 [参数]]
命令：
help 显示此帮助
dash 显示时间仪表板，当时间日志文件更改时重新显示
status 显示当前时间状态
what 发生了什么？ 默认情况下，首先显示最大余额，今天和深度 1
dots 打印 N 个点的行，按 4 个分组（适合 timedot）
x 今年的横向时间摘要，默认按月
y 今年的纵向时间摘要，默认按月
rweeks 最近几周的时间预算
weeks 本周和上周的时间预算
hours 显示每日小时的条形图
accunused 显示未使用/未声明的账户
accunusedcat 按类别显示未使用/未声明的账户
accadd 为所有未声明的账户添加声明
budgets 显示今年的每月时间预算表现
budgetsy 以垂直方式显示今年的每月时间预算表现
budgetsw 显示今年的每周时间预算表现
budgetswx 以横向方式显示今年的每周时间预算表现
OTHERCMD [参数] 在 $TIMELOG 上运行其他 hledger 命令
添加 hledger 选项以自定义报告。
'https://github.com/casey/just 是一个很好的工具，用于组织财务报告和脚本，类似于 make，但在这个用例中更为强大。我可以推荐它。另请参见 hledger 和 just。'
这里是一个 Justfile，更简单地重新实现了 ft 和 tt 脚本:
$ brew install just # 示例
$ alias j=just
$ cd ~/finance
$ cp ~/src/hledger/bin/Justfile . # 或从头开始: just --init
$ j
Justfile 命令:
watch CMD # 每当本地文件更改时，使用 watchexec 重新运行给定命令
get-csv # 下载可自动下载的 CSV（paypal）
import-dry # 将新下载的交易导入主日记，干运行
import # 将新下载的交易导入日记，记录并不打印错误
get-prices *PRICEHISTFETCHOPTS # 显示主要商品的价格（默认: 今天的）
bs *HLEDGERARGS # 显示资产负债表
is *HLEDGERARGS # 显示收入报表
a *HLEDGERARGS # 显示资产
r *HLEDGERARGS # 显示收入
x *HLEDGERARGS # 显示支出
ab *HLEDGERARGS # 显示资产柱状图
rb *HLEDGERARGS # 显示收入柱状图
xb *HLEDGERARGS # 显示支出柱状图
al *HLEDGERARGS # 显示资产折线图
rl *HLEDGERARGS # 显示收入折线图
xl *HLEDGERARGS # 显示支出折线图
forecast *HLEDGERARGS # 打印从上周开始的预测规则预测的交易
household *HLEDGERARGS # 显示上个月的家庭调整交易草稿
consulting *HLEDGERARGS # 显示咨询收入
tdash *HLEDGERARGS # 显示时间仪表板，文件更改时重新显示
tstatus *HLEDGERARGS # 显示当前时间状态
twhat *HLEDGERARGS # 发生了什么？ 默认情况下，首先显示最大的时间余额，今天和深度 1
tdots N # 打印 N 个点的行，按 4 个分组（适合 timedot）
tx *HLEDGERARGS # 今年的横向时间摘要，默认按月
ty *HLEDGERARGS # 今年的纵向时间摘要，默认按月
tweeks *HLEDGERARGS # 本周和上周的时间预算
tweekspast *HLEDGERARGS # 最近几周的时间预算
thours *HLEDGERARGS # 显示每日小时的柱状图
taccunused *HLEDGERARGS # 显示未使用/未声明的时间账户
taccunusedcat *HLEDGERARGS # 按类别显示未使用/未声明的时间账户
taccadd *HLEDGERARGS # 为所有未声明的时间账户添加声明
tbudgets *HLEDGERARGS # 显示今年的每月时间预算表现
tbudgetsy *HLEDGERARGS # 显示今年的每月时间预算表现，纵向
tbudgetsw *HLEDGERARGS # 显示今年的每周时间预算表现
tbudgetswx *HLEDGERARGS # 显示今年的每周时间预算表现，横向
watchaccounts 显示 hledger 账户名称，在当前目录下文件更改时更新。参数传递给 hledger accounts 命令。在整理账户时很有用。
$ watchaccounts 费用 -2
$ watchaccounts -f time.journal 客户1 日期:本月 -l
sortandmergepostings 是一个冒险的 awk 脚本，旨在清理和合并交易中相似的记录（见 原始讨论）。它对记录进行排序，使得正数记录在前，负数记录在后。在每个符号内，记录按账户名称的字母顺序排序。最后，如果同一方向有多个记录到同一账户，它会尝试合并它们（通过留下一些金额为空）。将输出通过管道传递给 hledger print 可以重新计算缺失的金额。可能需要多次运行以清理所有重复项。
$ sortandmergepostings input.journal | hledger -f - print -x
hledger-simplebal 显示了如何使用 hledger 可靠地报告一个机器可读的数字。这个和其他 "hledger-" 脚本是附加命令。
$ hledger 简单余额
hledger-bar 在终端中打印快速条形图。
$ hledger bar 报销
2023-01 ++++++
2023-02 ++
2023-03 ++
2023-04 -------
$ hledger bar # 显示帮助
$ hledger bar food # 每月食品开支
$ hledger bar -- 1 --count food # 每月食品发布计数
$ hledger bar -- type:c not:tag:clopen cur:\\$ -W # 每周现金流，仅限 $
$ hledger bar -- type:al not:tag:clopen cur:\\$ # 每月净资产变化 ($)
$ hledger bar -- type:rx --invert cur:\\$ # 每月利润/损失 ($)
$ hledger bar -- -v 1 -f $TIMELOG -D # 每日工时，带数字
hledger-git 提供了使用 git 对你的日记文件进行简单版本控制的功能。运行时不带参数以获取帮助。
$ hledger git log
$ hledger git status
$ hledger git record [消息]
hledger-pijul 提供了相同的功能，使用 pijul 版本控制系统..
$ hledger pijul 日志
$ hledger pijul 状态
$ hledger pijul 记录 [MSG]
该 hledger-utils python 包 提供了一个 hledger-edit 命令，可以在你的 $EDITOR 中编辑查询到的交易，无论它们位于哪个文件中。
安装或升级:
$ pip install -U hledger-utils # 可能在你的系统上略有不同
示例:
# 打开你的 $EDITOR 或 $VISUAL，仅显示佛罗里达的费用
# （如果你是这样命名和标记它们的）
# 编辑交易，保存并退出编辑器，
# 然后更改会分发到原始文件
$ hledger edit Cost tag:location=Florida
# 通过将 `$EDITOR` 设置为脚本来自动化更改
# （这里我们在佛罗里达那天吃的所有食物都是快餐 🌭，我们最初忘记写下这一点）
EDITOR='perl -pi -e "s|Cost:Food|Cost:Food:Fast Food|g"' hledger edit tag:location=Florida date:2022-12-20
该 hledger-utils python 包 提供了一个 hledger-plot 命令，用于使用 matplotlib 生成图表。
安装或升级:
$ pip install -U hledger-utils # 可能在你的系统上略有不同
示例:
$ hledger-plot -h
$ hledger plot -- bal -DH ^资产 -2
hledger-lots 显示了一个批次报告，或生成一个批次销售交易，使用 FIFO 策略（并且不需要批次的子账户）。
安装或升级:
$ pip install -U hledger-lots
示例:
$ hledger 大量
$ hledger 大量 视图
$ hledger 大量 列表
hledger-report1.sh 是一个用 shell 编写的自定义复合报告。另见 hledger-report1.hs.
这些脚本是用 Haskell 编写的，并使用 hledger 的 Haskell API（通过导入 hledger 或 hledger-lib Haskell 库）。它们通常是 堆栈脚本。它们可以执行 hledger 内置命令可以做的任何事情，并且通常比命令行脚本更稳健。一些内置命令最初是作为独立的 Haskell 脚本开发的。
hledger-script-example.hs 是编写您自己的 hledger 集成附加命令的模板。它与这里大多数附加组件具有相同的结构：
- 一个用于稳健性的堆栈脚本
- 提供命令行帮助
- 接受常见的 hledger 选项
hledger-print-location.hs 是 hledger 的 print 命令的一个变体，它在每个交易中添加文件和行号，作为标签:
$ hledger print-location -f hledger/examples/sample.journal desc:eat
2008/06/03 * 吃 & 购物
; 位置: /Users/simon/src/hledger/examples/sample.journal:30
费用:食品 $1
费用:用品 $1
资产:现金
hledger-swap-dates.hs 打印交易，交换它们的日期和 date2 字段。
hledger-check-tagfiles.hs 将所有包含 / (斜杠) 的标签值解释为文件路径，并检查这些文件是否存在。 hledger-check-tagfiles.cabal.hs 是以 cabal 脚本而不是 stack 脚本实现的相同命令。
hledger-register-max.hs 运行一个登记报告，并打印出历史余额最大的记录。
$ hledger-register-max -f examples/bcexample.hledger 支票
2013-01-03 Hoogle | 工资 资产:US:BofA:支票 1350.60 美元 8799.22 美元
$ hledger register-max -- -f examples/bcexample.hledger 支票
2013-01-03 Hoogle | 工资 资产:US:BofA:支票 1350.60 美元 8799.22 美元
hledger-check-postable.hs 检查是否没有对带有 postable:n 或 postable:no 标签的账户进行过账。当您必须声明一个父账户以控制显示顺序，但又不想允许对其进行过账时，这可以作为一种解决方法。例如，允许对 assets:cash 进行过账，但不允许对 assets 进行过账（请记住，账户标签是继承的）:
账户资产 ; 可发布:n
账户资产:现金 ; 可发布:'
hledger-check-fancyassertions.hs 以比 hledger 内置的余额断言更复杂的方式检查账户余额的变化。
hledger-combine-balances.hs 显示了两个不同时间段的余额报告并排。
hledger-balance-as-budget.hs 使用一个余额报告来设定另一个余额报告的预算目标。
hledger-smooth.hs 是一个不完整的尝试，旨在自动拆分不频繁/不规则的交易。
hledger-move.hs 有助于进行子账户/成本保留转账。
hledger-report1.hs 是用 Haskell 编写的自定义复合报告。另见 hledger-report1.sh.
hledger-txnsbycat.hs 是一个余额报告和登记报告的混合；它显示了每个账户在账户余额下的交易。
'附加组件 -------------------'
这些是您可以作为编译程序安装的一些官方和第三方插件：
'hledger-ui 是 hledger 的官方终端用户界面。它允许更快速地浏览您的账户和交易。'
hledger-web 是 hledger 的官方网页用户界面。它允许在网页浏览器中进行数据输入和简单报告。它适合非命令行用户。
hledger-iadd 是内置 add 命令的一个流行替代品。
hledger-interest 生成利息交易。
- hledger-stockquotes 获取市场价格。使用不广泛，考虑使用 pricehist。
- hledger-diff 比较两个日记文件。它现在内置于 hledger 中，因此你不需要它。
'如何... --------------------'
要使用这些 bin 脚本，您必须确保它们在您的 $PATH 中并且可运行:
以下是建议的安装步骤：
# 前往您存放财务文件的地方：
$ cd ~/finance
# 获取 hledger 仓库
# 快速方式，无需版本控制：
$ curl -LOJ https://github.com/simonmichael/hledger/archive/refs/heads/master.zip && unzip hledger-master.zip && mv hledger-master hledger
# 或者慢速方式，使用版本控制以便于轻松比较/更新/贡献
# git clone https://github.com/simonmichael/hledger
# 创建一个更方便的指向 bin 目录的符号链接：
$ ln -s hledger/bin
# 将 bin 目录添加到你的 PATH 中。例如作为 bash 用户：
$ echo "export PATH=$PATH:$PWD/bin" >>~/.bash_profile"
$ export PATH=$PATH:$PWD/bin
# 可选地，编译所有 Haskell 脚本以加快启动速度：
$ cd hledger; bin/compile.sh
# 可选地，安装 Python 脚本：
$ pip install -U hledger-utils
$ pip install -U hledger-lots
# 检查 hledger 的命令列表现在是否包含 bin 脚本。
# 例如 "check-fancyassertions" 和 "swap-dates" 应该被列出：
$ hledger
要创建一个新的 hledger 集成脚本，请复制 hledger-script-example.hs。在 Unix 上，新脚本应标记为可执行。这应该可以做到：
$ cd bin
$ cp hledger-script-example.hs hledger-cmd.hs # 用你的命令名称替换 cmd
# 编辑 hledger-cmd.hs，至少更新命令名称和帮助
$ stack install safe text # 确保脚本的依赖项已安装
$ hledger-cmd.hs --help
cmd [OPTIONS]
我的新 cmd 命令。
...
$ stack ghc hledger-cmd.hs # 可选编译以加快启动/耐用性
$ hledger cmd -- --help
cmd [OPTIONS]
我的新 cmd 命令。
...
$ stack exec --package 'safe text' -- ghcid hledger-cmd.hs
...
好的，已加载一个模块。
一切正常 (1 个模块，时间 10:50:48)
$ stack ghci --package 'safe text' hledger-cmd.hs
...
好的，已加载一个模块。
...
ghci>