Справка за синтаксиса на Beancount: директиви, сметки, суми

Това предоставя сбита, но изчерпателна справка за синтаксиса на езика Beancount, съчетавайки практическа структура, правила и примери. За повече подробности вижте Cheat Sheet.

Преглед​

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