Справочник по синтаксису 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

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

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

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

• Все транзакции должны быть сбалансированы: сумма весов всех проводок равна нулю. Вес проводки — это её сумма, или её себестоимость ({}) или цена (@), конвертированные в другую валюту, если она указана.
• Счета должны быть открыты до использования; на закрытые счета нельзя делать проводки.
• Проверка остатков проверяет только указанную валюту, может использоваться на родительских счетах и выполняется на начало даты (таким образом, она не учитывает операции того же дня).
• Ценовые аннотации (@ за единицу, @@ за сумму) влияют на балансировку: они устанавливают вес проводки в другой валюте. Например, -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