Beancount-syntaxreferentie: richtlijnen, rekeningen

Dit biedt een beknopte maar uitgebreide referentie voor de Beancount-taalsyntaxis, met een mix van praktische structuur, regels en voorbeelden. Voor meer details, zie het Spiekbriefje.

Overzicht​

Beancount is een boekhoudsysteem met dubbele boekhouding op basis van platte tekst. De taal is opgebouwd rond drie hoofdbouwstenen:

• Goederen (valuta's, aandelen, punten, enz.)
• Rekeningen (hiërarchische, gecategoriseerde grootboeken)
• Richtlijnen (gedateerde vermeldingen die gebeurtenissen of configuratie vastleggen)

Goederen​

Goederen worden altijd in hoofdletters geschreven, bijv. USD, EUR, AAPL, BTC, MILES, HOURS.

Rekeningen​

Rekeningen zijn hiërarchische namen, gescheiden door dubbele punten en met hoofdletters. Ze moeten beginnen met een van de vijf hoofdrekeningtypen:

• Onderdelen moeten met hoofdletters beginnen, gescheiden door dubbele punten (:), zonder spaties.
• Cijfers en streepjes zijn toegestaan in onderdelen.
• De hoofdrekeningnamen kunnen worden aangepast via opties (zie hieronder).

Richtlijnen​

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

Algemene indeling:

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

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 hij 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​

Stel bestandsbrede configuratie in:

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

Zie de Optiereferentie 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

Belangrijke regels​

• Alle transacties moeten in balans zijn: de gewichten van alle boekingen moeten optellen tot nul. Het gewicht van een boeking is het bedrag, of de kostprijs ({}) of prijs (@) omgerekend naar de andere valuta wanneer deze aanwezig is.
• Rekeningen moeten geopend zijn vóór gebruik; gesloten rekeningen kunnen geen boekingen accepteren.
• Saldo-asserties controleren alleen de opgegeven valuta, kunnen worden gebruikt op bovenliggende rekeningen en worden geëvalueerd aan het begin van hun datum (dus ze sluiten transacties van dezelfde dag uit).
• Prijsannotaties (@ per eenheid, @@ totaal) beïnvloeden wel de balancering: ze stellen het gewicht van de boeking in de andere valuta in. -100 USD @ 1.25 CAD weegt 125 CAD en compenseert een 125 CAD-boeking; verwijder de prijs en de transactie is niet langer in balans.

Veelvoorkomende patronen​

Rekeningen openen met beginsaldo​

Open beide rekeningen, pad op de startdatum en assert het saldo de volgende dag (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