Riferimento alla sintassi di Beancount

Questa è una guida concisa ma completa alla sintassi del linguaggio Beancount, che fonde struttura pratica, regole ed esempi. Per maggiori dettagli, vedi il Cheat Sheet.

Panoramica​

Beancount è un sistema di contabilità a partita doppia in testo semplice. Il suo linguaggio è strutturato attorno a tre elementi principali:

• Merci (valute, azioni, punti, ecc.)
• Conti (registri gerarchici e categorizzati)
• Direttive (voci datate che registrano eventi o configurazioni)

Merci​

Le merci sono sempre scritte in maiuscolo, es. USD, EUR, AAPL, BTC, MILES, HOURS.

Conti​

I conti sono nomi gerarchici separati da due punti e con lettere maiuscole. Devono iniziare con uno dei cinque tipi di conto radice:

• I componenti devono avere la prima lettera maiuscola, essere separati da due punti (:), senza spazi.
• Numeri e trattini sono consentiti nei componenti.
• I nomi dei conti radice possono essere personalizzati tramite le opzioni (vedi sotto).

Direttive​

Le direttive sono le istruzioni fondamentali in un file Beancount. La maggior parte inizia con una data, seguita dal tipo di direttiva e dagli argomenti. Vengono elaborate in ordine cronologico (per data), non in ordine di file.

Formato generale:

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

Direttive Comuni & Esempi​

Apertura e Chiusura dei Conti​

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

Dichiarazione delle Merci​

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

Dichiarazioni di Prezzo​

2022-04-30 price AAPL 150.00 USD

Note & Documenti​

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

Transazioni​

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

Funzionalità delle Registrazioni​

; 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

Verifiche di Saldo & Padding​

Il pad deve essere datato prima del balance a cui si riferisce, perché la verifica viene effettuata all'inizio del giorno della data:

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

Eventi​

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

Opzioni​

Imposta la configurazione a livello di file:

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

Vedi il Riferimento delle Opzioni per maggiori informazioni.

Plugin & Organizzazione dei File​

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

Regole Importanti​

• Tutte le transazioni devono bilanciare: la somma dei pesi di tutte le registrazioni deve essere zero. Il peso di una registrazione è il suo importo, oppure il suo costo ({}) o prezzo (@) convertito nell'altra valuta quando presente.
• I conti devono essere aperti prima dell'uso; i conti chiusi non possono accettare registrazioni.
• Le verifiche di saldo controllano solo la valuta specificata, possono essere usate sui conti genitore e vengono valutate all'inizio della loro data (quindi escludono le transazioni dello stesso giorno).
• Le annotazioni di prezzo (@ per unità, @@ totale) influenzano il bilanciamento: impostano il peso della registrazione nell'altra valuta. -100 USD @ 1.25 CAD pesa 125 CAD e compensa una registrazione di 125 CAD; rimuovi il prezzo e la transazione non è più bilanciata.

Modelli Comuni​

Apertura Conti con Saldo Iniziale​

Apri entrambi i conti, usa pad alla data di inizio e verifica il saldo il giorno successivo (la verifica viene controllata all'inizio della sua 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

Transazione di Investimento​

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

Transazione Multi-Valuta​

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

Commenti​

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