مرجع نحو 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

برای نقل‌قول‌های ارزش‌گذاری خودکار در یک دفتر کل میزبانی‌شده، قیمت‌های زنده را تنظیم کنید. فیدهای مدیریت‌شده دستورالعمل‌های عادی price تاریخ‌دار را فراهم می‌کنند. آن‌ها جایگزین قیمت‌های تراکنش (@، @@) یا هزینه‌های دسته ({}) نمی‌شوند.

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

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

Beancount.io میزبانی‌شده همچنین شامل URLهای قیمت مدیریت‌شده پشتیبانی‌شده را حل می‌کند. این یک افزونه به Beancount اصلی است: برای سازگاری میزبانی‌شده و محلی از راهنمای تنظیم قیمت‌های زنده استفاده کنید.

قوانین مهم​

• همه تراکنش‌ها باید متوازن باشند: وزن همه ثبت‌ها به صفر می‌رسد. وزن یک ثبت، مبلغ آن است، یا هزینه ({}) یا قیمت (@) آن که در صورت وجود، به ارز دیگر تبدیل شده است.
• حساب‌ها باید قبل از استفاده باز شوند؛ حساب‌های بسته نمی‌توانند ثبت بپذیرند.
• تأییدهای مانده فقط ارز مشخص‌شده را بررسی می‌کنند، می‌توانند روی حساب‌های والد استفاده شوند، و در ابتدای تاریخ خود ارزیابی می‌شوند (بنابراین تراکنش‌های همان روز را حذف می‌کنند).
• حاشیه‌نویسی‌های قیمت (@ به ازای هر واحد، @@ کل) بر توازن تأثیر می‌گذارند: آن‌ها وزن ثبت را در ارز دیگر تعیین می‌کنند. -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