# 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](https://beancount.io/it/docs/Basics/cheatsheet).

## 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:

| Nome          | Tipo | Contenuti tipici         | Esempio                   |
| ------------- | ---- | ------------------------ | ------------------------- |
| `Assets`      | +    | Contanti, Banca, Investimenti  | `Assets:Checking`         |
| `Liabilities` | -    | Carte di credito, Prestiti      | `Liabilities:CreditCard`  |
| `Income`      | -    | Stipendio, Interessi         | `Income:EmployerA`        |
| `Expenses`    | +    | Acquisti, Bollette         | `Expenses:Food:Dining`    |
| `Equity`      | -    | Saldi di apertura/chiusura | `Equity:Opening-Balances` |

- 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:**

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

### Direttive Comuni & Esempi

#### Apertura e Chiusura dei Conti

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

#### Dichiarazione delle Merci

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

#### Dichiarazioni di Prezzo

```bean
2022-04-30 price AAPL 150.00 USD
```

Per quotazioni di valutazione automatiche in un registro ospitato, [configura i prezzi live](https://beancount.io/it/docs/live-prices). I feed gestiti forniscono normali direttive `price` datate. Non sostituiscono i prezzi delle transazioni (`@`, `@@`) o i costi dei lotti (`{}`).

#### Note & Documenti

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

#### Transazioni

```bean
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

```bean
; 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:

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

#### Eventi

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

## Opzioni

Imposta la configurazione a livello di file:

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

Consulta il [Riferimento delle opzioni](http://furius.ca/beancount/doc/options) per ulteriori informazioni.

## Plugin & Organizzazione dei File

```bean
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](https://beancount.io/it/docs/live-prices) 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):

```bean
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

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

### Transazione Multi-Valuta

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

### Commenti

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