Referencia de sintaxis de Beancount

Esta es una referencia concisa pero completa de la sintaxis del lenguaje Beancount, que combina estructura práctica, reglas y ejemplos. Para más detalles, consulta la Chuleta.

Resumen​

Beancount es un sistema de contabilidad por partida doble en texto plano. Su lenguaje se estructura en torno a tres bloques fundamentales:

• Commodities (monedas, acciones, puntos, etc.)
• Cuentas (libros jerárquicos y categorizados)
• Directivas (entradas con fecha que registran eventos o configuración)

Mercancías​

Las commodities siempre se escriben en mayúsculas, por ejemplo: USD, EUR, AAPL, BTC, MILES, HOURS.

Cuentas​

Las cuentas son nombres jerárquicos separados por dos puntos y con mayúscula inicial. Deben comenzar por uno de los cinco tipos de cuenta raíz:

• Los componentes deben empezar con mayúscula, separados por dos puntos (:), sin espacios.
• Se permiten números y guiones en los componentes.
• Los nombres de las cuentas raíz se pueden personalizar mediante opciones (ver más abajo).

Directivas​

Las directivas son las sentencias fundamentales de un archivo Beancount. La mayoría comienza con una fecha, seguida del tipo de directiva y sus argumentos. Se procesan en orden cronológico (por fecha), no en el orden del archivo.

Formato general:

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

Directivas Comunes y Ejemplos​

Apertura y Cierre de Cuentas​

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

Declaración de Mercancías​

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

Declaraciones de Precio​

2022-04-30 price AAPL 150.00 USD

Para obtener cotizaciones de valoración automáticas en un libro alojado, configura Live Prices. Los feeds gestionados proporcionan directivas price fechadas ordinarias. No sustituyen a los precios de transacción (@, @@) ni a los costes de lote ({}).

Notas y Documentos​

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

Transacciones​

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

Características de las Anotaciones​

; 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

Verificaciones de Saldo y Relleno (Padding)​

El pad debe tener fecha anterior al balance que alimenta, porque la aserción se comprueba al inicio de su día:

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

Eventos​

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

Opciones​

Configuración para todo el archivo:

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

Consulta la Referencia de opciones para más información.

Plugins y Organización de Archivos​

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

Beancount.io alojado también resuelve las inclusiones de URL de precios gestionados compatibles. Esto es una extensión respecto a Beancount original: utiliza la guía de configuración de Live Prices para compatibilidad tanto alojada como local.

Reglas Importantes​

• Todas las transacciones deben cuadrar: los pesos de todos los postings suman cero. El peso de un posting es su monto, o su coste ({}) o precio (@) convertido a la otra moneda cuando alguno está presente.
• Las cuentas deben abrirse antes de usarse; las cuentas cerradas no pueden aceptar postings.
• Las aserciones de saldo solo comprueban la moneda especificada, pueden usarse en cuentas padre, y se evalúan al inicio de su fecha (por lo que excluyen las transacciones del mismo día).
• Las anotaciones de precio (@ por unidad, @@ total) sí afectan al cuadre: establecen el peso del posting en la otra moneda. -100 USD @ 1.25 CAD pesa 125 CAD y compensa un posting de 125 CAD; elimina el precio y la transacción deja de cuadrar.

Patrones Comunes​

Apertura de Cuentas con Saldo Inicial​

Abre ambas cuentas, aplica pad en la fecha de inicio y declara la aserción de saldo al día siguiente (la aserción se comprueba al inicio de su fecha):

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

Transacción de Inversión​

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

Transacción Multimoneda​

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

Comentarios​

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