Синтаксис мови 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
; вбудовані коментарі починаються з крапки з комою
* будь-який рядок, що не починається з дійсної директиви, також мовчки ігнорується