Справочник по синтаксису Beancount: директивы, счета, суммы

Здесь представлен краткий, но вместе с тем исчерпывающий справочник по синтаксису языка Beancount, объединяющий практическую структуру, правила и примеры. Подробнее см. Шпаргалку.

Обзор​

Beancount — это система двойной записи на основе обычного текста. Её язык построен вокруг трёх основных строительных блоков:

• Товары (валюты, акции, баллы и т. д.)
• Счета (иерархические, категоризированные журналы)
• Директивы (датированные записи, фиксирующие события или конфигурацию)

Товары​

Товары всегда записываются заглавными буквами, например: USD, EUR, AAPL, BTC, MILES, HOURS.

Счета​

Счета — это иерархические имена, разделённые двоеточиями и начинающиеся с заглавной буквы. Они должны начинаться с одного из пяти корневых типов счетов:

• Компоненты должны начинаться с заглавной буквы, разделяться двоеточиями (:), без пробелов.
• В компонентах допускаются цифры и дефисы.
• Имена корневых счетов можно настроить с помощью опций (см. ниже).

Директивы​

Директивы — это основные инструкции в файле Beancount. Большинство начинаются с даты, за которой следует тип директивы и аргументы. Они обрабатываются в хронологическом порядке (по дате), а не в порядке следования в файле.

Общий формат:

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

Распространённые директивы и примеры​

Открытие и закрытие счетов​

2023-01-01 open Assets:Checking USD,EUR  ; Optionally specify allowed currencies
2023-12-31 close Assets:Checking

Объявление товаров​

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

Объявление цен​

2022-04-30 price AAPL 150.00 USD

Для автоматических котировок оценки в размещённом журнале настройте Live Prices. Управляемые потоки данных предоставляют обычные датированные директивы price. Они не заменяют цены транзакций (@, @@) или затраты по лотам ({}).

Заметки и документы​

2022-03-20 note Assets:Checking "Asked about refund"
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"              ; Metadata
  Expenses:Utilities  60.00 USD
  Assets:Checking

Особенности проводок​

; With cost basis
  Assets:Stocks    1 AAPL {150.00 USD}
; With price annotation
  Assets:Cash   -100 USD @ 1.25 CAD
; With total price
  Assets:Cash   -100 USD @@ 125.00 CAD
; Implicit balance
  Assets:Cash   -100 USD
  Assets:Bank

Проверка остатков и выравнивание​

pad должен быть датирован раньше balance, который он обеспечивает, поскольку проверка утверждения выполняется в начале его дня:

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

События​

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

Опции​

Настройка конфигурации на уровне всего файла:

option "title" "My Ledger"
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

Размещённый Beancount.io также обрабатывает включения поддерживаемых управляемых URL цен. Это расширение по отношению к оригинальному Beancount: используйте руководство по настройке Live Prices для совместимости с размещённой и локальной версиями.

Важные правила​

• Все транзакции должны балансироваться: веса всех проводок в сумме дают ноль. Вес проводки — это её сумма, либо её стоимость ({}) или цена (@), пересчитанные в другую валюту, когда одна из них указана.
• Счета должны быть открыты до использования; закрытые счета не могут принимать проводки.
• Проверки баланса проверяют только указанную валюту, могут применяться к родительским счетам и оцениваются в начале своей даты (таким образом, они исключают транзакции того же дня).
• Аннотации цен (@ за единицу, @@ всего) влияют на балансировку: они задают вес проводки в другой валюте. -100 USD @ 1.25 CAD весит 125 CAD и компенсирует проводку 125 CAD; уберите цену — и транзакция перестанет балансироваться.

Распространённые шаблоны​

Открытие счетов с начальным остатком​

Откройте оба счета, укажите pad на начальную дату и утвердите баланс на следующий день (утверждение проверяется в начале своей даты):

2024-01-01 open Assets:Checking USD
2024-01-01 open Equity:Opening-Balances
2024-01-01 pad Assets:Checking Equity:Opening-Balances
2024-01-02 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
; inline comments begin with a semi-colon
* any line not starting with a valid directive is also ignored silently