Referència de sintaxi de Beancount

Aquesta referència concisa però exhaustiva del llenguatge Beancount combina estructura pràctica, regles i exemples. Per a més detalls, consulteu el Full de resum.

Visió General​

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

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

Mercaderies​

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

Comptes​

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

• Els components han de començar amb majúscula, separats per dos punts (:), sense espais.
• Es permeten números i guions als components.
• Els noms dels comptes arrel es poden personalitzar mitjançant opcions (vegeu més avall).

Directives​

Les directives són les declaracions principals d'un fitxer Beancount. La majoria comencen amb una data, seguida del tipus de directiva i els arguments. Es processen en ordre cronològic (per data), no per ordre del 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

Per a cotitzacions de valoració automàtiques en un llibre allotjat, configureu Live Prices. Els feeds gestionats proporcionen directives price ordinàries datades. No substitueixen els preus de transacció (@, @@) ni els costos de lot ({}).

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 d'estar datat abans 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​

Configureu la configuració de tot el fitxer:

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

Vegeu 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

Beancount.io allotjat també resol les inclusions d'URL de preus gestionats compatibles. Aquesta és una extensió del Beancount original: utilitzeu la guia de configuració de Live Prices per a la compatibilitat allotjada i local.

Regles importants​

• Totes les transaccions han de quadrar: els pesos de totes les anotacions sumen zero. El pes d'una anotació és el seu import, o el seu cost ({}) o preu (@) convertit a l'altra divisa quan n'hi ha un.
• Els comptes s'han d'obrir abans d'usar-los; els comptes tancats no poden acceptar anotacions.
• Les assercions de saldo comproven només la divisa especificada, es poden usar en comptes pare 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 quadrament: estableixen el pes de l'anotació en l'altra divisa. -100 USD @ 1.25 CAD pesa 125 CAD i compensa una anotació de 125 CAD; elimineu el preu i la transacció ja no quadra.

Patrons comuns​

Obertura de comptes amb saldo inicial​

Obriu tots dos comptes, feu pad a la data d'inici i assegureu 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