Riferimento alla sintassi di Beancount

Questo fornisce un riferimento conciso ma completo per la sintassi del linguaggio Beancount, combinando struttura pratica, regole ed esempi. Per maggiori dettagli, consulta il Cheat Sheet.

Panoramica​

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

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

Merci​

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

Conti​

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

• I componenti devono avere l'iniziale maiuscola, essere separati da due punti (:) e non contenere spazi.
• Numeri e trattini sono consentiti 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 & 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

Per quotazioni di valutazione automatiche in un registro ospitato, configura i prezzi live. I feed gestiti forniscono normali direttive price datate. Non sostituiscono i prezzi delle transazioni (@, @@) o i costi dei lotti ({}).

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 che alimenta, perché l'assertion viene verificata all'inizio del suo giorno:

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"

Consulta il Riferimento delle opzioni per ulteriori 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

Beancount.io ospitato risolve anche gli include supportati degli URL di prezzi gestiti. Questa è un'estensione rispetto a Beancount upstream: usa la guida alla configurazione dei prezzi live per la compatibilità ospitata e locale.

Regole Importanti​

• Tutte le transazioni devono bilanciarsi: i pesi di tutte le registrazioni sommano a 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 assertion di saldo verificano solo la valuta specificata, possono essere usate sui conti padre e vengono valutate all'inizio della loro data (quindi escludono le transazioni dello stesso giorno).
• Le annotazioni di prezzo (@ per unità, @@ totale) influiscono sul 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 si bilancia più.

Modelli Comuni​

Apertura Conti con Saldo Iniziale​

Apri entrambi i conti, applica pad sulla data iniziale e verifica il saldo il giorno successivo (l'assertion viene verificata 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