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