Sintaxis del Lenguaje

Esta guía proporciona una referencia concisa pero completa de la sintaxis del lenguaje Beancount, combinando estructura práctica, reglas y ejemplos. Para más detalles, consulta la Hoja de Referencia Rápida.

Descripción General​

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

• Mercancías (monedas, acciones, puntos, etc.)
• Cuentas (libros contables jerárquicos y categorizados)
• Directivas (entradas fechadas que registran eventos o configuración)

Mercancías​

Las mercancías siempre se escriben en mayúsculas, por ejemplo, USD, EUR, AAPL, BTC, MILLAS, HORAS.

Cuentas​

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

• Los componentes deben estar en mayúscula inicial, separados por dos puntos (:) y 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 declaraciones principales en 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:

AAAA-MM-DD <directiva> <argumentos...>

Directivas Comunes y Ejemplos​

Apertura y Cierre de Cuentas​

2023-01-01 open Activos:CuentaCorriente USD,EUR  ; Opcionalmente especificar monedas permitidas
2023-12-31 close Activos:CuentaCorriente

Declaración de Mercancías​

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

Declaraciones de Precio​

2022-04-30 price AAPL 150.00 USD

Notas y Documentos​

2022-03-20 note Activos:CuentaCorriente "Consultó sobre reembolso"
2022-03-20 document Activos:CuentaCorriente "extractos/2022-03.pdf"

Transacciones​

2024-01-05 * "Cafetería" "Café matutino"
  Gastos:Comida         4.50 USD
  Activos:Efectivo     -4.50 USD
 
2024-01-06 ! "Factura Teléfono" "Pago mensual" #servicios ^telefono
  id: "FACT12345"              ; Metadatos
  Gastos:Servicios  60.00 USD
  Activos:CuentaCorriente

Características de las Partidas​

; Con base de costo
  Activos:Acciones    1 AAPL {150.00 USD}
; Con anotación de precio
  Activos:Efectivo   -100 USD @ 1.25 CAD
; Con precio total
  Activos:Efectivo   -100 USD @@ 125.00 CAD
; Saldo implícito
  Activos:Efectivo   -100 USD
  Activos:Banco

Validaciones de Saldo y Relleno​

2024-06-01 balance Activos:CuentaCorriente 1000.00 USD
2024-06-01 pad Activos:CuentaCorriente Patrimonio:Saldos-Iniciales

Eventos​

2024-06-01 event "ubicación" "San Francisco, CA"

Opciones​

Establecer configuración a nivel de archivo:

option "title" "Mi Libro Mayor"
option "operating_currency" "USD"
option "documents" "docs/"
option "name_assets" "Vermoegen"

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

Complementos y Organización de Archivos​

plugin "beancount.plugins.nombre_modulo"
plugin "beancount.plugins.nombre_modulo" "cadena-config"
include "otro/archivo.beancount"
pushtag #proyecto
; ...
poptag #proyecto

Reglas Importantes​

• Todas las transacciones deben estar balanceadas (la suma de todas las partidas es cero; se usa el costo base si está presente).
• Las cuentas deben abrirse antes de usarse; las cuentas cerradas no pueden aceptar partidas.
• Las validaciones de saldo solo verifican la moneda especificada y se pueden usar en cuentas padre.
• Las anotaciones de precio (@) son informativas y no afectan al balanceo.

Patrones Comunes​

Apertura de Cuentas con Saldo Inicial​

2024-01-01 open Activos:CuentaCorriente USD
2024-01-01 pad Activos:CuentaCorriente Patrimonio:Saldos-Iniciales
2024-01-01 balance Activos:CuentaCorriente 1000.00 USD

Transacción de Inversión​

2024-01-01 * "Compra de acciones"
  Activos:Corredor:Acciones   10 AAPL {150.00 USD}
  Activos:Corredor:Efectivo -1500.00 USD

Transacción Multimoneda​

2024-01-01 * "Cambio de moneda"
  Activos:USD   -100.00 USD @ 1.25 CAD
  Activos:CAD    125.00 CAD

Comentarios​

poptag  #viaje-a-peru
; los comentarios en línea comienzan con punto y coma
* cualquier línea que no comience con una directiva válida también se ignora silenciosamente