Referència de sintaxi de Beancount

Això proporciona una referència concisa però completa per a la sintaxi del llenguatge Beancount, combinant estructura pràctica, regles i exemples. Per a més detalls, consulta la Fitxa de Referència Ràpida.

Visió General​

Beancount és un sistema de comptabilitat de doble entrada en text pla. El seu llenguatge s'estructura al voltant de tres blocs principals:

• Mercaderies (monedes, accions, punts, etc.)
• Comptes (llibres jeràrquics i categoritzats)
• Directives (entrades datades que registren esdeveniments o configuració)

Mercaderies​

Les mercaderies s'escriuen sempre en majúscules, p. ex., USD, EUR, AAPL, BTC, MILES, HOURS.

Comptes​

Els comptes són noms jeràrquics separats per dos punts i capitalitzats. Han de començar amb un dels cinc tipus de compte arrel:

• Els components han d'anar capitalitzats, separats per dos punts (:), sense espais.
• S'admeten números i guions en els components.
• Els noms dels comptes arrel es poden personalitzar mitjançant opcions (vegeu més avall).

Directives​

Les directives són les declaracions principals en un fitxer Beancount. La majoria comencen amb una data, seguida del tipus de directiva i arguments. Es processen en ordre cronològic (per data), no en ordre de fitxer.

Format general:

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

Directives comunes i exemples​

Obertura i tancament de comptes​

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

Declaració de mercaderies​

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

Declaracions de preu​

2022-04-30 price AAPL 150.00 USD

Notes i documents​

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

Transaccions​

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

Característiques de les anotacions​

; 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

Assertions de saldo i coixí (padding)​

El pad ha de portar una data anterior a la del balance que alimenta, perquè l'asserció es comprova a l'inici del seu dia:

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

Esdeveniments​

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

Opcions​

Estableix la configuració global del fitxer:

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

Consulta la Referència d'Opcions per a més informació.

Connectors (Plugins) i organització de fitxers​

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

Regles importants​

• Totes les transaccions han de quadrar: els pesos de totes les anotacions han de sumar zero. El pes d'una anotació és el seu import, o el seu cost ({}) o preu (@) convertit a l'altra moneda quan n'hi ha un.
• Els comptes s'han d'obrir abans d'utilitzar-los; els comptes tancats no poden acceptar anotacions.
• Les assertions de saldo comproven només la moneda especificada, es poden utilitzar en comptes pares i s'avaluen a l'inici de la seva data (per tant, exclouen les transaccions del mateix dia).
• Les anotacions de preu (@ per unitat, @@ total) sí afecten el balanç: estableixen el pes de l'anotació en l'altra moneda. -100 USD @ 1.25 CAD pesa 125 CAD i compensa una anotació de 125 CAD; si elimines el preu, la transacció ja no quadra.

Patrons comuns​

Obertura de comptes amb saldo inicial​

Obre tots dos comptes, afegeix el pad en la data d'inici i asserta el saldo l'endemà (l'asserció es comprova a l'inici de la seva data):

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

Transacció d'inversió​

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

Transacció multidivisa​

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

Comentaris​

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