نحو زبان Beancount

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

مرور کلی

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

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

کالاها

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

حساب‌ها

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

نام	نوع	محتویات معمول	مثال
Assets	+	نقد، بانک، سرمایه‌گذاری‌ها	Assets:Checking
Liabilities	-	کارت‌های اعتباری، وام‌ها	Liabilities:CreditCard
Income	-	حقوق، بهره	Income:EmployerA
Expenses	+	خریدها، صورتحساب‌ها	Expenses:Food:Dining
Equity	-	مانده‌های افتتاحیه/اختتامیه	Equity:Opening-Balances

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

دستورات

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

فرمت کلی:

YYYY-MM-DD <دستور> <آرگومان‌ها...>

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

باز کردن و بستن حساب‌ها

2023-01-01 open Assets:Checking USD,EUR  ; به صورت اختیاری ارزهای مجاز را مشخص کنید
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 "در مورد بازپرداخت سؤال شد"
2022-03-20 document Assets:Checking "statements/2022-03.pdf"

تراکنش‌ها

2024-01-05 * "Coffee Shop" "قهوه صبح"
  Expenses:Food         4.50 USD
  Assets:Cash         -4.50 USD

2024-01-06 ! "Phone Bill" "پرداخت ماهانه" #utilities ^phone
  id: "INV12345"              ; فراداده
  Expenses:Utilities  60.00 USD
  Assets:Checking

ویژگی‌های ارسال

; با مبنای هزینه
  Assets:Stocks    1 AAPL {150.00 USD}
; با حاشیه‌نویسی قیمت
  Assets:Cash   -100 USD @ 1.25 CAD
; با قیمت کل
  Assets:Cash   -100 USD @@ 125.00 CAD
; مانده ضمنی
  Assets:Cash   -100 USD
  Assets:Bank

ادعاهای مانده و پدینگ

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

رویدادها

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

گزینه‌ها

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

option "title" "دفتر من"
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

قوانین مهم

• همه تراکنش‌ها باید متعادل باشند (مجموع همه ارسال‌ها صفر است؛ در صورت وجود از مبنای هزینه استفاده می‌شود).
• حساب‌ها باید قبل از استفاده باز شوند؛ حساب‌های بسته شده نمی‌توانند ارسال‌ها را بپذیرند.
• ادعاهای مانده فقط ارز مشخص شده را بررسی می‌کنند و می‌توانند در حساب‌های والد استفاده شوند.
• حاشیه‌نویسی‌های قیمت (@) اطلاعاتی هستند و بر تعادل تأثیر نمی‌گذارند.

الگوهای رایج

باز کردن حساب‌ها با مانده اولیه

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

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

2024-01-01 * "خرید سهام"
  Assets:Broker:Stock   10 AAPL {150.00 USD}
  Assets:Broker:Cash -1500.00 USD

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

2024-01-01 * "تبدیل ارز"
  Assets:USD   -100.00 USD @ 1.25 CAD
  Assets:CAD    125.00 CAD

نظرات

poptag  #trip-to-peru
; نظرات درون خطی با یک نقطه ویرگول شروع می شوند
* هر خطی که با یک دستور معتبر شروع نشود نیز بی سر و صدا نادیده گرفته می شود