Beancount-Syntaxreferenz: Direktiven, Konten, Beträge

Dies ist eine präzise und umfassende Referenz zur Beancount-Sprachsyntax, die praktische Struktur, Regeln und Beispiele kombiniert. Für weitere Details siehe das Spickzettel.

Überblick​

Beancount ist ein textbasiertes System für doppelte Buchführung. Seine Sprache basiert auf drei Hauptbausteinen:

• Waren (Währungen, Aktien, Punkte usw.)
• Konten (hierarchische, kategorisierte Hauptbücher)
• Direktiven (datierte Einträge, die Ereignisse oder Konfigurationen erfassen)

Waren​

Waren werden immer in Großbuchstaben geschrieben, z. B. USD, EUR, AAPL, BTC, MILES, HOURS.

Konten​

Konten sind durch Doppelpunkte getrennte, großgeschriebene hierarchische Namen. Sie müssen mit einem der fünf Wurzelkontotypen beginnen:

• Bestandteile müssen durch Doppelpunkte (:) getrennt sein, ohne Leerzeichen.
• Zahlen und Bindestriche sind in Bestandteilen erlaubt.
• Die Wurzelkontonamen können über Optionen angepasst werden (siehe unten).

Direktiven​

Direktiven sind die zentralen Anweisungen in einer Beancount-Datei. Die meisten beginnen mit einem Datum, gefolgt von einem Direktiventyp und Argumenten. Sie werden in chronologischer Reihenfolge (nach Datum) verarbeitet, nicht nach Dateireihenfolge.

Allgemeines Format:

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

Häufige Direktiven & Beispiele​

Konten eröffnen und schließen​

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

Waren deklarieren​

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

Preisfestlegungen​

2022-04-30 price AAPL 150.00 USD

Notizen & Dokumente​

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

Transaktionen​

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

Buchungspositionen​

; 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

Saldenprüfungen & Auffüllungen​

Die pad-Direktive muss vor der balance-Direktive datiert sein, da die Prüfung zu Beginn des Tages der balance-Direktive erfolgt:

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

Ereignisse​

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

Optionen​

Dateiweite Konfiguration festlegen:

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

Siehe die Optionsreferenz für weitere Details.

Plugins & Dateiorganisation​

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

Wichtige Regeln​

• Alle Transaktionen müssen ausgeglichen sein: Die Gewichte aller Buchungspositionen summieren sich zu null. Das Gewicht einer Buchungsposition ist ihr Betrag oder ihr Kostenwert ({}) oder Preis (@), der in die andere Währung umgerechnet wird, falls vorhanden.
• Konten müssen vor ihrer Verwendung eröffnet werden; geschlossene Konten können keine Buchungen aufnehmen.
• Saldenprüfungen prüfen nur die angegebene Währung, können auf übergeordneten Konten verwendet werden und werden zu Beginn ihres Datums ausgewertet (sie schließen also Transaktionen desselben Tages aus).
• Preisangaben (@ pro Einheit, @@ insgesamt) beeinflussen den Ausgleich: Sie setzen das Gewicht der Buchungsposition in der anderen Währung. -100 USD @ 1.25 CAD wiegt 125 CAD und gleicht eine 125 CAD-Buchung aus; entfernen Sie den Preis, ist die Transaktion nicht mehr ausgeglichen.

Häufige Muster​

Konto mit Anfangssaldo eröffnen​

Eröffnen Sie beide Konten, pad am Startdatum und prüfen Sie den Saldo am nächsten Tag (die Prüfung wird zu Beginn ihres Datums ausgewertet):

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

Investitionstransaktion​

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

Multivalutentransaktion​

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

Kommentare​

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