Syntaxe du langage Beancount

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

Aperçu

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

• Biens (devises, actions, points, etc.)
• Comptes (grands livres hiérarchiques et catégorisés)
• Directives (écritures datées enregistrant des événements ou une configuration)

Biens

Les biens sont toujours écrits en majuscules, par exemple, USD, EUR, AAPL, BTC, MILES, HOURS.

Comptes

Les comptes sont des noms hiérarchiques capitalisés et séparés par des deux-points. Ils doivent commencer par l'un des cinq types de comptes racines :

Nom	Type	Contenu typique	Exemple
Assets	+	Espèces, Banque, Investissements	Assets:Checking
Liabilities	-	Cartes de crédit, Prêts	Liabilities:CreditCard
Income	-	Salaire, Intérêts	Income:EmployerA
Expenses	+	Achats, Factures	Expenses:Food:Dining
Equity	-	Soldes d'ouverture/de clôture	Equity:Opening-Balances

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

Directives

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

Format général :

AAAA-MM-JJ <directive> <arguments...>

Directives courantes et exemples

Ouverture et fermeture de comptes

2023-01-01 open Assets:Checking USD,EUR  ; Spécifier éventuellement les devises autorisées
2023-12-31 close Assets:Checking

Déclaration de biens

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 "Renseignement sur le remboursement"
2022-03-20 document Assets:Checking "statements/2022-03.pdf"

Transactions

2024-01-05 * "Coffee Shop" "Café du matin"
  Expenses:Food         4.50 USD
  Assets:Cash         -4.50 USD

2024-01-06 ! "Facture de téléphone" "Paiement mensuel" #utilities ^phone
  id: "INV12345"              ; Métadonnées
  Expenses:Utilities  60.00 USD
  Assets:Checking

Fonctionnalités de publication

; Avec coût de base
  Assets:Stocks    1 AAPL {150.00 USD}
; Avec annotation de prix
  Assets:Cash   -100 USD @ 1.25 CAD
; Avec prix total
  Assets:Cash   -100 USD @@ 125.00 CAD
; Solde implicite
  Assets:Cash   -100 USD
  Assets:Bank

Assertions de solde et remplissage

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

Événements

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

Options

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

option "title" "Mon grand livre"
option "operating_currency" "USD"
option "documents" "docs/"
option "name_assets" "Vermoegen"

Voir la Référence des options pour plus d'informations.

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 s'équilibrer (la somme de toutes les écritures est égale à zéro ; le coût de base est utilisé s'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 et peuvent être utilisées sur les comptes parents.
• Les annotations de prix (@) sont informatives et n'affectent pas l'équilibrage.

Modèles courants

Ouverture de comptes avec solde initial

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

Transaction d'investissement

2024-01-01 * "Achat d'actions"
  Assets:Broker:Stock   10 AAPL {150.00 USD}
  Assets:Broker:Cash -1500.00 USD

Transaction multi-devises

2024-01-01 * "Change de devises"
  Assets:USD   -100.00 USD @ 1.25 CAD
  Assets:CAD    125.00 CAD

Commentaires

poptag  #trip-to-peru
; les commentaires en ligne commencent par un point-virgule
* toute ligne ne commençant pas par une directive valide est également ignorée silencieusement