Довідник синтаксису 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