Синтаксис языка 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 <директива> <аргументы...>

Общие директивы и примеры

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

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 * "Кофейня" "Утренний кофе"
  Expenses:Food         4.50 USD
  Assets:Cash         -4.50 USD

2024-01-06 ! "Счет за телефон" "Ежемесячный платеж" #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 * "Купить акции"
  Assets:Broker:Stock   10 AAPL {150.00 USD}
  Assets:Broker:Cash -1500.00 USD

Мультивалютная транзакция

2024-01-01 * "Обмен валюты"
  Assets:USD   -100.00 USD @ 1.25 CAD
  Assets:CAD    125.00 CAD

Комментарии

poptag  #trip-to-peru
; встроенные комментарии начинаются с точки с запятой
* любая строка, не начинающаяся с допустимой директивы, также игнорируется молча