مرجع نحو Beancount: دستورالعمل‌ها، حساب‌ها، مبالغ

این یک مرجع مختصر و جامع برای نحو زبان Beancount است، که ساختار عملی، قوانین، و مثال‌ها را ترکیب می‌کند. برای جزئیات بیشتر، به برگه تقلب مراجعه کنید.

مرور​

Beancount یک سیستم حسابداری دوطرفه متن ساده است. زبان آن حول سه بلوک ساختمانی اصلی ساختار یافته است:

• کالاها (ارزها، سهام, امتیازها, و غیره)
• حساب‌ها (دفاتر سلسله‌مراتبی, دسته‌بندی‌شده)
• دستورها (ورودی‌های تاریخ‌دار ثبت رویدادها یا پیکربندی)

کالاها​

کالاها همیشه با حروف بزرگ نوشته می‌شوند, مانند USD, EUR, AAPL, BTC, MILES, HOURS.

حساب‌ها​

حساب‌ها نام‌های سلسله‌مراتبی با جداکننده دونقطه و با حروف بزرگ هستند. آن‌ها باید با یکی از پنج نوع حساب ریشه شروع شوند:

• اجزا باید با حروف بزرگ باشند, با دونقطه (:) جدا شوند, و بدون فاصله باشند.

• اعداد و خط تیره در اجزا مجاز هستند.

• نام حساب‌های ریشه می‌تواند از طریق گزینه‌ها سفارشی شود (به زیر مراجعه کنید).

دستورها​

دستورها عبارات اصلی در یک فایل Beancount هستند. بیشتر آن‌ها با یک تاریخ شروع می‌شوند, سپس نوع دستور و آرگومان‌ها می‌آیند. آن‌ها به ترتیب زمانی (بر اساس تاریخ) پردازش می‌شوند, نه ترتیب فایل.

قالب عمومی:

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

دستورهای رایج و مثال‌ها​

افتتاح و بستن حساب‌ها​

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

اعلام کالاها​

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

اعلام قیمت​

2022-04-30 price AAPL 150.00 USD

یادداشت‌ها و اسناد​

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

تراکنش‌ها​

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

ویژگی‌های ثبت​

; 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

تأیید موجودی و پر کردن​

دستور pad باید قبل از balance که آن را تغذیه می‌کند تاریخ‌گذاری شود, زیرا تأیید در ابتدای روز آن بررسی می‌شود:

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

رویدادها​

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

گزینه‌ها​

تنظیم پیکربندی سطح فایل:

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

به مرجع گزینه‌ها برای اطلاعات بیشتر مراجعه کنید.

افزونه‌ها و سازماندهی فایل​

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

قوانین مهم​

• همه تراکنش‌ها باید متوازن باشند: وزن همه ثبت‌ها باید به صفر جمع شود. وزن یک ثبت مقدار آن است, یا هزینه ({}) یا قیمت (@) آن به ارز دیگر تبدیل شده وقتی یکی موجود باشد.
• حساب‌ها باید قبل از استفاده باز شوند; حساب‌های بسته نمی‌توانند ثبت بپذیرند.
• تأیید موجودی فقط ارز مشخص‌شده را بررسی می‌کند, می‌تواند روی حساب‌های والد استفاده شود, و در ابتدا تاریخ آن ارزیابی می‌شود (بنابراین تراکنش‌های همان روز را حذف می‌کند).
• حاشیه‌های قیمت (@ برای هر واحد, @@ برای کل) بر توازن تأثیر می‌گذارند: آن‌ها وزن ثبت را در ارز دیگر تنظیم می‌کنند. -100 USD @ 1.25 CAD وزن 125 CAD دارد و یک ثبت 125 CAD را جبران می‌کند; حذف قیمت و تراکنش دیگر توازن ندارد.

الگوهای رایج​

افتتاح حساب‌ها با موجودی اولیه​

هر دو حساب را باز کنید, pad را در تاریخ شروع قرار دهید, و موجودی را روز بعد تأیید کنید (تأیید در ابتدای تاریخ آن بررسی می‌شود):

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

تراکنش سرمایه‌گذاری​

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

تراکنش چندارزی​

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

نظرات​

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