Sintaxe da Linguagem Beancount

Este documento fornece uma referência concisa e abrangente da sintaxe da linguagem Beancount, combinando estrutura prática, regras e exemplos. Para mais detalhes, consulte a Folha de Consulta.

Visão Geral

Beancount é um sistema de contabilidade em texto simples de partidas dobradas. 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 (entradas datadas registrando eventos ou configurações)

Commodities

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

Contas

Contas são nomes hierárquicos capitalizados separados por dois pontos. Elas devem começar com um dos cinco tipos de conta raiz:

Name	Type	Typical Contents	Example
Assets	+	Dinheiro, Banco, Investimentos	Assets:Checking
Liabilities	-	Cartões de Crédito, Empréstimos	Liabilities:CreditCard
Income	-	Salário, Juros	Income:EmployerA
Expenses	+	Compras, Contas	Expenses:Food:Dining
Equity	-	Saldos de Abertura/Fechamento	Equity:Opening-Balances

• Componentes devem ser capitalizados, separados por dois pontos (:), sem espaços.
• Números e traços são permitidos em componentes.
• Os nomes das contas raiz podem ser personalizados por meio de opções (veja abaixo).

Diretivas

Diretivas são as declaraçõ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 <diretiva> <argumentos...>

Diretivas Comuns & Exemplos

Abrindo e Fechando Contas

2023-01-01 open Assets:Checking USD,EUR  ; Opcionalmente, especifique as moedas permitidas
2023-12-31 close Assets:Checking

Declarando Commodities

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

Declarações de Preço

2022-04-30 price AAPL 150.00 USD

Notas & Documentos

2022-03-20 note Assets:Checking "Perguntou sobre reembolso"
2022-03-20 document Assets:Checking "statements/2022-03.pdf"

Transações

2024-01-05 * "Coffee Shop" "Café da manhã"
  Expenses:Food         4.50 USD
  Assets:Cash         -4.50 USD

2024-01-06 ! "Conta de Telefone" "Pagamento mensal" #utilities ^phone
  id: "INV12345"              ; Metadados
  Expenses:Utilities  60.00 USD
  Assets:Checking

Recursos de Lançamento

; Com custo base
  Assets:Stocks    1 AAPL {150.00 USD}
; Com anotação de preço
  Assets:Cash   -100 USD @ 1.25 CAD
; Com preço total
  Assets:Cash   -100 USD @@ 125.00 CAD
; Saldo implícito
  Assets:Cash   -100 USD
  Assets:Bank

Asserções de Saldo & Preenchimento

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

Eventos

2024-06-01 event "location" "São Francisco, CA"

Opções

Definir configuração para todo o arquivo:

option "title" "Meu Livro-Razão"
option "operating_currency" "USD"
option "documents" "docs/"
option "name_assets" "Vermoegen"

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

Plugins & Organização de Arquivos

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

Regras Importantes

• Todas as transações devem balancear (a soma de todos os lançamentos é zero; o custo base é usado se 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 e podem ser usadas em contas pai.
• As anotações de preço (@) são informativas e não afetam o balanceamento.

Padrões Comuns

Abrindo Contas com Saldo Inicial

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

Transação de Investimento

2024-01-01 * "Comprar ação"
  Assets:Broker:Stock   10 AAPL {150.00 USD}
  Assets:Broker:Cash -1500.00 USD

Transação Multi-Moeda

2024-01-01 * "Câmbio"
  Assets:USD   -100.00 USD @ 1.25 CAD
  Assets:CAD    125.00 CAD

Comentários

poptag  #trip-to-peru
; comentários em linha começam com um ponto e vírgula
* qualquer linha que não comece com uma diretiva válida também é ignorada silenciosamente