Référence de syntaxe Beancount

Ceci fournit une référence concise mais complète de la syntaxe du langage Beancount, combinant structure pratique, règles et exemples. Pour plus de détails, voir l'Aide-mémoire.

Vue d'ensemble​

Beancount est un système de comptabilité en partie double en texte brut. Son langage est structuré autour de trois éléments fondamentaux :

• Les devises (monnaies, actions, points, etc.)
• Les comptes (grands livres hiérarchiques et catégorisés)
• Les directives (entrées datées enregistrant des événements ou de la configuration)

Devises​

Les devises sont toujours écrites en majuscules, par ex., USD, EUR, AAPL, BTC, MILES, HOURS.

Comptes​

Les comptes sont des noms hiérarchiques séparés par des deux-points, avec une majuscule initiale. Ils doivent commencer par l'un des cinq types de comptes racines :

• Les composants doivent être capitalisés, séparés par des deux-points (:), sans espaces.
• Les nombres et les tirets sont autorisés dans les composants.
• Les noms des comptes racines peuvent être personnalisés via les options (voir ci-dessous).

Directives​

Les directives sont les déclarations centrales dans un fichier Beancount. La plupart commencent par une date, suivie d'un type de directive et d'arguments. Elles sont traitées dans l'ordre chronologique (par date), et non dans l'ordre du fichier.

Format général :

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

Directives Courantes et Exemples​

Ouverture et Fermeture de Comptes​

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

Déclaration des Devises​

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

Déclarations de Prix​

2022-04-30 price AAPL 150.00 USD

Notes et Documents​

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

Transactions​

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

Caractéristiques des Écritures​

; 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 Solde et Remplissage (Padding)​

Le pad doit être daté avant le balance qu'il alimente, car l'assertion est vérifiée au début de son jour :

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

Événements​

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

Options​

Définir la configuration à l'échelle du fichier :

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

Voir la Référence des Options pour plus de détails.

Plugins et Organisation des Fichiers​

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

Règles Importantes​

• Toutes les transactions doivent être équilibrées : les poids de toutes les écritures doivent totaliser zéro. Le poids d'une écriture est son montant, ou son coût ({}) ou son prix (@) converti dans l'autre devise lorsqu'il est présent.
• Les comptes doivent être ouverts avant utilisation ; les comptes fermés ne peuvent pas accepter d'écritures.
• Les assertions de solde ne vérifient que la devise spécifiée, peuvent être utilisées sur les comptes parents, et sont évaluées au début de leur date (elles excluent donc les transactions du même jour).
• Les annotations de prix (@ par unité, @@ au total) affectent l'équilibrage : elles fixent le poids de l'écriture dans l'autre devise. -100 USD @ 1.25 CAD pèse 125 CAD et compense une écriture de 125 CAD ; retirez le prix et la transaction n'est plus équilibrée.

Modèles Courants​

Ouverture de Comptes avec Solde Initial​

Ouvrez les deux comptes, utilisez pad à la date de début, et vérifiez le solde le lendemain (l'assertion est vérifiée au début de sa date) :

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

Transaction d'Investissement​

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

Transaction Multi-Devises​

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

Commentaires​

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