Beancount 语言语法

本文档为 Beancount 语言语法提供了一个简洁而全面的参考，融合了实践结构、规则和示例。 更多详情，请参阅 速查表。

概述

Beancount 是一个纯文本复式记账系统。 它的语言围绕三个主要构建块构建：

• 商品（货币、股票、积分等）
• 账户（分层的、分类的账簿）
• 指令（记录事件或配置的带日期条目）

商品

商品始终以大写形式书写，例如 USD、EUR、AAPL、BTC、MILES、HOURS。

账户

账户是冒号分隔的、首字母大写的分层名称。 它们必须以五个根账户类型之一开头：

名称	类型	典型内容	示例
Assets	+	现金、银行、投资	Assets:Checking
Liabilities	-	信用卡、贷款	Liabilities:CreditCard
Income	-	工资、利息	Income:EmployerA
Expenses	+	购买、账单	Expenses:Food:Dining
Equity	-	期初/期末余额	Equity:Opening-Balances

• 组件必须大写，用冒号 (:) 分隔，且没有空格。
• 组件中允许使用数字和破折号。
• 根账户名称可以通过选项进行自定义（见下文）。

指令

指令是 Beancount 文件中的核心语句。 大多数指令以日期开头，后跟指令类型和参数。 它们按时间顺序（按日期）处理，而不是按文件顺序处理。

通用格式：

YYYY-MM-DD <directive> <arguments...>

常用指令 & 示例

开户和销户

2023-01-01 open Assets:Checking USD,EUR  ; 可选地指定允许的货币
2023-12-31 close Assets:Checking

声明商品

2020-07-22 commodity AAPL
  name: "Apple Inc."

价格声明

2022-04-30 price AAPL 150.00 USD

备注 & 文档

2022-03-20 note Assets:Checking "询问退款"
2022-03-20 document Assets:Checking "statements/2022-03.pdf"

交易

2024-01-05 * "Coffee Shop" "Morning coffee"
  Expenses:Food         4.50 USD
  Assets:Cash         -4.50 USD

2024-01-06 ! "Phone Bill" "Monthly payment" #utilities ^phone
  id: "INV12345"              ; 元数据
  Expenses:Utilities  60.00 USD
  Assets:Checking

过账功能

; 带成本基础
  Assets:Stocks    1 AAPL {150.00 USD}
; 带价格注释
  Assets:Cash   -100 USD @ 1.25 CAD
; 带总价
  Assets:Cash   -100 USD @@ 125.00 CAD
; 隐式余额
  Assets:Cash   -100 USD
  Assets:Bank

余额断言 & 填充

2024-06-01 balance Assets:Checking 1000.00 USD
2024-06-01 pad Assets:Checking Equity:Opening-Balances

事件

2024-06-01 event "location" "San Francisco, CA"

选项

设置文件范围的配置：

option "title" "我的账本"
option "operating_currency" "USD"
option "documents" "docs/"
option "name_assets" "Vermoegen"

更多信息，请参阅 选项参考。

插件 & 文件组织

plugin "beancount.plugins.module_name"
plugin "beancount.plugins.module_name" "config-string"
include "other/file.beancount"
pushtag #project
; ...
poptag #project

重要规则

• 所有交易必须平衡（所有过账的总和为零；如果存在成本基础，则使用成本基础）。
• 账户必须在使用前打开；已关闭的账户不能接受过账。
• 余额断言仅检查指定的货币，并且可以在父账户上使用。
• 价格注释 (@) 仅供参考，不会影响平衡。

常见模式

使用初始余额开户

2024-01-01 open Assets:Checking USD
2024-01-01 pad Assets:Checking Equity:Opening-Balances
2024-01-01 balance Assets:Checking 1000.00 USD

投资交易

2024-01-01 * "Buy stock"
  Assets:Broker:Stock   10 AAPL {150.00 USD}
  Assets:Broker:Cash -1500.00 USD

多币种交易

2024-01-01 * "Currency exchange"
  Assets:USD   -100.00 USD @ 1.25 CAD
  Assets:CAD    125.00 CAD

评论

poptag  #trip-to-peru
; 行内评论以分号开头
* 任何不以有效指令开头的行也会被静默忽略