پیکربندی گزینه‌ها

رفتار Beancount با دستورات option که در بالای فایل دفتر کل اصلی شما قرار می‌گیرند سفارشی می‌شود. این جفت‌های کلید-مقدار نام حساب‌های ریشه شما، میزان مغایرت مجاز یک تراکنش، و افزونه‌های در حال اجرا را کنترل می‌کنند. ⚙️

هر گزینه در این صفحه بر اساس Beancount 3.2.3 بارگذاری شده است و هر پیام خطای نقل‌شده همان چیزی است که آن نسخه چاپ می‌کند. Beancount گزینه‌ای را که نمی‌شناسد رد می‌کند — option "default_tolerance" "USD:0.01" با خطای Invalid option: 'default_tolerance' شکست می‌خورد — بنابراین گزینه‌ای که از یک راهنمای قدیمی‌تر کپی شده است بی‌صدا شکست نمی‌خورد. پس از تغییر هر چیزی در اینجا، bea check را روی فایل خود اجرا کنید.

گزینه‌های اصلی پیکربندی​

این گزینه‌ها راه‌اندازی اساسی دفتر کل شما را کنترل می‌کنند.

تنظیمات پایه​

اینها برخی از رایج‌ترین گزینه‌هایی هستند که تنظیم می‌کنید.

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"

• title: عنوان را برای گزارش‌ها و رابط‌های وب تنظیم می‌کند. پیش‌فرض Beancount است.
• render_commas: اگر true باشد، اعداد در گزارش‌ها با جداکننده هزارگان قالب‌بندی می‌شوند (مثلاً 1,000,000.00). پیش‌فرض false است. هر یک از 1، TRUE، true یا yes به عنوان true خوانده می‌شود؛ هر رشته دیگری به عنوان false خوانده می‌شود.
• plugin_processing_mode: یا default (پیش‌فرض) یا raw. هر مقدار دیگری با خطای Error for option 'plugin_processing_mode' شکست می‌خورد.

raw نسخه ملایم‌تر default نیست — این کلیدی است که مراحل پردازش خود Beancount را خاموش می‌کند. تحت default، Beancount beancount.ops.documents را قبل از افزونه‌های شما و beancount.ops.pad و beancount.ops.balance را بعد از آنها اجرا می‌کند. تحت raw فقط افزونه‌هایی را که خودتان لیست می‌کنید اجرا می‌کند، بنابراین دستورات pad هرگز اعمال نمی‌شوند و بررسی‌های balance هرگز انجام نمی‌شوند:

; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"
 
1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances
 
1970-01-02 * "Opening balance"
  Assets:Cash                100.00 USD
  Equity:Opening-Balances   -100.00 USD
 
1970-01-03 balance Assets:Cash   999.00 USD

آن یک خط را به default تغییر دهید و همان فایل گزارش می‌دهد Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). فقط زمانی از raw استفاده کنید که عمداً آن مراحل را خودتان بازپیاده‌سازی می‌کنید.

سفارشی‌سازی نام حساب​

می‌توانید پنج نوع حساب بنیادی Beancount را تغییر نام دهید. این فقط ظاهری نیست. این گزینه تعریف می‌کند که تجزیه‌گر کدام نام‌های ریشه را می‌پذیرد، بنابراین هر حساب در فایل شما باید از نام جدید استفاده کند و نام قدیمی نامعتبر می‌شود.

option "name_assets" "Actifs"
option "name_expenses" "Depenses"
 
2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation
 
2024-01-02 * "Boulangerie" "Pain"
  Depenses:Alimentation      4.20 EUR
  Actifs:Banque:Courant     -4.20 EUR

یک ثبت واحد را روی ریشه قدیمی بگذارید و فایل با خطای Invalid account name: Assets:Banque:Courant از بارگذاری متوقف می‌شود. پنج گزینه عبارتند از name_assets، name_liabilities، name_equity، name_income و name_expenses؛ هر مقدار باید یک کلمه با حرف بزرگ واحد بدون دونقطه باشد، در غیر این صورت Error for option 'name_assets': Invalid root account name دریافت می‌کنید. ریشه‌ها را هنگام شروع دفتر کل تغییر نام دهید، نه در میانه آن.

پیکربندی حساب حقوق صاحبان سهام​

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

هر مقدار یک نام برگ است و Beancount آن را به طور خودکار تحت name_equity قرار می‌دهد. نوشتن خود ریشه حقوق صاحبان سهام Equity:Equity:Opening-Balances تولید می‌کند که حسابی متفاوت از حسابی است که منظور شماست.

option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"

account_rounding استثنا در این گروه است: یک نام حساب کامل دریافت می‌کند و دقیقاً همان‌طور که نوشته شده ذخیره می‌شود، به همین دلیل است که Equity:Rounding در بالا صحیح است و پیشوند تکراری نیست. همچنین به طور پیش‌فرض تنظیم نشده است و در Beancount 3.2.3 تنظیم آن تأثیری بر بارگذاری ندارد — برای اطلاعات در مورد آنچه واقعاً برای باقیمانده اتفاق می‌افتد، به دقت و تلورانس‌ها مراجعه کنید.

تنظیمات دقت و تلورانس​

این گزینه‌ها میزان مغایرت قابل قبول Beancount در یک تراکنش را کنترل می‌کنند.

پیکربندی تلورانس پیش‌فرض​

Beancount برای هر تراکنش از تعداد ارقام اعشار در ثبت‌های آن یک تلورانس استنتاج می‌کند. این سه گزینه آن استنتاج را تنظیم می‌کنند.

option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"

• inferred_tolerance_default: یک کف برای هر ارز، که زمانی استفاده می‌شود که تراکنش ارقام اعشاری برای استنتاج نداشته باشد. نحو آن <currency>:<number> است و * همه ارزها را یکجا تنظیم می‌کند. برای تنظیم چند ارز، گزینه را تکرار کنید.
• tolerance_multiplier: کسری از کوچک‌ترین رقم که به عنوان قابل تحمل محسوب می‌شود، پیش‌فرض 0.5. این افزایش درصدی نیست: 1.2 باعث می‌شود هر تلورانس استنتاج‌شده 2.4 برابر پیش‌فرض باشد.
• infer_tolerance_from_cost: اگر true باشد، ثبت‌های نگه‌داری‌شده به قیمت تمام‌شده، تلورانس را در ارز هزینه نیز گسترش می‌دهند. به طور پیش‌فرض خاموش است.

نام قدیمی inferred_tolerance_multiplier همچنان همان مقدار را تنظیم می‌کند، اما خطای بارگذاری Renamed to 'tolerance_multiplier'. را گزارش می‌دهد، بنابراین bea check روی فایلی که از آن استفاده می‌کند شکست می‌خورد. آن را تغییر نام دهید.

روش ثبت​

این گزینه قانون پیش‌فرض را برای انتخاب اینکه کدام دسته کاهش می‌یابد تنظیم می‌کند. به یک حساب قانون متفاوتی در دستور open آن بدهید.

; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"

Beancount 3.2.3 دقیقاً هفت نام را می‌پذیرد: STRICT (پیش‌فرض)، STRICT_WITH_SIZE، NONE، FIFO، LIFO، HIFO و AVERAGE. هر چیز دیگری هنگام بارگذاری با خطای Error for option 'booking_method' رد می‌شود — از جمله SIMPLE و FULL که روش‌های ثبت نیستند و هرگز نبوده‌اند. AVERAGE در اینجا پذیرفته می‌شود اما هیچ پیاده‌سازی پشت آن نیست؛ کاهش تحت آن خطای AVERAGE method is not supported ایجاد می‌کند. مدیریت موجودی روی همان دفتر کل از هر هفت روش کار می‌کند.

مدیریت ارز​

پیکربندی صحیح ارز برای گزارش‌دهی دقیق حیاتی است.

ارز عملیاتی​

ارز عملیاتی ارزی است که می‌خواهید گزارش‌ها در آن جمع شوند. برای اعلام بیش از یک ارز، گزینه را تکرار کنید؛ مقادیر جمع می‌شوند نه جایگزین یکدیگر.

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

اعلام ارزهای عملیاتی به ابزارهای گزارش‌دهی می‌گوید که به هر یک ستون جداگانه بدهند. conversion_currency ارز فرضی را نام‌گذاری می‌کند که Beancount تبدیل‌ها را با نرخ صفر در آن ثبت می‌کند؛ قبلاً به طور پیش‌فرض NOTHING است و تنها دلیل تنظیم آن انتخاب یک مکان‌نگه‌دار متفاوت است که دفتر کل شما هرگز از آن به عنوان کالای واقعی استفاده نمی‌کند.

مدیریت اسناد​

Beancount می‌تواند تراکنش‌ها را به فایل‌های خارجی مانند رسیدها یا فاکتورها پیوند دهد. گزینه documents به آن پوشه‌ای برای اسکن می‌دهد.

option "documents" "/home/user/Documents/beancount"

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

• پوشه باید وجود داشته باشد. پوشه گمشده بارگذاری را با خطای Document root '/no/such/place' does not exist شکست می‌دهد.
• زیرپوشه‌ها نام حساب هستند. بیانیه‌ای برای Assets:US:BofA:Checking باید در <root>/Assets/US/BofA/Checking/ باشد. فایلی که در ریشه شل است نادیده گرفته می‌شود.
• حساب باید باز باشد. اسناد یافت‌شده تحت حسابی که دفتر کل شما هرگز باز نمی‌کند بدون هشدار رد می‌شوند.
• نام فایل‌ها با تاریخ شروع می‌شود، به شکل YYYY-MM-DD.description.ext (مثلاً 2025-07-28.amazon-order.pdf). هر چیز دیگری در پوشه نادیده گرفته می‌شود.
• مسیرها می‌توانند مطلق یا نسبی به فایل دفتر کل اصلی باشند و گزینه ممکن است برای چند پوشه تکرار شود.

سیستم افزونه​

قابلیت‌های Beancount را می‌توان با افزونه‌ها گسترش داد.

پیکربندی افزونه​

یک افزونه با دستور مستقلی به نام plugin بارگذاری می‌شود، نه با option. option "plugin" "..." با خطای Option 'plugin' may not be set شکست می‌خورد.

plugin "beancount.plugins.auto_accounts"
 
2024-03-01 * "Coffee Shop" "Flat white"
  Expenses:Food:Coffee        4.50 USD
  Assets:US:BofA:Checking    -4.50 USD

آن فایل بارگذاری می‌شود زیرا auto_accounts هر دو حساب را برای شما باز می‌کند؛ خط plugin را حذف کنید و خطای Invalid reference to unknown account 'Expenses:Food:Coffee' گزارش می‌دهد. افزونه‌ای که پیکربندی می‌گیرد آن را به عنوان رشته دوم دریافت می‌کند، plugin "module" "config". افزونه‌ها به ترتیبی که می‌نویسید اجرا می‌شوند، بعد از مرحله documents خود Beancount و قبل از مراحل pad و balance آن — مگر اینکه plugin_processing_mode را روی raw تنظیم کنید که آن مراحل را کاملاً حذف می‌کند.

محدودیت‌ها و محدودیت‌های فنی​

این گزینه‌ها جنبه‌های فنی تجزیه‌گر Beancount را کنترل می‌کنند.

مدیریت رشته​

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

option "long_string_maxlines" "64"

دقت درون‌یابی​

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

option "use_precise_interpolation" "TRUE"

هیچ گزینه‌ای برای تلورانس‌های صریح روی یک ثبت وجود ندارد. تنها نحو تلورانس صریح که Beancount 3.2.3 دارد، تیلد روی دستور balance است — 4.271 ~ 0.01 RGAGX — و نیازی به هیچ گزینه‌ای ندارد. تیلد داخل یک ثبت تراکنش یک خطای نحوی است.

گزینه‌های منسوخ و حذف‌شده​

سه گزینه که راهنماهای قدیمی‌تر هنوز توصیه می‌کنند در Beancount 3.2.3 وجود ندارند. هر خط در این بلوک بارگذاری را شکست می‌دهد:

option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"

• experiment_explicit_tolerances — نحو ~ در سطح ثبت که فعال می‌کرد حذف شده است؛ به جای آن از تیلد دستور balance استفاده کنید.
• use_legacy_fixed_tolerances — تلورانس‌های ثابت 0.005/0.015 حذف شده‌اند؛ تلورانس برای هر تراکنش استنتاج می‌شود، با tolerance_multiplier و inferred_tolerance_default تنظیم می‌شود.
• default_tolerance — با inferred_tolerance_default برای تراز کردن و display_precision برای رندر جایگزین شده است.

سه گزینه دیگر همچنان کار می‌کنند اما خطای منسوخ‌شدن گزارش می‌دهند، که برای شکست bea check کافی است:

• inferred_tolerance_multiplier — به tolerance_multiplier تغییر نام داده شده است.
• allow_pipe_separator — جداکننده قدیمی | بین گیرنده و روایت را می‌پذیرد.
• allow_deprecated_none_for_tags_and_links — یک None تحت‌اللفظی را در جایی که برچسب‌ها و پیوندها قرار دارند می‌پذیرد.

گزینه‌های Fava جدا هستند​

همه چیز در این صفحه توسط خود Beancount خوانده می‌شود. تنظیمات خود Fava اصلاً دستورات option نیستند — آنها دستورات custom "fava-option" با تاریخ هستند و Beancount آنها را نادیده می‌گیرد. نوشتن یک تنظیم Fava به عنوان option با خطای Invalid option شکست می‌خورد. برای آن فهرست، به گزینه‌های Fava مراجعه کنید.

پیکربندی پیشنهادی ✅​

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

; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
 
; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"
 
; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"
 
; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"

نظرات با ; شروع می‌شوند. نظر // در Beancount یک خطای نحوی است و بقیه فایل را با خود به پایین می‌کشد.

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