Beancount-Syntaxreferenz: Direktiven, Konten, Beträge

Dies bietet eine prägnante und zugleich umfassende Referenz für die Beancount-Sprachsyntax, die praktische Struktur, Regeln und Beispiele miteinander verbindet. Weitere Details finden Sie im Cheat Sheet.

Überblick​

Beancount ist ein Klartext-Doppelbuchhaltungssystem. Seine Sprache ist um drei Hauptbausteine herum strukturiert:

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

Waren​

Commodities 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 Kontenwurzeltypen beginnen:

• Komponenten müssen großgeschrieben und durch Doppelpunkte (:) getrennt sein, ohne Leerzeichen.
• Zahlen und Bindestriche sind in Komponenten erlaubt.
• Die Namen der Wurzelkonten können über Optionen angepasst werden (siehe unten).

Direktiven​

Direktiven sind die Kernanweisungen in einer Beancount-Datei. Die meisten beginnen mit einem Datum, gefolgt von einem Direktivtyp und Argumenten. Sie werden in chronologischer Reihenfolge (nach Datum) verarbeitet, nicht in 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

Für automatische Bewertungskurse in einem gehosteten Hauptbuch richten Sie Live Prices ein. Verwaltete Feeds liefern gewöhnliche datierte price-Direktiven. Sie ersetzen weder Transaktionspreise (@, @@) noch Loskosten ({}).

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​

Das pad muss vor dem balance datiert sein, das es speist, da die Assertion zu Beginn ihres Tages geprüft wird:

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"

Weitere Informationen finden Sie in der Options Reference.

Plugins & Dateiorganisation​

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

Das gehostete Beancount.io löst auch unterstützte verwaltete Preis-URL-Includes auf. Dies ist eine Erweiterung gegenüber dem ursprünglichen Beancount: Verwenden Sie den Live Prices-Einrichtungsleitfaden für gehostete und lokale Kompatibilität.

Wichtige Regeln​

• Alle Transaktionen müssen ausgeglichen sein: Die Gewichte aller Buchungen summieren sich zu null. Das Gewicht einer Buchung ist ihr Betrag oder ihre Kosten ({}) bzw. ihr Preis (@), in die andere Währung umgerechnet, wenn eine vorhanden ist.
• Konten müssen vor der Verwendung eröffnet werden; geschlossene Konten können keine Buchungen annehmen.
• Saldo-Assertions prüfen nur die angegebene Währung, können auf übergeordneten Konten verwendet werden und werden zu Beginn ihres Datums ausgewertet (schließen also Transaktionen desselben Tages aus).
• Preisanmerkungen (@ pro Einheit, @@ gesamt) wirken sich auf den Ausgleich aus: Sie legen das Gewicht der Buchung in der anderen Währung fest. -100 USD @ 1.25 CAD wiegt 125 CAD und gleicht eine 125 CAD-Buchung aus; entfernen Sie den Preis, und die Transaktion gleicht nicht mehr aus.

Häufige Muster​

Konto mit Anfangssaldo eröffnen​

Eröffnen Sie beide Konten, pad am Startdatum und assertion Sie den Saldo am nächsten Tag (die Assertion wird zu Beginn ihres Datums geprüft):

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