Sintassi del Linguaggio

Questa è una guida di riferimento concisa ma completa per la sintassi del linguaggio Beancount, che unisce struttura pratica, regole ed esempi. Per maggiori dettagli, consulta il Cheat Sheet.

Panoramica​

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

• Materie (valute, azioni, punti, ecc.)
• Conti (registrazioni gerarchiche e categorizzate)
• Direttive (voci datate che registrano eventi o configurazioni)

Materie​

Le materie sono sempre scritte in maiuscolo, ad esempio USD, EUR, AAPL, BTC, MILES, HOURS.

Conti​

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

• I componenti devono essere in maiuscolo, separati da due punti (:), senza spazi.
• Sono consentiti numeri e trattini nei componenti.
• I nomi dei conti radice possono essere personalizzati tramite opzioni (vedi sotto).

Direttive​

Le direttive sono le istruzioni principali 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 ed 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 Materie​

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

Dichiarazioni di Prezzo​

2022-04-30 price AAPL 150.00 USD

Note e 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

Caratteristiche 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 e Padding​

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

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"

Consulta il Riferimento alle Opzioni per maggiori dettagli.

Plugin e 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 essere bilanciate (la somma di tutte le registrazioni è zero; se presente, si usa il costo base).
• I conti devono essere aperti prima dell'uso; i conti chiusi non possono accettare registrazioni.
• Le verifiche di saldo controllano solo la valuta specificata e possono essere utilizzate sui conti padre.
• Le annotazioni di prezzo (@) sono informative e non influenzano il bilanciamento.

Schemi Comuni​

Apertura dei Conti con Saldo Iniziale​

2024-01-01 open Assets:Checking USD
2024-01-01 pad Assets:Checking Equity:Opening-Balances
2024-01-01 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