Referência de sintaxe do Beancount

Esta referência concisa, porém abrangente, da sintaxe da linguagem Beancount combina estrutura prática, regras e exemplos. Para mais detalhes, consulte a Cheat Sheet.

Visão Geral​

O Beancount é um sistema de contabilidade de partidas dobradas em texto simples. Sua linguagem é estruturada em torno de três blocos de construção principais:

• Commodities (moedas, ações, pontos, etc.)
• Contas (livros-razão hierárquicos e categorizados)
• Diretivas (lançamentos datados que registram eventos ou configuração)

Commodities​

As commodities são sempre escritas em maiúsculas, por exemplo, USD, EUR, AAPL, BTC, MILES, HOURS.

Contas​

As contas são nomes hierárquicos separados por dois-pontos e com iniciais maiúsculas. Elas devem começar com um dos cinco tipos de conta raiz:

• Os componentes devem ter iniciais maiúsculas, separados por dois-pontos (:), sem espaços.
• Números e hífens são permitidos nos componentes.
• Os nomes das contas raiz podem ser personalizados por meio de opções (veja abaixo).

Diretivas​

As diretivas são as instruções centrais em um arquivo Beancount. A maioria começa com uma data, seguida por um tipo de diretiva e argumentos. Elas são processadas em ordem cronológica (por data), não na ordem do arquivo.

Formato geral:

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

Diretivas Comuns e Exemplos​

Abertura e Fechamento de Contas​

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

Declaração de Commodities​

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

Declarações de Preço​

2022-04-30 price AAPL 150.00 USD

Para cotações de avaliação automáticas em um livro-razão hospedado, configure Preços ao Vivo. Feeds gerenciados fornecem diretivas price datadas comuns. Eles não substituem preços de transação (@, @@) ou custos de lote ({}).

Notas e Documentos​

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

Transações​

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 Lançamentos​

; 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

Verificações de Saldo e Preenchimento​

O pad deve ser datado antes do balance que ele alimenta, porque a asserção é verificada no início do seu dia:

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"

Opções​

Defina a configuração para todo o arquivo:

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

Consulte a Referência de Opções para mais informações.

Plugins e Organização de Arquivos​

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

O Beancount.io hospedado também resolve inclusões de URL de preços gerenciados suportadas. Esta é uma extensão ao Beancount original: use o guia de configuração de Preços ao Vivo para compatibilidade hospedada e local.

Regras Importantes​

• Todas as transações devem balancear: os pesos de todos os lançamentos somam zero. O peso de um lançamento é o seu montante, ou o seu custo ({}) ou preço (@) convertido para a outra moeda quando um estiver presente.
• As contas devem ser abertas antes do uso; contas fechadas não podem aceitar lançamentos.
• As asserções de saldo verificam apenas a moeda especificada, podem ser usadas em contas pai e são avaliadas no início de sua data (portanto, excluem transações do mesmo dia).
• As anotações de preço (@ por unidade, @@ total) afetam o balanceamento: elas definem o peso do lançamento na outra moeda. -100 USD @ 1.25 CAD pesa 125 CAD e compensa um lançamento de 125 CAD; remova o preço e a transação deixa de balancear.

Padrões Comuns​

Abertura de Contas com Saldo Inicial​

Abra ambas as contas, faça o pad na data de início e declare a asserção de saldo no dia seguinte (a asserção é verificada no início de sua data):

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

Transação de Investimento​

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

Transação Multi-Moeda​

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

Comentários​

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