Beancount-syntaxreferentie: richtlijnen, rekeningen

Dit biedt een beknopte maar uitgebreide referentie voor de syntaxis van de Beancount-taal, met een combinatie van praktische structuur, regels en voorbeelden. Zie voor meer details het Cheat Sheet.

Overzicht​

Beancount is een plain-text dubbel boekhoudsysteem. De taal is opgebouwd rond drie hoofdelementen:

• Commodities (valuta's, aandelen, punten, enz.)
• Accounts (hiërarchische, gecategoriseerde grootboeken)
• Directives (gedateerde vermeldingen die gebeurtenissen of configuratie vastleggen)

Goederen​

Commodities worden altijd in hoofdletters geschreven, bijvoorbeeld USD, EUR, AAPL, BTC, MILES, HOURS.

Rekeningen​

Accounts zijn hiërarchische namen met dubbele punten als scheidingsteken en beginnen met een hoofdletter. Ze moeten beginnen met een van de vijf hoofdaccounttypen:

• Componenten moeten met een hoofdletter beginnen en gescheiden worden door dubbele punten (:), zonder spaties.
• Cijfers en streepjes zijn toegestaan in componenten.
• De namen van de hoofdaccounts kunnen worden aangepast via opties (zie hieronder).

Richtlijnen​

Directives zijn de kernstatements in een Beancount-bestand. De meeste beginnen met een datum, gevolgd door een directive-type en argumenten. Ze worden verwerkt in chronologische volgorde (op datum), niet in bestandsvolgorde.

Algemeen formaat:

YYYY-MM-DD <directive> <arguments...>

Veelvoorkomende richtlijnen en voorbeelden​

Rekeningen openen en sluiten​

2023-01-01 open Assets:Checking USD,EUR  ; Optionally specify allowed currencies
2023-12-31 close Assets:Checking

Goederen declareren​

2020-07-22 commodity AAPL
  name: "Apple Inc."

Prijsdeclaraties​

2022-04-30 price AAPL 150.00 USD

Voor automatische waarderingskoersen in een gehost grootboek, stel Live Prices in. Beheerde feeds leveren gewone gedateerde price-directives. Ze vervangen geen transactieprijzen (@, @@) of lotkosten ({}).

Notities en documenten​

2022-03-20 note Assets:Checking "Asked about refund"
2022-03-20 document Assets:Checking "statements/2022-03.pdf"

Transacties​

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

Boekingseigenschappen​

; 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

Saldo-asserties en aanvullingen​

De pad moet gedateerd zijn vóór de balance die deze voedt, omdat de assertie wordt gecontroleerd aan het begin van de dag:

2024-06-01 pad Assets:Checking Equity:Opening-Balances
2024-06-02 balance Assets:Checking 1000.00 USD

Gebeurtenissen​

2024-06-01 event "location" "San Francisco, CA"

Opties​

Bestandsbrede configuratie instellen:

option "title" "My Ledger"
option "operating_currency" "USD"
option "documents" "docs/"
option "name_assets" "Vermoegen"

Zie de Options Reference voor meer.

Plugins en bestandsorganisatie​

plugin "beancount.plugins.module_name"
plugin "beancount.plugins.module_name" "config-string"
include "other/file.beancount"
pushtag #project
; ...
poptag #project

Gehoste Beancount.io verwerkt ook ondersteunde managed price-URL-includes. Dit is een uitbreiding op upstream Beancount: gebruik de Live Prices-installatiegids voor gehoste en lokale compatibiliteit.

Belangrijke regels​

• Alle transacties moeten in balans zijn: de gewichten van alle postings tellen op tot nul. Het gewicht van een posting is het bedrag, of de kosten ({}) of prijs (@) omgerekend naar de andere valuta wanneer die aanwezig is.
• Accounts moeten worden geopend voordat ze worden gebruikt; gesloten accounts kunnen geen postings accepteren.
• Balansasserties controleren alleen de opgegeven valuta, kunnen worden gebruikt op bovenliggende accounts en worden geëvalueerd aan het begin van hun datum (dus exclusief transacties van dezelfde dag).
• Prijsannotaties (@ per eenheid, @@ totaal) beïnvloeden de balans: ze bepalen het gewicht van de posting in de andere valuta. -100 USD @ 1.25 CAD weegt 125 CAD en compenseert een posting van 125 CAD; verwijder de prijs en de transactie is niet meer in balans.

Veelvoorkomende patronen​

Rekeningen openen met beginsaldo​

Open beide accounts, pad op de startdatum, en stel de balans de volgende dag vast (de assertie wordt gecontroleerd aan het begin van de datum):

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

Investeringstransactie​

2024-01-01 * "Buy stock"
  Assets:Broker:Stock   10 AAPL {150.00 USD}
  Assets:Broker:Cash -1500.00 USD

Transactie met meerdere valuta's​

2024-01-01 * "Currency exchange"
  Assets:USD   -100.00 USD @ 1.25 CAD
  Assets:CAD    125.00 CAD

Opmerkingen​

poptag  #trip-to-peru
; inline comments begin with a semi-colon
* any line not starting with a valid directive is also ignored silently