.\"t .TH "HLEDGER" "1" "March 2026" "hledger-1.52 " "hledger User Manuals" .SH "نام (NAME)" hledger \- یک برنامه حسابداری متن‌ساده، قدرتمند و کاربرپسند (نسخه خط فرمان) .SH "خلاصه دستور (SYNOPSIS)" \f[CR]hledger\f[R] .PD 0 .P .PD یا .PD 0 .P .PD \f[CR]hledger COMMAND [OPTS] [ARGS]\f[R] .PD 0 .P .PD .SH "توضیحات (DESCRIPTION)" برنامه hledger مجموعه‌ای پایدار، کاربرپسند و چندسکویی از برنامه‌ها برای ردیابی پول، زمان یا هر کالای دیگر با استفاده از حسابداری دوطرفه (دوبل) و یک قالب فایل ساده و قابل ویرایش است. hledger از ledger(1) الهام گرفته شده و تا حد زیادی با آن سازگار است، و قابلیت تبدیل دوطرفه بالایی با beancount(1) دارد. .PP این راهنما مربوط به رابط خط فرمان hledger نسخه ۱.۵۲ است. همچنین گزینه‌های مشترک، قالب‌های فایل و مفاهیم استفاده‌شده توسط تمام برنامه‌های hledger را شرح می‌دهد. این مستند حتی ممکن است به‌طور اتفاقی نکاتی از دفترداری/حسابداری را نیز به شما بیاموزد! برای استفاده کاربردی از hledger نیازی نیست همه مطالب اینجا را بدانید، اما هرگاه سؤالی درباره قابلیت‌ها داشته باشید، این سند پاسخگوی آن خواهد بود. این مستند مفصل است، بنابراین در صورت نیاز می‌توانید از بخش‌هایی بگذرید یا آن را گذرا مرور کنید. می‌توانید آن را در hledger.org یا به عنوان یک راهنمای info یا صفحه man در سیستم خود بخوانید. همچنین می‌توانید با اجرای دستورهای زیر، نسخه‌ای درون‌برنامه‌ای را در موضوع مورد نظر باز کنید: .PD 0 .P .PD \f[CR]hledger \-\-man [CMD]\f[R]، \f[CR]hledger \-\-info [CMD]\f[R] یا \f[CR]hledger help [TOPIC]\f[R]. .PP (و برای راهنمای خلاصه‌تر، \f[CR]hledger \-\-tldr [CMD]\f[R] را امتحان کنید.) .PP وظیفه اصلی رابط خط فرمان hledger خواندن فایل‌های متن‌ساده توصیف‌کننده تراکنش‌های مالی، پردازش و محاسبه اعداد، و چاپ یک گزارش کاربردی در ترمینال (یا ذخیره آن به صورت HTML ،CSV ،JSON یا SQL) است. گزارش‌های متعددی در قالب زیردستورها در دسترس هستند. hledger همچنین سایر فایل‌های اجرایی \f[CR]hledger\-*\f[R] را به عنوان زیردستورهای اضافی شناسایی می‌کند. .PP hledger معمولاً از فایل دفتر روزنامه‌ای (journal) که توسط متغیر محیطی \f[CR]LEDGER_FILE\f[R] مشخص شده است می‌خواند (و به آن اضافه می‌کند) (با پیش‌فرض \f[CR]$HOME/.hledger.journal\f[R])؛ یا می‌توانید فایل‌ها را با گزینه‌های \f[CR]\-f\f[R] مشخص کنید. این برنامه همچنین می‌تواند فایل‌های timeclock، فایل‌های timedot یا هر فایل CSV/SSV/TSV دارای فیلد تاریخ را بخواند. .PP در اینجا یک فایل دفتر روزنامه کوچک آمده است که یک تراکنش را شرح می‌دهد: .IP .EX 2015\-10\-16 bought food expenses:food $10 assets:cash .EE .PP تراکنش‌ها جابه‌جایی‌های تاریخ‌دار پول (یا موارد دیگر) میان دو یا چند \f[I]حساب\f[R] (accounts) هستند: حساب‌های بانکی، کیف پول شما، دسته‌بندی‌های درآمد/هزینه، افراد و غیره. می‌توانید هر نام حسابی که می‌خواهید انتخاب کنید و از \f[CR]:\f[R] برای مشخص کردن زیرحساب‌ها بهره ببرید. باید حداقل دو فاصله (space) میان نام حساب و مبلغ وجود داشته باشد. مقادیر مثبت، ورودی به آن حساب (\f[I]بدهکار\f[R]) و مقادیر منفی، خروجی از آن (\f[I]بستانکار\f[R]) هستند. (در نتیجه، برخی گزارش‌ها مانده حساب‌های درآمد، بدهی و حقوق صاحبان سهام را به عنوان اعداد منفی نشان می‌دهند؛ این امر طبیعی است.) .PP دستور add در hledger می‌تواند به شما در افزودن تراکنش‌ها کمک کند، یا می‌توانید سایر رابط‌های کاربری ورود داده مانند hledger\-web یا hledger\-iadd را نصب کنید. برای تغییرات گسترده‌تر و بهینه‌تر، از یک ویرایشگر متن استفاده کنید: Emacs + ledger\-mode، VIM + vim\-ledger، یا VS Code + hledger\-vscode چند انتخاب خوب هستند (ببینید ). .PP برای شروع، \f[CR]hledger add\f[R] را اجرا کرده و اعلان‌ها را دنبال کنید، یا چند مدخل مانند نمونه بالا را در \f[CR]$HOME/.hledger.journal\f[R] ذخیره کنید، سپس دستورهایی مانند زیر را امتحان نمایید: .IP .EX $ hledger print \-x $ hledger aregister assets $ hledger balance $ hledger balancesheet $ hledger incomestatement .EE .PP برای مشاهده فهرست دستورها، \f[CR]hledger\f[R] را اجرا کنید. همچنین بخش‌های \(dqStarting a journal file\(dq و \(dqSetting opening balances\(dq را در PART 5: COMMON TASKS ببینید..SH "بخش ۱: رابط کاربری (PART 1: USER INTERFACE)" .SH "ورودی (INPUT)" دستور hledger با هر بار اجرا، یک یا چند فایل داده را می‌خواند. می‌توانید یک فایل را با استفاده از \f[CR]\-f\f[R] مشخص کنید، مانند زیر: .IP .EX $ hledger \-f FILE [\-f FILE2 ...] print .EE .PP فایل‌ها اغلب در قالب دفتر روزنامه (journal) برنامه hledger و با پسوند فایل \f[CR].journal\f[R] هستند (\f[CR].hledger\f[R] یا \f[CR].j\f[R] نیز کار می‌کنند)؛ این فایل‌ها تراکنش‌ها را مانند یک دفتر روزنامه عمومی حسابداری توصیف می‌کنند. .PP هنگامی که هیچ فایلی مشخص نشده باشد، hledger به دنبال \f[CR].hledger.journal\f[R] در پوشه خانگی (home) شما می‌گردد. .PP اما بیشتر افراد ترجیح می‌دهند فایل‌های مالی را در یک پوشه اختصاصی، احتمالاً همراه با سامانه کنترل نسخه نگهداری کنند. همچنین، شروع یک فایل روزنامه جدید در هر سال رایج است (اجباری نیست، اما به سریع و منظم ماندن کارها کمک می‌کند). بنابراین ما معمولاً با تنظیم متغیر محیطی \f[CR]LEDGER_FILE\f[R] روی مقداری مانند \f[CR]\(ti/finance/2023.journal\f[R]، فایل روزنامه متفاوتی را پیکربندی می‌کنیم. برای اطلاعات بیشتر در مورد نحوه انجام این کار در سیستم خود، به Common tasks > Setting LEDGER_FILE مراجعه کنید. .SS "کدگذاری متن (Text encoding)" برنامه hledger انتظار دارد ورودی‌های غیر ascii با کدگذاری متنی locale سیستم قابل رمزگشایی باشند. (برای فایل‌های CSV/SSV/TSV، این مورد می‌تواند با قاعده CSV \f[CR]encoding\f[R] لغو شود.) .PP بنابراین، تلاش برای خواندن فایل‌های غیر ascii که دارای کدگذاری متنی نادرست هستند، یا زمانی که هیچ locale سیستمی پیکربندی نشده است، با شکست مواجه خواهد شد. برای رفع این مشکل، locale سیستم خود را به درستی پیکربندی کنید و/یا فایل‌ها را به کدگذاری متنی سیستم خود تبدیل کنید (با استفاده از \f[CR]iconv\f[R] در unix، یا powershell یا notepad در ویندوز). برای نکات بیشتر به Install: Text encoding مراجعه کنید. .PP خروجی hledger از کدگذاری locale سیستم استفاده خواهد کرد. .PP مستندات و فایل‌های نمونه hledger اغلب از کدگذاری UTF\-8 استفاده می‌کنند. .SS "قالب‌های داده (Data formats)" معمولاً فایل داده در قالب journal متعلق به hledger است، اما می‌تواند در هر یک از قالب‌های فایل پشتیبانی‌شده باشد که در حال حاضر عبارتند از: .PP .TS tab(@); lw(13.5n) lw(33.0n) lw(23.5n). T{ خواننده (Reader): T}@T{ نوع داده (Reads): T}@T{ استفاده خودکار برای پسوندهای: T} _ T{ \f[CR]journal\f[R] T}@T{ فایل‌های دفتر روزنامه hledger و برخی دفاتر روزنامه Ledger، برای تراکنش‌ها T}@T{ \f[CR].journal\f[R] \f[CR].j\f[R] \f[CR].hledger\f[R] \f[CR].ledger\f[R] T} T{ \f[CR]timeclock\f[R] T}@T{ فایل‌های timeclock، برای ثبت دقیق زمان T}@T{ \f[CR].timeclock\f[R] T} T{ \f[CR]timedot\f[R] T}@T{ فایل‌های timedot، برای ثبت تقریبی زمان T}@T{ \f[CR].timedot\f[R] T} T{ \f[CR]csv\f[R] T}@T{ مقادیر جداشده با کاما یا سایر جداکننده‌ها، برای وارد کردن داده‌ها T}@T{ \f[CR].csv\f[R] T} T{ \f[CR]ssv\f[R] T}@T{ مقادیر جداشده با نقطه ویرگول (semicolon) T}@T{ \f[CR].ssv\f[R] T} T{ \f[CR]tsv\f[R] T}@T{ مقادیر جداشده با تب (tab) T}@T{ \f[CR].tsv\f[R] T} T{ \f[CR]rules\f[R] T}@T{ مقادیر جداشده با CSV/SSV/TSV/غیره، روش جایگزین T}@T{ \f[CR].rules\f[R] T} .TE .PP این قالب‌ها در ادامه با جزئیات بیشتری توضیح داده شده‌اند. .PP برنامه hledger قالب را بر اساس پسوندهای فایل نشان‌داده‌شده در بالا به طور خودکار تشخیص می‌دهد. اگر نتواند پسوند فایل را تشخیص دهد، قالب \f[CR]journal\f[R] را فرض می‌کند. بنابراین برای فایل‌های غیر journal، استفاده از یک پسوند فایل شناخته‌شده مهم است تا خواندن فایل با موفقیت انجام شود یا پیام‌های خطای مرتبط نمایش داده شوند. .PP همچنین می‌توانید با قرار دادن نام قالب و یک دونقطه در ابتدای مسیر فایل، استفاده از یک خواننده/قالب خاص را اجبار کنید. به عنوان مثال، برای خواندن یک فایل ‎.dat حاوی مقادیر جداشده با تب: .IP .EX $ hledger \-f tsv:/some/file.dat stats .EE.SS "ورودی استاندارد (Standard input)" نام فایل \f[CR]\-\f[R] به معنی ورودی استاندارد است: .IP .EX $ cat FILE | hledger \-f\- print .EE .PP در صورت خواندن داده‌های غیر از journal به این روش، باید قالب را به عنوان یک پیشوند مشخص کنید، مانند \f[CR]timeclock:\f[R] در اینجا: .IP .EX $ echo \(aqi 2009/13/1 08:00:00\(aq | hledger print \-f timeclock:\- .EE .SS "چندین فایل (Multiple files)" می‌توانید چند گزینهٔ \f[CR]\-f\f[R] را مشخص کنید تا چندین فایل به عنوان یک journal بزرگ خوانده شوند. هنگام انجام این کار، توجه داشته باشید که برخی ویژگی‌ها (توضیح داده شده در زیر) تحت تأثیر قرار خواهند گرفت: .IP \(bu 2 بررسی‌های تراز (balance assertions) تأثیر تراکنش‌های فایل‌های قبلی را نخواهند دید. (معمولاً این موضوع مشکلی ایجاد نمی‌کند زیرا هر فایل مانده‌های ابتدای دورهٔ متناظر خود را تنظیم می‌کند.) .IP \(bu 2 برخی دستورالعمل‌ها (directives) روی فایل‌های قبلی یا بعدی تأثیر نخواهند گذاشت. .PP در صورت نیاز، می‌توانید این مشکل را با استفاده از یک فایل والد (parent file) که سایر فایل‌ها را در بر می‌گیرد، یا با چسباندن فایل‌ها به یکدیگر دور بزنید؛ به عنوان مثال: \f[CR]cat a.journal b.journal | hledger \-f\- CMD\f[R]. .SS "حالت سخت‌گیرانه (Strict mode)" نرم‌افزار hledger فایل‌های ورودی را برای اطمینان از معتبر بودن داده‌ها بررسی می‌کند. به‌طور پیش‌فرض، مهم‌ترین خطاها شناسایی می‌شوند، در حالی که همچنان فایل‌های journal ساده را بدون نیاز به اعلان‌های فراوان می‌پذیرد: .IP \(bu 2 آیا فایل‌های ورودی با نحو (syntax) معتبر، قابل تجزیه هستند؟ .IP \(bu 2 آیا همهٔ تراکنش‌ها تراز هستند؟ .IP \(bu 2 آیا تمام بررسی‌های تراز با موفقیت تأیید می‌شوند؟ .PP با پرچم \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]، بررسی‌های بیشتری انجام می‌شود: .IP \(bu 2 آیا همهٔ حساب‌هایی که در آن‌ها تراکنشی ثبت شده، با یک دستورالعمل \f[CR]account\f[R] اعلان شده‌اند؟ (بررسی خطای حساب) .IP \(bu 2 آیا همهٔ کالاها با یک دستورالعمل \f[CR]commodity\f[R] اعلان شده‌اند؟ (بررسی خطای کالا) .IP \(bu 2 آیا همهٔ تبدیل‌های کالا به صراحت اعلان شده‌اند؟ .PP می‌توانید از دستور check برای اجرای بررسی‌های جداگانه استفاده کنید \- مواردی که در بالا ذکر شد و چند مورد بیشتر. .SH "دستورها (COMMANDS)" نرم‌افزار hledger زیردستورهای متنوعی را برای انجام کارها ارائه می‌دهد. بیشتر این دستورها فایل journal را تغییر نمی‌دهند؛ آن‌ها فقط فایل را می‌خوانند و یک گزارش در خروجی ارائه می‌دهند. چند دستور به افزودن داده‌ها و مدیریت فایل کمک می‌کنند. برخی از دستورهای پرکاربرد عبارتند از \f[CR]add\f[R]، \f[CR]print\f[R]، \f[CR]register\f[R]، \f[CR]balancesheet\f[R] و \f[CR]incomestatement\f[R]. .PP برای نمایش خلاصه‌ای از دستورها، \f[CR]hledger\f[R] را بدون هیچ آرگومانی اجرا کنید. می‌توانید همین خلاصهٔ دستورها را در ابتدای بخش ۴: دستورها (PART 4: COMMANDS) در ادامه مشاهده کنید. .PP برای استفاده از یک دستور خاص، این فرمان را اجرا کنید: \f[CR]hledger CMD [CMDOPTS] [CMDARGS]\f[R]، .IP \(bu 2 مقدار CMD نام کامل دستور، یا اختصار استاندارد آن است که در فهرست دستورها نمایش داده شده، یا هر پیشوند بدون ابهامی از نام آن دستور است. .IP \(bu 2 مقدار CMDOPTS گزینه‌های خاص دستور هستند (در صورت وجود). گزینه‌های خاص هر دستور باید حتماً بعد از نام دستور نوشته شوند. مثال: \f[CR]hledger print \-x\f[R]. .IP \(bu 2 مقدار CMDARGS آرگومان‌های اضافی دستور هستند (در صورت وجود). بیشتر دستورهای hledger آرگومان‌هایی را در قالب یک پرس‌وجو (query) می‌پذیرند تا داده‌ها را به نحوی محدود کنند. مثال: \f[CR]hledger reg assets:checking\f[R]. .PP برای مشاهدهٔ فهرست گزینه‌ها، آرگومان‌ها و مستندات یک دستور در ترمینال، دستور \f[CR]hledger CMD \-h\f[R] را اجرا کنید. مثال: \f[CR]hledger bal \-h\f[R]..SS دستورهای افزونه (Add\-on commands) علاوه بر دستورهای داخلی، می‌توانید \f[I]دستورهای افزونه\f[R] را نیز نصب کنید که در فهرست دستورهای hledger نیز نمایش داده خواهند شد. برخی از این‌ها را می‌توان به‌صورت بسته‌های جداگانه نصب کرد؛ موارد دیگر را می‌توان در دایرکتوری bin/ از hledger یافت که مستندات آن‌ها در https://hledger.org/scripts.html آمده است. .PP دستورهای افزونه برنامه‌ها یا اسکریپت‌هایی در PATH پوستهٔ شما هستند که نام آن‌ها با \(dqhledger\-\(dq آغاز می‌شود و بدون پسوند یا با یک پسوند شناخته‌شده (\(dq.bat\(dq، \(dq.com\(dq، \(dq.exe\(dq، \(dq.hs\(dq، \(dq.js\(dq، \(dq.lhs\(dq، \(dq.lua\(dq، \(dq.php\(dq، \(dq.pl\(dq، \(dq.py\(dq، \(dq.rb\(dq، \(dq.rkt\(dq یا \(dq.sh\(dq) به پایان می‌رسد، و (در unix و mac) دارای مجوز اجرا برای کاربر جاری هستند. .PP می‌توانید دستورهای افزونه را مستقیماً اجرا کنید: \f[CR]hledger\-ui \-\-watch\f[R]. .PP یا می‌توانید آن‌ها را مانند دستورهای داخلی با خود hledger اجرا کنید: \f[CR]hledger ui \-\-watch\f[R]. در این حالت از فایل پیکربندی hledger استفاده خواهد شد، بنابراین می‌توانید گزینه‌های سفارشی افزونه را در آنجا تنظیم کنید. (پیش از hledger نسخهٔ 1.50، آرگومان \f[CR]\-\-\f[R] پیش از گزینه‌های افزونه لازم بود، اما اکنون دیگر نیازی نیست.) .SH "گزینه‌ها (OPTIONS)" برای مشاهدهٔ راهنمای عمومی خط فرمان، \f[CR]hledger \-h\f[R] را اجرا کنید. گزینه‌ها را می‌توان قبل یا بعد از نام دستور درج کرد. این گزینه‌ها مختص واسط خط فرمان \f[CR]hledger\f[R] هستند: .IP .EX پرچم‌ها: \-\-conf=CONFFILE استفاده از گزینه‌های اضافی تعریف‌شده در این فایل کانفیگ. در صورت مشخص نشدن، به سمت بالا و در دایرکتوری کانفیگ XDG به دنبال hledger.conf (یا .hledger.conf در $HOME) می‌گردد. \-n \-\-no\-conf نادیده‌گرفتن هرگونه فایل پیکربندی .EE .PP و گزینه‌های عمومی زیر بین بیشتر دستورهای hledger مشترک هستند: .IP .EX پرچم‌های عمومی ورودی/تبدیل داده: \-f \-\-file=[FMT:]FILE خواندن داده از FILE، یا از stdin اگر FILE برابر \- باشد، با استنتاج قالب از پسوند یا پیشوند :FMT. می‌تواند بیش از یک بار مشخص شود. در صورت عدم تعیین، از $LEDGER_FILE یا $HOME/.hledger.journal می‌خواند. \-\-rules=RULESFILE استفاده از قواعد تعریف‌شده در این فایل برای تبدیل فایل‌های بعدی CSV/SSV/TSV. در صورت مشخص نشدن، برای هر FILE.csv از FILE.csv.rules استفاده می‌کند. \-\-alias=A=B|/RGX/=RPL تبدیل نام حساب‌ها از A به B، یا با جایگزینی تطابق‌های عبارت باقاعده \-\-auto تولید ثبت‌های اضافی با اعمال قواعد ثبت خودکار (\(dq=\(dq) بر روی تمام تراکنش‌ها \-\-forecast[=PERIOD] تولید تراکنش‌های اضافی از روی قواعد دوره‌ای (\(dq\(ti\(dq)، از پس از آخرین تراکنش عادی تا ۶ ماه بعد از اکنون. یا در طول PERIOD مشخص‌شده (علامت مساوی الزامی است). قواعد ثبت خودکار نیز بر روی این تراکنش‌ها اعمال خواهند شد. در hledger\-ui، همچنین تراکنش‌های دارای تاریخ آینده را در آغاز نمایان می‌کند. \-I \-\-ignore\-assertions بررسی نکردن گزاره‌های تراز به‌طور پیش‌فرض \-\-txn\-balancing=... نحوهٔ بررسی تراز بودن تراکنش‌ها: \(aqold\(aq: استفاده از دقت نمایش سراسری \(aqexact\(aq: استفاده از دقت تراکنش (پیش‌فرض) \-\-infer\-costs استنتاج ثبت‌های ارزش ویژه تبدیل از هزینه‌ها \-\-infer\-equity استنتاج هزینه‌ها از ثبت‌های ارزش ویژه تبدیل \-\-infer\-market\-prices استنتاج قیمت‌های بازار از هزینه‌ها \-\-pivot=TAGNAME استفاده از فیلد یا برچسبی دیگر به‌عنوان نام حساب‌ها \-s \-\-strict انجام بررسی‌های خطای بیشتر (و لغو اثر \-I) \-\-verbose\-tags افزودن برچسب‌های نشان‌دهندهٔ داده‌های تولید/ویرایش‌شده پرچم‌های عمومی خروجی/گزارش‌گیری (پشتیبانی‌شده در برخی دستورها): \-b \-\-begin=DATE شامل کردن ثبت‌ها/تراکنش‌ها در این تاریخ یا پس از آن \-e \-\-end=DATE شامل کردن ثبت‌ها/تراکنش‌ها پیش از این تاریخ (همراه با بازهٔ گزارش، با پایان زیردورهٔ بعدی تنظیم خواهد شد) \-D \-\-daily گزارش چنددوره‌ای با بازهٔ ۱ روزه \-W \-\-weekly گزارش چنددوره‌ای با بازهٔ ۱ هفته‌ای \-M \-\-monthly گزارش چنددوره‌ای با بازهٔ ۱ ماهه \-Q \-\-quarterly گزارش چنددوره‌ای با بازهٔ ۱ فصلی (سه‌ماهه) \-Y \-\-yearly گزارش چنددوره‌ای با بازهٔ ۱ ساله \-p \-\-period=PERIODEXP تنظیم تاریخ شروع، تاریخ پایان، و/یا بازهٔ گزارش، با انعطاف‌پذیری بیشتر \-\-today=DATE بازنویسی تاریخ امروز (بر تاریخ‌های نسبی اثر می‌گذارد) \-\-date2 تطابق/استفاده از تاریخ‌های ثانویه به‌جای آن (منسوخ) \-U \-\-unmarked فقط شامل کردن ثبت‌ها/تراکنش‌های بدون علامت \-P \-\-pending فقط شامل کردن ثبت‌ها/تراکنش‌های در انتظار \-C \-\-cleared فقط شامل کردن ثبت‌ها/تراکنش‌های تسویه‌شده (پرچم‌های \-U/\-P/\-C می‌توانند ترکیب شوند) \-R \-\-real فقط شامل کردن ثبت‌های غیرمجازی \-E \-\-empty نمایش موارد صفر، که معمولاً پنهان هستند. در hledger\-ui و hledger\-web عکس این عمل می‌کند. \-\-depth=DEPTHEXP اگر یک عدد (یا NUM\-) باشد: نمایش فقط NUM سطح بالای حساب‌ها. اگر REGEXP=NUM باشد، محدودیت فقط بر حساب‌های منطبق با عبارت باقاعده اعمال می‌شود. \-B \-\-cost نمایش مبالغ تبدیل‌شده به مبلغ هزینه/فروش آن‌ها \-V \-\-market نمایش مبالغ تبدیل‌شده به ارزش آن‌ها در پایان دوره(ها) در کالای ارزش‌گذاری پیش‌فرض آن‌ها. معادل با \-\-value=end. \-X \-\-exchange=COMM نمایش مبالغ تبدیل‌شده به ارزش آن‌ها در پایان دوره(ها) در کالای مشخص‌شده. معادل با \-\-value=end,COMM. \-\-value=WHEN[,COMM] نمایش مبالغ تبدیل‌شده به ارزش آن‌ها در تاریخ(های) مشخص‌شده در کالای ارزش‌گذاری پیش‌فرض یا یک کالای مشخص‌شده. مقدار WHEN می‌تواند چنین باشد: \(aqthen\(aq: ارزش در تاریخ‌های تراکنش \(aqend\(aq: ارزش در پایان دوره(ها) \(aqnow\(aq: ارزش امروز YYYY\-MM\-DD: ارزش در تاریخ معین \-c \-\-commodity\-style=S بازنویسی سبک نمایش یک کالا. مثال: \-c \(aq.\(aq یا \-c \(aq1.000,00 EUR\(aq \-\-pretty[=YN] استفاده از نویسه‌های کادرسازی در خروجی متنی؟ می‌تواند \(aqy\(aq/\(aqyes\(aq یا \(aqn\(aq/\(aqno\(aq باشد. در صورت تعیین YN، علامت مساوی الزامی است. پرچم‌های عمومی راهنما: \-h \-\-help نمایش راهنمای خط فرمان \-\-tldr نمایش مثال‌های دستور با tldr \-\-info نمایش دفترچهٔ راهنما با info \-\-man نمایش دفترچهٔ راهنما با man \-\-version نمایش اطلاعات نسخه \-\-debug=[1\-9] نمایش این میزان از خروجی اشکال‌زدایی (پیش‌فرض: 1) \-\-pager=YN استفاده از صفحه‌بند در صورت نیاز؟ y/yes (پیش‌فرض) یا n/no \-\-color=YNA \-\-colour استفاده از رنگ ANSI؟ y/yes، n/no، یا auto (پیش‌فرض) .EE .PP معمولاً hledger هر پیشوند بدون ابهامی از پرچم را می‌پذیرد؛ برای نمونه می‌توانید به‌جای \f[CR]\-\-tldr\f[R] بنویسید \f[CR]\-\-tl\f[R] یا به‌جای \f[CR]\-\-dry\-run\f[R] بنویسید \f[CR]\-\-dry\f[R]. .PP می‌توانید پرچم‌های کوتاهی را که آرگومان دریافت نمی‌کنند با یکدیگر ترکیب کنید؛ برای نمونه می‌توانید به‌جای \f[CR]\-M \-A \-S \-T\f[R] بنویسید \f[CR]\-MAST\f[R]. پرچم‌هایی که نیازمند آرگومان هستند را نمی‌توان به این صورت ترکیب کرد (\f[CR]\-If FILE\f[R] کار نخواهد کرد). .PP اگر یک گزینه بیش از یک بار در خط فرمان درج شود، معمولاً آخرین مورد (راست‌ترین) اولویت دارد. به‌همین ترتیب، اگر پرچم‌های مانعة‌الجمع با هم استفاده شوند، پرچم راست‌تر اعمال می‌شود. (هنگامی که پرچم‌ها مانعة‌الجمع باشند، معمولاً در \-\-help یک پیشوند گروهی خواهند داشت.) .PP در بیشتر دستورها، آرگومان‌ها به‌عنوان یک پرس‌وجوی hledger تفسیر می‌شوند که داده‌ها را پالایش می‌کند. برخی از پرس‌وجوها را می‌توان هم با گزینه‌ها و هم با آرگومان‌ها بیان کرد. .PP در ادامه نکته‌های بیشتری برای استفاده از واسط خط فرمان آورده شده است \- هر زمان که به آن‌ها نیاز داشتید می‌توانید آن‌ها را مطالعه کنید..SS نویسه‌های خاص در دستوراتی که در خط فرمان تایپ می‌کنید، نویسه‌های خاصی دارای معنای ویژه هستند و گاهی لازم است با افزودن یک بک‌اسلش در ابتدا یا قرار دادن درون نقل‌قول، \(dqگریزانده\(dq یا \(dqنقل‌قول\(dq شوند. .PP اگر بتوانید استفاده از نویسه‌های خاص را در داده‌های خود به حداقل برسانید، کمتر با این موضوع سر و کار خواهید داشت. به عنوان مثال، می‌توانید به جای فاصله در نام حساب‌ها از خط تیرهٔ \f[CR]\-\f[R] یا زیرخط \f[CR]_\f[R] استفاده کنید، و در مقادیر نیز از کد ارزی \f[CR]USD\f[R] به جای نماد ارزی \f[CR]$\f[R] بهره ببرید. .PP اما اگر ترجیح می‌دهید از نام‌های حساب دارای فاصله و \f[CR]$\f[R] استفاده کنید، مشکلی نیست. فقط از این موضوع آگاه باشید تا در صورت نیاز بتوانید به این سند مراجعه کنید. (بیشتر این مثال‌ها روی یونیکس آزمایش شده‌اند؛ اگر در ویندوز هستید ممکن است برخی جزئیات نیاز به انطباق داشته باشند.) .SS گریزاندن نویسه‌های خاص پوسته این‌ها برخی از نویسه‌هایی هستند که ممکن است برای پوستهٔ شما (برنامه‌ای که خطوط فرمان را تفسیر می‌کند) معنای ویژه‌ای داشته باشند: .IP \(bu 2 فاصله (SPACE)، \f[CR]<\f[R]، \f[CR]>\f[R]، \f[CR](\f[R]، \f[CR])\f[R]، \f[CR]|\f[R]، \f[CR]\(rs\f[R]، \f[CR]%\f[R] .IP \(bu 2 \f[CR]$\f[R] اگر بعد از آن یک نویسهٔ کلمه‌ای (word character) بیاید .PP بنابراین برای مثال، برای تطبیق یک نام حساب حاوی فاصله، مانند \(dqcredit card\(dq، این را ننویسید: .IP .EX $ hledger register credit card .EE .PP در عوض، نام را درون تک‌نقل‌قول قرار دهید: .IP .EX $ hledger register \(aqcredit card\(aq .EE .PP در یونیکس یا PowerShell ویندوز، اگر از نقل‌قول دوگانه استفاده کنید، پوستهٔ شما بی‌سر و صدا \f[CR]$\f[R] را به عنوان جایگزینی متغیر در نظر می‌گیرد. بنابراین احتمالاً باید از نقل‌قول دوگانه پرهیز کنید، مگر اینکه خواهان این رفتار باشید، مثلاً در یک اسکریپت: .IP .EX $ hledger register \(dqassets:$SOMEACCT\(dq .EE .PP اما در پنجره‌های قدیمی‌تر CMD.EXE ویندوز، باید از نقل‌قول دوگانه استفاده کنید: .IP .EX C:\(rsUsers\(rsMe> hledger register \(dqcredit card\(dq .EE .PP در یونیکس یا PowerShell ویندوز، به عنوان جایگزینی برای نقل‌قول‌ها می‌توانید قبل از هر نویسهٔ خاص یک بک‌اسلش بنویسید: .IP .EX $ hledger register credit\(rs card .EE .PP در نهایت، از آنجا که آرگومان‌های پرس‌وجوی hledger عبارت‌های باقاعده هستند (که در زیر توضیح داده شده‌اند)، می‌توانید آن فاصله را با \f[CR].\f[R] که با هر نویسه‌ای مطابقت دارد نیز پر کنید: .IP .EX $ hledger register credit.card .EE .SS گریزاندن نویسه‌های خاص در عبارت‌های باقاعده برخی نویسه‌ها همچنین در عبارت‌های باقاعده (که آرگومان‌های hledger معمولاً چنین هستند) معنای ویژه‌ای دارند. این نویسه‌ها عبارتند از: .IP \(bu 2 \f[CR].\f[R]، \f[CR]\(ha\f[R]، \f[CR]$\f[R]، \f[CR][\f[R]، \f[CR]]\f[R]، \f[CR](\f[R]، \f[CR])\f[R]، \f[CR]|\f[R]، \f[CR]\(rs\f[R] .PP برای گریزاندن یکی از این‌ها، یک \f[CR]\(rs\f[R] قبل از آن بنویسید. اما توجه داشته باشید که این علاوه بر گریزاندن پوسته در بالا است. بنابراین برای نویسه‌هایی که هم برای پوسته و هم برای عبارت‌های باقاعده خاص هستند، مانند \f[CR]\(rs\f[R] و \f[CR]$\f[R]، گاهی به دو سطح گریزاندن نیاز خواهید داشت. .PP برای مثال، یک گزارش تراز که از پرس‌وجوی \f[CR]cur:\f[R] استفاده کرده و آن را فقط به ارز $ محدود می‌کند، باید به این صورت نوشته شود: .IP .EX $ hledger balance cur:\(rs\(rs$ .EE .PP توضیح: .IP "1." 3 افزودن یک بک‌اسلش \f[CR]\(rs\f[R] قبل از علامت دلار \f[CR]$\f[R] برای محافظت از آن در برابر عبارت‌های باقاعده (تا به صورت تحت‌اللفظی و بدون معنای ویژه مطابقت داده شود). .IP "2." 3 افزودن یک بک‌اسلش دیگر قبل از آن بک‌اسلش، برای محافظت از آن در برابر پوسته (تا پوسته آن را مصرف نکند). .IP "3." 3 در این مورد نیازی به محافظت از \f[CR]$\f[R] در برابر پوسته نیست، زیرا پس از آن نویسهٔ کلمه‌ای نیامده است؛ اما انجام این کار هم بی‌ضرر است. .PP اما روش دیگری نیز برای نوشتن آن وجود دارد که معمولاً ساده‌تر است: افزودن بک‌اسلش برای گریز از عبارت‌های باقاعده، و سپس محصور کردن آن در نقل‌قول برای گریز از پوسته: .IP .EX $ hledger balance cur:\(aq\(rs$\(aq .EE.SS "گریز دادن در موقعیت‌های دیگر" گزینه‌ها و آرگومان‌های hledger گاهی در جاهایی به جز خط فرمان به کار می‌روند که قوانین گریز دادن/نقل‌قول (escaping/quoting) در آن‌ها متفاوت است. برای نمونه، نقل‌قول با بک‌اسلش ممکن است در دسترس نباشد. در اینجا یک راهنمای مرجع سریع آورده شده است: .PP .TS tab(@); lw(17.5n) lw(52.5n). T{ در شل unix T}@T{ از نقل‌قول تکی و/یا بک‌اسلش (یا نقل‌قول دوتایی برای جایگذاری متغیرها) استفاده کنید T} T{ در \f[CR]powershell\f[R] ویندوز T}@T{ از نقل‌قول تکی (یا نقل‌قول دوتایی برای جایگذاری متغیرها) استفاده کنید T} T{ در \f[CR]cmd\f[R] ویندوز T}@T{ از نقل‌قول دوتایی استفاده کنید T} T{ در اعلان فیلتر hledger\-ui T}@T{ از نقل‌قول تکی یا دوتایی استفاده کنید T} T{ در فرم جستجوی hledger\-web T}@T{ از نقل‌قول تکی یا دوتایی استفاده کنید T} T{ در یک فایل آرگومان T}@T{ از فاصله استفاده نکنید، گریزدهی پوسته (shell\-escape) انجام ندهید، گریزدهی عبارات منظم (regex\-escape) را انجام دهید، در هر سطر یک آرگومان/گزینه بنویسید T} T{ در یک فایل پیکربندی T}@T{ از نقل‌قول تکی یا دوتایی استفاده کنید و کل آرگومان را درون آن قرار دهید (\f[CR]\(aqdesc:a b\(aq\f[R] نه \f[CR]desc:\(aqa b\(aq\f[R]) T} T{ در \f[CR]ghci\f[R] (محیط REPL زبان Haskell) T}@T{ از نقل‌قول دوتایی استفاده کنید و کل آرگومان را درون آن قرار دهید T} .TE .SS "کاراکترهای یونیکد" انتظار می‌رود hledger کاراکترهای غیر ascii را به درستی پردازش کند: .IP \(bu 2 آن‌ها باید در فایل‌های ورودی و در خط فرمان توسط تمامی ابزارهای hledger (مانند add،‏ iadd، فرم‌های جستجو/افزودن/ویرایش hledger\-web و غیره) به درستی تجزیه شوند .IP \(bu 2 آن‌ها باید توسط تمامی ابزارهای hledger به درستی نمایش داده شوند و چینش متن روی صفحه حفظ شود. .PP این امر نیازمند یک محیط به خوبی پیکربندی‌شده است. در اینجا چند نکته آورده شده است: .IP \(bu 2 یک locale برای سیستم باید پیکربندی شود تا بتواند کاراکترهای مورد استفاده را رمزگشایی کند. این مورد حیاتی است \- بخش Text encoding و Install: Text encoding را ببینید. .IP \(bu 2 نرم‌افزار ترمینال شما (مانند Terminal.app،‏ iTerm،‏ CMD.exe،‏ xterm و...) باید از یونیکد پشتیبانی کند. در ویندوز ممکن است نیاز به استفاده از Windows Terminal داشته باشید. .IP \(bu 2 ترمینال باید از قلمی استفاده کند که حاوی گلیف‌های یونیکد مورد نیاز باشد. .IP \(bu 2 ترمینال باید طوری پیکربندی شود که کاراکترهای عریض (wide characters) را با عرض دوگانه نمایش دهد (جهت حفظ چینش گزارش‌ها). .IP \(bu 2 در ویندوز، برای دستیابی به بهترین نتیجه باید hledger را در همان محیطی اجرا کنید که در آن ساخته شده است. به عنوان نمونه، hledger ساخته‌شده در محیط استاندارد CMD.EXE (مانند باینری‌های موجود در صفحه دانلود ما) ممکن است در هنگام اجرا در ترمینال cygwin یا msys با مشکلات نمایشی مواجه شود و بالعکس. (به عنوان نمونه #961 را ببینید)..SS "عبارات باقاعده (Regular expressions)" یک عبارت باقاعده (regexp) قطعه‌متن کوچکی است که در آن نویسه‌های خاصی (مانند \f[CR].\f[R]، \f[CR]\(ha\f[R]، \f[CR]$\f[R]، \f[CR]+\f[R]، \f[CR]*\f[R]، \f[CR]()\f[R]، \f[CR]|\f[R]، \f[CR][]\f[R]، \f[CR]\(rs\f[R]) معانی ویژه‌ای دارند و زبان کوچکی را برای تطبیق دقیق متن تشکیل می‌دهند \- که در hledger و جاهای دیگر بسیار کاربردی است. برای یادگیری کامل دربارهٔ آن‌ها، از regular\-expressions.info بازدید کنید. .PP ابزار hledger هر زمان که الگویی را برای تطبیق چیزی وارد کنید، از عبارات باقاعده پشتیبانی می‌کند؛ برای مثال در آرگومان‌های جستار (query)، نام‌های مستعار حساب، قواعد if در CSV، فرم جستجوی hledger\-web، جستجوی \f[CR]/\f[R] در hledger\-ui و غیره. ممکن است لازم باشد آن‌ها را داخل نقل‌قول (کوتیشن) قرار دهید، به‌ویژه در خط فرمان (به بخش نویسه‌های خاص در بالا مراجعه کنید). چند مثال در ادامه آمده است: .PP جستارهای نام حساب (برای استفاده در خط فرمان داخل نقل‌قول قرار گرفته‌اند): .IP .EX عبارت باقاعده: تطابق‌ها: \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- bank assets:bank, assets:bank:savings, expenses:art:banksy, ... :bank assets:bank:savings, expenses:art:banksy :bank: assets:bank:savings \(aq\(habank\(aq هیچ‌کدام ( \(ha با ابتدای متن مطابقت می‌یابد ) \(aqbank$\(aq assets:bank ( $ با انتهای متن مطابقت می‌یابد ) \(aqbig \(rs$ bank\(aq big $ bank ( \(rs معنای ویژهٔ نویسه بعدی را غیرفعال می‌کند ) \(aq\(rsbbank\(rsb\(aq assets:bank, assets:bank:savings ( \(rsb با مرزهای کلمه تطابق دارد ) \(aq(sav|check)ing\(aq saving یا checking ( (|) با هر یک از دو حالت تطابق می‌یابد ) \(aqsaving|checking\(aq saving یا checking ( پرانتزهای بیرونی لازم نیستند ) \(aqsavings?\(aq saving یا savings ( ? با ۰ یا ۱ مورد از مورد پیشین تطابق می‌یابد ) \(aqmy +bank\(aq my bank, my bank, ... ( + با ۱ یا چند مورد از مورد پیشین تطابق می‌یابد ) \(aqmy *bank\(aq mybank, my bank, my bank, ... ( * با ۰ یا چند مورد از مورد پیشین تطابق می‌یابد ) \(aqb.nk\(aq bank, bonk, b nk, ... ( . با هر نویسه‌ای مطابقت دارد ) .EE .PP برخی جستارهای دیگر: .IP .EX desc:\(aqamazon|amzn|audible\(aq تراکنش‌های Amazon cur:EUR مبالغی با نماد کالای حاوی EUR cur:\(aq\(rs$\(aq مبالغی با نماد کالای حاوی $ cur:\(aq\(ha\(rs$$\(aq فقط مبالغ $، نه مثلاً AU$ یا CA$ cur:....? مبالغی با نمادهای ۴ نویسه‌ای یا بیشتر tag:.=202[1\-3] مواردی با هر برچسبی که مقدار آن شامل 2021، 2022 یا 2023 باشد .EE .PP نام‌های مستعار حساب: پذیرش \f[CR].\f[R] به‌جای \f[CR]:\f[R] به‌عنوان جداکنندهٔ حساب: .IP .EX alias /\(rs./=: تمام نقطه‌ها در نام‌های حساب را با دونقطه جایگزین می‌کند .EE .PP نمایش چندین حساب سطح اول به‌صورت ترکیب‌شده در یک حساب: .IP .EX \-\-alias=\(aq/\(ha[\(ha:]+/=combined\(aq ( [\(ha:] با هر نویسه‌ای غیر از : تطابق دارد ) .EE .PP نمایش حساب‌ها با حذف بخش سطح دوم: .IP .EX \-\-alias \(aq/\(ha([\(ha:]+):[\(ha:]+/ = \(rs1\(aq یک حساب سطح اول و یک حساب سطح دوم را تطبیق می‌دهد و آن‌ها را فقط با حساب سطح اول جایگزین می‌کند ( \(rs1 در متن جایگزینی به‌معنای \(dqهر آن‌چه با نخستین بخش پرانتزدار عبارت باقاعده تطابق یافته\(dq است ) .EE .PP قواعد CSV: تطبیق رکوردهای CSV حاوی کدهای MCC مرتبط با غذاخوری: .IP .EX if \(rs?MCC581[124] .EE .PP تطبیق رکوردهای CSV با مبلغی مشخص در حوالی پایان یا آغاز ماه: .IP .EX if %amount \(rsb3\(rs.99 & %date (29|30|31|01|02|03)$ .EE.SS عبارت‌های باقاعده hledger (hledger\(aqs regular expressions) عبارت‌های باقاعده hledger از کتابخانه regex\-tdfa می‌آیند. اگر آن‌طور که انتظار دارید عمل نمی‌کنند، دانستن دقیق مواردی که پشتیبانی می‌کنند مهم است: .IP "1." 3 آن‌ها به بزرگی و کوچکی حروف حساس نیستند (case insensitive). .IP "2." 3 آن‌ها تطبیق درونی هستند (نیازی نیست کل رشته مورد تطبیق را پوشش دهند). .IP "3." 3 آن‌ها از نوع POSIX ERE (عبارت‌های باقاعده توسعه‌یافته) هستند. .IP "4." 3 آن‌ها همچنین از مرزهای کلمه گنو پشتیبانی می‌کنند (\f[CR]\(rsb\f[R]، \f[CR]\(rsB\f[R]، \f[CR]\(rs<\f[R]، \f[CR]\(rs>\f[R]). .IP "5." 3 ارجاع‌های به عقب (backreferences) هنگام جایگزینی متن در نام‌های مستعار حساب یا قوانین CSV پشتیبانی می‌شوند؛ در این بخش‌ها می‌توان از ارجاع‌های به عقب در رشته جایگزین برای ارجاع به گروه‌های گیرنده (capturing groups) در عبارت باقاعده جستجو استفاده کرد. در غیر این صورت، اگر \f[CR]\(rs1\f[R] را بنویسید، با رقم \f[CR]1\f[R] تطبیق می‌یابد. .IP "6." 3 آن‌ها از کمّیت‌سنج‌های تنبل (\f[CR]*?\f[R])، تغییردهنده‌های حالت (\f[CR](?s)\f[R])، کلاس‌های نویسه (\f[CR]\(rsw\f[R]، \f[CR]\(rsd\f[R]) یا هر چیز دیگری که در بالا ذکر نشده است پشتیبانی نمی‌کنند. .IP "7." 3 آن‌ها ممکن است (احتمالاً نه) به‌درستی از متن‌های راست‌به‌چپ یا دوجهته پشتیبانی نکنند. .PP چند نکته قابل توجه: .IP \(bu 2 در دستورالعمل \f[CR]alias\f[R] و گزینه \f[CR]\-\-alias\f[R]، عبارت‌های باقاعده باید درون اسلش‌های رو به جلو قرار گیرند (\f[CR]/REGEX/\f[R]). در جاهای دیگر در hledger، این کار الزامی نیست. .IP \(bu 2 در پرس‌وجوها، برای تطبیق یک فرانویسه عبارت باقاعده مانند \f[CR]$\f[R] به عنوان یک نویسه لفظی، یک بک‌اسلش در ابتدا قرار دهید. به عنوان مثال برای جستجوی مبالغ دارای علامت دلار در hledger\-web، بنویسید \f[CR]cur:\(rs$\f[R]. .IP \(bu 2 در خط فرمان، برخی از فرانویسه‌ها مانند \f[CR]$\f[R] معنای خاصی برای شل دارند و بنابراین باید حداقل یک بار دیگر گریز داده شوند. بخش نویسه‌های خاص (Special characters) را ببینید. .SS فایل‌های آرگومان (Argument files) شما می‌توانید مجموعه‌ای از گزینه‌ها و آرگومان‌های خط فرمان را در یک فایل ذخیره کرده و سپس با نوشتن \f[CR]\(atFILE.args\f[R] به عنوان یک آرگومان دستور hledger از آن‌ها استفاده کنید. پسوند فایل \f[CR].args\f[R] مرسوم است، اما الزامی نیست. در یک فایل آرگومان: .IP \(bu 2 هر خط می‌تواند شامل یک آرگومان، پرچم یا گزینه باشد. .IP \(bu 2 خطوط خالی یا خطوطی که با \f[CR]#\f[R] شروع می‌شوند نادیده گرفته می‌شوند. .IP \(bu 2 پرچم و مقدار یک گزینه باید با \f[CR]=\f[R] به یکدیگر متصل شوند. .IP \(bu 2 مقدار یک گزینه یا یک آرگومان می‌تواند حاوی فاصله باشد. از نقل‌قول‌های تکی یا جفتی استفاده نکنید. .IP \(bu 2 و به‌طور کلی، از یک سطح نقل‌قول/گریز کمتر نسبت به خط فرمان استفاده کنید. به عنوان مثال \f[CR]cur:\(rs$\f[R]، نه \f[CR]cur:\(rs\(rs$\f[R] مانند آنچه در خط فرمان است. .PP برای مثال: .IP .EX # cash.args assets:cash assets:charles schwab:sweep cur:\(rs$ \-c=$1. .EE .IP .EX $ hledger bal \(atcash.args .EE .SS فایل‌های پیکربندی (Config files) با hledger نسخه 1.40 به بالا، می‌توانید گزینه‌ها و آرگومان‌های اضافی خط فرمان را در یک فایل پیکربندی کامل‌تر hledger ذخیره کنید. در اینجا یک مثال کوچک آمده است: .IP .EX \f[I]# General options are listed first, and used with hledger commands that support them.\f[R] \-\-pretty \f[I]# Options following a \(ga[COMMAND]\(ga heading are used with that hledger command only.\f[R] \f[B][print]\f[R] \-\-explicit \-\-infer\-costs .EE .PP برای استفاده از یک فایل پیکربندی، آن را با گزینه \f[CR]\-\-conf\f[R] مشخص کنید. گزینه‌های آن در نزدیکی ابتدای خط فرمان شما درج می‌شوند، بنابراین در صورت نیاز می‌توانید آن‌ها را با گزینه‌های خط فرمان بازنویسی کنید. .PP یا می‌توانید با ایجاد \f[CR]hledger.conf\f[R] در دایرکتوری جاری یا دایرکتوری‌های بالاتر، یا \f[CR].hledger.conf\f[R] در دایرکتوری خانگی خود (\f[CR]\(ti/.hledger.conf\f[R])، یا \f[CR]hledger.conf\f[R] در دایرکتوری پیکربندی XDG خود (\f[CR]\(ti/.config/hledger/hledger.conf\f[R])، یک فایل پیکربندی خودکار تنظیم کنید که هر زمان hledger را اجرا می‌کنید مورد استفاده قرار گیرد. .PP در اینجا یک نمونه پیکربندی دیگر وجود دارد که می‌توانید از آن شروع کنید: https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample .PP شما می‌توانید نه تنها گزینه‌ها، بلکه آرگومان‌ها را نیز در فایل پیکربندی قرار دهید. اگر اولین کلمه در بخش بالایی (عمومی) یک فایل پیکربندی با خط تیره شروع نشود (مانند: \f[CR]print\f[R])، به عنوان آرگومان دستور در نظر گرفته می‌شود (و هر آرگومانی را در خط فرمان لغو می‌کند). .PP در رایانه‌های یونیکس، می‌توانید یک خط shebang در بالای فایل پیکربندی اضافه کنید، مجوز اجرا را روی فایل تنظیم کرده و مانند یک اسکریپت از آن استفاده کنید. برای مثال (\f[CR]\-S\f[R] در برخی سیستم‌عامل‌ها مورد نیاز است): .IP .EX #!/usr/bin/env \-S hledger \-\-conf .EE .PP شما می‌توانید با افزودن پرچم \f[CR]\-n\f[R]/\f[CR]\-\-no\-conf\f[R] به خط فرمان، فایل‌های پیکربندی را نادیده بگیرید. این قابلیت هنگام استفاده از hledger در اسکریپت‌ها یا هنگام عیب‌یابی مفید است. هنگامی که هر دو گزینه \f[CR]\-\-conf\f[R] و \f[CR]\-\-no\-conf\f[R] استفاده شوند، گزینه سمت راستی اولویت دارد. .PP برای بررسی نحوه پردازش فایل‌های پیکربندی، از \f[CR]\-\-debug\f[R] یا \f[CR]\-\-debug=8\f[R] استفاده کنید. یا دستور \f[CR]setup\f[R] را اجرا کنید که هرگونه فایل پیکربندی فعال را نمایش می‌دهد. (برخلاف سایر دستورات، خود \f[CR]setup\f[R] تحت تأثیر فایل‌های پیکربندی قرار نمی‌گیرد.) .PP \f[B]هشدار!\f[R] .PP قابلیت‌های زیادی در hledger وجود ندارند که نیازمند هشدار باشند، اما این یکی هست! .PP فایل‌های پیکربندی خودکار در عین راحتی، hledger را کمتر قابل پیش‌بینی و اتکا می‌کنند. ساختن یک فایل پیکربندی که رفتار یک گزارش را تغییر دهد یا اسکریپت‌ها/برنامه‌های متکی بر hledger شما را به روش‌هایی خراب کند که بعداً شما را شگفت‌زده کند، آسان است. .PP اگر این را نمی‌خواهید: .IP "1." 3 فقط فایل hledger.conf را روی سیستم خود ایجاد نکنید. .IP "2." 3 همچنین مراقب دایرکتوری‌های دانلودشده که ممکن است حاوی یک فایل hledger.conf باشند باشید. .IP "3." 3 همچنین اگر در حال اشتراک‌گذاری اسکریپت‌ها، مثال‌ها یا پشتیبانی هستید، توجه داشته باشید که دیگران ممکن است یک فایل hledger.conf داشته باشند. .PP برعکس، هنگامی که تصمیم به استفاده از این قابلیت گرفتید، سعی کنید به یاد داشته باشید: .IP "1." 3 هر زمان که یک دستور hledger طبق انتظار کار نکرد، دوباره آن را با \f[CR]\-n\f[R] (\f[CR]\-\-no\-conf\f[R]) اجرا کنید تا ببینید آیا فایل پیکربندی مقصر بوده است یا خیر. .IP "2." 3 هر زمان که hledger را از یک اسکریپت فراخوانی می‌کنید، در نظر بگیرید که آیا آن فراخوانی باید از \f[CR]\-n\f[R] استفاده کند یا خیر. .IP "3." 3 در مورد آنچه در فایل پیکربندی خود قرار می‌دهید محتاط باشید؛ سعی کنید تأثیر آن را بر تمام گزارش‌های خود در نظر بگیرید. .IP "4." 3 برای عیب‌یابی تأثیر فایل‌های پیکربندی، با \f[CR]\-\-debug\f[R] یا \f[CR]\-\-debug 8\f[R] اجرا کنید. .PP قابلیت فایل پیکربندی در hledger 1.40 اضافه شد..SS "تکمیل خودکار در پوسته (Shell completions)" اگر از پوسته‌های bash یا zsh استفاده می‌کنید، می‌توانید در صورت تمایل تکمیل خودکار حساس به متن را برای خطوط فرمان hledger تنظیم کنید. فشردن \f[CR]hledger\f[R] (که باید تمام دستورات hledger را فهرست کند) یا \f[CR]hledger reg acct:\f[R] (که باید نام حساب‌های سطح بالای شما را فهرست کند) را امتحان کنید. اگر تکمیل خودکار کار نمی‌کند، یا برای جزئیات بیشتر، به Install > Shell completions مراجعه کنید. .SH "خروجی (OUTPUT)" .SS "مقصد خروجی (Output destination)" دستورات hledger خروجی خود را به‌طور پیش‌فرض به ترمینال ارسال می‌کنند. البته می‌توانید با استفاده از نحو استاندارد پوسته، آن را تغییر مسیر دهید، مثلاً به درون یک فایل: .IP .EX $ hledger print > foo.txt .EE .PP برخی از دستورات (print، register، stats و دستورات balance) گزینهٔ \f[CR]\-o\f[R]/\f[CR]\-\-output\-file\f[R] را نیز ارائه می‌دهند که همین کار را بدون نیاز به پوسته انجام می‌دهد. به عنوان مثال: .IP .EX $ hledger print \-o foo.txt $ hledger print \-o \- # write to stdout (the default) .EE .SS "قالب خروجی (Output format)" برخی از دستورات انواع دیگری از خروجی را نیز ارائه می‌دهند، نه فقط متن روی ترمینال. در اینجا آن دستورات و قالب‌هایی که در حال حاضر پشتیبانی می‌شوند آورده شده است: .PP .TS tab(@); lw(20.6n) lw(5.1n) lw(6.2n) lw(9.3n) lw(6.2n) lw(11.3n) lw(5.1n) lw(6.2n). T{ command T}@T{ txt T}@T{ html T}@T{ csv/tsv T}@T{ fods T}@T{ beancount T}@T{ sql T}@T{ json T} _ T{ aregister T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T}@T{ Y T} T{ balance T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T}@T{ Y T} T{ balancesheet T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T}@T{ Y T} T{ balancesheetequity T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T}@T{ Y T} T{ cashflow T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T}@T{ Y T} T{ incomestatement T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T}@T{ Y T} T{ print T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T} T{ register T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T}@T{ Y T} .TE .PP همچنین می‌توانید با اجرای \f[CR]hledger CMD \-h\f[R] و بررسی گزینهٔ \f[CR]\-O\f[R]/\f[CR]\-\-output\-format=FMT\f[R] ببینید که یک دستور از چه قالب‌های خروجی پشتیبانی می‌کند،.PP می‌توانید قالب خروجی را با استفاده از آن گزینه تعیین کنید: .IP .EX $ hledger print \-O csv # print CSV to standard output .EE .PP یا با انتخاب یک پسوند نام فایل مناسب به کمک گزینهٔ \f[CR]\-o\f[R]/\f[CR]\-\-output\-file=FILE.FMT\f[R]: .IP .EX $ hledger balancesheet \-o foo.csv # write CSV to foo.csv .EE .PP در صورت نیاز، گزینهٔ \f[CR]\-O\f[R] می‌تواند با \f[CR]\-o\f[R] ترکیب شود تا پسوند فایل را لغو و جایگزین کند: .IP .EX $ hledger balancesheet \-o foo.txt \-O csv # write CSV to foo.txt .EE .PP در ادامه نکاتی پیرامون قالب‌های مختلف خروجی آمده است. .SS "خروجی متنی (Text output)" این حالت پیش‌فرض است: خروجی گزارش به صورت متن ساده و خوانا برای انسان، مناسب برای مشاهده با قلمی با عرض یکسان (monospace) در یک ترمینال. اگر داده‌های شما حاوی نویسه‌های یونیکد یا عریض هستند، به ترمینال و قلمی نیاز خواهید داشت که آن‌ها را به درستی نمایش دهند. (این امر ممکن است در MS Windows چالش‌برانگیز باشد.) .PP برخی از گزارش‌ها (\f[CR]register\f[R]، \f[CR]aregister\f[R]) به طور معمول از تمام عرض پنجره استفاده می‌کنند. اگر این حالت به درستی کار نمی‌کند یا مایل به تغییر آن هستید، می‌توانید از گزینهٔ \f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] استفاده کنید. .PP گزارش‌های ترازنامه و موجودی (\f[CR]balance\f[R]، \f[CR]balancesheet\f[R]، \f[CR]incomestatement\f[R]...) به هر میزان عرض که نیاز داشته باشند استفاده می‌کنند. گزارش‌های چنددوره‌ای و چندارزی اغلب می‌توانند از عرض پنجره فراتر بروند. علاوه بر استفاده از یک صفحه‌بند (pager)، فنون کاربردی برای این وضعیت عبارتند از: \f[CR]\-\-layout=bare\f[R]، \f[CR]\-X COMM\f[R]، \f[CR]cur:\f[R]، \f[CR]\-\-transpose\f[R]، \f[CR]\-\-tree\f[R]، \f[CR]\-\-depth\f[R]، \f[CR]\-\-drop\f[R]، تغییر وضعیت به خروجی html و غیره. .SS "نویسه‌های رسم کادر (Box\-drawing characters)" برنامهٔ hledger به طور پیش‌فرض حاشیه‌های جدول را به شکل ساده رسم می‌کند تا خطر بروز مشکلات نمایشی ناشی از عدم پشتیبانی ترمینال یا قلم از نویسه‌های رسم کادر به حداقل برسد. .PP اما ترمینال و قلم شما احتمالاً از آن‌ها پشتیبانی می‌کنند؛ بنابراین توصیه می‌کنیم از پرچم \f[CR]\-\-pretty\f[R] برای نمایش جدول‌های زیباتر در ترمینال استفاده کنید. این پرچم گزینهٔ مناسبی برای افزودن به فایل پیکربندی hledger شما است. .SS "رنگ (Colour)" ابزار hledger تلاش می‌کند پشتیبانی از رنگ‌های ANSI و استایل‌های متنی را به صورت خودکار شناسایی کند و در مواقع مناسب آن را به کار گیرد. (در حال حاضر، این قابلیت به صورت حداقلی استفاده می‌شود: برخی گزارش‌ها اعداد منفی را با رنگ قرمز نمایش می‌دهند و خروجی راهنما از متن برجسته (bold) برای تأکید بهره می‌برد.) .PP شما می‌توانید با تنظیم متغیر محیطی \f[CR]NO_COLOR\f[R] برای غیرفعال کردن آن، یا با استفاده از گزینهٔ \f[CR]\-\-color/\-\-colour\f[R] (احتمالاً در فایل پیکربندی‌تان) همراه با مقدار \f[CR]y\f[R]/\f[CR]yes\f[R] یا \f[CR]n\f[R]/\f[CR]no\f[R] جهت اجبار به فعال یا غیرفعال بودن، این رفتار را تغییر دهید. .SS "صفحه‌بندی (Paging)" در محیط‌های شبه‌یونیکس (unix\-like)، هنگام نمایش خروجی‌های حجیم (در هر قالبی) در ترمینال، hledger تلاش می‌کند در صورت لزوم از یک صفحه‌بند استفاده کند. (می‌توانید این قابلیت را با گزینهٔ \f[CR]\-\-pager=no\f[R]، مثلاً در فایل پیکربندی خود، غیرفعال کنید.) .PP صفحه‌بند هر بار یک صفحه از متن را نشان می‌دهد و به شما امکان می‌دهد برای دیدن متن بیشتر به بخش‌های مختلف پیمایش کنید. هنگام فعال بودن آن، معمولاً کلید \f[CR]SPACE\f[R] صفحهٔ بعدی را نشان می‌دهد، کلید \f[CR]h\f[R] راهنما را باز می‌کند و \f[CR]q\f[R] خارج می‌شود. کلیدهای پیمایش ماوس، کلیدهای جهت‌نما، و کلیدهای home/end/page up/page down نیز ممکن است کار کنند. .PP برنامهٔ hledger از صفحه‌بند مشخص‌شده در متغیر محیطی \f[CR]PAGER\f[R] استفاده خواهد کرد؛ در غیر این صورت، در صورت وجود از \f[CR]less\f[R]، و سپس در صورت دردسترس بودن از \f[CR]more\f[R] استفاده خواهد کرد. (با یک استثنا: دستور \f[CR]hledger help \-p TOPIC\f[R] همواره از \f[CR]less\f[R] استفاده می‌کند تا بتواند به بخش مربوط به آن مبحث پیمایش کند.) .PP انتظار می‌رود که صفحه‌بند رنگ‌های ANSI و استایل‌بندی متن hledger را نمایش دهد. اگر نویسه‌های به‌هم‌ریخته و نامفهوم مشاهده می‌کنید، ممکن است نیاز باشد صفحه‌بند خود را برای پردازش کدهای ANSI پیکربندی کنید. یا می‌توانید رنگ را طبق توضیحات بالا غیرفعال نمایید. .PP اگر از صفحه‌بند \f[CR]less\f[R] استفاده می‌کنید، hledger سعی می‌کند با اجرای آن به همراه گزینه‌های اضافی اضافه‌شده به متغیر محیطی \f[CR]LESS\f[R] شما، تجربه‌ای همواره روان و بی‌نقص ارائه دهد: .PP \-\-chop\-long\-lines \-\-hilite\-unread \-\-ignore\-case \-\-no\-init \-\-quit\-if\-one\-screen \-\-shift=8 \-\-squeeze\-blank\-lines \-\-use\-backslash .PP و هنگامی که خروجی رنگی فعال باشد: .PP \-\-RAW\-CONTROL\-CHARS .PP می‌توانید با تعریف گزینه‌های مورد نظر خود در متغیر \f[CR]HLEDGER_LESS\f[R] که به جای \f[CR]LESS\f[R] استفاده خواهد شد، از این سازوکار جلوگیری کنید..SS خروجی HTML خروجی HTML می‌تواند با یک فایل اختیاری \f[CR]hledger.css\f[R] در همان دایرکتوری استایل‌بندی شود. .PP خروجی HTML یک قطعه‌کد HTML خواهد بود، نه یک سند کامل HTML. مانند سایر خروجی‌های hledger، برای نویسه‌های غیر\-ASCII از کدگذاری متن locale سیستم استفاده خواهد کرد (بخش Text encoding را ببینید). .SS خروجی CSV / TSV در خروجی CSV یا TSV، نشانه‌های گروه‌بندی ارقام (مانند جداکننده‌های هزارگان) به‌طور خودکار غیرفعال می‌شوند. .SS خروجی FODS فرمت FODS همان قالب OpenDocument Spreadsheet به‌صورت XML ساده است، آن‌گونه که توسط LibreOffice و OpenOffice پذیرفته می‌شود. اگر از برنامه‌های صفحه‌گسترده آن‌ها استفاده می‌کنید، این قالب بهتر از CSV است زیرا در localeهای گوناگون کار می‌کند (نقطه اعشار در برابر کامای اعشار، ذخیره کدگذاری نویسه‌ها در سرآیند XML و در نتیجه عدم بروز مشکل با اوملاوت‌ها)، از ردیف‌ها و ستون‌های ثابت سرآیند، نوع سلول‌ها (رشته در برابر عدد در برابر تاریخ)، تفکیک عدد و واحد پول (واحد پول نمایش داده می‌شود اما نوع سلول همچنان عددی و برای محاسبات در دسترس است)، سبک‌ها (حالت برجسته/bold) و حاشیه‌ها پشتیبانی می‌کند. ضمناً همچنان می‌توانید با استفاده از ابزارهای مختلفی مانند \f[CR]libreoffice \-\-headless\f[R] یا ods2csv از FODS/ODS داده‌های CSV را استخراج کنید. .SS خروجی Beancount این قالب دفتر روزنامه Beancount است. می‌توانید از این برای برون‌بری داده‌های hledger خود به Beancount، مثلاً برای استفاده از برنامه تحت وب Fava بهره ببرید. .PP ابزار hledger تلاش خواهد کرد تا داده‌های شما را به‌طور خودکار متناسب با Beancount تنظیم کند. محتاط باشید و تبدیل را بررسی کنید تا زمانی که از درستی آن مطمئن شوید. اگر قصد دارید به‌طور مکرر به Beancount خروجی بگیرید، ممکن است برای تبدیلی تمیزتر بخواهید از قواعد آن پیروی کنید: .IP \(bu 2 استفاده از نام‌های حساب سازگار با Beancount .IP \(bu 2 استفاده از کدهای ارز به‌جای نمادهای ارز .IP \(bu 2 استفاده از نشانه‌گذاری بهای تمام‌شده (cost notation) به‌جای ثبت‌های تبدیل حقوق صاحبان سهام (equity conversion postings) .IP \(bu 2 اجتناب از ثبت‌های مجازی، تخصیص‌های تراز (balance assignments) و تاریخ‌های ثانویه. .PP یک تنظیم اساسی وجود دارد که باید خودتان آن را مدیریت کنید: برای Beancount، نام حساب‌های سطح بالا باید \f[CR]Assets\f[R]، \f[CR]Liabilities\f[R]، \f[CR]Equity\f[R]، \f[CR]Income\f[R] و/یا \f[CR]Expenses\f[R] باشند. در صورت نیاز می‌توانید از نام‌های مستعار حساب برای بازنویسی موقت نام‌های حساب خود استفاده کنید، مانند آنچه در فایل پیکربندی hledger2beancount.conf آمده است. .PP 2024\-12\-20: چند مورد دیگر که هنوز برای شما به‌طور خودکار انجام نمی‌شوند: .IP \(bu 2 دستورالعمل‌های P به‌طور خودکار تبدیل نمی‌شوند \- آن‌ها را خودتان تبدیل کنید. .IP \(bu 2 تخصیص‌های تراز (Balance assignments) تبدیل نمی‌شوند (Beancount از آن‌ها پشتیبانی نمی‌کند) \- آن‌ها را با مقادیر صریح جایگزین کنید. .SS نام‌های حساب Beancount جدا از نام‌های سطح بالا، hledger با بزرگ نوشتن حرف اول هر بخش، جایگزینی فاصله‌ها با \f[CR]\-\f[R]، جایگزینی سایر نویسه‌های پشتیبانی‌نشده با \f[CR]C\f[R]، افزودن \f[CR]A\f[R] به ابتدای بخش‌هایی از نام حساب که با یک حرف یا رقم آغاز نمی‌شوند، و افزودن \f[CR]:A\f[R] به نام‌های حسابی که فقط از یک بخش تشکیل شده‌اند، نام‌های حساب شما را به نام‌های حساب معتبر در Beancount تبدیل می‌کند. .SS نام‌های کالای Beancount ابزار hledger نام‌های کالای (commodity) شما را جهت تبدیل به نام‌های معتبر کالا/ارز در Beancount تنظیم خواهد کرد؛ این نام‌ها باید بین ۲ تا ۲۴ نویسه از حروف بزرگ، ارقام، یا \f[CR]\(aq\f[R]، \f[CR].\f[R]، \f[CR]_\f[R]، \f[CR]\-\f[R] باشند که با یک حرف شروع شده و با یک حرف یا رقم پایان می‌یابند. ابزار hledger نمادهای ارزی شناخته‌شده را به کدهای ارزی ISO 4217 تبدیل می‌کند، حروف را بزرگ می‌سازد، فاصله‌ها را با \f[CR]\-\f[R] جایگزین می‌کند، سایر نویسه‌های پشتیبانی‌نشده را با \f[CR]C\f[R] جایگزین می‌نماید، و در صورت نیاز \f[CR]C\f[R] را به ابتدا یا انتهای آن می‌افزاید. .SS ثبت‌های مجازی Beancount ابزار Beancount اجازه استفاده از ثبت‌های مجازی را نمی‌دهد؛ اگر مواردی از آن‌ها را داشته باشید، از خروجی Beancount حذف خواهند شد. .SS متاداده Beancount برچسب‌های hledger به متاداده‌های Beancount تبدیل خواهند شد (به‌جز برچسب‌هایی که نام آن‌ها با \f[CR]_\f[R] آغاز می‌شود). نام‌های متاداده طوری تنظیم می‌شوند که با Beancount سازگار باشند: با یک حرف کوچک آغاز شوند، حداقل دو نویسه طول داشته باشند، و نویسه‌های پشتیبانی‌نشده کدگذاری شوند. مقادیر متاداده از نوع رشته‌ای (string) Beancount استفاده خواهند کرد. .PP در hledger، اشیاء می‌توانند یک برچسب یکسان را با مقادیر متعدد تکرار کنند. برای نمونه یک حساب \f[CR]assets:cash\f[R] ممکن است هر دو برچسب \f[CR]type:Asset\f[R] و \f[CR]type:Cash\f[R] را داشته باشد. برای Beancount این برچسب‌ها با یکدیگر ترکیب شده و مقادیر آن‌ها با کاما از هم جدا می‌شوند. مانند: \f[CR]type: \(dqAsset, Cash\(dq\f[R]..SS "هزینه‌های Beancount (Beancount costs)" Beancount برخلاف hledger، هزینه‌ها و ثبت‌های تبدیل (conversion postings) اضافی را مجاز نمی‌داند. اگر هر یک از این موارد را داشته باشید، ثبت‌های تبدیل حذف خواهند شد. در حال حاضر حداکثر از یک گروه «هزینه + ثبت‌های تبدیل» در هر تراکنش پشتیبانی می‌کنیم. .SS "ارز عملیاتی Beancount (Beancount operating currency)" اعلان یک (یا چند) ارز عملیاتی، گزارش‌های Beancount و Fava را بهبود می‌بخشد. در حال حاضر hledger هر ارزی را که در مقادیر هزینه استفاده شده باشد به عنوان یک ارز عملیاتی اعلام می‌کند. در صورت نیاز، این موارد را با اعلان خود جایگزین کنید، مانند: .IP .EX option \(dqoperating_currency\(dq \(dqUSD\(dq .EE .SS "خروجی SQL (SQL output)" انتظار می‌رود خروجی SQL دست‌کم با SQLite، MySQL و Postgres کار کند. .PP انتظار می‌رود دستورات SQL در یک پایگاه داده خالی اجرا شوند. اگر از قبل جدول‌هایی دارید که از طریق خروجی SQL در hledger ایجاد شده‌اند، احتمالاً بهتر است پیش از درون‌ریزی، یا داده‌های آن‌ها را پاک کنید (از طریق دستورات SQL مانند \f[CR]delete\f[R] یا \f[CR]truncate\f[R]) یا جدول‌ها را به‌طور کامل \f[CR]drop\f[R] کنید؛ در غیر این صورت ثبت‌های شما تکراری خواهند شد. .PP برای SQLite، مفیدتر است که فیلد \f[CR]id\f[R] تولیدشده را به یک PRIMARY KEY تغییر دهید. به عنوان مثال: .IP .EX $ hledger print \-O sql | sed \(aqs/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g\(aq | ... .EE .PP این قابلیت هنوز چندان مورد استفاده قرار نگرفته است؛ از بازخوردها استقبال می‌شود. .SS "خروجی JSON (JSON output)" خروجی JSON ما نسبتاً بزرگ و پرحجم (verbose) است، چرا که بازنمایی دقیقی از انواع داده‌های داخلی hledger است. برای درک ساختار آن، تعاریف نوع Haskell را که بیشتر در نشانی زیر قرار دارند مطالعه کنید: https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs مشخصات OpenAPI مربوط به hledger\-web نیز ممکن است مرتبط باشد. .PP hledger اعداد را گاهی تا ۲۵۵ رقم بااهمیت ذخیره می‌کند. این تعداد رقم برای بیشتر مصرف‌کنندگان JSON بیش از حد زیاد است، بنابراین در خروجی JSON اعداد را حداکثر تا ۱۰ رقم اعشار گرد می‌کنیم. (ما تعداد ارقام صحیح را محدود نمی‌کنیم.) اگر متوجه شدید که این مسئله مشکلی ایجاد می‌کند، لطفاً به ما اطلاع دهید. مرتبط: #1195 .PP این قابلیت هنوز چندان مورد استفاده قرار نگرفته است؛ از بازخوردها استقبال می‌شود. .SS "شیوه‌های کالا (Commodity styles)" هنگام نمایش مقادیر، hledger یک شیوه نمایش استاندارد را برای هر کالا/ارز استنتاج می‌کند، همان‌طور که در ادامه در «شیوه نمایش کالا» توضیح داده شده است. .PP در صورت نیاز، می‌توان این شیوه را با گزینه \f[CR]\-c/\-\-commodity\-style\f[R] بازنویسی کرد (به‌جز برای مقادیر هزینه و مقادیر نمایش‌داده‌شده توسط دستور \f[CR]print\f[R]، که همیشه با تمام ارقام اعشار نمایش داده می‌شوند). برای مثال، دستور زیر مقادیر دلاری را مجبور می‌کند تا به صورت نشان‌داده‌شده نمایش داده شوند: .IP .EX $ hledger print \-c \(aq$1.000,0\(aq .EE .PP این گزینه می‌تواند برای تعیین شیوه نمایش برای چندین کالا/ارز تکرار شود. آرگومان آن همان‌طور است که در دستورالعمل commodity شرح داده شده است. توجه داشته باشید که حذف نماد کالا، شیوه نمایش را تنها برای کالای بدون نماد تعیین می‌کند، نه تمام کالاها. .PP در برخی موارد hledger قالب‌بندی اعداد را برای بهبود قابلیت تجزیه (parseability) آن‌ها تنظیم می‌کند (مانند افزودن ممیزهای اعشاری انتهایی در صورت نیاز). .SS "خروجی اشکال‌زدایی (Debug output)" هدف ما این است که عیب‌یابی، بررسی درونی و توسعه hledger نسبتاً آسان باشد. می‌توانید \f[CR]\-\-debug[=N]\f[R] را به هر خط فرمان hledger اضافه کنید تا خروجی اشکال‌زدایی اضافی را مشاهده کنید. مقدار N از ۱ (کمترین خروجی، پیش‌فرض) تا ۹ (بیشترین خروجی) متغیر است. معمولاً از ۱ شروع می‌کنید و تا زمانی که خروجی کافی ببینید، آن را افزایش می‌دهید. خروجی اشکال‌زدایی به stderr ارسال می‌شود و تحت تأثیر \f[CR]\-o/\-\-output\-file\f[R] قرار نمی‌گیرد (مگر اینکه stderr را به stdout تغییر مسیر دهید، مانند: \f[CR]2>&1\f[R]). این خروجی با خروجی عادی درهم‌آمیخته می‌شود، که می‌تواند به آشکار شدن زمان ارزیابی بخش‌هایی از کد کمک کند. برای ثبت خروجی اشکال‌زدایی در یک فایل گزارش به جای آن، معمولاً می‌توانید stderr را تغییر مسیر دهید، مانند: .IP .EX hledger bal \-\-debug=3 2>hledger.log .EE .PP (این گزینه هنوز در فایل پیکربندی کار نمی‌کند.).SH "محیط (ENVIRONMENT)" این متغیرهای محیطی بر hledger تأثیر می‌گذارند: .PP \f[B]HLEDGER_LESS\f[R] اگر \f[CR]less\f[R] صفحه‌بند (pager) شما باشد، این متغیر گزینه‌های \f[CR]less\f[R] را که hledger باید استفاده کند، مشخص می‌نماید. (در غیر این صورت، \f[CR]LESS\f[R] + گزینه‌های سفارشی استفاده می‌شوند.) .PP \f[B]LEDGER_FILE\f[R] فایل ژورنال پیش‌فرض، برای زمانی که هیچ گزینهٔ \f[CR]\-f/\-\-file\f[R] ارائه نشده باشد. برای مثال، می‌تواند \f[CR]\(ti/finance/main.journal\f[R] باشد. این مقدار همچنین می‌تواند یک الگوی glob باشد، مانند \f[CR]./2???.journal\f[R]. (اگر الگو با چندین فایل تطبیق یابد، تنها نخستین فایل بر اساس ترتیب الفبایی\-عددی استفاده می‌شود.) اگر LEDGER_FILE به فایلی اشاره کند که وجود ندارد، خطایی رخ خواهد داد. اگر مقدار آن یک رشتهٔ خالی باشد، نادیده گرفته می‌شود. .PP اگر LEDGER_FILE تنظیم نشده باشد و \f[CR]\-f\f[R] نیز ارائه نشود، فایل ژورنال پیش‌فرض \f[CR]$HOME/.hledger.journal\f[R] خواهد بود (یا چنانچه دایرکتوری خانگی شناسایی نشود، \f[CR]./.hledger.journal\f[R]). .PP همچنین بخش کارهای متداول > تنظیم LEDGER_FILE (Common tasks > Setting LEDGER_FILE) را ببینید. .PP \f[B]NO_COLOR\f[R] اگر این متغیر محیطی وجود داشته باشد (با هر مقداری، از جمله خالی)، hledger از کدهای رنگ ANSI در خروجی ترمینال استفاده نخواهد کرد، مگر اینکه با یک گزینهٔ صریح \f[CR]\-\-color=y\f[R] یا \f[CR]\-\-colour=y\f[R] لغو شود. .SH "بخش ۲: قالب‌های داده (PART 2: DATA FORMATS)" .SH "ژورنال (Journal)" منبع دادهٔ معمول hledger یک فایل متنی ساده (plain text) است که شامل ورودی‌های ژورنال در قالب \f[CR]journal\f[R] متعلق به hledger است. اگر به‌دنبال یک مرجع سریع هستید، به برگهٔ تقلب ژورنال بروید (یا از فهرست مطالب در استفاده کنید). .PP این فایل نشان‌دهندهٔ یک دفتر روزنامهٔ عمومی (General Journal) حسابداری است. پسوند فایل \f[CR].journal\f[R] بیشتر از همه استفاده می‌شود، گرچه کاملاً الزامی نیست. فایل ژورنال شامل تعدادی ورودی تراکنش است که هر یک انتقال پول (یا هر کالا و واحدی) را میان دو یا چند حساب نام‌گذاری‌شده، در قالبی ساده که هم برای انسان و هم برای hledger خواناست، توصیف می‌کند. .PP قالب ژورنال hledger با بیشتر بخش‌های قالب ژورنال Ledger سازگار است، اما نه با همهٔ آن. تفاوت‌ها و نکات تعامل‌پذیری در hledger and Ledger شرح داده شده‌اند. با کمی دقت و اجتناب از ویژگی‌های ناسازگار، می‌توانید ژورنال hledger خود را برای Ledger نیز خوانا نگه دارید و برعکس. این امر می‌تواند برای مثال در مقایسهٔ رفتار یک برنامه در برابر برنامهٔ دیگر مفید باشد. .PP شما می‌توانید بدون یادگیری بیشتر دربارهٔ این فایل از hledger استفاده کنید؛ تنها کافی است از دستورهای add یا web یا import برای ایجاد و به‌روزرسانی آن بهره ببرید. .PP با این حال، بسیاری از کاربران فایل ژورنال را با یک ویرایشگر متن ویرایش می‌کنند و تغییرات را با یک سیستم کنترل نسخه مانند git پیگیری می‌نمایند. افزونه‌های ویرایشگر مانند ledger\-mode یا hledger\-mode برای Emacs، vim\-ledger برای Vim، و hledger\-vscode برای Visual Studio Code این کار را با افزودن رنگ، قالب‌بندی، تکمیل با Tab، و دستورهای مفید آسان‌تر می‌کنند. برای فهرست کامل، Editors را در hledger.org ببینید. .PP یک فایل ژورنال hledger می‌تواند شامل سه نوع مورد باشد: خطوط توضیح، تراکنش‌ها، و/یا دستورالعمل‌ها (شامل قواعد تراکنش‌های دوره‌ای و قواعد ارسال خودکار). درک قالب فایل ژورنال همچنین فهم خوبی از مدل دادهٔ hledger به شما خواهد داد. در ادامه یک برگهٔ تقلب/نمای کلی سریع، و به‌دنبال آن توضیحات دقیق هر بخش آمده است. .SS "برگهٔ تقلب ژورنال (Journal cheatsheet)" .IP .EX # ساختار دستوری اصلی قالب ژورنال hledger در اینجا آمده است # (بدون در نظر گرفتن دستور زبان اضافی برای سازگاری با Ledger). ############################################################################### # ۱. این‌ها خطوط توضیح هستند، برای یادداشت‌ها یا غیرفعال‌سازی موقت موارد. ; آن‌ها با # یا ; آغاز می‌شوند comment یا این‌که خطوط می‌توانند درون \(dqcomment\(dq / \(dqend comment\(dq قرار گیرند. این یک بلوک از خطوط توضیح است. end comment # برخی ورودی‌های ژورنال می‌توانند در انتهای خط توضیح با نقطه‌ویرگول داشته باشند ; مانند این # برخی از آن‌ها به ۲ یا چند فاصله قبل از نقطه‌ویرگول نیاز دارند. ############################################################################### # ۲. دستورالعمل‌ها پردازش یا خروجی را به نوعی سفارشی می‌کنند. # برای شروع به هیچ دستورالعملی نیاز ندارید. # اما آن‌ها می‌توانند بررسی خطای بیشتری اضافه کنند، یا نحوهٔ نمایش موارد را تغییر دهند. # آن‌ها با یک کلمه، حرف یا نماد آغاز می‌شوند. # آن‌ها اغلب در بالا، پیش از تراکنش‌ها قرار می‌گیرند. account assets ; اعلان نام‌های حساب معتبر و ترتیب نمایش. account assets:savings ; یک زیرحساب. این یکی نشان‌دهندهٔ یک حساب بانکی است. account assets:checking ; دیگری. توجه: ۲+ فاصله پس از نام حساب. account assets:receivable ; نوع حسابداری از نام‌های انگلیسی استنباط می‌شود، account passifs ; یا با یک برچسب \(dqtype\(dq اعلام می‌گردد، type:L account expenses ; type:X ; یک خط توضیح ادامه‌دار، با تورفتگی. account expenses:rent ; دسته‌های هزینه و درآمد نیز حساب هستند. ; زیرحساب‌ها نوع والد خود را به ارث می‌برند. commodity $0.00 ; اعلان کالاهای معتبر و سبک‌های نمایش آن‌ها. commodity 1.000,00 EUR decimal\-mark . ; نشانگر اعشار استفاده‌شده در این فایل (در صورت مبهم بودن). payee Whole Foods ; اعلان یک نام دریافت‌کننده وجه معتبر. tag trip ; اعلان یک نام برچسب معتبر. P 2024\-03\-01 AAPL $179 ; اعلان قیمت بازار برای AAPL به $ در این تاریخ. include other.journal ; درج یک فایل ژورنال دیگر در اینجا. # اعلان یک «تراکنش دوره‌ای» (\(dqperiodic transaction\(dq)، برای گزارش‌های بودجه/پیش‌بینی \(ti monthly set budget goals ; <\- توجه: ۲+ فاصله پیش از شرح. (expenses:rent) $1000 (expenses:food) $500 # اعلان یک قاعدهٔ ارسال خودکار، برای تغییر تراکنش‌های موجود در گزارش‌ها = revenues:consulting liabilities:tax:2024:us *0.25 ; افزودن بدهی مالیاتی و هزینه expenses:tax:2024:us *\-0.25 ; به میزان ۲۵٪ از درآمد. ############################################################################### # ۳. تراکنش‌ها اصل ماجرا هستند. # آن‌ها رویدادهای تاریخ‌داری هستند، معمولاً انتقال پول میان ۲ یا چند حساب. # آن‌ها با یک تاریخ عددی آغاز می‌شوند. # شکل کلی آن‌ها بدین صورت است: # # DATE DESCRIPTION ; تاریخ و شرح اختیاری تراکنش. # ACCOUNT1 AMOUNT ; ثبت یک مبلغ به/از این حساب، با تورفتگی. # ACCOUNT2 AMOUNT ; ثبت دوم، که ثبت اول را تراز می‌کند. # ... ; موارد بیشتر در صورت نیاز. مجموع مبالغ باید صفر شود. # ; توجه: ۲+ فاصله بین نام‌های حساب و مبالغ. 2024\-01\-01 opening balances ; در ابتدا، موجودی‌های از پیش موجود را بدین صورت اعلام کنید. assets:savings $10000 ; نام حساب می‌تواند هر چیزی باشد. حروف کوچک تایپ آسان‌تری دارند. assets:checking $1000 ; assets، liabilities، equity، revenues، expenses رایج هستند. liabilities:credit card $\-500 ; موجودی‌های liabilities، equity، revenues معمولاً منفی هستند. equity:start ; یک مبلغ می‌تواند خالی بماند. $\-10500 در اینجا استنباط می‌شود. ; برخی از این حساب‌ها را در بالا اعلان نکردیم، ; بنابراین \-s/\-\-strict ایراد خواهد گرفت. 2024\-01\-03 ! (12345) pay rent ; خطوط توضیح اضافی تراکنش، با تورفتگی. ; می‌تواند یک ! یا * پس از تاریخ باشد به معنای «در انتظار» (\(dqpending\(dq) یا «تسویه‌شده» (\(dqcleared\(dq). ; می‌تواند یک (code) داخل پرانتز پس از تاریخ/وضعیت وجود داشته باشد. ; علامت مبالغ جهت گردش را نشان می‌دهد. assets:checking $\-500 ; منفی یعنی برداشت از این حساب (بستانکار/credit). expenses:rent $500 ; مثبت یعنی واریز به این حساب (بدهکار/debit). ; نگه‌داشتن تراکنش‌ها به ترتیب تاریخ اختیاری است (اما به بررسی خطا کمک می‌کند). 2024\-01\-02 Gringott\(aqs Bank | withdrawal ; شرح می‌تواند به‌صورت PAYEE | NOTE باشد assets:bank:gold \-10 gold assets:pouch 10 gold 2024\-01\-02 shopping expenses:clothing 1 gold expenses:wands 5 gold assets:pouch \-6 gold 2024\-01\-02 receive gift revenues:gifts \-3 \(dqChocolate Frogs\(dq ; نمادهای پیچیدهٔ کالا assets:pouch 3 \(dqChocolate Frogs\(dq ; باید داخل علامت نقل‌قول باشند. 2024\-01\-15 buy some shares, in two lots ; هزینه می‌تواند قید شود. assets:investments:2024\-01\-15 2.0 AAAA \(at $1.50 ; \(at به معنای هزینهٔ هر واحد است assets:investments:2024\-01\-15\-02 3.0 AAAA \(at\(at $4 ; \(at\(at به معنای هزینهٔ کل است ; \(ha زیرحساب‌های به ازای هر بهر (lot) گاهی مفید هستند. assets:checking $\-7 2024\-01\-15 assert some account balances on this date ; موجودی‌ها را می‌توان در هر تراکنش با = تصدیق کرد، برای بررسی خطای بیشتر. ; تراکنش‌های تصدیقی مانند این را می‌توان با hledger close \-\-assert \-\-show\-costs ایجاد کرد ; assets:savings $0 = $10000 assets:checking $0 = $493 assets:bank:gold 0 gold = \-10 gold assets:pouch 0 gold = 4 gold assets:pouch 0 \(dqChocolate Frogs\(dq = 3 \(dqChocolate Frogs\(dq assets:investments:2024\-01\-15 0.0 AAAA = 2.0 AAAA \(at $1.50 assets:investments:2024\-01\-15\-02 0.0 AAAA = 3.0 AAAA \(at\(at $4 liabilities:credit card $0 = $\-500 2024\-02\-01 note some event, or a transaction not yet fully entered, on this date ; ثبت‌ها (postings) الزامی نیستند. # قالب تاریخ یکدست YYYY\-MM\-DD توصیه می‌شود، # اما در صورت تمایل می‌توانید از . یا / استفاده کرده و صفرهای ابتدایی را حذف کنید. 2024.01.01 2024/1/1 .EE.SS کامنت‌ها (Comments) خطوط دفتر روزنامه (journal) در صورتی که با یک علامت هش (\f[CR]#\f[R]) یا یک نقطه\-ویرگول (\f[CR];\f[R]) آغاز شوند نادیده گرفته خواهند شد. (همچنین بخش «سایر ساختارها» را ببینید.) برنامه hledger همچنین بخش‌هایی را که با یک خط \f[CR]comment\f[R] آغاز شده و با یک خط \f[CR]end comment\f[R] (یا انتهای فایل) پایان می‌یابند، نادیده می‌گیرد. در اینجا پیشنهادی برای انتخاب میان آن‌ها آورده شده است: .IP \(bu 2 \f[CR]#\f[R] برای یادداشت‌های سطح بالا .IP \(bu 2 \f[CR];\f[R] برای کامنت کردن موقت موارد .IP \(bu 2 \f[CR]comment\f[R] برای کامنت کردن سریع بخش‌های بزرگ (به خاطر داشته باشید که آنجاست، وگرنه ممکن است گیج شوید) .PP برای مثال: .IP .EX # a comment line ; another commentline comment A multi\-line comment block, continuing until \(dqend comment\(dq directive or the end of the current file. end comment .EE .PP برخی مدخل‌های hledger می‌توانند کامنت‌های درون‌خطی داشته باشند، از ; (نقطه\-ویرگول) تا پایان خط. بخش‌های «کامنت‌های تراکنش» (Transaction comments)، «کامنت‌های ثبت» (Posting comments) و «کامنت‌های حساب» (Account comments) را در ادامه ببینید. .SS تراکنش‌ها (Transactions) تراکنش‌ها واحد اصلی اطلاعات در یک فایل دفتر روزنامه هستند. آن‌ها نشان‌دهنده رویدادها هستند، معمولاً جابه‌جایی مقداری از دارایی‌ها بین دو یا چند حساب مشخص. .PP هر تراکنش به عنوان یک مدخل در دفتر روزنامه ثبت می‌شود که با یک تاریخ ساده در ستون 0 آغاز می‌گردد. پس از آن می‌تواند هر یک از فیلدهای اختیاری زیر قرار گیرد که با فاصله از هم جدا می‌شوند: .IP \(bu 2 یک نویسه وضعیت (خالی، \f[CR]!\f[R]، یا \f[CR]*\f[R]) .IP \(bu 2 یک کد (هر عدد یا متن کوتاه، محصور در پرانتز) .IP \(bu 2 یک شرح (هر متن باقی‌مانده تا انتهای خط یا نقطه\-ویرگول) .IP \(bu 2 یک کامنت (هر متن باقی‌مانده پس از یک نقطه\-ویرگول تا انتهای خط، و هر خط تورفته پس از آن که با نقطه\-ویرگول آغاز شود) .IP \(bu 2 0 یا چند خط تورفته \f[I]ثبت\f[R] (posting)، که توصیف‌کننده موارد منتقل‌شده و حساب‌های درگیر است (خطوط کامنت تورفته نیز مجاز هستند، اما خطوط خالی یا خطوط بدون تورفتگی مجاز نیستند). .PP در اینجا یک فایل دفتر روزنامه ساده شامل یک تراکنش آورده شده است: .IP .EX 2008/01/01 income assets:bank:checking $1 income:salary $\-1 .EE .SS تاریخ‌ها (Dates) .SS تاریخ‌های ساده (Simple dates) تاریخ‌ها در فایل دفتر روزنامه از قالب \f[I]تاریخ‌های ساده\f[R] استفاده می‌کنند: \f[CR]YYYY\-MM\-DD\f[R] یا \f[CR]YYYY/MM/DD\f[R] یا \f[CR]YYYY.MM.DD\f[R]، که صفرهای ابتدایی در آن‌ها اختیاری است. ممکن است سال حذف شود، که در این حالت از زمینه استنباط خواهد شد: تراکنش فعلی، سال پیش‌فرضی که با دستورالعمل \f[CR]Y\f[R] تنظیم شده، یا تاریخ جاری هنگام اجرای دستور. چند مثال: \f[CR]2010\-01\-31\f[R]، \f[CR]2010/01/31\f[R]، \f[CR]2010.1.31\f[R]، \f[CR]1/31\f[R]. .PP (رابط کاربری علاوه بر تاریخ‌های ساده، تاریخ‌های هوشمندِ انعطاف‌پذیرتر را که در دفترچه راهنمای hledger مستند شده‌اند نیز می‌پذیرد.) .SS تاریخ‌های ثبت (Posting dates) می‌توانید با افزودن یک کامنت ثبت شامل یک برچسب (در ادامه ببینید) مانند \f[CR]; date:DATE\f[R]، به هر یک از ثبت‌ها تاریخی متفاوت از تراکنش والد اختصاص دهید. (همچنین یک ساختار سازگار با Ledger وجود دارد: \f[CR]; [DATE]\f[R]، که می‌تواند کارآمد باشد.) .PP این روش احتمالاً بهترین راه برای کنترل دقیق تاریخ‌های ثبت است. برای مثال در این نمونه، هزینه باید در گزارش‌های May نمایش داده شود و کسر از حساب checking باید در 6/1 گزارش شود تا تطبیق بانکی به سادگی انجام گیرد: .IP .EX 2015/5/30 expenses:food $10 ; food purchased on saturday 5/30 assets:checking ; bank cleared it on monday, date:6/1 .EE .IP .EX $ hledger \-f t.j register food 2015\-05\-30 expenses:food $10 $10 .EE .IP .EX $ hledger \-f t.j register checking 2015\-06\-01 assets:checking $\-10 $\-10 .EE .PP مقدار DATE باید یک تاریخ ساده باشد؛ اگر سال مشخص نشده باشد، از سالِ تاریخ تراکنش استفاده خواهد شد. .PD 0 .P .PD برچسب \f[CR]date:\f[R] در صورت وجود باید یک مقدار معتبر از تاریخ ساده داشته باشد؛ برای مثال، برچسب \f[CR]date:\f[R] بدون مقدار مجاز نیست..SS "وضعیت (Status)" تراکنش‌ها (یا ثبت‌های مجزا درون یک تراکنش) می‌توانند یک نشان وضعیت داشته باشند، که نویسه‌ای منفرد پیش از شرح تراکنش (یا نام حسابِ ثبت) است، با یک فاصله از آن جدا می‌شود، و نشان‌دهنده یکی از سه وضعیت زیر است: .PP .TS tab(@); l l. T{ نشان \ T}@T{ وضعیت T} _ T{ \ T}@T{ unmarked (بدون نشان) T} T{ \f[CR]!\f[R] T}@T{ pending (در انتظار) T} T{ \f[CR]*\f[R] T}@T{ cleared (تسویه‌شده) T} .TE .PP هنگام گزارش‌گیری، می‌توانید با پرچم‌های \f[CR]\-U/\-\-unmarked\f[R]، \f[CR]\-P/\-\-pending\f[R] و \f[CR]\-C/\-\-cleared\f[R] بر اساس وضعیت فیلتر کنید (و می‌توانید این پرچم‌ها را ترکیب کنید، برای مثال \f[CR]\-UP\f[R] برای تطبیق همه موارد به جز موارد تسویه‌شده). یا می‌توانید از پرس‌وجوهای \f[CR]status:\f[R]، \f[CR]status:!\f[R] و \f[CR]status:*\f[R]، یا کلیدهای U، P و C در hledger\-ui استفاده کنید. .PP (یادداشت: در Ledger وضعیت \(dqunmarked\(dq به نام \(dquncleared\(dq خوانده می‌شود؛ در hledger ما آن را برای شفافیت معنایی به \(dqunmarked\(dq تغییر نام دادیم.) .PP نشان‌های وضعیت اختیاری هستند، اما می‌توانند به عنوان مثال برای مغایرت‌گیری با حساب‌های دنیای واقعی (real\-world) مفید باشند. برخی حالت‌های ویرایشگر قابلیت برجسته‌سازی و میان‌برهایی را برای کار با وضعیت ارائه می‌دهند. برای مثال در ledger\-mode ایمکس (Emacs)، می‌توانید وضعیت تراکنش را با C\-c C\-e، یا وضعیت ثبت را با C\-c C\-c تغییر وضعیت (toggle) دهید. .PP این‌که \(dquncleared\(dq، \(dqpending\(dq و \(dqcleared\(dq در عمل واقعاً چه معنایی دارند، به شما بستگی دارد. در این‌جا یک پیشنهاد آمده است: .PP .TS tab(@); lw(9.7n) lw(60.3n). T{ وضعیت T}@T{ معنا T} _ T{ uncleared T}@T{ ثبت‌شده اما هنوز مغایرت‌گیری نشده است؛ نیازمند بازبینی T} T{ pending T}@T{ به‌طور موقت مغایرت‌گیری‌شده (در صورت نیاز، مثلاً حین یک مغایرت‌گیری بزرگ) T} T{ cleared T}@T{ کامل، تا حد امکان مغایرت‌گیری‌شده، و درست در نظر گرفته‌شده T} .TE .PP با این شیوه، می‌توانید از \f[CR]\-PC\f[R] برای دیدن موجودی فعلی در بانک خود، از \f[CR]\-U\f[R] برای مشاهده مواردی که احتمالاً به‌زودی در بانک شما اعمال می‌شوند (مانند چک‌های وصول‌نشده)، و بدون هیچ پرچمی برای دیدن به‌روزترین وضعیت مالی خود استفاده کنید..SS "کد (Code)" پس از نشانگر وضعیت، اما پیش از شرح، می‌توانید به‌صورت اختیاری یک \(dqکد\(dq (code) برای تراکنش، مانند شماره چک یا شناسهٔ تراکنش را محصور در پرانتز بنویسید. .PP این کار چند محدودیت دارد: کد نباید حاوی پرانتز بسته باشد (وگرنه کوتاه و بریده خواهد شد). کدها معمولاً تراز گزارش دفاتر (register report) را به هم می‌زنند و بازبینی چشمی آن را سخت‌تر می‌کنند. همچنین نمی‌توانید در هر تراکنش بیش از یک مقدار در آن ذخیره کنید. به این دلایل ممکن است ترجیح دهید از فیلد کد اجتناب کرده و در عوض از tags(#tags] استفاده کنید. .SS "شرح (Description)" پس از فیلدهای تاریخ، نشانگر وضعیت و/یا کد، باقی‌ماندهٔ سطر (یا تا جایی که کامنت با \f[CR];\f[R] آغاز شود) شرح تراکنش است. در اینجا می‌توانید تراکنش را توصیف کنید (که در حسابداری سنتی \(dqشرح سند\(dq نامیده می‌شود)، یا می‌توانید نام دریافت‌کننده/پرداخت‌کننده (payee/payer) را ثبت کنید، یا آن را خالی بگذارید. .PP شرح‌های تراکنش در خروجی دستور print و در گزارش‌های register نمایش داده می‌شوند و می‌توان آن‌ها را با دستور descriptions فهرست کرد. .PP می‌توانید با استفاده از \f[CR]desc:DESCREGEX\f[R] بر اساس شرح پرس‌وجو کنید، یا با \f[CR]\-\-pivot desc\f[R] گزارش را بر اساس شرح محوری (pivot) کنید. .SS "دریافت‌کننده و یادداشت (Payee and note)" گاهی افراد یک فیلد اختصاصی دریافت‌کننده/پرداخت‌کننده می‌خواهند که بتوان آن را با دقت بیشتری پرس‌وجو و بررسی کرد. اگر چنین چیزی می‌خواهید، می‌توانید یک نویسهٔ \f[CR]|\f[R] (خط عمودی/pipe) در شرح بنویسید. این کار آن را به یک فیلد \(dqpayee\(dq در سمت چپ و یک فیلد \(dqnote\(dq در سمت راست تقسیم می‌کند. (هر یک از آن‌ها می‌توانند خالی باشند.) .PP می‌توانید این موارد را با \f[CR]payee:PAYEEREGEX\f[R] و \f[CR]note:NOTEREGEX\f[R] پرس‌وجو کنید، مقادیر آن‌ها را با دستورهای payees و notes فهرست نمایید، یا روی \f[CR]payee\f[R] یا \f[CR]note\f[R] عملیات محوربندی (pivot) انجام دهید. .PP نکته: در تراکنش‌های فاقد نویسهٔ \f[CR]|\f[R]، مقادیر description، payee و note همگی یکسان هستند. به‌محض اضافه شدن یک \f[CR]|\f[R]، آن‌ها از یکدیگر مجزا می‌شوند. (اگر مایلید این رفتار تغییر کند، لطفاً آن را در لیست پستی مطرح کنید.) .PP اگر خواستار بررسی دقیق‌تر خطاها هستید، می‌توانید نام‌های معتبر دریافت‌کننده را با دستورالعمل‌های payee تعریف کنید، و سپس این موارد را با hledger check payees اعمال و اعتبارسنجی نمایید. (توجه: به دلیل نکتهٔ ذکر شده در بالا، برای این کار باید مطمئن شوید شرح هر تراکنش شامل یک \f[CR]|\f[R] و در نتیجه یک نام payee قابل‌بررسی باشد، حتی اگر خالی بماند.) .SS "کامنت‌های تراکنش (Transaction comments)" متنی که پس از \f[CR];\f[R]، بعد از شرح تراکنش، و/یا در سطرهای تورفته بلافاصله زیر آن قرار می‌گیرد، کامنت‌های آن تراکنش را تشکیل می‌دهد. این کامنت‌ها توسط \f[CR]print\f[R] بازتولید می‌شوند اما در غیر این صورت نادیده گرفته خواهند شد، مگر اینکه حاوی برچسب‌ها (tags) باشند که در آن صورت نادیده گرفته نمی‌شوند. .IP .EX 2012\-01\-01 something ; a transaction comment ; a second line of transaction comment expenses 1 assets .EE .SS "ثبت‌ها (Postings)" یک ثبت عبارت است از افزودن مقداری به، یا کسر مقداری از یک حساب. هر سطر ثبت با حداقل یک فاصله یا تب آغاز می‌شود (معمولاً ۲ یا ۴ فاصله)، و در ادامه: .IP \(bu 2 (اختیاری) یک نویسهٔ وضعیت (خالی، \f[CR]!\f[R] یا \f[CR]*\f[R])، به همراه یک فاصله در ادامه .IP \(bu 2 (الزامی) یک نام حساب (هر متنی، اختیاری شامل فاصله‌های تکی. اگر هر چیزی بعد از نام حساب در همان سطر بیاید، نام حساب باید به \f[B]دو یا چند فاصله\f[R] ختم شود.) .IP \(bu 2 (اختیاری) یک مبلغ .IP \(bu 2 (اختیاری) یک کامنت ثبت در همان سطر، که با یک نقطه‌ویرگول (\f[CR];\f[R]) آغاز می‌شود. .PP اگر مبلغ مثبت باشد، به حساب افزوده می‌شود؛ اگر منفی باشد، از حساب کسر می‌گردد. .PP مبالغ ثبت در یک تراکنش باید مجموعاً برابر با صفر شوند، که نشان می‌دهد ورودی‌ها و خروجی‌ها برابر هستند. ما این را یک تراکنش تراز شده (balanced transaction) می‌نامیم. (می‌توانید دربارهٔ جزئیات تراز کردن تراکنش در ادامه اطلاعات بیشتری کسب کنید.) .PP اگر مبلغی نوشته نشود، به‌طور خودکار از سایر ثبت‌های درون تراکنش محاسبه خواهد شد تا تراکنش تراز شود. به عبارت دیگر، در هر تراکنش می‌توانید برای صرفه‌جویی در تایپ، یک ثبت را بدون مبلغ رها کنید..SS بدهکار و بستانکار (Debits and credits) مفاهیم سنتی حسابداری بدهکار و بستانکار مسلماً در hledger وجود دارند، اما ما آن‌ها را با علامت عددی نمایش می‌دهیم. مبالغ مثبت و منفی ثبتی (posting) به ترتیب نمایانگر بدهکار و بستانکار هستند. .PP نیازی نیست این موضوع را حفظ کنید، اما اگر تمایل دارید \- مثلاً برای راهنمایی تازه‌واردها یا گفتگو با حسابدارتان \- این یک عبارت یادیار مفید است: .PP \f[I]\f[CI]debit / plus / left / short words\f[I]\f[R] .PD 0 .P .PD \f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R] .SS نام‌های حساب (Account names) حساب‌ها شیوه اصلی دسته‌بندی موارد در hledger هستند. همانند دفترداری دوطرفه، آن‌ها می‌توانند نمایانگر حساب‌های دنیای واقعی (مانند یک حساب بانکی)، یا دسته‌بندی‌های انتزاعی‌تر مانند «پول خرج‌شده برای غذا» یا «پول قرض‌گرفته‌شده از فرانک» باشند. .PP نام‌های حساب منعطف هستند. می‌توانند با حروف بزرگ یا کوچک نوشته شوند؛ می‌توانند شامل حروف، اعداد، علائم نگارشی، نمادها، یا فاصله‌های تکی باشند؛ و می‌توانند به هر زبانی باشند. .PP به‌طور معمول از پنج دسته‌بندی سنتی حسابداری به‌عنوان نقطه شروع نام‌گذاری حساب‌ها استفاده می‌کنیم. در انگلیسی این دسته‌ها عبارتند از: .PP \f[CR]assets\f[R], \f[CR]liabilities\f[R], \f[CR]equity\f[R], \f[CR]revenues\f[R], \f[CR]expenses\f[R] .PP این موارد در ادامه در بخش انواع حساب (Account types) بیشتر مورد بحث قرار خواهند گرفت. در مستندات hledger ممکن است این موارد را به‌صورت اختصاری با A، L، E، R و X ببینید. .SS جداکننده دو فاصله (Two space delimiter) به جداکننده \f[B]دو یا چند فاصله\f[R] که گاهی پس از نام‌های حساب لازم است، توجه داشته باشید. نام‌های حساب در hledger که از Ledger به ارث رسیده‌اند، بسیار منعطف هستند؛ آن‌ها می‌توانند تقریباً شامل هر نوع متنی، از جمله فاصله‌های تکی و نقطه‌ویرگول باشند. به همین دلیل، اگر چیزی در همان خط به دنبال آن‌ها بیاید، باید با \f[B]دو یا چند فاصله\f[R] خاتمه یابند. برای مثال، اگر یک مبلغ، انتساب موجودی (balance assignment)، یا توضیحی در همان خط پس از نام حساب بیاید، باید پیش از آن‌ها دو یا چند فاصله قرار گیرد، در غیر این صورت بخشی از نام حساب در نظر گرفته خواهند شد: .IP .EX bad: assets:accounts receivable $10 ; <\- too close! good: assets:accounts receivable $10 .EE .IP .EX bad: assets:accounts receivable =$1000 ; <\- too close! good: assets:accounts receivable =$1000 .EE .IP .EX bad: assets:accounts receivable ; comment. <\- too close! good: assets:accounts receivable ; comment .EE .PP این جداکننده دو فاصله‌ای در چند بخش از hledger دیده می‌شود؛ مانند پس از نام‌های حساب در ثبت‌ها (postings) یا دستورالعمل‌های حساب (account directives)؛ و همچنین پس از عبارت دوره زمانی در قواعد تراکنش‌های دوره‌ای. در ابتدای کار، انتظار داشته باشید که حداقل یک بار این موضوع شما را به اشتباه بیندازد. این مسئله گاهی آزاردهنده است، اما به ما اجازه می‌دهد ضمن حفظ سادگی نحو (syntax)، از نام‌های حساب رسا و واضح استفاده کنیم. .SS سلسله‌مراتب حساب (Account hierarchy) برای گزارش‌گیری دقیق‌تر، معمولاً با قرار دادن دو‌نقطه (:) بین بخش‌های نام حساب، آن‌ها را به زیرحساب‌ها، زیرزیرحساب‌ها و موارد جزئی‌تر تقسیم می‌کنیم. به‌عنوان مثال، به‌جای نوشتن \f[CR]assets\f[R] و \f[CR]expenses\f[R]، ممکن است بنویسیم \f[CR]assets:bank:checking\f[R] و \f[CR]expenses:food\f[R]. از این نام‌ها، hledger این سلسله‌مراتب شامل پنج حساب را استنباط خواهد کرد: .IP .EX assets assets:bank assets:bank:checking expenses expenses:food .EE .PP یا به‌صورت یک ساختار درختی: .IP .EX assets bank checking expenses food .EE .PP گزارش‌های hledger می‌توانند درخت حساب‌ها را در هر عمقی خلاصه کنند، بنابراین می‌توانید زیردسته‌های خود را تا هر اندازه که مایلید با جزئیات تعریف کنید. اما به‌ویژه در شروع کار زیاده‌روی نکنید؛ دسته‌بندی‌های ساده‌تر زحمت کمتری دارند..SS سایر ویژگی‌های نام حساب قراردادن نام حساب در پرانتز یا قلاب، مانند \f[CR](expenses:food)\f[R]، قابلیتی غیر‌استاندارد در حسابداری را فعال می‌کند: ثبت‌های مجازی (virtual postings). .PP نام‌های حساب را می‌توان با استفاده از نام‌های مستعار حساب (account aliases)، به‌طور موقت یا دائمی بازنویسی کرد و ساختارشان را تغییر داد. .SS مقادیر (Amounts) پس از نام حساب، معمولاً یک مقدار قرار می‌گیرد. (به یاد داشته باشید: بین نام حساب و مقدار، باید دو یا چند فاصله وجود داشته باشد.) .PP قالب مقدار در hledger انعطاف‌پذیر است و از چندین قالب بین‌المللی پشتیبانی می‌کند. در اینجا چند مثال آورده شده است. مقادیر دارای یک عدد (همان «تعداد» یا «quantity») هستند: .IP .EX 1 .EE .PP \&..و معمولاً یک نماد ارز یا نام کالا (commodity) (توضیحات بیشتر در ادامه)، در سمت چپ یا راست مقدار عددی، با یا بدون فاصله جداکننده: .IP .EX $1 4000 AAPL 3 \(dqgreen apples\(dq .EE .PP پیش از مقادیر می‌تواند علامت منفی (یا علامت مثبت، هرچند مثبت پیش‌فرض است) بیاید. این علامت می‌تواند قبل یا بعد از نماد کالای واقع در سمت چپ نوشته شود: .IP .EX \-$1 $\-1 .EE .PP یک یا چند فاصله بین علامت و عدد هنگام تجزیه (parsing) پذیرفته می‌شود (اما در خروجی نمایش داده نخواهند شد): .IP .EX + $1 $\- 1 .EE .PP نماد علمی E مجاز است: .IP .EX 1E\-6 EUR 1E3 .EE .PP .SS نشانه‌های اعشار (Decimal marks) یک \f[I]نشانه اعشار\f[R] می‌تواند به‌صورت نقطه یا کاما نوشته شود: .IP .EX 1.23 1,23 .EE .PP هر دوی این‌ها در قالب‌های بین‌المللی اعداد رایج هستند، بنابراین hledger نسبت به یکی بر دیگری تعصبی ندارد. از آنجا که hledger از نشانه‌های گروه‌بندی ارقام (مانند جداکننده‌های هزارگان) نیز پشتیبانی می‌کند، این بدان معناست که عددی مانند \f[CR]1,000\f[R] یا \f[CR]1.000\f[R] که تنها شامل یک نقطه یا کاما باشد، مبهم است. در چنین مواردی، hledger به‌طور پیش‌فرض آن را نشانه اعشار در نظر می‌گیرد و هر دوی آن‌ها را به عنوان 1 تجزیه خواهد کرد. .PP برای کمک به hledger جهت تجزیه دقیق‌تر چنین اعداد مبهمی، اگر از نشانه‌های گروه‌بندی ارقام استفاده می‌کنید، توصیه می‌کنیم نشانه اعشار را صریحاً تعریف کنید. بهترین روش افزودن یک دستورالعمل \f[CR]decimal\-mark\f[R] در ابتدای هر فایل داده است، مانند این: .IP .EX decimal\-mark . .EE .PP یا می‌توانید آن را به ازای هر کالا با دستورالعمل‌های \f[CR]commodity\f[R] که در ادامه شرح داده شده است، تعریف کنید. .PP hledger همچنین اعدادی مانند \f[CR]10.\f[R] را بدون هیچ رقمی پس از نشانه اعشار می‌پذیرد (و گاهی اوقات اعداد را برای رفع ابهام به همین شکل نمایش می‌دهد \- بخش نشانه‌های اعشار پایانی یا Trailing decimal marks را ببینید)..SS "نشانه‌های تفکیک ارقام (Digit group marks)" در بخش صحیح مقدارِ مبلغ (سمت چپ نشانهٔ اعشار)، گروه‌های ارقام می‌توانند به صورت اختیاری با یک \f[I]نشانهٔ تفکیک ارقام\f[R] \- یک کاما یا نقطه (هر کدام که به عنوان نشانهٔ اعشار استفاده نشده باشد)، یا فاصله (چندین نوع فاصله در یونیکد، مانند فاصلهٔ نشکستنی [no\-break space] نیز پذیرفته می‌شوند) جدا شوند. \ بنابراین این‌ها همگی مقادیر معتبری در یک فایل دفتر روزنامه هستند: .IP .EX $1,000,000.00 EUR 2.000.000,00 INR 9,99,99,999.00 1 000 000.00 ; <\- ordinary space 1\ 000\ 000.00 ; <\- no\-break space .EE .SS "کالا (Commodity)" مبالغ در hledger هم دارای یک \(dqمقدار\(dq (quantity) هستند که یک عدد اعشاری علامت‌دار است، و هم دارای یک \(dqکالا\(dq (commodity) که یک نماد ارز، نماد معاملاتی سهام، یا هر کلمه یا عبارتی است که چیزی را که ردیابی می‌کنید توصیف می‌کند. .PP اگر نام کالا شامل نویسه‌های غیرحرفی (فاصله‌ها، اعداد، یا علائم نگارشی) باشد، باید همیشه آن را درون نقل‌قول دوتایی بنویسید (\f[CR]\(dqgreen apples\(dq\f[R]، \f[CR]\(dqABC123\(dq\f[R]). .PP اگر تنها یک عدد خالی بنویسید، آن نیز کالایی با نام \f[CR]\(dq\(dq\f[R] خواهد داشت؛ ما آن را \(dqکالای بدون نماد\(dq (no\-symbol commodity) می‌نامیم. .PP در واقع، hledger این مبالغ تک‌کالایی را در قالب مبالغ چندکالایی قدرتمندتری ترکیب می‌کند، که در اکثر مواقع با آن‌ها کار می‌کند. یک مبلغ چندکالایی می‌تواند برای مثال به این صورت باشد: \f[CR]1 USD, 2 EUR, 3.456 TSLA\f[R]. در عمل، شما مبالغ چندکالایی را تنها در خروجی hledger خواهید دید؛ نمی‌توانید آن‌ها را مستقیماً در فایل دفتر روزنامه بنویسید. \ .PP به‌طور پیش‌فرض، قالب مبالغ در دفتر روزنامه بر نحوهٔ نمایش آن‌ها توسط hledger در خروجی تأثیر می‌گذارد. این موضوع در بخش «شیوهٔ نمایش کالا» (Commodity display style) در ادامه توضیح داده شده است. .PP .SS "بها (Costs)" در دفترداری دوطرفهٔ سنتی، برای ثبت تراکنشی که در آن یک کالا با کالایی دیگر مبادله می‌شود، ثبت‌های حقوق مالکانه‌ی (equity postings) اضافی برای تراز کردن دو کالا اضافه می‌کنید. برای مثال: .IP .EX 2026\-01\-01 buy euros assets:dollars $\-123 equity:conversion $123 equity:conversion €\-100 assets:euros €100 .EE .PP نرم‌افزار hledger شیوهٔ نشانه‌گذاری کارآمدتر \(at/\(at\(at موسوم به \(dqنشانه‌گذاری بها\(dq (cost notation) را به عنوان یک جایگزین ارائه می‌دهد: به جای ثبت‌های حقوق مالکانه، می‌توانید \(dqنرخ تبدیل\(dq یا \(dqقیمت معامله‌شده\(dq را پس از مبلغِ یک ثبت بنویسید. مستندات hledger، چه در حالت خرید و چه در فروش، این را به‌طور کلی \(dqبها\(dq (cost) می‌نامند. این مقدار می‌تواند به صورت \f[CR]\(at UNITPRICE\f[R] یا \f[CR]\(at\(at TOTALPRICE\f[R] نوشته شود. برای مثال می‌توانید مورد بالا را این‌گونه بنویسید: .IP .EX 2026\-01\-01 buy euros assets:dollars $\-123 assets:euros €100 \(at $1.23 ; unit cost (exchange rate) .EE .PP یا: .IP .EX 2026\-01\-01 buy euros assets:dollars $\-123 assets:euros €100 \(at\(at $123 ; total cost .EE .PP بها معمولاً باید یک مقدار مثبت باشد. بهای منفی نیز پشتیبانی می‌شود، اما می‌تواند گیج‌کننده باشد، همان‌طور که در بخش \-\-infer\-market\-prices: market prices from transactions مورد بحث قرار گرفته است. .PP بها در تراز کردن تراکنش مشارکت دارد. مبالغ پیش از بررسی اینکه آیا تراکنش تراز است یا خیر، به بهای خود تبدیل می‌شوند. همچنین می‌توانید مورد بالا را با افزونگی کمتر و به این صورت بنویسید: .IP .EX 2026\-01\-01 buy euros assets:dollars ; $\-123 is inferred assets:euros €100 \(at $1.23 .EE .PP یا: .IP .EX 2026\-01\-01 buy euros assets:dollars ; $\-123 is inferred assets:euros €100 \(at\(at $123 .EE .PP یا حتی: .IP .EX 2026\-01\-01 buy euros assets:euros €100 ; \(at\(at $123 is inferred assets:dollars $\-123 .EE .PP این حالتِ آخر برای تراکنش‌هایی که دقیقاً شامل دو کالا هستند، بدون نیاز به نشانه‌گذاری بها یا ثبت‌های حقوق مالکانه کار می‌کند. توجه داشته باشید که ترتیب ثبت‌ها اهمیت دارد: بها به نخستین ثبت (بالایی) نسبت داده خواهد شد. بنابراین ما مجبور شدیم ترتیب ثبت‌ها را جابه‌جا کنیم تا همان معنای بالا حاصل شود. همچنین، در این شیوه ارتکاب خطاهای کشف‌نشده از همه آسان‌تر است؛ از این رو توسط \f[CR]hledger check balanced\f[R] و همچنین توسط حالت سخت‌گیرانه (strict mode) رد می‌شود. .PP مزایای نشانه‌گذاری بها: .IP "1." 3 فشرده‌تر است و خواندن و نوشتن آن آسان‌تر است. .IP "2." 3 هنگامی که پرچم \f[CR]\-B/\-\-cost\f[R] را اضافه کنید، گزارش‌های hledger می‌توانند چنین مبالغی را تبدیل‌شده به بهای آن‌ها نشان دهند (بخش Cost reporting را ببینید). .PP مزایای ثبت‌های حقوق مالکانه (equity postings): .IP "1." 3 به برقرار ماندن تراز معادلهٔ حسابداری کمک می‌کنند (اگر این موضوع برایتان اهمیت دارد). .IP "2." 3 به‌آسانی به هر سامانهٔ حسابداری دوطرفهٔ دیگری قابل انتقال هستند. .PP بیشتر کاربران hledger از نشانه‌گذاری بها استفاده می‌کنند و ثبت‌های حقوق مالکانه را به کار نمی‌برند. .PP اما شما همواره می‌توانید با افزودن \f[CR]\-\-infer\-equity\f[R]، نشانه‌گذاری بها را به ثبت‌های حقوق مالکانه تبدیل کنید. برای نمونه دستور \f[CR]hledger print \-x \-\-infer\-equity\f[R] را امتحان کنید. .PP و معمولاً می‌توانید با افزودن \f[CR]\-\-infer\-costs\f[R]، ثبت‌های حقوق مالکانه را به نشانه‌گذاری بها تبدیل کنید (بخش Requirements for detecting equity conversion postings را ببینید). برای نمونه دستور \f[CR]hledger print \-x \-\-infer\-costs\f[R] را امتحان کنید. .PP در نهایت: استفادهٔ هم‌زمان از ثبت‌های حقوق مالکانه و نشانه‌گذاری بها تا زمانی که ساختار مدخل دفتر روزنامه مناسب باشد به طوری که معادل‌های ثبت‌های حقوق مالکانه / بها قابل تشخیص باشند، مجاز است. (در غیر این صورت، پیام خطایی دریافت خواهید کرد مبنی بر اینکه تراکنش ناتراز است.): .IP .EX 2026\-01\-01 buy euros assets:dollars $\-123 equity:conversion $123 equity:conversion €\-100 assets:euros €100 \(at $1.23 .EE .PP بنابراین در اصل می‌توانید هر دو گزینهٔ \f[CR]\-\-infer\-equity\f[R] و \f[CR]\-\-infer\-costs\f[R] را در فایل پیکربندی خود فعال کنید، و گزارش‌های شما از مزایای هر دو بهره‌مند خواهند شد..SS مبنای هزینه / نحو بهر (Cost basis / lot syntax) اگر کالایی را برای نگهداری به‌عنوان سرمایه‌گذاری خریداری می‌کنید، ممکن است رهگیری موارد زیر حائز اهمیت باشد: .IP "1." 3 هزینهٔ اولیهٔ تملک آن .IP "2." 3 تاریخ اولیهٔ تملک آن .IP "3." 3 و یک شمارهٔ ترتیبی یا برچسب در صورت نیاز، برای ابهام‌زدایی از خریدهای متعدد در یک روز، یا استفاده به‌منزلهٔ یادآور جهت ارجاع آسان. .PP در hledger به این سه مورد \(dqمبنای هزینه\(dq (cost basis) می‌گوییم؛ و اگر مقداری که تملک می‌شود دارای مبنای هزینه باشد، آن را یک \(dqبهر\(dq (lot) می‌نامیم. مقامات مالیاتی معمولاً الزام می‌کنند که بهرها به‌دقت رهگیری شده و به ترتیب مشخصی واگذار (فروخته) شوند. .PP توجه داشته باشید هرچند \(dqمبنای هزینه\(dq مشابه \(dqهزینه\(dq (قیمت معامله) که در بالا بحث شد به نظر می‌رسد، اما این دو مفاهیمی متمایز هستند. در برخی تراکنش‌ها قیمت معامله و مبنای هزینه یکسان هستند، اما در برخی دیگر تفاوت دارند. .PP بنابراین مبنای هزینه نحو مختص به خود را دارد که \(dqنحو بهر\(dq (lot syntax) نیز نامیده می‌شود. نحو lot در hledger مشابه نحو Ledger است: یک یا چند مورد از یادداشت‌های زیر که پس از مقدار اصلی می‌آیند: .IP \(bu 2 \f[CR]{LOTUNITCOST}\f[R] یا \f[CR]{{LOTTOTALCOST}}\f[R] (مبحث lot price را ببینید) .IP \(bu 2 \f[CR][LOTDATE]\f[R] (مبحث lot date را ببینید) .IP \(bu 2 \f[CR](LOTLABEL)\f[R] (مبحث lot note را ببینید) .PP برنامهٔ hledger هنوز عملیاتی با این نحو lot انجام نمی‌دهد، به‌جز حفظ آن و نمایش در خروجی‌های \f[CR]txt\f[R]، \f[CR]beancount\f[R] و \f[CR]json\f[R] دستور \f[CR]print\f[R]. این بدان معناست که می‌توانید از این نحو در دفترهای روزنامهٔ hledger خود استفاده کنید (به‌همراه یک ثبت اضافیِ بدون مقدار در صورت نیاز برای کمک به تراز شدن تراکنش‌ها)، سپس از دستور \f[CR]print\f[R] برای برون‌بری به Ledger ،Beancount یا rustledger استفاده نمایید تا گزارش‌های بهرها/سودها (lots/gains) آن‌ها را به‌کار بگیرید (گردش‌کار Export Lots را ببینید). .SS تصدیق‌های تراز (Balance assertions) نرم‌افزار hledger از تصدیق‌های تراز به سبک Ledger در فایل‌های دفتر روزنامه پشتیبانی می‌کند. این تصدیق‌ها برای نمونه مانند \f[CR]= EXPECTEDBALANCE\f[R] هستند که پس از مقدار یک ثبت (posting) قرار می‌گیرند. برای مثال در اینجا تراز دلاری مورد انتظار در حساب‌های a و b را پس از هر ثبت تصدیق می‌کنیم: .IP .EX 2013/1/1 a $1 = $1 b = $\-1 2013/1/2 a $1 = $2 b $\-1 = $\-2 .EE .PP پس از خواندن یک فایل دفتر روزنامه، hledger تمام تصدیق‌های تراز را بررسی کرده و در صورت نادرست بودن هر یک از آن‌ها، خطایی گزارش می‌کند. تصدیق‌های تراز می‌توانند برای مثال از به‌هم‌ریختن سهوی ترازهای تطبیق‌داده‌شده هنگام پاک‌سازی مدخل‌های قدیمی جلوگیری کنند. می‌توانید آن‌ها را با پرچم \f[CR]\-I/\-\-ignore\-assertions\f[R] به‌طور موقت غیرفعال کنید که می‌تواند برای عیب‌یابی یا خواندن فایل‌های Ledger مفید باشد. (نکته: این پرچم در حال حاضر انتساب‌های تراز را که در زیر شرح داده شده است، غیرفعال نمی‌کند). .SS تصدیق‌ها و ترتیب (Assertions and ordering) برنامهٔ hledger تصدیق‌های تراز یک حساب را به ترتیب تاریخ (و هنگامی که چندین تصدیق در یک روز وجود داشته باشد، به ترتیب تجزیه) محاسبه و بررسی می‌کند. توجه داشته باشید که این رفتار با Ledger متفاوت است؛ Ledger تصدیق‌ها را همیشه به ترتیب تجزیه و بدون در نظر گرفتن تاریخ‌ها بررسی می‌کند. .PP این بدان معناست که در hledger می‌توانید آزادانه تراکنش‌ها، ثبت‌ها یا فایل‌ها را بازآرایی کنید و تصدیق‌های تراز معمولاً به کار خود ادامه خواهند داد. استثنا زمانی است که چندین ثبت در یک روز و برای یک حساب را که دارای تصدیق تراز هستند بازآرایی کنید؛ در این صورت احتمالاً آن تصدیق‌ها نیازمند به‌روزرسانی خواهند بود. .SS تصدیق‌ها و فایل‌های چندگانه (Assertions and multiple files) اگر حسابی دارای تراکنش‌هایی در چند فایل مختلف باشد، تصدیق‌های تراز همچنان می‌توانند کار کنند \- اما \f[I]تنها در صورتی که آن فایل‌ها بخشی از یک ساختار سلسله‌مراتبی ایجادشده توسط دستورهای include باشند\f[R]. .PP اگر همان فایل‌ها با دو گزینهٔ \f[CR]\-f\f[R] در خط فرمان مشخص شوند، تصدیق‌های موجود در فایل دوم ترازهای فایل اول را نخواهند دید. .PP برای دور زدن این مشکل، فایل‌های خود را با استفاده از \f[CR]include\f[R] در یک ساختار سلسله‌مراتبی مرتب کنید. یا اینکه می‌توانید فایل‌ها را موقتاً به هم متصل (concatenate) کرده و آن‌ها را مانند یک فایل بزرگ پردازش کنید. .PP چرا سیستم به این شیوه کار می‌کند؟ این امر احتمالاً با هدف hledger برای تولید گزارش‌های پایدار و قابل پیش‌بینی مرتبط است. سلسله‌مراتب فایل‌ها بخشی \(dqهمیشگی\(dq و جزئی از داده‌های شما در نظر گرفته می‌شود، در حالی که ترتیب گزینه‌ها/آرگومان‌های خط فرمان این‌گونه نیست. ما نمی‌خواهیم تغییرات گذرا بتوانند معنای داده‌ها را تغییر دهند. به عنوان مثال بسیار ناامیدکننده خواهد بود اگر فردا همهٔ تصدیق‌های تراز شما نقض شوند، صرفاً به این دلیل که آرگومان‌های خط فرمان را با ترتیبی متفاوت وارد کرده‌اید. (از بحث و تبادل نظر در این زمینه استقبال می‌شود.).SS ادعاها و هزینه‌ها ادعاهای موجودی هزینه‌ها را نادیده می‌گیرند، و به‌طور معمول باید بدون هزینه نوشته شوند: .IP .EX 2019/1/1 (a) $1 \(at €1 = $1 .EE .PP با این حال، ما اجازه می‌دهیم هزینه‌ها در مقادیر ادعای موجودی نوشته شوند، و print آن‌ها را نمایش می‌دهد، اما بر قبولی یا رد ادعا تأثیری ندارند. این امر برای سازگاری رو به عقب است (دستور close در hledger در گذشته ادعاهای موجودی را به همراه هزینه ایجاد می‌کرد)، و به این دلیل که \f[I]انتساب‌های\f[R] موجودی از هزینه‌ها استفاده می‌کنند (پایین‌تر را ببینید). .SS ادعاها و کالاها ادعاهای موجودی توصیف‌شده تا اینجا «\f[B]ادعاهای موجودی تک‌کالایی\f[R]» هستند: آن‌ها موجودی را در یک کالا ادعا و بررسی می‌کنند، و هر کالای دیگری را که ممکن است وجود داشته باشد نادیده می‌گیرند. این همان روشی است که ادعاهای موجودی در Ledger نیز کار می‌کنند. .PP اگر یک حساب شامل چندین کالا باشد، می‌توانید موجودی آن‌ها را با نوشتن چندین ثبت (posting) به همراه ادعای موجودی، یکی برای هر کالا، ادعا و بررسی کنید: .IP .EX 2013/1/1 usd $\-1 eur €\-1 both 2013/1/2 both 0 = $1 both 0 = €1 .EE .PP در hledger می‌توانید با نوشتن دو علامت مساوی (\f[CR]== EXPECTEDBALANCE\f[R])، یک «\f[B]ادعای موجودی کالای یگانه\f[R]» قوی‌تر ایجاد کنید. این کار همچنین ادعا می‌کند که به‌جز کالای ادعاشده هیچ کالای دیگری در حساب وجود ندارد (یا دست‌کم، موجودی فعلی آن‌ها صفر است): .IP .EX 2013/1/1 usd $\-1 == $\-1 ; these sole commodity assertions succeed eur €\-1 == €\-1 both ;== $1 ; this one would fail because \(aqboth\(aq contains $ and € .EE .PP ایجاد یک «\f[B]ادعای موجودی چندکالای یگانه\f[R]» (به جمع بودن کلمه دقت کنید) دشوارتر است \- یعنی ادعای این‌که یک حساب شامل دو یا چند کالای مشخص‌شده و بدون هیچ کالای دیگری است. این کار می‌تواند با انجام موارد زیر انجام شود: .IP "1." 3 جداسازی هر کالا در یک زیرحساب، و ادعا کردن آن‌ها .IP "2." 3 و همچنین ادعا کردن این‌که هیچ کالایی در خودِ حساب والد وجود ندارد: .IP .EX 2013/1/1 usd $\-1 eur €\-1 both 0 == 0 ; nothing up my sleeve both:usd $1 == $1 ; a dollar here both:eur €1 == €1 ; a euro there .EE .SS ادعاها و زیرحساب‌ها تمام ادعاهای موجودی بالا (هم \f[CR]=\f[R] و هم \f[CR]==\f[R]) «\f[B]ادعاهای موجودی بدون احتساب زیرحساب\f[R]» هستند؛ آن‌ها هر موجودی که در زیرحساب‌های عمیق‌تر وجود داشته باشد را نادیده می‌گیرند. .PP در hledger می‌توانید با افزودن یک ستاره پس از علامت مساوی (\f[CR]=*\f[R] یا \f[CR]==*\f[R])، «\f[B]ادعاهای موجودی با احتساب زیرحساب\f[R]» ایجاد کنید: .IP .EX 2019/1/1 equity:start assets:checking $10 assets:savings $10 assets $0 ==* $20 ; assets + subaccounts contains $20 and nothing else .EE.SS ادعاها و وضعیت ادعاهای تراز همواره ثبت‌های مربوط به تمام وضعیت‌ها (علامت‌نخورده، در انتظار، یا تسویه‌شده) را در نظر می‌گیرند؛ آن‌ها تحت تأثیر پرچم‌های \f[CR]\-U\f[R]/\f[CR]\-\-unmarked\f[R] / \f[CR]\-P\f[R]/\f[CR]\-\-pending\f[R] / \f[CR]\-C\f[R]/\f[CR]\-\-cleared\f[R] یا پرس‌وجوی \f[CR]status:\f[R] قرار نمی‌گیرند. .SS ادعاها و ثبت‌های مجازی ادعاهای تراز همواره هر دو نوع ثبت‌های واقعی و مجازی را در نظر می‌گیرند؛ آن‌ها تحت تأثیر پرچم \f[CR]\-\-real/\-R\f[R] یا پرس‌وجوی \f[CR]real:\f[R] قرار نمی‌گیرند. .SS ادعاها و ثبت‌های خودکار ادعاهای تراز \f[I]تحت تأثیر\f[R] پرچم \f[CR]\-\-auto\f[R] قرار می‌گیرند که ثبت‌های خودکار (auto postings) تولید می‌کند و می‌تواند تراز حساب‌ها را تغییر دهد. از آنجا که ثبت‌های خودکار در hledger اختیاری هستند، حساب‌های تحت تأثیر آن‌ها در عمل دارای دو تراز هستند. اما ادعاهای تراز تنها می‌توانند یکی از این دو حالت را بیازمایند. بنابراین برای جلوگیری از ایجاد ادعاهای شکننده، یکی از موارد زیر را انجام دهید: .IP \(bu 2 ترازی را ادعا کنید که با \f[CR]\-\-auto\f[R] محاسبه شده است، و همواره برای آن فایل از \f[CR]\-\-auto\f[R] استفاده کنید .IP \(bu 2 یا ترازی را ادعا کنید که بدون \f[CR]\-\-auto\f[R] محاسبه شده است، و هرگز برای آن فایل از \f[CR]\-\-auto\f[R] استفاده نکنید .IP \(bu 2 یا از ادعاهای تراز روی حساب‌های متأثر از ثبت‌های خودکار اجتناب کنید (یا ثبت‌های خودکار را کاملاً کنار بگذارید). .SS ادعاها و دقت اعشار ادعاهای تراز مقادیر را دقیقاً بر اساس محاسبات مقایسه می‌کنند، مقادیری که لزوماً همیشه همان ارقام نمایش‌یافته در گزارش‌ها نیستند. برای مثال یک دستورالعمل commodity ممکن است دقت نمایش را محدود کند، اما این موضوع بر ادعاهای تراز تأثیری نخواهد داشت. پیام‌های خطای شکست ادعای تراز، مقادیر دقیق را نمایش می‌دهند. .SS ادعاها و add در hledger ادعاهای تراز می‌توانند در مقادیر داده‌شده در \f[CR]add\f[R] گنجانده شوند. تمام انواع ادعاها پشتیبانی می‌شوند، و ادعاها می‌توانند مشابه یک فایل دفتر روزنامه (journal) عادی استفاده شوند. .PP همه تراکنش‌ها، نه فقط مواردی که دارای ادعای صریح هستند، در برابر ادعاهای موجود در دفتر روزنامه اعتبارسنجی می‌شوند. این بدان معناست که ممکن است افزودن یک تراکنش شکست بخورد، حتی اگر ادعاهای آن تا تاریخ وقوع تراکنش صحیح باشند. .PP اگر این بررسی ادعاها مد نظر نیست، می‌توان آن را با \f[CR]\-I\f[R] غیرفعال کرد. .PP با این حال، تخصیص‌های تراز (balance assignments) در حال حاضر پشتیبانی نمی‌شوند. .SS کامنت‌های ثبت متنی که پس از \f[CR];\f[R]، در انتهای یک خط ثبت (posting)، و/یا در خطوط تورفته مستقیماً در زیر آن قرار می‌گیرد، کامنت‌های مربوط به آن ثبت را تشکیل می‌دهد. آن‌ها توسط دستور \f[CR]print\f[R] بازتولید می‌شوند اما در غیر این صورت نادیده گرفته می‌شوند، مگر اینکه حاوی برچسب‌ها (tags) باشند که نادیده گرفته نمی‌شوند. .IP .EX 2012\-01\-01 expenses 1 ; a comment for posting 1 assets ; a comment for posting 2 ; a second comment line for posting 2 .EE .SS تراز کردن تراکنش ابزار hledger دقیقاً چگونه تصمیم می‌گیرد که یک تراکنش تراز است؟ به‌ویژه زمانی که پای هزینه‌ها (costs) در میان است، که اغلب به دلیل اعشارهای متناوب یا داده‌های غیردقیق مؤسسات مالی، دقیق نیستند؟ در هر commodity، ابزار hledger مقادیر ثبت تراکنش را پس از تبدیل موارد دارای هزینه، با یکدیگر جمع می‌زند؛ سپس بررسی می‌کند که آیا این حاصل‌جمع پس از گرد شدن به تعداد ارقام اعشار مناسب، برابر با صفر است یا خیر \- که آن را \f[I]دقت تراز کردن (balancing precision)\f[R] می‌نامیم. .PP از نسخه 1.50، ابزار hledger دقت تراز کردن در هر تراکنش را از روی مقادیر موجود در مدخل دفتر روزنامه همان تراکنش استنتاج می‌کند (مشابه Ledger). یعنی هنگام بررسی تراز commodity A، از بالاترین دقت اعشاری دیده‌شده برای A در مدخل دفتر روزنامه (به‌استثنای مقادیر cost) استفاده می‌نماید. این کار تراز کردن تراکنش را پایدار و محکم می‌سازد؛ هرگونه عدم تراز باید به صورت آشکار در مدخل دفتر روزنامه لحاظ شود، دقت نمایش را می‌توان آزادانه با \f[CR]\-c\f[R] افزایش داد، و سازگاری با دفاتر روزنامه Ledger و Beancount بسیار خوب است. .PP توجه داشته باشید که نسخه‌های hledger پیش از 1.50 به شیوه متفاوتی عمل می‌کردند: آن‌ها اجازه می‌دادند دقت نمایش بر دقت تراز کردن اولویت پیدا کند (override شود). این مسئله باعث پنهان شدن عدم ترازهای جزئی و ایجاد شکنندگی می‌شد (به مسئله #2402 مراجعه کنید). در نتیجه، برخی مدخل‌های دفتر روزنامه (یا قوانین CSV) که با hledger <1.50 کار می‌کردند، اکنون با خطای \(dqunbalanced transaction\(dq (تراکنش نامتراز) رد می‌شوند. اگر به این مشکل برخوردید، رفع آن آسان است: .IP \(bu 2 می‌توانید رفتار پیشین را با افزودن \f[CR]\-\-txn\-balancing=old\f[R] به دستور یا به فایل \f[CR]\(ti/.hledger.conf\f[R] خود بازیابی کنید. این به شما امکان می‌دهد همچنان بدون تغییر از دفاتر روزنامه قدیمی استفاده کنید، هرچند مزایای فوق را نخواهید داشت. .IP \(bu 2 یا می‌توانید مدخل‌های دارای مشکل را برطرف کنید (توصیه‌شده). سه راهکار وجود دارد، از هر کدام که مناسب‌تر است استفاده نمایید: .RS 2 .IP "1." 3 مقادیر هزینه (cost) را دقیق‌تر کنید (ارقام اعشاری بیشتر/دقیق‌تری اضافه کنید) .IP "2." 3 یا مقادیر غیرهزینه‌ای را با دقت کمتری درج کنید (ارقام اعشاری غیرضروری که دقت را بالا می‌برند حذف کنید) .IP "3." 3 یا یک ثبت برای جذب عدم تراز اضافه نمایید (مانند \(dqexpenses:rounding\(dq. به یاد داشته باشید که در یک ثبت می‌توان مقدار را خالی گذاشت؛ این ویژگی در اینجا کارآمد است.) .RE.SS "برچسب‌ها (Tags)" برچسب‌ها روشی برای افزودن برچسب‌ها یا فیلدهای داده اضافی به تراکنش‌ها، ثبت‌ها، یا حساب‌ها هستند که می‌توانید با یک پرس‌وجوی \f[CR]tag:\f[R] در گزارش‌ها آن‌ها را مطابقت دهید. (پرس‌وجوهای زیر را ببینید.) .PP برچسب‌ها یک کلمه واحد یا کلمه‌ای با خط تیره هستند که بلافاصله پس از آن یک دونقطه قرار می‌گیرد و در داخل یک توضیح نوشته می‌شوند. (بله، ذخیره داده‌ها در توضیحات کمی عجیب است.) در اینجا تراکنشی با یک برچسب آورده شده است: .IP .EX 2025\-01\-01 groceries ; some\-tag: assets:checking expenses:food $1 .EE .PP یک برچسب می‌تواند مقداری داشته باشد؛ یک خط متنی که بعد از دونقطه نوشته می‌شود. مقادیر برچسب نمی‌توانند شامل خط جدید باشند.: .IP .EX 2025\-01\-01 groceries ; tag1: this is tag1\(aqs value .EE .PP چندین برچسب می‌توانند با ویرگول از هم جدا شوند. مقادیر برچسب نمی‌توانند شامل ویرگول باشند.: .IP .EX 2025\-01\-01 groceries ; tag1:value 1, tag2:value 2, comment text .EE .PP یک برچسب می‌تواند چندین مقدار داشته باشد: .IP .EX 2025\-01\-01 groceries ; tag1:value 1, tag1:value 2 .EE .PP در صورت تمایل می‌توانید هر برچسب را در خط جداگانه خود بنویسید (اما همچنان نمی‌توانند شامل ویرگول باشند): .IP .EX 2025\-01\-01 groceries ; tag1: value 1 ; tag2: value 2 .EE .PP برچسب‌ها را می‌توان به جای کل تراکنش، به ثبت‌های جداگانه متصل کرد: .IP .EX 2025\-01\-01 rent assets:checking expenses:rent $1000 ; postingtag: .EE .PP برچسب‌ها را می‌توان در دستورالعمل حساب آن‌ها، به حساب‌ها متصل کرد: .IP .EX account assets:checking ; acct\-number: 123\-45\-6789 .EE .SS "انتشار برچسب (Tag propagation)" برچسب‌ها علاوه بر آنچه به آن متصل شده‌اند، به چند روش بر داده‌های مرتبط نیز تأثیر می‌گذارند و امکان پرس‌وجوهای قدرتمندتری را فراهم می‌سازند: .IP "1." 3 حساب‌ها \-> ثبت‌ها. ثبت‌ها برچسب‌ها را از حساب خود به ارث می‌برند. .IP "2." 3 تراکنش‌ها \-> ثبت‌ها. ثبت‌ها برچسب‌ها را از تراکنش خود به ارث می‌برند. .IP "3." 3 ثبت‌ها \-> تراکنش‌ها. تراکنش‌ها نیز برچسب‌های ثبت‌های خود را دریافت می‌کنند. \ .PP بنابراین وقتی از پرس‌وجوی \f[CR]tag:\f[R] برای مطابقت کل تراکنش‌ها، ثبت‌های جداگانه یا حساب‌ها استفاده می‌کنید، بهتر است نحوه رفتار برچسب‌ها را بدانید. در اینجا مثالی آمده است که هر سه نوع انتشار را نشان می‌دهد: .IP .EX account assets:checking account expenses:food ; atag: 2025\-01\-01 groceries ; ttag: assets:checking ; p1tag: expenses:food $1 ; p2tag: .EE .PP .TS tab(@); lw(16.0n) lw(16.0n) lw(38.0n). T{ بخش داده T}@T{ دارای برچسب‌های T}@T{ توضیحات T} _ T{ حساب\ assets:checking T}@T{ T}@T{ هیچ برچسبی متصل نشده است T} T{ حساب\ expenses:food T}@T{ atag T}@T{ atag: در توضیح T} T{ ثبت\ assets:checking T}@T{ p1tag, ttag T}@T{ p1tag: در توضیح، ttag از تراکنش دریافت شده T} T{ ثبت\ expenses:food T}@T{ p2tag, atag, ttag T}@T{ p2tag: در توضیح، atag از حساب، ttag از تراکنش T} T{ تراکنش\ groceries T}@T{ ttag, p1tag, p2tag, atag T}@T{ ttag: در توضیح، p1tag از ثبت اول، p2tag و atag از ثبت دوم T} .TE.SS نمایش برچسب‌ها (Displaying tags) می‌توانید از دستور \f[CR]tags\f[R] برای فهرست کردن نام‌ها یا مقادیر برچسب‌ها استفاده کنید. .PP دستور \f[CR]print\f[R] نیز برچسب‌ها را نمایش می‌دهد. .PP می‌توانید از \-\-pivot برای نمایش مقادیر برچسب در سایر گزارش‌ها، به روش‌های گوناگون (مانند الحاق به نام حساب‌ها، شبیه به شبه‌حساب‌های فرعی) استفاده کنید. .SS چه زمانی از برچسب‌ها استفاده کنیم؟ (When to use tags ?) برچسب‌ها ابعاد بیشتری از دسته‌بندی را فراهم کرده و مکمل حساب‌ها و شرح تراکنش‌ها هستند. اینکه چه زمانی از هر یک از این‌ها استفاده کنید تا حدی سلیقه‌ای است. حساب‌ها بیشترین پشتیبانی توکار را دارند و پرس‌وجوهای regex روی شرح‌ها نیز بسیار قدرتمند هستند. بنابراین ممکن است اصلاً به برچسب‌ها نیازی نداشته باشید. اما اگر می‌خواهید چندین دسته‌بندی متقاطع را پیگیری کنید، می‌توانند گزینه مناسبی باشند. برای نمونه، می‌توانید تراکنش‌های مربوط به سفر را با \f[CR]trip: YEAR:PLACE\f[R] برچسب‌گذاری کنید، بدون اینکه دسته‌بندی‌های معمول حساب‌های خود را برهم بزنید. .SS نام‌های برچسب (Tag names) چه نویسه‌هایی در نام برچسب مجاز است؟ بیشتر نویسه‌های غیرفاصله‌ای. برای نمونه \f[CR]😀:\f[R] یک برچسب معتبر است. .PP برای بررسی بیشتر خطاها، می‌توانید نام‌های معتبر برچسب را با دستورالعمل \f[CR]tag\f[R] تعریف کرده و سپس آن‌ها را با دستور \f[CR]check\f[R] اعمال کنید. اما توجه داشته باشید که در حال حاضر برچسب‌ها به‌صورت نه‌چندان سخت‌گیرانه شناسایی می‌شوند، گاهی در جاهایی که قصد آن را نداشته‌اید. برای نمونه یادداشتی مانند \f[CR]; see https://foo.com\f[R] یک برچسب \f[CR]https\f[R] اضافه می‌کند. .PP چندین نام برچسب وجود دارند که برای hledger اهمیت ویژه‌ای دارند. آن‌ها در بخش‌های دیگر توضیح داده شده‌اند، اما در اینجا یک راهنمای سریع آورده شده است: .IP .EX type \-\- نوع یک حساب را اعلان می‌کند date \-\- تاریخ یک ثبت را بازنویسی می‌کند date2 \-\- تاریخ ثانویه یک ثبت را بازنویسی می‌کند assert \-\- روی تراکنش‌های تولیدشده توسط close \-\-assert ظاهر می‌شود retain \-\- روی تراکنش‌های تولیدشده توسط close \-\-retain ظاهر می‌شود start \-\- روی تراکنش‌های تولیدشده توسط close \-\-migrate/\-\-close/\-\-open/\-\-assign ظاهر می‌شود t \-\- روی ثبت‌های تولیدشده از نویسه‌های timedot ظاهر می‌شود generated\-transaction \-\- روی تراکنش‌های تولیدشده توسط یک قانون دوره‌ای ظاهر می‌شود modified\-transaction \-\- روی تراکنش‌هایی که ثبت‌های خودکار به آن‌ها افزوده شده ظاهر می‌شود generated\-posting \-\- روی ثبت‌های تولیدشده ظاهر می‌شود cost\-posting \-\- روی ثبت‌هایی که دارای (یا می‌توانند دارای) بها باشند ظاهر می‌شود، و دارای ثبت‌های تبدیل معادل در تراکنش هستند conversion\-posting \-\- روی ثبت‌هایی ظاهر می‌شود که به یک حساب V/Conversion هستند و یک ثبت بهای معادل در تراکنش دارند .EE .PP گروه دوم در بالا (generated\-transaction و غیره) معمولاً پنهان هستند و پیشوند \f[CR]_\f[R] به آن‌ها افزوده شده است. این بدان معناست که \f[CR]print\f[R] به‌طور پیش‌فرض آن‌ها را نمایش نمی‌دهد؛ اما همچنان می‌توانید از آن‌ها در پرس‌وجوها استفاده کنید. می‌توانید پرچم \f[CR]\-\-verbose\-tags\f[R] را اضافه کنید تا در خروجی \f[CR]print\f[R] قابل مشاهده شوند، که می‌تواند برای عیب‌یابی مفید باشد. .SS دستورالعمل‌ها (Directives) علاوه بر تراکنش‌ها، مورد دیگری نیز وجود دارد که می‌توانید در یک فایل \f[CR]journal\f[R] قرار دهید: دستورالعمل‌ها (directives). این‌ها اعلان‌هایی هستند که با یک کلیدواژه آغاز می‌شوند و رفتار hledger را تغییر می‌دهند. برخی دستورالعمل‌ها می‌توانند زیردستورالعمل‌های مشخص‌تری داشته باشند که با تورفتگی در زیر آن‌ها قرار می‌گیرند. دستورالعمل‌های hledger در بسیاری از موارد مشابه Ledger هستند، اما تفاوت‌های زیادی نیز وجود دارد. دستورالعمل‌ها اجباری نیستند، اما می‌توانند سودمند باشند. در اینجا دستورالعمل‌های اصلی آورده شده‌اند: .PP .TS tab(@); lw(39.7n) lw(30.3n). T{ هدف T}@T{ دستورالعمل T} _ T{ \f[B]خواندن داده‌ها (READING DATA):\f[R] T}@T{ T} T{ بازنویسی نام حساب‌ها T}@T{ \f[CR]alias\f[R] T} T{ کامنت کردن بخش‌هایی از فایل T}@T{ \f[CR]comment\f[R] T} T{ اعلان نشانگر اعشار فایل، برای کمک به تجزیه دقیق مقادیر T}@T{ \f[CR]decimal\-mark\f[R] T} T{ قراردادن سایر فایل‌های داده T}@T{ \f[CR]include\f[R] T} T{ \f[B]تولید داده‌ها (GENERATING DATA):\f[R] T}@T{ T} T{ تولید تراکنش‌های تکرارشونده یا اهداف بودجه T}@T{ \f[CR]\(ti\f[R] T} T{ تولید ثبت‌های اضافی روی تراکنش‌های موجود T}@T{ \f[CR]=\f[R] T} T{ \f[B]بررسی خطاها (CHECKING FOR ERRORS):\f[R] T}@T{ T} T{ تعریف موجودیت‌های معتبر برای بررسی بیشتر خطاها T}@T{ \f[CR]account\f[R]، \f[CR]commodity\f[R]، \f[CR]payee\f[R]، \f[CR]tag\f[R] T} T{ \f[B]گزارش‌گیری (REPORTING):\f[R] T}@T{ T} T{ اعلان نوع و ترتیب نمایش حساب‌ها T}@T{ \f[CR]account\f[R] T} T{ اعلان شیوه‌های نمایش ارز و کالا T}@T{ \f[CR]commodity\f[R] T} T{ اعلان قیمت‌های بازار T}@T{ \f[CR]P\f[R] T} .TE.SS "دستورالعمل‌ها و چندین فایل" دستورالعمل‌ها از نظر دامنه اثر خود، یعنی این‌که بر کدام مدخل‌های دفتر روزنامه و کدام فایل‌های ورودی تأثیر می‌گذارند، تفاوت دارند. اغلب اوقات، یک دستورالعمل بر مدخل‌های بعدی و فایل‌های گنجانده‌شده (در صورت وجود)، تا پایان فایل جاری تأثیر می‌گذارد \- و نه فراتر از آن. شاید این موضوع به نظرتان ناخوشایند بیاید! برای مثال، دستورالعمل‌های \f[CR]alias\f[R] بر فایل‌های والد یا هم‌سطح تأثیری ندارند. اما معمولاً راه‌حل‌هایی وجود دارد؛ برای نمونه، قرار دادن دستورالعمل‌های \f[CR]alias\f[R] در بالاترین فایل خود، پیش از گنجاندن فایل‌های دیگر. .PP این محدودیت، اگرچه ممکن است در ابتدا آزاردهنده باشد، اما هدف خوبی دارد؛ این امر باعث می‌شود گزارش‌ها مستقل از ترتیب ورودی، پایدار و قطعی باشند. بدون آن، گزارش‌ها ممکن بود بسته به ترتیب گزینه‌های \-f، یا جایگاه دستورالعمل‌های include در فایل‌هایتان، اعداد متفاوتی را نشان دهند. .SS "تأثیرات دستورالعمل‌ها" در این‌جا تمام دستورالعمل‌های hledger به همراه خلاصه‌ای از اثرات و دامنه آن‌ها آورده شده است \- نُه دستورالعمل اصلی، به‌علاوه چهار مورد دیگر که آن‌ها را غیرضروری می‌دانیم: .PP .TS tab(@); lw(3.5n) lw(64.1n) lw(2.4n). T{ دستورالعمل T}@T{ عملکرد T}@T{ خاتمه در انتهای فایل؟ T} _ T{ \f[B]\f[CB]account\f[B]\f[R] T}@T{ یک حساب را برای بررسی تمام مدخل‌ها در همه فایل‌ها، و همچنین ترتیب نمایش و نوع آن اعلام می‌کند. دستورالعمل‌های فرعی: هر متنی، نادیده گرفته می‌شود. T}@T{ خیر T} T{ \f[B]\f[CB]alias\f[B]\f[R] T}@T{ نام‌های حساب را در مدخل‌های بعدی تا انتهای فایل جاری یا \f[CR]end aliases\f[R] بازنویسی می‌کند. معادل در خط فرمان: \f[CR]\-\-alias\f[R] T}@T{ بله T} T{ \f[B]\f[CB]comment\f[B]\f[R] T}@T{ بخشی از فایل دفتر روزنامه را تا پایان فایل جاری یا \f[CR]end comment\f[R] نادیده می‌گیرد. T}@T{ بله T} T{ \f[B]\f[CB]commodity\f[B]\f[R] T}@T{ تا چهار مورد را تعیین می‌کند: 1. یک نماد کالا، برای بررسی تمام مقادیر در همه فایل‌ها 2. سبک نمایش برای تمام مقادیر این کالا 3. علامت اعشار برای تجزیه مقادیر این کالا، در ادامه این فایل و فرزندان آن، در صورتی که هیچ دستورالعمل \f[CR]decimal\-mark\f[R] وجود نداشته باشد 4. دقت مورد استفاده برای بررسی تراکنش‌های تراز در این کالا، در این فایل و فرزندان آن. \ بر \f[CR]D\f[R] اولویت دارد. دستورالعمل‌های فرعی: \f[CR]format\f[R] (نادیده گرفته می‌شود). معادل در خط فرمان: \f[CR]\-c/\-\-commodity\-style\f[R] T}@T{ خیر، خیر، بله، بله T} T{ \f[B]\f[CB]decimal\-mark\f[B]\f[R] T}@T{ علامت اعشار را برای تجزیه مقادیر تمام کالاها در مدخل‌های بعدی تا \f[CR]decimal\-mark\f[R] بعدی یا پایان فایل جاری تعیین می‌کند. فایل‌های گنجانده‌شده می‌توانند آن را بازنویسی کنند. بر \f[CR]commodity\f[R] و \f[CR]D\f[R] اولویت دارد. T}@T{ بله T} T{ \f[B]\f[CB]include\f[B]\f[R] T}@T{ مدخل‌ها و دستورالعمل‌ها را از فایلی دیگر می‌گنجاند، به‌گونه‌ای که گویی به‌صورت درون‌خطی نوشته شده‌اند. جایگزین در خط فرمان: چند گزینه \f[CR]\-f/\-\-file\f[R] T}@T{ خیر T} T{ \f[B]\f[CB]payee\f[B]\f[R] T}@T{ نام دریافت‌کننده وجه را برای بررسی تمام مدخل‌ها در همه فایل‌ها تعیین می‌کند. T}@T{ خیر T} T{ \f[B]\f[CB]P\f[B]\f[R] T}@T{ قیمت بازار یک کالا را در تاریخی مشخص، برای گزارش‌های ارزش‌گذاری اعلام می‌کند. T}@T{ خیر T} T{ \f[B]\f[CB]\(ti\f[B]\f[R] (تیلدا / tilde) T}@T{ یک قاعده تراکنش دوره‌ای را تعیین می‌کند که تراکنش‌های آینده را با \f[CR]\-\-forecast\f[R] و اهداف بودجه را با \f[CR]balance \-\-budget\f[R] تولید می‌کند. T}@T{ خیر T} T{ سایر نحوها: T}@T{ T}@T{ T} T{ \f[B]\f[CB]apply account\f[B]\f[R] T}@T{ یک حساب والد مشترک را به ابتدای تمام نام‌های حساب در مدخل‌های بعدی تا پایان فایل جاری یا \f[CR]end apply account\f[R] می‌افزاید. T}@T{ بله T} T{ \f[B]\f[CB]D\f[B]\f[R] T}@T{ یک کالای پیش‌فرض را برای استفاده در مقادیر بدون نماد تنظیم می‌کند؛ و اگر هیچ دستورالعمل \f[CR]commodity\f[R] برای این کالا وجود نداشته باشد: علامت اعشار، دقت ترازسازی، و سبک نمایش آن را مطابق موارد بالا تنظیم می‌کند. T}@T{ بله، بله، خیر، خیر T} T{ \f[B]\f[CB]Y\f[B]\f[R] T}@T{ یک سال پیش‌فرض را برای استفاده در تاریخ‌های بدون سال در مدخل‌های بعدی تا پایان فایل جاری تنظیم می‌کند. T}@T{ بله T} T{ \f[B]\f[CB]=\f[B]\f[R] (مساوی / equals) T}@T{ یک قاعده ثبت خودکار را تعیین می‌کند که ثبت‌های اضافی را در تراکنش‌های منطبق با \f[CR]\-\-auto\f[R]، در فایل‌های جاری، والد و فرزند تولید می‌کند (اما نه در فایل‌های هم‌سطح، گزارش #1212 را ببینید). T}@T{ تا حدی T} T{ \f[B]سایر دستورالعمل‌های Ledger\f[R] T}@T{ سایر دستورالعمل‌های برگرفته از قالب فایل Ledger پذیرفته می‌شوند اما نادیده گرفته خواهند شد. T}@T{ T} .TE.SS دستورالعمل \f[CR]account\f[R] دستورالعمل‌های \f[CR]account\f[R] می‌توانند برای اعلان حساب‌ها (یعنی مکان‌هایی که مبالغ از آن‌ها و به آن‌ها منتقل می‌شوند) استفاده شوند. گرچه الزامی نیست، اما این اعلان‌ها می‌توانند مزایای متعددی را فراهم کنند: .IP \(bu 2 می‌توانند ساختار و نمودار حساب‌های (chart of accounts) مدنظر شما را مستند کرده و یک مرجع ارائه دهند. .IP \(bu 2 می‌توانند اطلاعات تکمیلی حساب را به‌صورت کامنت، یا برچسب‌هایی که می‌توان برای فیلتر کردن یا تغییر جهت (pivot) گزارش‌ها استفاده کرد، ذخیره کنند. .IP \(bu 2 می‌توانند حساب‌هایی را که تراکنش‌ها مجاز به ثبت در آن‌ها هستند محدود کنند؛ مثلاً در حالت strict mode، که به جلوگیری از خطاها کمک می‌کند. .IP \(bu 2 آن‌ها بر ترتیب نمایش حساب‌ها در گزارش‌ها اثر می‌گذارند و امکان مرتب‌سازی غیرالفبایی را فراهم می‌سازند (مثلاً درآمدها بالاتر از هزینه‌ها نمایش یابند). .IP \(bu 2 می‌توانند به hledger در شناسایی نوع حساب‌های شما (asset، liability، equity، revenue، expense) کمک کنند و گزارش‌هایی مانند balancesheet و incomestatement را امکان‌پذیر سازند. .IP \(bu 2 به تکمیل خودکار نام حساب کمک می‌کنند (در hledger add، hledger\-web، hledger\-iadd، ledger\-mode و غیره). .PP آن‌ها به‌صورت کلمهٔ \f[CR]account\f[R] به همراه یک نام حساب به سبک hledger نوشته می‌شوند. برای مثال: .IP .EX account assets:bank:checking .EE .PP زیردستورالعمل‌های دارای تورفتگی به سبک Ledger نیز پذیرفته می‌شوند، اما نادیده گرفته می‌شوند: .IP .EX account assets:bank:checking format subdirective ; currently ignored .EE .SS کامنت‌های حساب متنی که پس از \f[B]دو یا چند فاصله\f[R] و \f[CR];\f[R] در انتهای خط یک دستورالعمل account، و/یا پس از \f[CR];\f[R] در خطوط دارای تورفتگی بلافاصله زیر آن بیاید، کامنت‌های آن حساب را تشکیل می‌دهد. .PP کامنت‌های حساب در همان خط به بیش از ۲ فاصله پیش از \f[CR];\f[R] نیاز دارند زیرا این نویسه می‌تواند در نام حساب‌ها نیز ظاهر شود. .IP .EX account assets:bank:checking ; same\-line comment, at least 2 spaces before the semicolon ; next\-line comment ; some tags \- type:A, acctnum:12345 .EE .SS برچسب‌های حساب کامنتِ یک دستورالعمل account می‌تواند شامل برچسب‌ها باشد. این برچسب‌ها به تمام ثبت‌های تراکنش (postings) که از آن حساب استفاده می‌کنند، به‌عنوان برچسب‌های ثبت پنهان اما قابل جست‌وجو، منتقل می‌شوند، مگر در مواردی که آن ثبت از قبل برچسبی با همان نام داشته باشد. (برچسب‌های ثبت بر برچسب‌های حساب اولویت دارند.) .SS بررسی خطای حساب به‌طور پیش‌فرض، نیازی به اعلان حساب‌ها نیست؛ آن‌ها زمانی به وجود می‌آیند که یک ثبت تراکنش به آن‌ها ارجاع دهد. این ویژگی راحت است، اما به این معنی است که hledger نمی‌تواند هنگام اشتباه املایی در نام حساب در journal به شما هشدار دهد. معمولاً چنین خطایی را بعداً خواهید یافت، به‌عنوان یک حساب اضافی در گزارش‌های تراز، یا یک تراز نادرست هنگام تطبیق حساب‌ها (reconciling). .PP در حالت سخت‌گیرانه (strict mode)، که با پرچم \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] فعال می‌شود، یا زمانی که دستور \f[CR]hledger check accounts\f[R] را اجرا می‌کنید، اگر هر تراکنشی از نام حسابی استفاده کند که توسط دستورالعمل account اعلان نشده باشد، hledger یک خطا گزارش می‌دهد. چند نکته: .IP \(bu 2 اعلان حساب حساس به بزرگی و کوچکی حروف (case\-sensitive) است؛ تراکنش‌ها باید از بزرگی و کوچکی صحیح حروف نام حساب استفاده کنند. .IP \(bu 2 دامنهٔ دستورالعمل account به‌صورت \(dqتمام فایل و زیرمجموعه‌ها\(dq (بخش directives را ببینید) است. این یعنی بر تمام فایل جاری و هر فایلی که شامل (include) کرده است اثر می‌گذارد، اما بر فایل‌های والد یا هم‌سطح تأثیری ندارد. موقعیت قرارگیری دستورالعمل‌های account درون فایل اهمیتی ندارد، اگرچه معمول است که در بالای فایل قرار داده شوند. .IP \(bu 2 حساب‌ها فقط در فایل‌های \f[CR]journal\f[R] قابل اعلان هستند، اما بر فایل‌های گنجانده‌شده از تمام انواع تأثیر می‌گذارند. .IP \(bu 2 در حال حاضر اعلان \(dqتمام زیرحساب‌های ممکن\(dq با یک نویسهٔ عامه‌نما (wildcard) امکان‌پذیر نیست؛ هر حسابی که به آن ثبتی تخصیص داده می‌شود باید اعلان شده باشد. .IP \(bu 2 اگر از پرچم \-\-infer\-equity استفاده می‌کنید، به اعلان‌هایی برای نام‌های حسابی که این پرچم ایجاد می‌کند نیز نیاز خواهید داشت..SS "ترتیب نمایش حساب‌ها (Account display order)" دستورهای account همچنین باعث می‌شوند که hledger حساب‌ها را نه فقط به ترتیب الفبایی، بلکه به ترتیبی مشخص نمایش دهد. برای نمونه، این یک ترتیب متداول برای حساب‌های سطح بالا (top\-level) است: .IP .EX account assets account liabilities account equity account revenues account expenses .EE .PP اکنون hledger آن‌ها را با همین ترتیب نمایش می‌دهد: .IP .EX $ hledger accounts assets liabilities equity revenues expenses .EE .PP اگر حساب‌های اعلان‌نشده‌ای وجود داشته باشند، در انتها و به ترتیب الفبایی نمایش داده خواهند شد. .PP مرتب‌سازی در هر گروه از حساب‌های هم‌سطح (هم‌نیا)، در هر سطح از درخت حساب‌ها انجام می‌شود. برای نمونه، اعلانی مانند \f[CR]account parent:child\f[R] بر جایگاه \f[CR]child\f[R] در میان حساب‌های هم‌سطحش اثر می‌گذارد. .PP توجه داشته باشید که این اعلان تأثیری بر جایگاه \f[CR]parent\f[R] ندارد؛ برای این کار، به اعلان \f[CR]account parent\f[R] نیاز دارید. .PP حساب‌های هم‌سطح همواره کنار یکدیگر نمایش داده می‌شوند؛ hledger هیچ‌گاه \f[CR]x:y\f[R] را میان \f[CR]a:b\f[R] و \f[CR]a:c\f[R] نمایش نخواهد داد. .PP یک دستور account هم یک حساب را به عنوان مقصدی معتبر برای ثبت سند (posting target) اعلان می‌کند و هم ترتیب نمایش آن را مشخص می‌سازد؛ نمی‌توانید به آسانی یکی را بدون دیگری انجام دهید. .SS "انواع حساب‌ها (Account types)" نرم‌افزار hledger می‌داند که در حسابداری سه نوع حساب اصلی وجود دارد: .PP .TS tab(@); l l l. T{ \f[CR]Asset\f[R] T}@T{ \f[CR]A\f[R] T}@T{ دارایی‌های شما T} T{ \f[CR]Liability\f[R] T}@T{ \f[CR]L\f[R] T}@T{ بدهی‌های شما T} T{ \f[CR]Equity\f[R] T}@T{ \f[CR]E\f[R] T}@T{ سرمایهٔ مالک، برقرارکنندهٔ توازن میان دو مورد بالا T} .TE .PP و دو نوع دیگر که تغییرات در این‌ها را نشان می‌دهند: .PP .TS tab(@); l l l. T{ \f[CR]Revenue\f[R] T}@T{ \f[CR]R\f[R] T}@T{ جریان‌های ورودی (شناخته‌شده با عنوان \f[CR]Income\f[R]) T} T{ \f[CR]Expense\f[R] T}@T{ \f[CR]X\f[R] T}@T{ جریان‌های خروجی T} .TE .PP همچنین hledger از چند زیرنوع (subtype) استفاده می‌کند: .PP .TS tab(@); lw(23.3n) lw(23.3n) lw(23.3n). T{ \f[CR]Cash\f[R] T}@T{ \f[CR]C\f[R] T}@T{ دارایی‌های نقد (زیرنوعی از \f[CR]Asset\f[R]) T} T{ \f[CR]Conversion\f[R] T}@T{ \f[CR]V\f[R] T}@T{ حقوق صاحبان سهام تبدیل کالا (زیرنوعی از \f[CR]Equity\f[R]) T} T{ \f[CR]Gain\f[R] T}@T{ \f[CR]G\f[R] T}@T{ سودها/زیان‌های سرمایه‌ای (زیرنوعی از \f[CR]Revenue\f[R]) T} .TE .PP برای آسودگی، hledger بیشتر این نوع‌ها را به طور خودکار از روی نام‌های انگلیسی حساب‌ها تشخیص می‌دهد. اما بهتر است با افزودن برچسب \f[CR]type:\f[R] در دستورهای account، آن‌ها را به طور صریح اعلان کنید. مقدار برچسب می‌تواند هر یک از انواع یا اختصارات تک‌حرفی بالا باشد. .PP در اینجا مجموعه‌ای نمونه از اعلان‌های نوع حساب آورده شده است. زیرحساب‌ها نوع والد خود را به ارث می‌برند، یا می‌توانند آن را بازنویسی کنند: .IP .EX account assets ; type: A account liabilities ; type: L account equity ; type: E account revenues ; type: R account expenses ; type: X account assets:bank ; type: C account assets:cash ; type: C account equity:conversion ; type: V account revenues:capital ; type: G .EE .PP این کار تولید آسان گزارش‌های balancesheet ،balancesheetequity ،cashflow و incomestatement، و همچنین پرس‌وجو بر اساس نوع را امکان‌پذیر می‌سازد:. .PP نکات: .IP \(bu 2 می‌توانید برای عیب‌یابی، حساب‌ها و انواع آن‌ها را فهرست کنید: .RS 2 .IP .EX $ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH] [\-\-locations] .EE .RE .IP \(bu 2 ایدهٔ خوبی است که دست‌کم یک حساب را برای هر نوع حساب اعلان کنید. اعلان برخی نوع‌ها و استنتاج برخی دیگر می‌تواند باعث اختلال در برخی گزارش‌ها شود. .IP \(bu 2 قواعد استنتاج نوع‌ها از نام حساب‌ها به شرح زیر است (با استفاده از عبارات باقاعده \- Regular expressions). .PD 0 .P .PD اگر این قواعد برای شما کارآمد نیستند، کافی است آن‌ها را نادیده بگیرید و انواع خود را با برچسب‌های \f[CR]type:\f[R] اعلان کنید. .RS 2 .IP .EX If account\(aqs name contains this case insensitive regular expression | its type is \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\- \(haassets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash \(haassets?(:|$) | Asset \(ha(debts?|liabilit(y|ies))(:|$) | Liability \(haequity:(trad(e|ing)|conversion)s?(:|$) | Conversion \(haequity(:|$) | Equity \(ha(income|revenue)s?(:|$) | Revenue \(haexpenses?(:|$) | Expense .EE .RE.IP \(bu 2 همان‌طور که در بالا اشاره شد، زیرحساب‌ها نوع را از حساب والد خود به ارث خواهند برد. به‌طور دقیق، نوع یک حساب با نخستین مورد از موارد زیر که وجود داشته باشد تعیین می‌شود: .RS 2 .IP "1." 3 یک اعلان \f[CR]type:\f[R] برای این حساب. .IP "2." 3 یک اعلان \f[CR]type:\f[R] در حساب‌های والد بالاتر از آن، با اولویت نزدیک‌ترین حساب. .IP "3." 3 یک نوع حساب استنباط‌شده از نام این حساب. .IP "4." 3 یک نوع حساب استنباط‌شده از نام حساب والد، با اولویت نزدیک‌ترین حساب والد. .IP "5." 3 در غیر این صورت، حسابی بدون نوع خواهد بود. .RE .IP \(bu 2 نام‌های مستعار حساب می‌توانند انواع حساب‌ها را مختل کنند. .SS دستورالعمل \f[CR]alias\f[R] می‌توانید قواعد نام مستعار حساب (alias) را تعریف کنید که نام حساب‌های شما، یا بخش‌هایی از آن‌ها را پیش از تولید گزارش‌ها بازنویسی می‌کنند. این قابلیت می‌تواند برای موارد زیر مفید باشد: .IP \(bu 2 بسط دادن نام‌های اختصاری حساب‌ها به شکل کاملشان، جهت ورود آسان‌تر داده‌ها و داشتن یک دفتر روزنامه مختصرتر .IP \(bu 2 تطبیق دادن دفترهای روزنامه قدیمی با نمودار حساب‌های فعلی شما .IP \(bu 2 آزمودن سازمان‌دهی‌ها و ساختارهای جدید حساب، مانند یک سلسله‌مراتب تازه .IP \(bu 2 ترکیب دو حساب در یکی، برای مثال جهت مشاهده مجموع یا تفاضل آن‌ها در یک خط .IP \(bu 2 سفارشی‌سازی گزارش‌ها .PP نام‌های مستعار حساب همچنین نام‌های حساب را در دستورالعمل‌های account بازنویسی می‌کنند. آن‌ها بر نام‌های حسابی که از طریق hledger add یا hledger\-web وارد می‌شوند تأثیری ندارند. .PP نام‌های مستعار حساب بسیار قدرتمند هستند. استفاده صحیح از آن‌ها به‌طور کلی آسان است، اما می‌توانید با آن‌ها نام‌های حساب نامعتبر نیز ایجاد کنید؛ در ادامه به این موضوع بیشتر پرداخته خواهد شد. .PP همچنین بخش «بازنویسی نام‌های حساب» (Rewrite account names) را ببینید. .SS نام‌های مستعار پایه برای تنظیم یک نام مستعار حساب، از دستورالعمل \f[CR]alias\f[R] در فایل دفتر روزنامه خود استفاده کنید. این کار بر تمام ورودی‌های بعدی دفتر روزنامه در فایل جاری یا فایل‌های ضمیمه‌شده به آن تأثیر می‌گذارد (اما توجه داشته باشید: بر فایل‌های هم‌سطح یا والد تأثیری ندارد). فاصله‌های اطراف = اختیاری هستند: .IP .EX alias OLD = NEW .EE .PP یا می‌توانید از گزینه \f[CR]\-\-alias \(aqOLD=NEW\(aq\f[R] در خط فرمان استفاده کنید. این کار بر تمام ورودی‌ها تأثیر می‌گذارد. این روش برای آزمایش تعاملی نام‌های مستعار مفید است. .PP عبارات OLD و NEW نام‌های حساب کامل و حساس به بزرگی و کوچکی حروف هستند. ‏hledger هر رخدادی از نام حساب قدیمی را با نام جدید جایگزین خواهد کرد. زیرحساب‌ها نیز متأثر می‌شوند. برای مثال: .IP .EX alias checking = assets:bank:wells fargo:checking ; rewrites \(dqchecking\(dq to \(dqassets:bank:wells fargo:checking\(dq, or \(dqchecking:a\(dq to \(dqassets:bank:wells fargo:checking:a\(dq .EE .SS نام‌های مستعار مبتنی بر عبارت باقاعده (Regex) گونه‌ای قدرتمندتر نیز وجود دارد که از یک عبارت باقاعده استفاده می‌کند و با قرار گرفتن الگو در میان اسلش‌های رو به جلو مشخص می‌شود. (این تنها جایی است که hledger به اسلش‌های رو به جلو در اطراف یک عبارت باقاعده نیاز دارد.) .PP برای مثال: .IP .EX alias /REGEX/ = REPLACEMENT .EE .PP یا: .IP .EX $ hledger \-\-alias \(aq/REGEX/=REPLACEMENT\(aq ... .EE .PP هر بخشی از نام حساب که با REGEX تطبیق داده شود، با REPLACEMENT جایگزین خواهد شد. ‏REGEX طبق معمول به بزرگی و کوچکی حروف حساس نیست (case\-insensitive). .PP اگر نیاز دارید با یک اسلش رو به جلو تطبیق دهید، آن را با یک بک‌اسلش گریز دهید، مانند \f[CR]/\(rs/=:\f[R]. .PP اگر REGEX شامل گروه‌های تطبیق پرانتزبندی‌شده باشد، می‌توان در REPLACEMENT با استفاده از بک‌اسلش و شماره به آن‌ها ارجاع داد: .IP .EX alias /\(ha(.+):bank:([\(ha:]+):(.*)/ = \(rs1:\(rs2 \(rs3 ; rewrites \(dqassets:bank:wells fargo:checking\(dq to \(dqassets:wells fargo checking\(dq .EE .PP ‏REPLACEMENT تا انتهای خط (یا در خط فرمان، تا انتهای آرگومان گزینه) ادامه می‌یابد، بنابراین می‌تواند شامل نویسه‌های فاصله خالی انتهایی باشد..SS ترکیب نام‌های مستعار می‌توانید با استفاده از دستورالعمل‌های ژورنال و/یا گزینه‌های خط فرمان، به هر تعداد که مایلید نام مستعار (alias) تعریف کنید. .PP نام‌های مستعار بازگشتی \- که در آن نام یک حساب ابتدا توسط یک نام مستعار، سپس توسط نام مستعاری دیگر و به همین ترتیب بازنویسی می‌شود \- مجاز هستند. هر نام مستعار، تأثیر نام‌های مستعار اعمال‌شده پیشین را مشاهده می‌کند. .PP در چنین مواردی درک اینکه کدام نام‌های مستعار و با چه ترتیبی اعمال خواهند شد می‌تواند حائز اهمیت باشد. برای (هر نام حساب در) هر ورودی ژورنال، موارد زیر اعمال می‌شوند: .IP "1." 3 دستورالعمل‌های \f[CR]alias\f[R] پیش از ورودی ژورنال، به ترتیب آخرین مورد تجزیه‌شده (یعنی با خواندن رو به بالا از ورودی ژورنال، از پایین به بالا) .IP "2." 3 گزینه‌های \f[CR]\-\-alias\f[R]، به همان ترتیبی که در خط فرمان ظاهر شده‌اند (از چپ به راست). .PP به عبارت دیگر، برای (یک نام حساب در) یک ورودی مشخص ژورنال: .IP \(bu 2 نزدیک‌ترین تعریف نام مستعار قبل/بالای ورودی ابتدا اعمال می‌شود .IP \(bu 2 نام مستعار بعدی قبل/بالای آن در مرحله بعد اعمال خواهد شد، و به همین ترتیب .IP \(bu 2 نام‌های مستعار تعریف‌شده بعد/پایین‌تر از ورودی روی آن تأثیری ندارند. .PP این کار به نام‌های مستعار نزدیک‌تر نسبت به موارد دورتر اولویت می‌دهد و به ارائه پایداری معنایی کمک می‌کند \- نام‌های مستعار مستقل از اینکه چه فایل‌هایی و با چه ترتیبی خوانده می‌شوند، عملکرد یکسانی خواهند داشت. .PP در صورت بروز مشکل، افزودن \f[CR]\-\-debug=6\f[R] به خط فرمان نشان خواهد داد که کدام نام‌های مستعار در چه زمانی اعمال می‌شوند. .SS نام‌های مستعار و چندین فایل همان‌طور که در بخش «دستورالعمل‌ها و چندین فایل» توضیح داده شد، دستورالعمل‌های \f[CR]alias\f[R] بر فایل‌های والد یا هم‌سطح تأثیری نمی‌گذارند. به عنوان مثال در این دستور، .IP .EX hledger \-f a.aliases \-f b.journal .EE .PP نام‌های مستعار حساب تعریف‌شده در a.aliases روی b.journal تأثیری نخواهند داشت. شامل کردن (include) نام‌های مستعار نیز کارساز نیست: .IP .EX include a.aliases 2023\-01\-01 ; not affected by a.aliases foo 1 bar .EE .PP این بدان معناست که نام‌های مستعار حساب معمولاً باید در ابتدای بالاترین فایل شما اعلان شوند، مانند این: .IP .EX alias foo=Foo alias bar=Bar 2023\-01\-01 ; affected by aliases above foo 1 bar include c.journal ; also affected .EE .SS دستورالعمل \f[CR]end aliases\f[R] می‌توانید با این دستورالعمل، تمام نام‌های مستعار تعریف‌شده کنونی (دیده شده در ژورنال تا این لحظه، یا تعریف شده در خط فرمان) را پاک (فراموش) کنید: .IP .EX end aliases .EE .SS نام‌های مستعار می‌توانند نام‌های حساب نامعتبر ایجاد کنند توجه داشته باشید که نام‌های مستعار حساب می‌توانند نام‌های حساب بدریخت و ناهنجاری تولید کنند که ممکن است به گزارش‌های گیج‌کننده یا خروجی نامعتبر \f[CR]print\f[R] منجر شود. به عنوان مثال، می‌توانید تمام نام‌های حساب را پاک کنید: .IP .EX 2021\-01\-01 a:aa 1 b .EE .IP .EX $ hledger print \-\-alias \(aq/.*/=\(aq 2021\-01\-01 1 .EE .PP خروجی \f[CR]print\f[R] بالا یک ژورنال معتبر نیست. یا می‌توانید یک فاصله دوتایی غیرمجاز درج کنید، که باعث ایجاد خروجی \f[CR]print\f[R] می‌شود که در صورت تجزیه مجدد، ژورنال متفاوتی به دست می‌دهد: .IP .EX 2021\-01\-01 old 1 other .EE .IP .EX $ hledger print \-\-alias old=\(dqnew USD\(dq | hledger \-f\- print 2021\-01\-01 new USD 1 other .EE.SS نام‌های مستعار و انواع حساب اگر حسابی با اعلان نوع (بخش اعلان حساب‌ها > انواع حساب را ببینید) از طریق یک نام مستعار تغییر نام یابد، نوع حساب معمولاً به قوت خود باقی می‌ماند. .PP با این حال، تغییر نام به گونه‌ای که ساختار درخت حساب را دگرگون کند (برای نمونه تغییر نام حساب‌های والد بدون تغییر نام فرزندانشان، یا برعکس) می‌تواند مانع از به ارث بردن نوع حسابِ والدین توسط حساب‌های فرزند شود. .PP دوم اینکه، اگر نوع یک حساب از نام آن استنتاج می‌شود، تغییر نام آن توسط یک نام مستعار می‌تواند مانع از این کار شده یا آن را تغییر دهد. .PP اگر از نام‌های مستعار حساب استفاده می‌کنید و پرس‌وجوی \f[CR]type:\f[R] حساب‌ها را آن‌طور که انتظار دارید تطبیق نمی‌دهد، عیب‌یابی را با دستور accounts امتحان کنید؛ برای مثال چیزی مانند: .IP .EX $ hledger accounts \-\-types \-1 \-\-alias assets=bassetts .EE .SS دستورالعمل \f[CR]commodity\f[R] دستورالعمل \f[CR]commodity\f[R] چندین عملکرد را انجام می‌دهد: .IP "1." 3 اعلان می‌کند که چه نمادهای کالایی مجاز به استفاده در دفتر روزنامه هستند، و بررسی خطای مفیدی را با حالت سخت‌گیرانه (strict mode) یا دستور check ممکن می‌سازد. بخش «بررسی خطای کالا» را در زیر ببینید. .IP "2." 3 اعلان می‌کند که تمام مقادیر این کالا چگونه باید نمایش داده شوند؛ برای نمونه چه تعداد رقم اعشار نمایش یابد. بخش «سبک نمایش کالا» را در بالا ببینید. .IP "3." 3 (اگر هیچ دستورالعمل \f[CR]decimal\-mark\f[R] فعالی در کار نباشد:) نشانه اعشاری مورد انتظار (نقطه یا کاما) را هنگام تجزیه مقادیر این کالا، در این فایل و فایل‌های شامل‌شده در آن، از مکان این دستورالعمل تا انتهای فایل جاری تعیین می‌کند. بخش «نشانه‌های اعشار» را در بالا ببینید. .IP "4." 3 دقتی را اعلان می‌کند که مقادیر این کالا باید هنگام بررسی تراز بودن تراکنش‌ها با آن مقایسه شوند، در هر کجای این فایل و فایل‌های شامل‌شده در آن، تا انتهای فایل جاری. .PP اعلان کالاها چندین مشکل رایج تجزیه/نمایش را برطرف می‌کند، بنابراین استفاده از آن را توصیه می‌کنیم. .PP توجه داشته باشید که تأثیرات ۳ و ۴ در بالا، در انتهای فایلِ دستورالعمل خاتمه می‌یابند و روی فایل‌های همتا یا والد تأثیری نخواهند گذاشت. بنابراین اگر به آن‌ها متکی هستید (به‌ویژه مورد ۴) و از چندین فایل استفاده می‌کنید، قرار دادن دستورالعمل‌های commodity در یک فایل والد بالاترین سطح ممکن است حائز اهمیت باشد. یا اینکه، نشانه‌های اعشار خود را بدون ابهام نگه دارید و ورودی‌هایتان را دقیق و به‌خوبی تراز کنید. .PP حذف نماد کالا، سبک نمایش را تنها برای کالای بدون‌نماد تعیین می‌کند، نه همه کالاها. .PP سبک‌های کالا را می‌توان با گزینه خط فرمان \f[CR]\-c/\-\-commodity\-style\f[R] بازنویسی کرد. .PP (مرتبط: #793) .SS ساختار دستورالعمل commodity یک دستورالعمل کالا معمولاً کلمه \f[CR]commodity\f[R] است که در ادامه آن یک مقدار نمونه، و به صورت اختیاری یک توضیح می‌آید. تنها نماد مقدار و قالب عدد حائز اهمیت است. برای مثال: .IP .EX commodity $1000.00 commodity 1.000,00 EUR commodity 1 000 000.0000 ; the no\-symbol commodity .EE .PP مقدار نمونه در دستورالعمل کالا همواره باید شامل یک نشانه اعشار نقطه یا کاما باشد (این قاعده به رفع ابهام بین نشانه‌های اعشار و نشانه‌های گروه‌بندی ارقام کمک می‌کند). اگر نمی‌خواهید هیچ رقم اعشاری نشان داده شود، نشانه اعشار را در انتها بنویسید: .IP .EX commodity 1000. AAAA ; show AAAA with no decimals .EE .PP نمادهای کالایی حاوی فاصله، اعداد، یا نشانه‌های نگارشی باید طبق معمول داخل علامت‌های نقل‌قول دوتایی قرار گیرند: .IP .EX commodity 1.0000 \(dqAAAA 2023\(dq .EE .PP دستورالعمل‌های کالا معمولاً شامل یک مقدار نمونه هستند، اما می‌توانند تنها یک نماد را اعلان کنند (یعنی فقط عملکرد ۱ در بالا): .IP .EX commodity $ commodity INR commodity \(dqAAAA 2023\(dq commodity \(dq\(dq ; the no\-symbol commodity .EE .PP دستورالعمل‌های کالا ممکن است با یک زیردستورالعمل دندانه‌دار \f[CR]format\f[R] نیز نوشته شوند، همانند Ledger. نماد تکرار می‌شود و باید در هر دو مکان یکسان باشد. سایر زیردستورالعمل‌ها در حال حاضر نادیده گرفته می‌شوند: .IP .EX ; display indian rupees with currency name on the left, ; thousands, lakhs and crores comma\-separated, ; period as decimal point, and two decimal places. commodity INR format INR 1,00,00,000.00 an unsupported subdirective ; ignored by hledger .EE.SS برچسب‌های کالا (Commodity tags) یادداشت یک دستور commodity می‌تواند حاوی برچسب‌ها باشد. این برچسب‌ها به تمام ثبت‌هایی (postings) که از آن کالا در مقدار اصلی خود استفاده می‌کنند، به‌عنوان برچسب‌های ثبت پنهان اما قابل پرس‌وجو، منتقل می‌شوند؛ مگر در مواردی که ثبت مذکور از قبل برچسبی با همان نام داشته باشد. (برچسب‌های ثبت بر برچسب‌های حساب، و برچسب‌های حساب بر برچسب‌های کالا اولویت دارند.) .SS بررسی خطای کالا (Commodity error checking) در حالت سخت‌گیرانه (\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]) (یا هنگام اجرای \f[CR]hledger check commodities\f[R])، اگر نماد کالای تعریف‌نشده‌ای استفاده شود، hledger خطایی را گزارش خواهد کرد. (با یک استثنا: مقادیر صفر همیشه مجازند که نماد کالا نداشته باشند.) عملکرد آن مشابه بررسی خطای حساب (که در بالا توضیح داده شد) است. .SS دستور \f[CR]decimal\-mark\f[R] می‌توانید از دستور \f[CR]decimal\-mark\f[R] \- معمولاً یکی به ازای هر فایل، در بالای فایل \- استفاده کنید تا مشخص نمایید هنگام تجزیه مقادیر در این فایل، چه نویسه‌ای نشان‌دهنده ممیز اعشاری است. می‌تواند به شکل زیر باشد: .IP .EX decimal\-mark . .EE .PP یا .IP .EX decimal\-mark , .EE .PP این کار از هرگونه ابهام هنگام تجزیه اعداد در فایل جلوگیری می‌کند، بنابراین استفاده از آن توصیه می‌شود؛ به‌ویژه اگر فایل حاوی نشانه‌های گروه‌بندی ارقام (مانند جداکننده‌های هزارگان) باشد. .SS دستور \f[CR]include\f[R] می‌توانید با نوشتن یک دستور include، محتوای فایل‌های دیگر را به پرونده اضافه کنید، مانند زیر: .IP .EX include SOMEFILE .EE .PP این کار همان اثری را دارد که گویی محتوای SOMEFILE در همین نقطه درج شده است. (همچنین هر دستور include درون SOMEFILE نیز به همین ترتیب و به‌صورت بازگشتی پردازش می‌شود.) .PP فقط فایل‌های journal می‌توانند فایل‌های دیگر را ضمیمه (include) کنند. آن‌ها می‌توانند فایل‌های journal، timeclock یا timedot را دربرگیرند، اما فایل‌های CSV مجاز نیستند. .PP اگر مسیر فایل با علامت مدک (tilde) شروع شود، به معنی دایرکتوری خانگی شماست: \f[CR]include \(ti/main.journal\f[R]. .PP اگر با یک اسلش شروع شود، یک مسیر مطلق است: \f[CR]include /home/user/main.journal\f[R]. در غیر این صورت، مسیر نسبت به پوشه فایلی که آن را ضمیمه کرده، سنجیده می‌شود: \f[CR]include ../finances/main.journal\f[R]. .PP همچنین، مسیر ممکن است دارای یک پیشوند نوع فایل باشد تا قالب فایلی مشخصی را تحمیل کرده و پسوند(های) فایل را نادیده بگیرد (همان‌طور که در Data formats شرح داده شده است): \f[CR]include timedot:notes/2023.md\f[R]. .PP مسیر ممکن است شامل الگوهای glob برای تطبیق با چندین فایل باشد. الگوهای glob در hledger شبیه به zsh هستند: \f[CR]?\f[R] برای تطبیق با هر نویسه؛ \f[CR][a\-z]\f[R] برای تطبیق با هر نویسه در یک محدوده؛ \f[CR]*\f[R] برای تطبیق با صفر یا چند نویسه که جداکننده مسیر نیستند (مانند \f[CR]/\f[R])؛ \f[CR]**\f[R] برای تطبیق با صفر یا چند زیردایرکتوری و/یا صفر یا چند نویسه در ابتدای نام فایل؛ و غیره. برای سهولت کار، \f[CR]include\f[R] همواره فایل فعلی را مستثنی می‌کند. بنابراین، می‌توانید از چنین مواردی استفاده کنید: .IP \(bu 2 \f[CR]include *.journal\f[R] برای ضمیمه‌کردن تمام فایل‌های journal دیگر در دایرکتوری فعلی (به‌استثنای فایل‌های نقطه‌دار) .IP \(bu 2 \f[CR]include **.journal\f[R] برای ضمیمه‌کردن تمام فایل‌های journal دیگر در این دایرکتوری و زیرشاخه‌های آن (به‌استثنای فایل‌های نقطه‌دار و دایرکتوری‌های نقطه‌دار سطح اول) .IP \(bu 2 \f[CR]include timelogs/2???.timedot\f[R] برای ضمیمه‌کردن تمام فایل‌های timedot که نامی شبیه به شماره سال دارند. .PP توجه داشته باشید که \f[CR]*\f[R] و \f[CR]**\f[R] معمولاً با فایل‌ها یا دایرکتوری‌های نقطه‌دار تطبیق داده نمی‌شوند، با یک استثنا: \f[CR]**\f[R] دایرکتوری‌های نقطه‌داری که در سطح اول نیستند را جستجو می‌کند. اگر این مسئله مشکلی ایجاد می‌کند، الگوی glob خود را دقیق‌تر تعیین کنید (مثلاً \f[CR]**.journal\f[R] به‌جای \f[CR]**\f[R]). .PP اگر از فایل‌های ضمیمه‌شده فراوان، یا با تو‌در‌تویی عمیق استفاده می‌کنید و به خطایی برخورد کرده‌اید که یافتن دقیق آن دشوار است، یک دستور عیب‌یابی خوب \f[CR]hledger files \-\-debug=6\f[R] (یا 7) است..SS دستورالعمل \f[CR]P\f[R] دستورالعمل \f[CR]P\f[R] یک قیمت بازار را اعلان می‌کند، که در واقع نرخ تبدیل بین دو کالا در یک تاریخ مشخص است. این قابلیت به گزارش‌های ارزش اجازه می‌دهد مقادیر یک کالا را به ارزش آن در کالایی دیگر، در آن تاریخ یا پس از آن تبدیل کنند. این قیمت‌ها معمولاً از بورس اوراق بهادار، صرافی رمزارز، یا بازار تبادل ارزهای خارجی (فارکس) به دست می‌آیند. .PP قالب آن بدین صورت است: .IP .EX P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT .EE .PP DATE یک تاریخ ساده است، COMMODITY1SYMBOL نماد کالایی است که قیمت‌گذاری می‌شود، و COMMODITY2AMOUNT مقدار (نماد و کمیت) کالای ۲ است که یک واحد از کالای ۱ در این تاریخ ارزش دارد. مثال‌ها: .IP .EX # one euro was worth $1.35 from 2009\-01\-01 onward: P 2009\-01\-01 € $1.35 # and $1.40 from 2010\-01\-01 onward: P 2010\-01\-01 € $1.40 .EE .PP پرچم‌های \f[CR]\-V\f[R]، \f[CR]\-X\f[R] و \f[CR]\-\-value\f[R] از این قیمت‌های بازار برای نمایش مقادیر بر حسب کالایی دیگر استفاده می‌کنند. بخش گزارش‌دهی ارزش (Value reporting) را ببینید. .PP .SS دستورالعمل \f[CR]payee\f[R] \f[CR]payee PAYEE NAME\f[R] .PP از این دستورالعمل می‌توان برای اعلان مجموعه‌ای محدود از دریافت‌کنندگان وجه که ممکن است در توضیحات تراکنش ظاهر شوند استفاده کرد. در صورتی که هر تراکنشی به دریافت‌کننده‌ای اشاره کند که اعلان نشده باشد، بررسی \(dqpayees\(dq خطا گزارش خواهد کرد. برای مثال: .IP .EX payee Whole Foods ; a comment .EE .PP دریافت‌کنندگان وجه برچسب (tag) ندارند (برچسب‌ها در یادداشت نادیده گرفته می‌شوند). .PP برای اعلان نام دریافت‌کننده خالی، از \f[CR]\(dq\(dq\f[R] استفاده کنید. .IP .EX payee \(dq\(dq .EE .PP زیردستورالعمل‌های دارای تورفتگی به سبک Ledger، در صورت وجود، در حال حاضر نادیده گرفته می‌شوند. .SS دستورالعمل \f[CR]tag\f[R] \f[CR]tag TAGNAME\f[R] .PP از این دستورالعمل می‌توان برای اعلان مجموعه‌ای محدود از نام‌های مجاز در برچسب‌ها استفاده کرد. TAGNAME باید یک نام برچسب معتبر باشد (بدون فاصله). برای مثال: .IP .EX tag item\-id .EE .PP هرگونه زیردستورالعمل دارای تورفتگی در حال حاضر نادیده گرفته می‌شود. .PP در صورتی که از هر نام برچسبِ اعلان‌نشده‌ای استفاده شود، بررسی \(dqtags\(dq خطا گزارش خواهد کرد. ایجاد تصادفی یک برچسب با استفاده معمول از دونقطه در یادداشت‌ها بسیار آسان است؛ اگر می‌خواهید از این کار جلوگیری کنید، می‌توانید برچسب‌های خود را اعلان و بررسی نمایید. .SS تراکنش‌های دوره‌ای (Periodic transactions) دستورالعمل \f[CR]\(ti\f[R] یک «قاعده دوره‌ای» (\(dqperiodic rule\(dq) را اعلان می‌کند که هنگام اجرای hledger با پرچم \f[CR]\-\-forecast\f[R]، تراکنش‌های اضافی موقتی ایجاد می‌کند که معمولاً در بازه‌های زمانی مشخص تکرار می‌شوند. این «تراکنش‌های پیش‌بینی» (\(dqforecast transactions\(dq) برای پیش‌بینی فعالیت‌های آینده مفید هستند. آن‌ها تنها در طول مدت تولید گزارش و تنها زمانی که \f[CR]\-\-forecast\f[R] استفاده شده باشد وجود دارند؛ آن‌ها توسط hledger در فایل دفتر روزنامه ذخیره نمی‌شوند. .PP قواعد دوره‌ای کاربرد دومی نیز دارند: با پرچم \f[CR]\-\-budget\f[R]، آن‌ها اهداف بودجه را برای بودجه‌بندی تعیین می‌کنند. .PP قواعد دوره‌ای می‌توانند کمی قلق‌دار باشند، بنابراین پیش از استفاده از آن‌ها، تمام این بخش یا دست‌کم نکات زیر را مطالعه کنید: .IP "1." 3 افزودن یا حذف تصادفی دو فاصله برایتان دردسر ایجاد خواهد کرد \- در این باره در ادامه بخوانید. .IP "2." 3 برای عیب‌یابی، تراکنش‌های تولیدشده را با \f[CR]hledger print \-\-forecast tag:generated\f[R] یا \f[CR]hledger register \-\-forecast tag:generated\f[R] نمایش دهید. .IP "3." 3 تراکنش‌های پیش‌بینی‌شده تنها پس از تاریخ آخرین تراکنش غیرپیش‌بینی‌شده آغاز خواهند شد. .IP "4." 3 تراکنش‌های پیش‌بینی‌شده به‌طور پیش‌فرض ۶ ماه پس از امروز پایان می‌یابند. برای قواعد دقیق شروع/پایان به ادامه مراجعه کنید. .IP "5." 3 عبارت‌های دوره زمانی (period expressions) می‌توانند قلق‌دار باشند. مستندات آن‌ها نیازمند بهبود است، اما ارزش مطالعه را دارد. .IP "6." 3 برخی از عبارت‌های دوره زمانی با بازه تکرارشونده باید در مرز طبیعی آن بازه آغاز شوند. برای مثال در \f[CR]weekly from DATE\f[R]، مقدار DATE باید یک دوشنبه باشد. عبارت \f[CR]\(ti weekly from 2019/10/1\f[R] (که یک سه‌شنبه است) خطا خواهد داد. .IP "7." 3 سایر عبارت‌های دوره زمانی با یک بازه به‌طور خودکار گسترش می‌یابند تا تعداد کاملی از آن بازه را پوشش دهند. (این کار برای بهبود گزارش‌ها انجام می‌شود، اما بر تراکنش‌های دوره‌ای نیز تأثیر می‌گذارد. بله، کمی با مورد بالا ناهماهنگ است.) برای مثال: \f[CR]\(ti every 10th day of month from 2023/01\f[R] که معادل \f[CR]\(ti every 10th day of month from 2023/01/01\f[R] است، به‌گونه‌ای تنظیم خواهد شد که از 2019/12/10 آغاز شود..SS ساختار قواعد دوره‌ای یک قاعده تراکنش دوره‌ای شبیه به یک مدخل عادی دفتر روزنامه است، که در آن تاریخ با یک مدک (\f[CR]\(ti\f[R]) جایگزین شده و پس از آن یک عبارت دوره‌ای می‌آید (یادآور: \f[CR]\(ti\f[R] شبیه یک موج سینوسی تکرارشونده است.): .IP .EX # every first of month \(ti monthly expenses:rent $2000 assets:bank:checking # every 15th of month in 2023\(aqs first quarter: \(ti monthly from 2023\-04\-15 to 2023\-06\-16 expenses:utilities $400 assets:bank:checking .EE .PP عبارت دوره دارای همان نحوی است که برای مشخص کردن گزارش‌های چنددوره‌ای استفاده می‌شود، فقط تفسیر متفاوتی دارد؛ در آنجا دوره‌های گزارش را تعیین می‌کند؛ در اینجا تاریخ‌های تکرار (تاریخ‌های شروع دوره‌ها) را مشخص می‌سازد. .SS قواعد دوره‌ای و تاریخ‌های نسبی تاریخ‌های ناقص یا نسبی (مانند \f[CR]12/31\f[R]، \f[CR]25\f[R]، \f[CR]tomorrow\f[R]، \f[CR]last week\f[R]، \f[CR]next quarter\f[R]) معمولاً در قواعد دوره‌ای توصیه نمی‌شوند، زیرا با گذشت زمان نتایج تغییر خواهند کرد. در صورت استفاده، بر اساس اولویت نسبت به موارد زیر تفسیر می‌شوند: .IP "1." 3 روز اول سال پیش‌فرض مشخص‌شده توسط یک دستور \f[CR]Y\f[R] اخیر .IP "2." 3 یا تاریخ مشخص‌شده با \f[CR]\-\-today\f[R] .IP "3." 3 یا تاریخی که در آن گزارش را اجرا می‌کنید. .PP آن‌ها به هیچ وجه تحت تأثیر تاریخ‌های دوره گزارش یا دوره پیش‌بینی قرار نخواهند گرفت. .SS دو فاصله میان عبارت دوره و شرح تراکنش! اگر به دنبال عبارت دوره یک شرح تراکنش بیاید، این دو باید با \f[B]دو یا چند فاصله\f[R] از هم جدا شوند. این کار به hledger کمک می‌کند تا پایان عبارت دوره را تشخیص دهد، به طوری که شرح‌ها نتوانند تصادفاً معنای آن را تغییر دهند، مانند این مثال: .IP .EX ; 2 or more spaces needed here, so the period is not understood as \(dqevery 2 months in 2023\(dq ; || ; vv \(ti every 2 months in 2023, we will review assets:bank:checking $1500 income:acme inc .EE .PP بنابراین، .IP \(bu 2 حتماً بین عبارت دوره و شرح تراکنش خود (در صورت وجود) دو فاصله قرار دهید. .IP \(bu 2 در میان عبارت دوره، به طور تصادفی دو فاصله نگذارید. .SS ثبت‌های خودکار (Auto postings) دستور \f[CR]=\f[R] یک «قاعده ثبت خودکار» (\(dqauto posting rule\(dq) را اعلان می‌کند که ثبت‌های اضافی به تراکنش‌های موجود می‌افزاید. (به یاد داشته باشید، ثبت‌ها (postings) خطوط نام حساب و مبلغ در زیر تاریخ و شرح یک تراکنش هستند.) .PP در دفتر روزنامه، یک قاعده ثبت خودکار کاملاً شبیه یک تراکنش است، اما به جای تاریخ و شرح، دارای \f[CR]=\f[R] (یادآور: تطابق یا \(dqmatch\(dq) و یک پرس‌وجو (query) است، مانند این: .IP .EX = QUERY ACCOUNT AMOUNT ... .EE .PP پرس‌وجوها دقیقاً مانند پرس‌وجوهای خط فرمان هستند؛ زیررشته نام حساب رایج‌ترین آن‌هاست. عبارت‌های پرس‌وجو که دارای فاصله هستند باید داخل گیومه تکی یا دوتایی قرار گیرند. .PP هر قاعده \f[CR]=\f[R] به این صورت کار می‌کند: هنگامی که hledger با پرچم \f[CR]\-\-auto\f[R] اجرا می‌شود، هر جا که QUERY با ثبتی در دفتر روزنامه مطابقت داشته باشد، ثبت‌های آن قاعده دقیقاً زیر ثبت منطبق‌شده به آن تراکنش اضافه می‌شوند. توجه داشته باشید که این ثبت‌های تولیدشده موقتی هستند، و تنها در طول مدت گزارش و فقط زمانی که \f[CR]\-\-auto\f[R] استفاده می‌شود وجود دارند؛ آن‌ها توسط hledger در فایل دفتر روزنامه ذخیره نمی‌شوند. .PP ثبت‌ها می‌توانند حاوی رشته ویژه \f[CR]%account\f[R] باشند که به نام حسابی که تطبیق یافته است بسط داده می‌شود. .PP مبالغ ثبت‌های تولیدشده می‌تواند به مبلغ ثبت منطبق‌شده وابسته باشد. بنابراین ثبت‌های خودکار می‌توانند مثلاً برای افزودن ثبت‌های مالیاتی با درصدی استاندارد مفید باشند. AMOUNT می‌تواند به شکل‌های زیر باشد: .IP \(bu 2 یک عدد بدون نماد ارز/کالا، مانند \f[CR]2\f[R]. نماد کالای ثبت منطبق‌شده به این اضافه خواهد شد. .IP \(bu 2 یک مبلغ معمولی با نماد ارز/کالا، مانند \f[CR]$2\f[R]. این مقدار بدون تغییر استفاده خواهد شد. .IP \(bu 2 یک ستاره به همراه یک عدد، مانند \f[CR]*2\f[R]. این کار مبلغ ثبت منطبق‌شده (و قیمت کل، در صورت وجود) را در آن عدد ضرب می‌کند. .IP \(bu 2 یک ستاره به همراه مبلغی دارای نماد ارز/کالا، مانند \f[CR]*$2\f[R]. این کار مقدار را ضرب کرده و همچنین نماد ارز/کالا را با نماد جدید جایگزین می‌کند. .PP چند مثال: .IP .EX ; every time I buy food, schedule a dollar donation = expenses:food (liabilities:charity) $\-1 ; when I buy a gift, also deduct that amount from a budget envelope subaccount = expenses:gifts assets:checking:gifts *\-1 assets:checking *1 2017/12/1 expenses:food $10 assets:checking 2017/12/14 expenses:gifts $20 assets:checking .EE .IP .EX $ hledger print \-\-auto 2017\-12\-01 expenses:food $10 assets:checking (liabilities:charity) $\-1 2017\-12\-14 expenses:gifts $20 assets:checking assets:checking:gifts \-$20 assets:checking $20 .EE .PP توجه داشته باشید که اتکای کامل به داده‌های تولیدشده‌ای مانند این معایبی دارد \- قابلیت حمل کمتر، پایداری کمتر در آینده، دشواری بیشتر در حسابرسی توسط دیگران، و استحکام کمتر (به عنوان مثال، balance assertions شما به این وابسته خواهد بود که از \f[CR]\-\-auto\f[R] استفاده کنید یا خیر). یک راهکار جایگزین استفاده از ثبت‌های خودکار به صورت «یک‌باره» است \- استفاده از آن‌ها برای کمک به ساخت یک مدخل پیچیده در دفتر روزنامه، مشاهده آن با \f[CR]hledger print \-\-auto\f[R]، و سپس کپی کردن آن خروجی در فایل دفتر روزنامه برای دائمی کردن آن..SS ثبت‌های خودکار و چندین فایل یک قاعدهٔ ثبت خودکار می‌تواند بر هر تراکنشی در فایل جاری، یا در هر فایل والد یا فایل فرزند تأثیر بگذارد. توجه داشته باشید که در حال حاضر این قواعد بر فایل‌های هم‌سطح تأثیری نخواهند داشت (زمانی که از چند \f[CR]\-f\f[R]/\f[CR]\-\-file\f[R] استفاده شده باشد \- به #1212 مراجعه کنید). .SS ثبت‌های خودکار و تاریخ‌ها تاریخ ثبت (یا تاریخ ثانویه) در ثبت منطبق‌شده، یا (با اولویت بالاتر) تاریخ ثبت در خودِ قاعدهٔ ثبت خودکار، در ثبت ایجادشده نیز استفاده خواهد شد. .SS ثبت‌های خودکار و تراز تراکنش / مبالغ استنتاج‌شده / ادعاهای موجودی در حال حاضر، ثبت‌های خودکار اضافه می‌شوند: .IP \(bu 2 پس از این‌که مبالغ درج‌نشده استنتاج شدند، و تراکنش‌ها از نظر تراز بودن بررسی گردیدند، .IP \(bu 2 اما پیش از این‌که ادعاهای موجودی بررسی شوند. .PP توجه داشته باشید که این بدان معناست که مدخل‌های دفتر روزنامه باید هم پیش از اضافه شدن ثبت‌های خودکار و هم پس از آن تراز باشند. این سازوکار در hledger نسخهٔ 1.12+ تغییر کرد؛ برای پیش‌زمینه به #893 مراجعه کنید. .PP این همچنین بدین معنی است که نمی‌توانید بیش از یک ثبت خودکار با مبلغ درج‌نشده را برای یک تراکنش معین اعمال کنید، زیرا در استنتاج مبالغ ناتوان خواهد بود. .SS برچسب‌های ثبت خودکار ثبت‌های خودکار دارای چند برچسب اضافی خواهند بود: .IP \(bu 2 \f[CR]generated\-posting:= QUERY\f[R] \- نشان می‌دهد که این مورد توسط یک قاعدهٔ ثبت خودکار ایجاد شده است، و عبارت جستجو (query) را نمایش می‌دهد .IP \(bu 2 \f[CR]_generated\-posting:= QUERY\f[R] \- یک برچسب پنهان که در خروجی hledger نمایش داده نمی‌شود. این برچسب می‌تواند برای تطبیق ثبت‌هایی به کار رود که \(dqهمین حالا\(dq ایجاد شده‌اند، نه ثبت‌هایی که در گذشته ایجاد و در دفتر روزنامه ذخیره شده‌اند. .PP همچنین، به هر تراکنشی که توسط قواعد ثبت خودکار تغییر یافته باشد، این برچسب‌ها اضافه خواهند شد: .IP \(bu 2 \f[CR]modified:\f[R] \- این تراکنش تغییر یافته است .IP \(bu 2 \f[CR]_modified:\f[R] \- یک برچسب پنهان که در یادداشت‌ها ظاهر نمی‌شود؛ این تراکنش \(dqهمین حالا\(dq تغییر یافته است. .SS ثبت‌های خودکار تنها روی تراکنش‌های پیش‌بینی نکته: می‌توانید با افزودن \f[CR]tag:_generated\-transaction\f[R] به QUERY آن‌ها، ثبت‌های خودکاری ایجاد کنید که تنها بر تراکنش‌های پیش‌بینی اعمال شوند و نه تراکنش‌های ثبت‌شده. این ویژگی هنگام تولید مدخل‌های جدید دفتر روزنامه برای ذخیره شدن در دفتر روزنامه می‌تواند مفید باشد. .SS ساختارهای نحوی دیگر قالب دفتر روزنامهٔ hledger از چندین قابلیت دیگر پشتیبانی می‌کند، که عمدتاً برای آسان‌تر ساختن تعامل‌پذیری با Ledger یا تبدیل از آن هستند. توجه داشته باشید که برخی از قابلیت‌های زیر قدرتمند هستند و می‌توانند در موارد خاص سودمند باشند، اما به‌طور کلی، ویژگی‌های این بخش کم‌اهمیت‌تر تلقی می‌شوند یا حتی استفاده از آن‌ها به بیشتر کاربران توصیه نمی‌شود. معایب آن‌ها ذکر شده است تا به شما در تصمیم‌گیری برای استفاده از آن‌ها کمک کند. .SS تخصیص‌های موجودی تخصیص‌های موجودی به سبک Ledger نیز پشتیبانی می‌شوند. این‌ها شبیه به ادعاهای موجودی هستند، اما در سمت چپ علامت مساوی هیچ مبلغ ثبتی وجود ندارد؛ در عوض این مبلغ به‌طور خودکار محاسبه می‌شود تا شرط ادعا برآورده شود. این ویژگی می‌تواند هنگام ورود داده‌ها، مثلاً هنگام تنظیم موجودی‌های اولیه، کار را راحت‌تر کند: .IP .EX ; starting a new journal, set asset account balances 2016/1/1 opening balances assets:checking = $409.32 assets:savings = $735.24 assets:cash = $42 equity:opening balances .EE .PP یا هنگام تطبیق موجودی با واقعیت: .IP .EX ; no cash left; update balance, record any untracked spending as a generic expense 2016/1/15 assets:cash = $0 expenses:misc .EE .PP مبلغ محاسبه‌شده به موجودی حساب در آن کالا (commodity) در آن نقطه بستگی دارد (که خود به ثبت‌های دارای تاریخ قبلیِ آن کالا در آن حساب از زمان آخرین ادعا یا تخصیص موجودی وابسته است). .PP معایب: استفاده از تخصیص‌های موجودی باعث می‌شود دفتر روزنامهٔ شما از صراحت کمتری برخوردار باشد؛ برای آگاهی از مبلغ دقیق ثبت‌شده، به جای خواندن مستقیم آن، باید hledger را اجرا کنید یا خودتان محاسبات را انجام دهید. همچنین، تحمیل موجودی‌ها توسط تخصیص موجودی می‌تواند خطاها را پنهان کند. این موارد سبب می‌شوند داده‌های مالی شما کمتر قابل‌حمل، کمتر مقاوم در برابر تغییرات آتی، و در حسابرسی کمتر قابل‌اعتماد باشند..SS انتساب‌های تراز و هزینه‌ها یک هزینه (cost) در انتساب تراز باعث می‌شود که مقدار محاسبه‌شده، آن هزینه را به همراه داشته باشد: .IP .EX 2019/1/1 (a) = $1 \(at €2 .EE .IP .EX $ hledger print \-\-explicit 2019\-01\-01 (a) $1 \(at €2 = $1 \(at €2 .EE .SS انتساب‌های تراز و چندین فایل انتساب‌های تراز مانند تصدیق‌های تراز (balance assertions) با چندین فایل برخورد می‌کنند. آن‌ها موجودی را از فایل‌های دیگری که پیش‌تر از فایل جاری وارد (\f[CR]include\f[R]) شده‌اند مشاهده می‌کنند، اما از فایل‌های هم‌سطح یا والد قبلی خیر. .SS تاریخ‌های ثبت درون قلاب برای تنظیم تاریخ‌های ثبت و تاریخ‌های ثبت ثانویه، نحوِ تاریخ درون قلاب در Ledger نیز پشتیبانی می‌شود: \f[CR][DATE]\f[R]، \f[CR][DATE=DATE2]\f[R] یا \f[CR][=DATE2]\f[R] در یادداشت‌های ثبت (posting comments). دستور hledger تلاش خواهد کرد هر دنباله‌ای درون قلاب از نویسه‌های \f[CR]0123456789/\-.=\f[R] را به این روش تجزیه کند. با این نحو، DATE سال خود را از تراکنش استنتاج می‌کند و DATE2 سال خود را از DATE برمی‌دارد. .PP معایب: نحوی مضاعف برای یادگیری، افزونگی با برچسب‌های \f[CR]date:\f[R]/\f[CR]date2:\f[R] در hledger، و شباهت گیج‌کننده به نحو تاریخ دسته (lot date) در Ledger. .SS دستورالعمل \f[CR]D\f[R] \f[CR]D AMOUNT\f[R] .PP این دستورالعمل، یک کالای پیش‌فرض را تعیین می‌کند تا برای هر مقدار فاقد کالای پس از آن (یعنی اعداد ساده) که هنگام تجزیه دفتر روزنامه مشاهده می‌شود، به کار رود. این اثر تا دستورالعمل بعدی \f[CR]D\f[R] یا پایان فایل جاری ادامه دارد. .PP به دلایل تاریخی یا سازگاری، \f[CR]D\f[R] همچنین مانند یک دستورالعمل \f[CR]commodity\f[R] عمل می‌کند (تنظیم نشانه‌گذار اعشاری کالا برای تجزیه، و سبک نمایش برای خروجی). بنابراین آرگومان آن تنها یک نماد کالا نیست، بلکه مقداری کامل است که سبک نمایش را نشان می‌دهد. مقدار حتماً باید شامل یک نشانه‌گذار اعشاری (نقطه یا ویرگول) باشد. به عنوان مثال: .IP .EX ; commodity\-less amounts should be treated as dollars ; (and displayed with the dollar sign on the left, thousands separators and two decimal places) D $1,000.00 1/1 a 5 ; <\- commodity\-less amount, parsed as $5 and displayed as $5.00 b .EE .PP برهم‌کنش با سایر دستورالعمل‌ها: .PP برای تنظیم سبک نمایش کالا، دستورالعمل \f[CR]commodity\f[R] بالاترین اولویت را دارد و پس از آن دستورالعمل \f[CR]D\f[R] قرار می‌گیرد. .PP برای تشخیص نشانه‌گذار اعشاری کالا هنگام تجزیه، \f[CR]decimal\-mark\f[R] بالاترین اولویت را دارد، سپس \f[CR]commodity\f[R]، و در نهایت \f[CR]D\f[R]. .PP برای بررسی نمادهای کالا با دستور check، وجود یک دستورالعمل \f[CR]commodity\f[R] الزامی است (\f[CR]hledger check commodities\f[R] دستورالعمل‌های \f[CR]D\f[R] را نادیده می‌گیرد). .PP معایب: حذف نمادهای کالا داده‌های مالی شما را کمتر صریح، کمتر قابل حمل و در حسابرسی کمتر قابل اعتماد می‌کند. این کار معمولاً یک میان‌بُر ناپایدار است؛ دیر یا زود تمایل خواهید داشت چندین کالا را ردیابی کنید. دستور D با قابلیت‌هایی که نسبت به \f[CR]commodity\f[R] و \f[CR]decimal\-mark\f[R] مازاد هستند، سربارگذاری شده است. همچنین سازوکار آن با \f[CR]D\f[R] در Ledger متفاوت است. .SS دستورالعمل \f[CR]apply account\f[R] این دستورالعمل، یک حساب والد پیش‌فرض تعیین می‌کند که تا زمان رسیدن به دستورالعمل \f[CR]end apply account\f[R] یا پایان فایل جاری، به ابتدای تمام حساب‌ها در ورودی‌های پس از آن اضافه خواهد شد. به عنوان مثال: .IP .EX apply account home 2010/1/1 food $10 cash end apply account .EE .PP معادل است با: .IP .EX 2010/01/01 home:food $10 home:cash $\-10 .EE .PP دستورالعمل‌های \f[CR]account\f[R] و همچنین هر محتوای واردشده (\f[CR]include\f[R]) نیز تحت تأثیر قرار می‌گیرند. .PP نام‌های حسابی که از طریق hledger add یا hledger\-web وارد شوند تحت تأثیر قرار نمی‌گیرند. .PP نام‌های مستعار حساب (در صورت وجود)، پس از اضافه شدن حساب والد به ابتدای نام اعمال می‌شوند. .PP معایب: این کار می‌تواند داده‌های مالی شما را در حسابرسی کمتر صریح، کمتر قابل حمل و کمتر قابل اعتماد سازد..SS رهنمود \f[CR]Y\f[R] \f[CR]Y YEAR\f[R] .PP یا (شکل‌های منسوخ‌شده برای سازگاری رو به عقب): .PP \f[CR]year YEAR\f[R] \f[CR]apply year YEAR\f[R] .PP فاصله اختیاری است. این دستور یک سال پیش‌فرض را تعیین می‌کند تا برای تاریخ‌های پس از آن که سالی را مشخص نکرده‌اند استفاده شود. برای مثال: .IP .EX Y2009 ; set default year to 2009 12/15 ; equivalent to 2009/12/15 expenses 1 assets year 2010 ; change default year to 2010 2009/1/30 ; specifies the year, not affected expenses 1 assets 1/31 ; equivalent to 2010/1/31 expenses 1 assets .EE .PP معایب: حذف سال (دست‌کم از تاریخ‌های اصلی تراکنش‌ها) باعث می‌شود داده‌های مالی شما کمتر صریح، با قابلیت حمل کمتر و در حسابرسی کمتر قابل اعتماد باشند. چنین تاریخ‌هایی ممکن است از رهنمود Y متناظر خود جدا شوند؛ برای مثال هنگام ارزیابی بخشی از دفتر روزنامه در ویرایشگر متن. نبود رهنمود Y باعث می‌شود گزارش‌ها وابسته به تاریخ امروز شوند. .SS تاریخ‌های ثانویه تاریخ ثانویه پس از تاریخ اصلی و به دنبال علامت مساوی نوشته می‌شود: \f[CR]DATE1=DATE2\f[R]. اگر سال حذف شود، سالِ تاریخ اصلی در نظر گرفته می‌شود. هنگام اجرای گزارش‌ها، تاریخ اصلی (سمت چپ) به‌طور پیش‌فرض استفاده می‌شود، اما با پرچم \f[CR]\-\-date2\f[R] (گزینه‌های \f[CR]\-\-aux\-date\f[R] یا \f[CR]\-\-effective\f[R] نیز برای کاربران Ledger کار می‌کنند)، تاریخ ثانویه (سمت راست) به جای آن به کار خواهد رفت. .PP معنای تاریخ‌های ثانویه به شما بستگی دارد. برای مثال می‌تواند به این صورت باشد: \(dqتاریخ اصلی، تاریخ تسویه بانک است و تاریخ ثانویه، در صورت تفاوت، تاریخ آغاز تراکنش است\(dq. .PP در عمل، این قابلیت معمولاً موجب سردرگمی می‌شود: .IP \(bu 2 باید معنای تاریخ‌های اصلی و ثانویه را به یاد داشته باشید و همواره آن را رعایت کنید. .IP \(bu 2 دفترداری شما را به دو حالت تقسیم می‌کند و باید به خاطر بسپارید که کدام حالت برای یک گزارش مشخص مناسب است. .IP \(bu 2 معمولاً اعتبارسنجی‌های تراز (balance assertions) تنها با یکی از این حالت‌ها کار خواهند کرد. .IP \(bu 2 داده‌های مالی شما را پیچیده‌تر، با قابلیت حمل کمتر و در یک حسابرسی با وضوح کمتر همراه می‌سازد. .IP \(bu 2 با تمامی امکانات دیگر تداخل پیدا می‌کند و هزینه‌ای پیوسته برای توسعه‌دهندگان پدید می‌آورد. .IP \(bu 2 موجب حواس‌پرتی کاربران تازه‌کار و حامیان پروژه می‌شود. .IP \(bu 2 تاریخ‌های ثبت (posting dates) ساده‌تر هستند و کارایی بهتری دارند. .PP بنابراین تاریخ‌های ثانویه رسماً در hledger منسوخ شده‌اند و تنها برای سازگاری با Ledger باقی مانده‌اند؛ توصیه می‌کنیم به جای آن‌ها از posting dates استفاده کنید. .SS یادداشت‌های ستاره‌دار خطوطی که با \f[CR]*\f[R] (ستاره) آغاز می‌شوند نیز خطوط یادداشت (کامنت) هستند. این قابلیت به کاربران Emacs اجازه می‌دهد سرتیترهای org را در دفتر روزنامه خود درج کنند تا بتوانند هنگام مشاهده در org mode، آن را مانند یک ساختار سلسله‌مراتبی جمع، باز و پیمایش کنند. .PP معایب: یک نحو نامتعارف دیگر برای نوشتن کامنت که باید آموخته شود. قابلیت حمل دفتر روزنامه شما را کاهش می‌دهد. همچنین جابه‌جایی به حالت Emacs org صرفاً برای جمع/باز کردن، به معنای از دست دادن مزایای ledger mode بود؛ امروزه می‌توانید حالت outshine را به ledger mode بیفزایید تا بدون از دست دادن امکانات ledger mode از جمع‌وباز کردن متن نیز بهره‌مند شوید..SS "عبارت‌های ارزش‌گذاری (Valuation expressions)" نرم‌افزار Ledger اجازه می‌دهد یک تابع ارزش‌گذاری یا مقدار در پرانتزهای مضاعف پس از یک مبلغ نوشته شود. hledger این موارد را نادیده می‌گیرد. .SS "ثبت‌های مجازی (Virtual postings)" ثبتی که پرانتزهایی در اطراف نام حساب دارد، مانند \f[CR](some:account) 10\f[R]، یک \f[I]ثبت مجازی نامتوازن\f[R] نامیده می‌شود. این ثبت‌ها در تراز کردن تراکنش شرکت نمی‌کنند. (و اگر آن‌ها را بدون مبلغ بنویسید، همواره مقدار صفر استنباط می‌شود.) این موارد گاهی اوقات می‌توانند برای شرایط خاص مناسب باشند، اما دفترداری دوطرفه را نقض می‌کنند و قابلیت انتقال داده‌های شما را میان برنامه‌های مختلف کاهش می‌دهند، بنابراین بسیاری از افراد اصلاً از آن‌ها استفاده نمی‌کنند. .PP ثبتی که دارای قلاب (کروشه) در اطراف نام حساب باشد (\f[CR][some:account]\f[R])، یک \f[I]ثبت مجازی متوازن\f[R] نامیده می‌شود. مجموع ثبت‌های مجازی متوازن در یک تراکنش، درست مانند ثبت‌های عادی اما به‌صورت جداگانه از آن‌ها، باید به صفر برسد. این موارد نیز بخشی از دفترداری دوطرفه نیستند، اما دست‌کم متوازن هستند. یک مثال: .IP .EX 2022\-01\-01 buy food with cash, update budget envelope subaccounts, & something else assets:cash $\-10 ; <\- these balance each other expenses:food $7 ; <\- expenses:food $3 ; <\- [assets:checking:budget:food] $\-10 ; <\- and these balance each other [assets:checking:available] $10 ; <\- (something:else) $5 ; <\- this is not required to balance .EE .PP ثبت‌های عادی، که نام حساب آن‌ها نه درون پرانتز است و نه درون قلاب، \f[I]ثبت‌های واقعی\f[R] نامیده می‌شوند. می‌توانید با استفاده از پرچم \f[CR]\-R/\-\-real\f[R] یا پرس‌وجوی \f[CR]real:1\f[R]، ثبت‌های مجازی را از گزارش‌ها مستثنی کنید. .SS "سایر دستورالعمل‌های Ledger (Other Ledger directives)" سایر دستورالعمل‌های Ledger زیر در حال حاضر پذیرفته می‌شوند اما نادیده گرفته می‌شوند. این ویژگی به hledger امکان می‌دهد فایل‌های بیشتری از Ledger را بخواند، اما توجه داشته باشید که در صورت استفاده از این موارد، ممکن است گزارش‌های hledger با گزارش‌های Ledger تفاوت داشته باشند. .IP .EX apply fixed COMM AMT apply tag TAG assert EXPR bucket / A ACCT capture ACCT REGEX check EXPR define VAR=EXPR end apply fixed end apply tag end apply year end tag eval / expr EXPR python PYTHONCODE tag NAME value EXPR \-\-command\-line\-flags .EE .PP همچنین برای مقایسه تفصیلی نحو hledger و Ledger به مراجعه کنید. .SS "هزینه‌های مجازی Ledger (Ledger virtual costs)" در Ledger، عبارت‌های \f[CR](\(at) UNITCOST\f[R] و \f[CR](\(at\(at) TOTALCOST\f[R] هزینه‌های مجازی هستند که قیمت‌های بازار ایجاد نمی‌کنند. در hledger، این موارد معادل \f[CR]\(at\f[R] و \f[CR]\(at\(at\f[R] هستند. .SS "نحو لات‌های Ledger (Ledger lot syntax)" در Ledger، این یادداشت‌های اختیاریِ پس از یک مبلغ، به تعیین مبنای هزینه (بهای تمام‌شده) یک لات تازه خریداری‌شده، یا انتخاب لات(های) موجود برای واگذاری کمک می‌کنند: .IP \(bu 2 \f[CR]{LOTUNITCOST}\f[R] و \f[CR]{{LOTTOTALCOST}}\f[R] (قیمت لات) .IP \(bu 2 \f[CR][LOTDATE]\f[R] (تاریخ لات) .IP \(bu 2 \f[CR](LOTNOTE)\f[R] (یادداشت لات) .PP نرم‌افزار hledger هنوز خود لات‌ها را محاسبه نمی‌کند، اما این یادداشت‌ها را می‌پذیرد و آن‌ها را در قالب‌های خروجی \f[CR]txt\f[R]، \f[CR]beancount\f[R] و \f[CR]json\f[R] دستور \f[CR]print\f[R] نمایش می‌دهد. این بدان معناست که می‌توانید از این نحو در دفترهای روزنامه hledger خود استفاده کنید (در صورت نیاز، همراه با یک ثبت اضافی بدون مبلغ برای کمک به تراز شدن تراکنش‌ها)، و هر زمان که خواستید لات‌ها و سود سرمایه‌ای را محاسبه کنید، از دستور \f[CR]print\f[R] برای برون‌بری به Ledger یا Beancount بهره ببرید..SS "هزینه‌های لات ثابت در Ledger (Ledger fixed lot costs)" .IP \(bu 2 \f[CR]{=UNITCOST}\f[R] و \f[CR]{{=TOTALCOST}}\f[R] (قیمت ثابت) .RS 2 .IP \(bu 2 هنگام خرید، به معنای \(dqاین هزینه همان ارزش ثابت نیز هست، اجازه ندهید در گزارش‌های ارزش نوسان کند\(dq است .RE .PP احتمالاً معادل با \f[CR]\(at\f[R]/\f[CR]\(at\(at\f[R] است، اما مطمئن نیستم. .PP \f[B]Beancount\f[R] نشانه‌گذاری ساده‌تر و رفتار متفاوتی دارد: .IP \(bu 2 \f[CR]\(at UNITCOST\f[R] و \f[CR]\(at\(at TOTALCOST\f[R] .RS 2 .IP \(bu 2 هزینه‌ای را بدون ایجاد لات، همانند hledger، بیان می‌کند .IP \(bu 2 هنگام خرید (به‌دست آوردن) یا فروش (واگذاری) یک لات، و در ترکیب با \f[CR]{...}\f[R]: جز برای ثبت بهای تمام‌شده/قیمت فروش استفاده نمی‌شود .RE .IP \(bu 2 \f[CR]{UNITCOST}\f[R] و \f[CR]{{TOTALCOST}}\f[R] .RS 2 .IP \(bu 2 هنگام خرید، هزینه را برای تراز تراکنش بیان کرده، و همچنین یک لات به همراه این مبنای هزینه ضمیمه‌شده ایجاد می‌کند .IP \(bu 2 هنگام فروش، .RS 2 .IP \(bu 2 لاتی را بر اساس مبنای هزینه آن انتخاب می‌کند .IP \(bu 2 در صورتی که آن لات موجود نباشد یا نتوان آن را بدون ابهام انتخاب کرد (بسته به روش ثبت پیکربندی‌شده)، خطایی ایجاد می‌کند .IP \(bu 2 قیمت فروش را برای تراز تراکنش بیان می‌کند .RE .RE .IP \(bu 2 \f[CR]{}\f[R]، \f[CR]{YYYY\-MM\-DD}\f[R]، \f[CR]{\(dqLABEL\(dq}\f[R]، \f[CR]{UNITCOST, \(dqLABEL\(dq}\f[R]، \f[CR]{UNITCOST, YYYY\-MM\-DD, \(dqLABEL\(dq}\f[R] .RS 2 .IP \(bu 2 هنگام فروش، ترکیب‌های دیگری از تاریخ/هزینه/برچسب، مانند موارد بالا، برای انتخاب لات پذیرفته می‌شوند. .RE .PP در حال حاضر، hledger .IP \(bu 2 از \f[CR]\(at\f[R] و \f[CR]\(at\(at\f[R] پشتیبانی می‌کند .IP \(bu 2 نشانه‌گذاری \f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] را می‌پذیرد، اما آن را نادیده می‌گیرد .IP \(bu 2 و سایر موارد را رد می‌کند. .PP .SH "سی‌اس‌وی (CSV)" ابزار hledger می‌تواند تراکنش‌ها را از فایل‌های CSV (مقادیر جداشده با کاما) بخواند. دقیق‌تر آنکه می‌تواند داده‌های DSV (مقادیر جداشده با جداکننده) را از یک فایل یا ورودی استاندارد بخواند. فرمت‌های جداشده با کاما، جداشده با نقطه‌ویرگول و جداشده با تب، رایج‌ترین انواع هستند و hledger این سه نوع را به‌طور خودکار بر پایه پسوند نام فایل \f[CR].csv\f[R]، \f[CR].ssv\f[R] یا \f[CR].tsv\f[R] یا پیشوند مسیر فایل \f[CR]csv:\f[R]، \f[CR]ssv:\f[R] یا \f[CR]tsv:\f[R] شناسایی می‌کند. .PP (برای کسب اطلاعات درباره نحوه تولید \f[I]خروجی\f[R] با فرمت CSV یا TSV، بخش Output format را ببینید.) .PP هر فایل CSV باید توسط یک \f[I]فایل قوانین\f[R] (rules file) متناظر توصیف شود. این فایل شامل قوانینی است که داده‌های CSV (خط سربرگ، چینش فیلدها، قالب تاریخ و غیره)، چگونگی ساخت تراکنش‌های hledger از آن، و نحوه دسته‌بندی تراکنش‌ها بر اساس شرح یا سایر ویژگی‌ها را توصیف می‌کند. .PP به‌طور پیش‌فرض، hledger انتظار دارد نام این فایل قوانین مشابه فایل CSV همراه با یک پسوند الحاقی \f[CR].rules\f[R] در همان دایرکتوری باشد. به‌عنوان مثال، هنگام درخواست خواندن \f[CR]foo/FILE.csv\f[R]، ابزار hledger به دنبال \f[CR]foo/FILE.csv.rules\f[R] می‌گردد. می‌توانید با استفاده از گزینه \f[CR]\-\-rules\f[R]، فایل قوانین متفاوتی را مشخص کنید. .PP در کمترین حالت، فایل قوانین باید فیلدهای تاریخ (date) و مبلغ (amount) را مشخص کند، و اغلب همچنین قالب تاریخ و تعداد خطوط سربرگ را تعیین می‌نماید. در اینجا یک فایل ساده CSV و فایل قوانین متناظر با آن آورده شده است: .IP .EX Date, Description, Id, Amount 12/11/2019, Foo, 123, 10.23 .EE .IP .EX # basic.csv.rules skip 1 fields date, description, , amount date\-format %d/%m/%Y .EE .IP .EX $ hledger print \-f basic.csv 2019\-11\-12 Foo expenses:unknown 10.23 income:unknown \-10.23 .EE .PP یک آموزش مقدماتی با عنوان Tutorial: Import CSV data در hledger.org، و نمونه‌های بیشتری از قوانین CSV در ادامه، و مجموعه‌ای بزرگ‌تر در آدرس https://github.com/simonmichael/hledger/tree/master/examples/csv در دسترس است..SS برگه تقلب قواعد CSV (CSV rules cheatsheet) انواع قواعد زیر می‌توانند به هر ترتیبی در فایل قواعد ظاهر شوند. (خطوط خالی و خطوطی که با \f[CR]#\f[R] یا \f[CR];\f[R] یا \f[CR]*\f[R] آغاز می‌شوند نادیده گرفته می‌شوند.) .PP .TS tab(@); lw(23.7n) lw(46.3n). T{ \f[B]\f[CB]source\f[B]\f[R] T}@T{ به‌طور اختیاری مشخص می‌کند داده‌ها از کدام فایل خوانده شوند T} T{ \f[B]\f[CB]archive\f[B]\f[R] T}@T{ به‌طور اختیاری ایجاد بایگانی از فایل‌های واردشده را فعال می‌کند T} T{ \f[B]\f[CB]encoding\f[B]\f[R] T}@T{ به‌طور اختیاری کدگذاری متنی (text encoding) داده‌ها را مشخص می‌کند T} T{ \f[B]\f[CB]separator\f[B]\f[R] T}@T{ جداکننده فیلدها را به‌جای تکیه بر پسوند فایل مشخص می‌کند T} T{ \f[B]\f[CB]decimal\-mark\f[B]\f[R] T}@T{ در صورت مبهم بودن، ممیز اعشاری مورد استفاده در مقادیر CSV را مشخص می‌کند T} T{ \f[B]\f[CB]date\-format\f[B]\f[R] T}@T{ نحوه تجزیه تاریخ‌ها/تاریخ\-زمان‌های CSV را مشخص می‌کند T} T{ \f[B]\f[CB]timezone\f[B]\f[R] T}@T{ منطقه زمانی تاریخ\-زمان‌های مبهم CSV را مشخص می‌کند T} T{ \f[B]\f[CB]newest\-first\f[B]\f[R] T}@T{ ترتیب تراکنش‌ها (txn) را بهبود می‌بخشد هنگامی که: چندین رکورد وجود دارد، جدیدترین‌ها در ابتدا هستند و همگی تاریخی یکسان دارند T} T{ \f[B]\f[CB]intra\-day\-reversed\f[B]\f[R] T}@T{ ترتیب تراکنش‌ها (txn) را بهبود می‌بخشد هنگامی که: تراکنش‌های هم‌روز در ترتیبی معکوس نسبت به کل فایل قرار دارند T} T{ \f[B]\f[CB]skip\f[B]\f[R] T}@T{ (در سطح بالا) خط(های) سرایند (header) را در ابتدای فایل نادیده می‌گیرد T} T{ \f[B]فهرست \f[CB]fields\f[B]\f[R] T}@T{ فیلدهای CSV را برای ارجاع آسان نام‌گذاری می‌کند، و به‌طور اختیاری مقادیر آنها را به فیلدهای hledger اختصاص می‌دهد T} T{ \f[B]تخصیص فیلد\f[R] T}@T{ یک مقدار CSV یا مقدار متنی درون‌یابی‌شده را به یک فیلد hledger اختصاص می‌دهد T} T{ \f[B]بلوک \f[CB]if\f[B]\f[R] T}@T{ به‌صورت شرطی مقادیری را به فیلدهای hledger اختصاص می‌دهد، یا یک رکورد را نادیده می‌گیرد (\f[CR]skip\f[R])، یا به پردازش پایان می‌دهد (\f[CR]end\f[R]، نادیده گرفتن بقیه فایل) T} T{ \f[B]جدول \f[CB]if\f[B]\f[R] T}@T{ به‌صورت شرطی و با استفاده از ساختار نگارشی فشرده مقادیری را به فیلدهای hledger اختصاص می‌دهد T} T{ \f[B]\f[CB]skip\f[B]\f[R] T}@T{ (درون یک قاعده \f[CR]if\f[R]) رکورد(های) فعلی را نادیده می‌گیرد T} T{ \f[B]\f[CB]end\f[B]\f[R] T}@T{ (درون یک قاعده \f[CR]if\f[R]) تمام رکوردهای باقی‌مانده را نادیده می‌گیرد T} T{ \f[B]\f[CB]balance\-type\f[B]\f[R] T}@T{ نوع گزاره‌ها/تخصیص‌های موجودی (balance assertions/assignments) تولیدی را انتخاب می‌کند T} T{ \f[B]\f[CB]include\f[B]\f[R] T}@T{ یک فایل قواعد CSV دیگر را به‌صورت درون‌خطی وارد می‌کند T} .TE .PP نکات کار با CSV را می‌توان در ادامه یافت، از جمله نحوه ارزیابی قواعد CSV..SS \f[CR]source\f[R] اگر به hledger بگویید که یک فایل csv را با \f[CR]\-f foo.csv\f[R] بخواند، در \f[CR]foo.csv.rules\f[R] به دنبال قوانین خواهد گشت. یا می‌توانید به آن بگویید فایل قوانین را با \f[CR]\-f foo.csv.rules\f[R] بخواند، و آن در \f[CR]foo.csv\f[R] به دنبال داده‌ها خواهد گشت (از نسخهٔ 1.30). این دو روش عمدتاً معادل هستند، اما روش دوم قابلیت‌های اضافه‌ای را ارائه می‌دهد. از جمله اینکه فایل داده می‌تواند وجود نداشته باشد، بدون اینکه خطایی رخ دهد؛ در این حالت صرفاً خالی در نظر گرفته می‌شود. .PP برای انعطاف‌پذیری بیشتر، یک قاعدهٔ \f[CR]source\f[R] اضافه کنید که به شما امکان می‌دهد فایل دادهٔ متفاوتی را مشخص کنید: .IP .EX source ./Checking1.csv .EE .PP اگر فایل وجود نداشته باشد، بدون ایجاد خطا، صرفاً خالی در نظر گرفته می‌شود. .PP اگر تنها نام یک فایل را بدون مسیر مشخص کنید، hledger در پوشهٔ \f[CR]\(ti/Downloads\f[R] به دنبال آن خواهد گشت: .IP .EX source Checking1.csv .EE .PP می‌توانید از یک الگوی glob استفاده کنید تا از مشخص کردن دقیق نام فایل اجتناب شود: .IP .EX source Checking1*.csv .EE .PP این کار مزیت دیگری نیز دارد: اگر الگو با چندین فایل مطابقت داشته باشد، hledger جدیدترین آن‌ها (که اخیراً تغییر یافته است) را خواهد خواند. این امر در صورتی که فایلی را چندین بار بدون پاکسازی بارگیری کرده باشید، از بروز مشکلات جلوگیری می‌کند. .PP همهٔ این‌ها یک گردش کاری آسان را فراهم می‌کنند که در آن می‌توانید صرفاً فایل‌های CSV را بارگیری کرده و سپس دستور \f[CR]hledger import rules/*\f[R] را اجرا نمایید. .PP همچنین بخش \(dqWorking with CSV > Reading files specified by rule\(dq را ببینید. .SS دستورهای پاکسازی داده / تولید داده پس از الگوی فایلِ \f[CR]source\f[R]، می‌توانید \f[CR]|\f[R] (پایپ) و یک دستور پاکسازی داده (یا زنجیره‌ای از دستورها) بنویسید. اگر قوانین CSV در hledger کافی نیستند، می‌توانید داده‌های بارگیری‌شده را در اینجا با یک دستور یا اسکریپت شل پیش‌پردازش کنید تا برای تبدیل مناسب‌تر شوند. این دستور توسط شل پیش‌فرض شما، در دایرکتوریِ فایل قوانین اجرا خواهد شد، محتوای فایل داده را به عنوان ورودی استاندارد دریافت خواهد کرد و باید صفر یا چند خط از مقادیر جدا شده با نویسه (CSV) را که برای تبدیل توسط قوانین CSV مناسب هستند، در خروجی ارائه دهد. .PP مثال‌ها: .IP .EX source ./paypal.json | paypalcsv source data/simplefin.json | simplefincsv \- \(aqchase.*card\(aq source OfxDownload*.csv | grep \-vE \(aq\(ha(([\(ha,]*,){6}[\(ha,]*|)$\(aq | sort \-t, \-n +2 source History_for_Account_Z20144832*.csv # | grep \-E \(aq\(ha([\(ha,]*,){12}[\(ha,]*$\(aq | sed \-E \-e \(aqs/\(ha //\(aq \-e \(aqs/\(rs.([0\-9]),/.\(rs10,/g\(aq \-e \(aqs/,([0\-9]+),/,\(rs1.00,/g\(aq .EE .PP یا اینکه، پس از \f[CR]source\f[R] می‌توانید \f[CR]|\f[R] و یک دستور تولید داده را (بدون الگوی فایل پیش از \f[CR]|\f[R]) بنویسید. این دستور هیچ ورودی‌ای دریافت نمی‌کند و باید صفر یا چند خط از مقادیر جدا شده با نویسه را که برای تبدیل توسط قوانین CSV مناسب هستند، در خروجی تولید کند. .PP مثال‌ها: .IP .EX source | paypaljson | paypalcsv source | paypalcsv data/paypal.json source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json \(aqchase.*card\(aq source | simplefincsv data/simplefin.json \(aqunify.*checking\(aq .EE .PP (اسکریپت‌های \f[CR]paypal*\f[R] و \f[CR]simplefin*\f[R] در bin/ قرار دارند) .PP هر زمان که hledger یکی از این دستورها را اجرا کند، آن دستور را در stderr بازتاب (echo) خواهد داد. اگر دستور خروجی خطا تولید کند اما با موفقیت خاتمه یابد، hledger خروجی خطا را به عنوان یک هشدار نمایش می‌دهد. اگر دستور با شکست مواجه شود، hledger نیز ناموفق خواهد بود و خروجی خطا را در پیام خطا نمایش می‌دهد. .PP \f[I]اضافه‌شده در نسخهٔ 1.50؛ آزمایشی.\f[R].SS \f[CR]archive\f[R] با افزودن \f[CR]archive\f[R] به یک فایل قوانین، دستور \f[CR]import\f[R] هر فایل داده یا خروجی دستور دادهٔ پردازش‌شده با موفقیت را در یک دایرکتوری \f[CR]data/\f[R] مجاور بایگانی خواهد کرد. نام فایل بایگانی بر اساس فایل قوانین و تاریخ ویرایش و پسوند فایل داده (یا برای دستوری که داده تولید می‌کند، تاریخ جاری و پسوند \(dq.csv\(dq) تعیین خواهد شد. فایل دادهٔ اصلی، در صورت وجود، حذف خواهد شد. .PP همچنین، در این حالت \f[CR]import\f[R] قدیمی‌ترین فایل منطبق با الگوی glob در قانون \f[CR]source\f[R] را ترجیح می‌دهد، نه جدیدترین را. (بنابراین اگر چندین بارگیری وجود داشته باشد، ابتدا قدیمی‌ترین‌ها وارد و بایگانی می‌شوند.) .PP بایگانی کردن اختیاری است، اما می‌تواند برای عیب‌یابی قوانین CSV، بازتولید مدخل‌ها با قوانین بهبودیافته، بررسی تغییرات در CSV بانک شما و غیره مفید باشد. .PP \f[I]در نسخهٔ 1.50 افزوده شد؛ آزمایشی.\f[R] .SS \f[CR]encoding\f[R] .IP .EX encoding ENCODING .EE .PP hledger به‌طور معمول انتظار دارد متن‌های غیر ascii با کدگذاری متن locale سیستم باشند. اگر نیاز به خواندن فایل‌های CSV با کدگذاری دیگری دارید، می‌توانید با افزودن \f[CR]encoding ENCODING\f[R] به قوانین CSV خود این کار را انجام دهید. برای مثال: \f[CR]encoding iso\-8859\-1\f[R]. .PP کدگذاری‌های زیر پشتیبانی می‌شوند: .PP \f[CR]ascii\f[R], \f[CR]utf\-8\f[R], \f[CR]utf\-16\f[R], \f[CR]utf\-32\f[R], \f[CR]iso\-8859\-1\f[R], \f[CR]iso\-8859\-2\f[R], \f[CR]iso\-8859\-3\f[R], \f[CR]iso\-8859\-4\f[R], \f[CR]iso\-8859\-5\f[R], \f[CR]iso\-8859\-6\f[R], \f[CR]iso\-8859\-7\f[R], \f[CR]iso\-8859\-8\f[R], \f[CR]iso\-8859\-9\f[R], \f[CR]iso\-8859\-10\f[R], \f[CR]iso\-8859\-11\f[R], \f[CR]iso\-8859\-13\f[R], \f[CR]iso\-8859\-14\f[R], \f[CR]iso\-8859\-15\f[R], \f[CR]iso\-8859\-16\f[R], \f[CR]cp1250\f[R], \f[CR]cp1251\f[R], \f[CR]cp1252\f[R], \f[CR]cp1253\f[R], \f[CR]cp1254\f[R], \f[CR]cp1255\f[R], \f[CR]cp1256\f[R], \f[CR]cp1257\f[R], \f[CR]cp1258\f[R], \f[CR]koi8\-r\f[R], \f[CR]koi8\-u\f[R], \f[CR]gb18030\f[R], \f[CR]macintosh\f[R], \f[CR]jis\-x\-0201\f[R], \f[CR]jis\-x\-0208\f[R], \f[CR]iso\-2022\-jp\f[R], \f[CR]shift\-jis\f[R], \f[CR]cp437\f[R], \f[CR]cp737\f[R], \f[CR]cp775\f[R], \f[CR]cp850\f[R], \f[CR]cp852\f[R], \f[CR]cp855\f[R], \f[CR]cp857\f[R], \f[CR]cp860\f[R], \f[CR]cp861\f[R], \f[CR]cp862\f[R], \f[CR]cp863\f[R], \f[CR]cp864\f[R], \f[CR]cp865\f[R], \f[CR]cp866\f[R], \f[CR]cp869\f[R], \f[CR]cp874\f[R], \f[CR]cp932\f[R]. .PP \f[I]در نسخهٔ 1.42 افزوده شد.\f[R] .SS \f[CR]separator\f[R] می‌توانید از قانون \f[CR]separator\f[R] برای خواندن انواع دیگر داده‌های جداشده با نویسه (character\-separated) استفاده کنید. آرگومان می‌تواند هر تک‌نویسهٔ جداکننده یا کلمات \f[CR]tab\f[R] یا \f[CR]space\f[R] (بدون حساسیت به بزرگی و کوچکی حروف) باشد. برای مثال، برای مقادیر جداشده با کاما (CSV): .IP .EX separator , .EE .PP یا برای مقادیر جداشده با نقطه‌ویرگول (SSV): .IP .EX separator ; .EE .PP یا برای مقادیر جداشده با تب (TSV): .IP .EX separator TAB .EE .PP اگر فایل ورودی دارای پسوند فایل \f[CR].csv\f[R]، \f[CR].ssv\f[R] یا \f[CR].tsv\f[R] (یا پیشوند \f[CR]csv:\f[R]، \f[CR]ssv:\f[R] یا \f[CR]tsv:\f[R]) باشد، جداکنندهٔ مناسب به‌طور خودکار استنتاج می‌شود و نیازی به این قانون نخواهید داشت..SS \f[CR]skip\f[R] .IP .EX skip N .EE .PP واژه \f[CR]skip\f[R] به همراه یک عدد (یا بدون عدد، به معنای ۱) به hledger می‌گوید که این تعداد خط غیرخالی را در ابتدای داده‌های ورودی نادیده بگیرد. هر زمان که داده‌های CSV شما حاوی خطوط سرآیند باشد، به این مورد نیاز خواهید داشت. توجه داشته باشید که خطوط خالی به‌طور خودکار نادیده گرفته می‌شوند، بنابراین نیازی به شمارش آن‌ها نیست. .PP دستور \f[CR]skip\f[R] کاربرد دومی نیز دارد: می‌توان از آن درون بلوک‌های if (که در ادامه توضیح داده شده) استفاده کرد تا در صورت برقرار بودن شرط، یک یا چند رکورد نادیده گرفته شوند. رکوردهایی که به این صورت رد می‌شوند نادیده گرفته خواهند شد، با این استثنا که همچنان باید CSV معتبر باشند. .SS \f[CR]date\-format\f[R] .IP .EX date\-format DATEFMT .EE .PP این یک قاعده کمکی برای فیلدهای \f[CR]date\f[R] (و \f[CR]date2\f[R]) است. اگر تاریخ‌های CSV شما به قالب \f[CR]YYYY\-MM\-DD\f[R]، \f[CR]YYYY/MM/DD\f[R] یا \f[CR]YYYY.MM.DD\f[R] نیستند، باید یک قاعده date\-format اضافه کنید که آن‌ها را با یک الگوی تجزیه تاریخ به سبک strptime توصیف کند \- پیوند زیر را ببینید: https://hackage.haskell.org/package/time/docs/Data\-Time\-Format.html#v:formatTime الگو باید مقدار تاریخ CSV را به‌طور کامل تجزیه کند. چند مثال: .IP .EX # MM/DD/YY date\-format %m/%d/%y .EE .IP .EX # D/M/YYYY # The \- makes leading zeros optional. date\-format %\-d/%\-m/%Y .EE .IP .EX # YYYY\-Mmm\-DD date\-format %Y\-%h\-%d .EE .IP .EX # M/D/YYYY HH:MM AM some other junk # Note the time and junk must be fully parsed, though only the date is used. date\-format %\-m/%\-d/%Y %l:%M %p some other junk .EE .PP توجه داشته باشید که در حال حاضر هیچ‌گونه پشتیبانی از محلی‌سازی (locale) برای مواردی مانند \f[CR]%b\f[R] وجود ندارد و مقداردهی LC_TIME کمکی نخواهد کرد. .SS \f[CR]timezone\f[R] .IP .EX timezone TIMEZONE .EE .PP هنگامی که CSV حاوی تاریخ\-زمان‌هایی است که به‌طور ضمنی در منطقه‌ای زمانی غیر از منطقه شما قرار دارند اما حاوی اطلاعات صریح منطقه زمانی نیستند، می‌توانید از این قاعده برای اعلام منطقه زمانی بومی CSV استفاده کنید؛ این کار به جلوگیری از خطای جابه‌جایی یک‌روزه تاریخ‌ها (off\-by\-one) کمک می‌کند. .PP هنگامی که تاریخ\-زمان‌های CSV حاوی اطلاعات منطقه زمانی هستند، به این قاعده نیازی نخواهید داشت؛ در عوض، از \f[CR]%Z\f[R] در \f[CR]date\-format\f[R] استفاده کنید (یا \f[CR]%z\f[R]، \f[CR]%EZ\f[R]، \f[CR]%Ez\f[R]؛ پیوند formatTime در بالا را ببینید). .PP در هر یک از این حالات، hledger تبدیلی آگاه از منطقه زمانی انجام داده و تاریخ\-زمان‌های CSV را به منطقه زمانی جاری سیستم شما محلی‌سازی می‌کند. اگر ترجیح می‌دهید محلی‌سازی به منطقه زمانی دیگری انجام شود، برای نمونه جهت بازتولیدپذیری، می‌توانید (دست‌کم در یونیکس) منطقه زمانی خروجی را با متغیر محیطی TZ تنظیم کنید؛ برای مثال: .IP .EX $ TZ=\-1000 hledger print \-f foo.csv # or TZ=\-1000 hledger import foo.csv .EE .PP قاعده \f[CR]timezone\f[R] در حال حاضر نام‌های مناطق زمانی را تشخیص نمی‌دهد، به جز \(dqUTC\(dq، \(dqGMT\(dq، \(dqEST\(dq، \(dqEDT\(dq، \(dqCST\(dq، \(dqCDT\(dq، \(dqMST\(dq، \(dqMDT\(dq، \(dqPST\(dq یا \(dqPDT\(dq. برای سایر موارد، از قالب عددی استفاده کنید: +HHMM یا \-HHMM..SS \f[CR]newest\-first\f[R] ابزار hledger تلاش می‌کند تا اطمینان حاصل کند که تراکنش‌های تولیدشده دارای ترتیب زمانی خواهند بود، از جمله تراکنش‌های مربوط به یک روز یکسان. معمولاً این ابزار می‌تواند ترتیب رکوردهای CSV را به‌طور خودکار تشخیص دهد. اما اگر با یک فایل CSV مواجه شود که تمام رکوردهای آن دارای تاریخی یکسان باشند، فرض را بر این می‌گذارد که رکوردها از قدیمی‌ترین به جدیدترین مرتب شده‌اند. اگر در واقعیت رکوردهای CSV معمولاً از جدیدترین به قدیمی‌ترین باشند، مانند: .IP .EX 2022\-10\-01, txn 3... 2022\-10\-01, txn 2... 2022\-10\-01, txn 1... .EE .PP می‌توانید قاعده \f[CR]newest\-first\f[R] را اضافه کنید تا به hledger در تولید تراکنش‌ها با ترتیب درست کمک نمایید. .IP .EX # same\-day CSV records are newest first newest\-first .EE .SS \f[CR]intra\-day\-reversed\f[R] اگر رکوردهای CSV در یک روز معین برعکس ترتیب کلی رکوردها مرتب شده باشند، می‌توانید قاعده \f[CR]intra\-day\-reversed\f[R] را برای بهبود ترتیب مدخل‌های دفتر کل اضافه کنید. به‌عنوان مثال، در اینجا ترتیب کلی رکوردها از جدیدترین به قدیمی‌ترین است، اما رکوردهای همان روز از قدیمی‌ترین به جدیدترین مرتب شده‌اند: .IP .EX 2022\-10\-02, txn 3... 2022\-10\-02, txn 4... 2022\-10\-01, txn 1... 2022\-10\-01, txn 2... .EE .IP .EX # transactions within each day are reversed with respect to the overall date order intra\-day\-reversed .EE .SS \f[CR]decimal\-mark\f[R] .IP .EX decimal\-mark . .EE .PP یا: .IP .EX decimal\-mark , .EE .PP ابزار hledger هنگام تجزیه اعداد، به‌طور خودکار نقطه یا ویرگول را به‌عنوان نشانگر اعشار می‌پذیرد (رجوع کنید به Amounts). با این حال، اگر هر یک از اعداد در فایل CSV شامل نشانگرهای گروه‌بندی ارقام مانند ویرگول‌های جداکننده هزارگان باشند، باید با استفاده از این قاعده نشانگر اعشار را به‌طور صریح مشخص کنید تا از خطای تجزیه اعداد جلوگیری شود. .SS فیلدهای CSV و فیلدهای hledger این موضوع می‌تواند گیج‌کننده باشد، بنابراین اجازه دهید با یک مرور کلی شروع کنیم: .IP \(bu 2 \f[B]فیلدهای CSV\f[R] توسط فایل داده شما ارائه می‌شوند. نام‌گذاری آن‌ها بر اساس موقعیت مکانی‌شان در رکورد CSV و با شروع از ۱ انجام می‌شود. همچنین می‌توانید یک نام خوانا به آن‌ها اختصاص دهید. .IP \(bu 2 \f[B]فیلدهای hledger\f[R] از پیش تعریف‌شده هستند؛ \f[CR]date\f[R]، \f[CR]description\f[R]، \f[CR]account1\f[R]، \f[CR]amount1\f[R] و \f[CR]account2\f[R] برخی از آن‌ها هستند. آن‌ها بیشتر با بخش‌هایی از یک مدخل دفتر کل تراکنش مطابقت دارند. .IP \(bu 2 فیلدهای CSV و فیلدهای hledger تنها فیلدهایی هستند که با آن‌ها کار خواهید کرد؛ شما نمی‌توانید فیلدهای جدید یا متغیرهایی مانند یک زبان برنامه‌نویسی تعریف کنید. (اما می‌توانید در مرحله پیش‌پردازش، پیش از اجرای قواعد، فیلدهای CSV اضافی را به داده‌ها اضافه نمایید.) .IP \(bu 2 برای هر رکورد CSV، مقادیری را به یک یا چند مورد از فیلدهای hledger اختصاص می‌دهید تا یک تراکنش (مدخل دفتر کل) ایجاد شود. مقادیر می‌توانند متنی ایستا، مقادیر فیلد CSV از رکورد جاری، یا ترکیبی از این‌ها باشند. .IP \(bu 2 برای موارد ساده، می‌توانید نام یک فیلد CSV را هم‌نام با یکی از فیلدهای hledger تعیین کنید؛ در این صورت مقدار آن به‌طور خودکار به آن فیلد hledger اختصاص خواهد یافت. .IP \(bu 2 فیلدهای CSV فقط قابل خواندن هستند و امکان نوشتن در آن‌ها وجود ندارد. آن‌ها در سمت راست و با یک پیشوند % قرار می‌گیرند. به‌عنوان مثال: .RS 2 .IP \(bu 2 بررسی مقدار یک فیلد CSV: \f[CR]if %CSVFIELD ...\f[R] .IP \(bu 2 درج و جایگزینی مقدار آن: \f[CR]HLEDGERFIELD %CSVFIELD\f[R] .RE .IP \(bu 2 فیلدهای hledger فقط قابل نوشتن هستند و خوانده نمی‌شوند. آن‌ها در سمت چپ (یا در فهرست فیلدها) و بدون هیچ پیشوندی قرار می‌گیرند. به‌عنوان مثال: .RS 2 .IP \(bu 2 تنظیم شرح تراکنش روی یک مقدار: \f[CR]description VALUE\f[R] .IP \(bu 2 تنظیم شرح تراکنش با مقدار دومین فیلد CSV: .PD 0 .P .PD \f[CR]fields date, description, amount\f[R] .RE.SS فهرست \f[CR]fields\f[R] .IP .EX fields FIELDNAME1, FIELDNAME2, ... .EE .PP یک فهرست فیلدها (کلمهٔ \f[CR]fields\f[R] که در ادامهٔ آن نام‌های فیلد با کاما از هم جدا شده‌اند) اختیاری، اما کارآمد است. این فهرست دو کار انجام می‌دهد: .IP "1." 3 به فیلد CSV در هر ستون نام اختصاص می‌دهد. این کار در صورتی که در سایر قوانین به آن‌ها ارجاع دهید سودمند است، تا بتوانید به‌جای به‌خاطر سپردن \f[CR]%13\f[R]، از \f[CR]%SomeField\f[R] استفاده کنید. .IP "2." 3 هر زمان که از یکی از نام‌های فیلد خاص hledger (که در ادامه شرح داده شده) استفاده کنید، مقدار CSV در این موقعیت را به آن فیلد hledger اختصاص می‌دهد. این سریع‌ترین راه برای مقداردهی فیلدهای hledger و ساخت یک تراکنش است. .PP در اینجا مثالی آمده است که می‌گوید \(dqاز فیلدهای اول، دوم و چهارم به‌عنوان تاریخ، شرح و مقدار تراکنش استفاده کن؛ دو فیلد آخر را برای ارجاع‌های بعدی نام‌گذاری کن؛ و بقیه را نادیده بگیر\(dq: .IP .EX fields date, description, , amount, , , somefield, anotherfield .EE .PP در فهرست فیلدها، جداکننده همیشه کاما است؛ این مورد ارتباطی با جداکنندهٔ فایل CSV ندارد. همچنین: .IP \(bu 2 باید دست‌کم دو مورد در فهرست وجود داشته باشد (حداقل یک کاما). .IP \(bu 2 نام‌های فیلد نباید شامل فاصله باشند. فاصله‌های قبل یا بعد از نام فیلد اختیاری هستند. .IP \(bu 2 نام‌های فیلد می‌توانند شامل \f[CR]_\f[R] (خط زیرین) یا \f[CR]\-\f[R] (خط پیوند) باشند. .IP \(bu 2 به فیلدهایی که برایتان اهمیتی ندارند می‌توان یک نام ساختگی یا یک نام خالی اختصاص داد. .PP اگر فایل CSV شامل سرستون باشد، مناسب است که از آن‌ها برای نام‌های فیلد خود، پس از اعمال تغییرات لازم (مثلاً تبدیل به حروف کوچک و جایگزینی فاصله‌ها با خط زیرین) استفاده کنید. .PP گاهی اوقات ممکن است بخواهید نام یک فیلد CSV را تغییر دهید تا از انتساب به یک فیلد هم‌نام در hledger جلوگیری کنید. به‌عنوان مثال، می‌توانید فیلد \(dqbalance\(dq در CSV را \f[CR]balance_\f[R] بنامید تا از تنظیم مستقیم فیلد \f[CR]balance\f[R] در hledger (و ایجاد یک اعتبارسنجی تراز) جلوگیری شود. .SS تخصیص فیلد .IP .EX HLEDGERFIELD FIELDVALUE .EE .PP تخصیص فیلد روش انعطاف‌پذیرتری برای انتساب مقادیر CSV به فیلدهای hledger است. از آن‌ها می‌توان به‌جای فهرست فیلدها یا علاوه بر آن (به بالا مراجعه کنید) استفاده کرد. .PP برای انتساب یک مقدار به فیلد hledger، نام فیلد (هر یک از نام‌های فیلدها/شبه‌فیلدهای استاندارد hledger که در ادامه تعریف شده‌اند)، یک فاصله، و سپس یک مقدار متنی در همان خط بنویسید. این مقدار متنی می‌تواند فیلدهای CSV را درون‌یابی کند، که یا با موقعیت مبتنی بر ۱ آن‌ها در رکورد CSV (\f[CR]%N\f[R]) یا با نامی که در فهرست فیلدها به آن‌ها داده شده است (\f[CR]%CSVFIELD\f[R]) و گروه‌های تطابق عبارت باقاعده (\f[CR]\(rsN\f[R]) به آن‌ها ارجاع داده می‌شود. .PP چند مثال: .IP .EX # تنظیم مقدار بر روی چهارمین فیلد CSV، همراه با افزودن \(dq USD\(dq در انتها amount %4 USD # ترکیب سه فیلد برای ساخت کامنت، شامل برچسب‌های note: و date: comment note: %somefield \- %anotherfield, date: %1 .EE .PP نکات: .IP \(bu 2 درون‌یابی فاصله‌های خالی ابتدا و انتها را حذف می‌کند (بنابراین یک مقدار CSV مانند \f[CR]\(dq 1 \(dq\f[R] هنگام درون‌یابی به \f[CR]1\f[R] تبدیل می‌شود) (#1051). .IP \(bu 2 درون‌یابی‌ها همیشه به یک فیلد CSV ارجاع می‌دهند \- نمی‌توانید یک فیلد hledger را درون‌یابی کنید. (به «ارجاع به سایر فیلدها» در ادامه مراجعه کنید)..SS "نام‌های فیلد (Field names)" به دو نوع نام فیلد که در اینجا ذکر شده و فقط در فایل‌های قواعد CSV برنامهٔ hledger به کار می‌روند، توجه کنید: .IP "1." 3 \f[B]نام‌های فیلد CSV\f[R] (در این مستندات \f[CR]CSVFIELD\f[R]): می‌توانید ستون‌های CSV را به‌طور اختیاری برای ارجاع آسان نام‌گذاری کنید (چرا که hledger هنوز عناوین ستون‌ها را در یک فایل CSV به‌طور خودکار تشخیص نمی‌دهد)، از طریق نوشتن نام‌های دلخواه در یک فهرست \f[CR]fields\f[R]، به عنوان مثال: .RS 4 .IP .EX fields When, What, Some_Id, Net, Total, Foo, Bar .EE .RE .IP "2." 3 \f[B]نام‌های فیلد ویژهٔ hledger\f[R] (در این مستندات \f[CR]HLEDGERFIELD\f[R]): برای تولید تراکنش hledger از یک رکورد CSV، باید حداقل برخی از این‌ها را با نوشتن آن‌ها در سمت چپ یک انتساب فیلد مقداردهی کنید، به عنوان مثال: .RS 4 .IP .EX date %When code %Some_Id description %What comment %Foo %Bar amount1 $ %Total .EE .PP یا مستقیماً در یک فهرست \f[CR]fields\f[R]: .IP .EX fields date, description, code, , amount1, Foo, Bar currency $ comment %Foo %Bar .EE .RE .PP در اینجا تمام نام‌های فیلد ویژهٔ موجود در hledger و آنچه هنگام مقداردهی به آن‌ها رخ می‌دهد آمده است: .SS "فیلد date (date field)" مقداردهی به \f[CR]date\f[R] تاریخ تراکنش را تعیین می‌کند. .SS "فیلد date2 (date2 field)" فیلد \f[CR]date2\f[R] تاریخ ثانویهٔ تراکنش را، در صورت وجود، تعیین می‌کند. .SS "فیلد status (status field)" فیلد \f[CR]status\f[R] وضعیت تراکنش را، در صورت وجود، تعیین می‌کند. .SS "فیلد code (code field)" فیلد \f[CR]code\f[R] کد تراکنش را، در صورت وجود، تعیین می‌کند. .SS "فیلد description (description field)" فیلد \f[CR]description\f[R] شرح تراکنش را، در صورت وجود، تعیین می‌کند. .SS "فیلد comment (comment field)" فیلد \f[CR]comment\f[R] یادداشت تراکنش را، در صورت وجود، تعیین می‌کند. .PP فیلد \f[CR]commentN\f[R]، که در آن N یک عدد است، یادداشت Nاُمین ثبت (posting) را تعیین می‌کند. .PP می‌توانید یادداشت‌های چندخطی را با نوشتن صریح \f[CR]\(rsn\f[R] در کد تعیین کنید. یادداشتی که با \f[CR]\(rsn\f[R] شروع شود، از یک خط جدید آغاز خواهد شد. .PP یادداشت‌ها طبق معمول می‌توانند شامل برچسب‌ها (tags) باشند. .PP یادداشت‌های ثبت همچنین می‌توانند حاوی تاریخ ثبت باشند. تاریخ ثانویه، یا تاریخی بدون سال، نادیده گرفته خواهد شد. .SS "فیلد account (account field)" مقداردهی به \f[CR]accountN\f[R]، که در آن N عددی از ۱ تا ۹۹ است، نام حسابِ Nاُمین ثبت را تعیین کرده و باعث تولید آن ثبت می‌شود. .PP در بیشتر مواقع دو ثبت وجود دارد، بنابراین مایلید \f[CR]account1\f[R] و \f[CR]account2\f[R] را تعیین کنید. معمولاً \f[CR]account1\f[R] با فایل CSV مرتبط است و یک‌بار با یک انتساب در سطح بالا مقداردهی می‌شود، در حالی که \f[CR]account2\f[R] بر اساس شرح هر تراکنش در قواعد شرطی مقداردهی می‌شود. .PP اگر نام حسابِ یک ثبت تعیین نشود اما مبلغ آن مشخص شده باشد (پایین را ببینید)، یک نام حساب پیش‌فرض انتخاب خواهد شد (مانند \(dqexpenses:unknown\(dq یا \(dqincome:unknown\(dq). .SS "فیلد amount (amount field)" روش‌های مختلفی برای تعیین مبالغ ثبت از روی CSV وجود دارد که در موقعیت‌های گوناگون مفید هستند. .IP "1." 3 فیلد \f[B]\f[CB]amount\f[B]\f[R] قدیمی‌ترین و ساده‌ترین حالت است. مقداردهی به این فیلد، مبلغ اولین و دومین ثبت را تعیین می‌کند. در ثبت دوم، علامت مبلغ منفی می‌شود؛ همچنین، اگر بهایی به آن پیوست شده باشد، به بهای تمام‌شده تبدیل خواهد شد. .IP "2." 3 فیلدهای \f[B]\f[CB]amount\-in\f[B]\f[R] و \f[B]\f[CB]amount\-out\f[B]\f[R] دقیقاً مانند مورد بالا عمل می‌کنند، اما زمانی باید استفاده شوند که CSV دو فیلد مبلغ دارد (مانند \(dqDebit\(dq و \(dqCredit\(dq، یا \(dqInflow\(dq و \(dqOutflow\(dq). هر فیلدی که مقدار غیرصفر داشته باشد، به عنوان مبلغ ثبت اول و دوم استفاده خواهد شد. در اینجا نکاتی برای جلوگیری از سردرگمی آمده است: .RS 4 .IP \(bu 2 به این صورت نیست که \(dqamount\-in برای ثبت ۱ و amount\-out برای ثبت ۲ باشد\(dq، بلکه به این صورت است که \(dqیک مبلغ واحد را از فیلد amount\-in یا amount\-out استخراج کن، و از آن برای ثبت ۱ و (به‌صورت منفی‌شده) برای ثبت ۲ استفاده کن\(dq. .IP \(bu 2 از هر دوی \f[CR]amount\f[R] و \f[CR]amount\-in\f[R]/\f[CR]amount\-out\f[R] در یک فایل قواعد مشترک استفاده نکنید؛ بر اساس اینکه آیا مبلغ در یک فیلد منفرد CSV قرار دارد یا بین دو فیلد پخش شده است، انتخاب کنید. .IP \(bu 2 در هر رکورد، حداکثر یکی از دو فیلد CSV باید حاوی مبلغ غیرصفر باشد؛ فیلد دیگر باید شامل صفر یا خالی باشد. .IP \(bu 2 برنامهٔ hledger فرض می‌کند که هر دو فیلد CSV شامل اعداد بدون علامت هستند و به‌طور خودکار مقادیر amount\-out را منفی می‌کند. .IP \(bu 2 اگر داده‌ها با این نیازمندی‌ها مطابقت ندارند، احتمالاً به یک قاعدهٔ if نیاز خواهید داشت (پایین را ببینید). .RE .IP "3." 3 فیلد \f[B]\f[CB]amountN\f[B]\f[R] (که در آن N عددی از ۱ تا ۹۹ است) مبلغِ تنها یک ثبت را تعیین می‌کند: Nاُمین ثبت در تراکنش. معمولاً برای ایجاد یک تراکنش تراز (متوازن) به حداقل دو مورد از این انتساب‌ها نیاز خواهید داشت. همچنین می‌توانید برای نمایش تراکنش‌های پیچیده‌تر، بیش از دو ثبت تولید کنید. شماره‌های ثبت نیازی نیست متوالی باشند؛ همراه با قواعد if، شماره‌های ثبت بالاتر می‌توانند برای اطمینان از یک ترتیب مشخص برای ثبت‌ها مفید باشند. .IP "4." 3 فیلدهای \f[B]\f[CB]amountN\-in\f[B]\f[R] و \f[B]\f[CB]amountN\-out\f[B]\f[R] دقیقاً مانند مورد بالا عمل می‌کنند، اما زمانی باید استفاده شوند که فایل CSV دو فیلد مبلغ دارد. این فیلدها معادل \f[CR]amount\-in\f[R] و \f[CR]amount\-out\f[R] هستند و نکات یادشده در مورد آن‌ها در اینجا نیز صدق می‌کند. .IP "5." 3 به یاد داشته باشید که یک فهرست \f[CR]fields\f[R] نیز می‌تواند انتساب‌ها را انجام دهد. بنابراین اگر در یک فهرست fields یک فیلد CSV را \(dqamount\(dq بنامید، این عمل معادل انتساب به \f[CR]amount\f[R] به حساب می‌آید. (اگر این را نمی‌خواهید، در فهرست fields نام دیگری به آن بدهید، مانند \(dqamount_\(dq.) .IP "6." 3 موارد بالا پاسخگوی هر وضعیتی نیستند؛ اگر به انعطاف‌پذیری بیشتری نیاز دارید، از یک قاعدهٔ \f[CR]if\f[R] برای تعیین شرطی مبالغ استفاده کنید. برای اطلاعات بیشتر در این مورد و به‌طور کلی دربارهٔ نحوهٔ تعیین مبالغ، به بخش \(dqکار با CSV > تعیین مبالغ (Working with CSV > Setting amounts)\(dq در زیر مراجعه کنید..SS فیلد currency \f[CR]currency\f[R] یک نماد واحد پولی تعیین می‌کند تا به ابتدای مبالغ تمام ثبت‌ها افزوده شود. اگر مبالغ CSV نماد ارز ندارند، برای نمونه زمانی که در یک ستون جداگانه قرار دارند، می‌توانید از این مورد استفاده کنید. .PP \f[CR]currencyN\f[R] نماد واحد پولی را تنها به ابتدای مبلغ ثبت Nام می‌افزاید. .SS فیلد balance \f[CR]balanceN\f[R] یک مبلغ راستی‌آزمایی تراز (یا اگر مبلغ ثبت خالی رها شود، یک انتساب تراز) را روی ثبت Nام تنظیم می‌کند. .PP \f[CR]balance\f[R] نگارشی برای سازگاری با نسخه‌های پیش از 1.17 برنامهٔ hledger است؛ این مورد معادل \f[CR]balance1\f[R] می‌باشد. .PP می‌توانید نوع راستی‌آزمایی/انتساب را با قاعدهٔ \f[CR]balance\-type\f[R] تنظیم کنید (به بخش زیر مراجعه کنید). .PP برای اطلاعات بیشتر پیرامون تنظیم مبالغ و ارز، به نکات بخش Working with CSV در ادامه مراجعه کنید. .SS بلوک \f[CR]if\f[R] قواعد می‌توانند بسته به الگوهای موجود در داده‌های CSV، به‌صورت شرطی اعمال شوند. این ویژگی انعطاف‌پذیری بالایی فراهم می‌کند؛ به‌ویژه روشی است که از طریق آن می‌توانید تراکنش‌ها را دسته‌بندی کرده و (برای مثال) بر اساس شرح آن‌ها، نام حساب مناسب را انتخاب کنید. دو روش برای نوشتن قواعد شرطی وجود دارد: «بلوک‌های if» که در اینجا توضیح داده شده‌اند، و «جدول‌های if» که در ادامه شرح داده می‌شوند. .PP یک بلوک if شامل کلمهٔ \f[CR]if\f[R] و یک یا چند عبارت «تطبیق‌دهنده» (می‌تواند یک کلمه یا عبارت باشد) در هر سطر است، که از همان سطر یا سطر بعدی آغاز می‌شوند؛ و به دنبال آن یک یا چند قاعدهٔ دندانه‌دار می‌آید. برای نمونه، .IP .EX if MATCHER RULE .EE .PP یا .IP .EX if MATCHER MATCHER MATCHER RULE RULE .EE .PP اگر هر یک از تطبیق‌دهنده‌ها موفق شود، همهٔ قواعد دندانه‌دار اعمال خواهند شد. این قواعد معمولاً انتساب فیلدها هستند، اما قواعد ویژهٔ زیر نیز می‌توانند درون یک بلوک if استفاده شوند: .IP \(bu 2 \f[CR]skip\f[R] \- رکوردِ تطبیق‌یافتهٔ CSV را نادیده می‌گیرد (هیچ تراکنشی از آن ایجاد نمی‌کند) .IP \(bu 2 \f[CR]end\f[R] \- از باقی‌ماندهٔ فایل CSV جاری صرف‌نظر می‌کند. .PP چند مثال: .IP .EX # اگر رکورد شامل «groceries» باشد، account2 را روی «expenses:groceries» تنظیم کن if groceries account2 expenses:groceries .EE .IP .EX # اگر رکورد شامل هر یک از این عبارت‌ها باشد، account2 و یک توضیح تراکنش را مطابق نمایش داده‌شده تنظیم کن if monthly service fee atm transaction fee banking thru software account2 expenses:business:banking comment XXX deductible ? check it .EE .IP .EX # اگر یک رکورد خالی مشاهده شود (با فرض پنج فیلد)، از بقیهٔ فایل CSV صرف‌نظر کن if ,,,, end .EE.SS تطبیق‌دهنده‌ها (Matchers) دو نوع تطبیق‌دهنده وجود دارد: .IP "1." 3 یک تطبیق‌دهنده کل رکورد ساده‌ترین نوع است: صرفاً یک کلمه، تکه‌متن تک‌خطی یا هر عبارت باقاعده دیگری است که hledger تلاش می‌کند آن را بدون حساسیت به بزرگی و کوچکی حروف در هر کجای رکورد CSV تطبیق دهد. .PD 0 .P .PD برای مثال: \f[CR]whole foods\f[R]. .IP "2." 3 یک تطبیق‌دهنده فیلد دارای شماره یا نام فیلد CSV با پیشوند درصد (%) قبل از الگو است. .PD 0 .P .PD برای مثال: \f[CR]%3 whole foods\f[R] یا \f[CR]%description whole foods\f[R]. .PD 0 .P .PD دستور hledger تلاش خواهد کرد تا الگو را صرفاً درون فیلد نام‌برده‌شدهٔ CSV تطبیق دهد. .PP هنگام استفاده از این‌ها، باید به دو نکته توجه داشت: .IP "1." 3 تطبیق‌دهنده‌های کل رکورد، رکورد اصلی و دقیق را نمی‌بینند؛ بلکه بازسازی‌شده‌ای از آن را می‌بینند که در آن مقادیر با کاما از یکدیگر جدا شده‌اند و علامت‌های نقل‌قولِ دربرگیرنده مقادیر و فاصله‌های خالی خارج از آن نقل‌قول‌ها حذف شده‌اند. .PD 0 .P .PD برای مثال، هنگام خواندن یک رکورد SSV مانند: \f[CR]2023\-01\-01 ; \(dqAcme, Inc. \(dq ; 1,000\f[R] .PD 0 .P .PD تطبیق‌دهنده کل رکورد در عوض این مقدار را می‌بیند: \f[CR]2023\-01\-01,Acme, Inc. ,1,000\f[R] .IP "2." 3 تطبیق‌دهنده‌های فیلد انتظار یک شماره فیلد CSV یا نام فیلد CSV تعریف‌شده با \f[CR]fields\f[R] را دارند. هر مقدار دیگری باعث می‌شود که با رشته خالی تطبیق داده شود و احتمالاً بدون هیچ پیامی ناموفق شود (این رفتار، استفاده مجدد از قوانین مشترک با فایل‌های مختلف CSV را آسان‌تر می‌کند). در اینجا از نام فیلد hledger استفاده نکنید (به بخش فیلدهای CSV و فیلدهای hledger مراجعه کنید). .PP همچنین می‌توانید در ابتدای یک تطبیق‌دهنده از \f[CR]!\f[R] (و یک فاصله اختیاری) استفاده کنید تا آن را نقیض کنید. برای مثال \f[CR]! whole foods\f[R]، \f[CR]! %3 whole foods\f[R] و \f[CR]!%description whole foods\f[R] در صورتی تطبیق می‌یابند که عبارت \(dqwhole foods\(dq وجود نداشته باشد. \f[I]اضافه‌شده در نسخه 1.32.\f[R] .PP الگو، طبق معمول در hledger، یک عبارت باقاعده تعمیم‌یافته POSIX است که از مرزهای کلمه گنو (\f[CR]\(rsb\f[R]، \f[CR]\(rsB\f[R]، \f[CR]\(rs<\f[R] و \f[CR]\(rs>\f[R]) و هیچ چیز دیگری پشتیبانی نمی‌کند. برای جزئیات و نکات بیشتر، به بخش «عبارت‌های باقاعده در قوانین CSV» در زیر مراجعه کنید. .SS چندین تطبیق‌دهنده (Multiple matchers) هنگامی که یک بلوک if چندین تطبیق‌دهنده داشته باشد که هر کدام در خط خودش قرار دارد: .IP \(bu 2 به طور پیش‌فرض با یکدیگر OR می‌شوند (تطبیق هر یک از آن‌ها کافی است). .IP \(bu 2 خطوط تطبیق‌دهنده‌ای که با \f[CR]&\f[R] (یا \f[CR]&&\f[R]، \f[I]از نسخه 1.42\f[R]) شروع می‌شوند، با تطبیق‌دهنده بالایی AND می‌شوند (تمام موارد موجود در گروه AND شده باید تطبیق یابند). .IP \(bu 2 خطوط تطبیق‌دهنده‌ای که با \f[CR]& !\f[R] (\f[I]از نسخه 1.41\f[R]، یا \f[CR]&& !\f[R]، \f[I]از نسخه 1.42\f[R]) شروع می‌شوند، ابتدا نقیض شده و سپس با تطبیق‌دهنده بالایی AND می‌شوند. .PP همچنین می‌توانید چندین تطبیق‌دهنده را در همان خط با جداکننده \f[CR]&&\f[R] (عملگر AND) یا \f[CR]&& !\f[R] (عملگر AND NOT) ترکیب کنید. برای مثال \f[CR]%description amazon && %date 2025\-01\-01\f[R] تنها در صورتی تطبیق می‌یابد که فیلد description شامل \(dqamazon\(dq و فیلد date شامل \(dq2025\-01\-01\(dq باشد. \f[I]اضافه‌شده در نسخه 1.42.\f[R] .SS گروه‌های تطبیق (Match groups) \f[I]اضافه‌شده در نسخه 1.32\f[R] .PP تطبیق‌دهنده‌ها می‌توانند گروه‌های تطبیق تعریف کنند: بخش‌های پرانتزدار از عبارت باقاعده که برای ارجاع در انتساب‌های فیلد در دسترس هستند. گروه‌ها در پرانتزهای معمولی (\f[CR](\f[R] و \f[CR])\f[R]) محصور می‌شوند و می‌توانند تو در تو باشند. هر گروه با استفاده از نشانه \f[CR]\(rsN\f[R] در انتساب‌های فیلد قابل دسترسی است، که در آن N نمایه گروه تطبیق برای این بلوک شرطی است (مانند \f[CR]\(rs1\f[R]، \f[CR]\(rs2\f[R] و غیره). .PP مثال: انتقال ثبتهای پرداخت کارت اعتباری به ابتدای دوره صورت‌حساب (آغاز ماه)، برای تطابق با نحوه نمایش آن‌ها در صورت‌حساب‌ها با استفاده از تاریخ‌های ثبت: .IP .EX if %date (....\-..)\-.. comment2 date:\(rs1\-01 .EE .PP مثالی دیگر: خواندن حساب هزینه از فیلد CSV، اما دور انداختن یک پیشوند: .IP .EX if %account1 liabilities:family:(expenses:.*) account1 \(rs1 .EE.SS جدول \f[CR]if\f[R] «جدول‌های if» جایگزینی برای بلوک‌های if هستند؛ آن‌ها می‌توانند تطبیق‌دهنده‌ها و انتساب‌های فیلد متعددی را در قالب جدولی فشرده‌تر بیان کنند، مانند نمونه زیر: .IP .EX if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,... MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) ; Comment line that explains MATCHERD MATCHERD,VALUE1,VALUE2,... .EE .PP نخستین نویسه پس از \f[CR]if\f[R] به عنوان جداکننده فیلد این جدول if در نظر گرفته می‌شود. این جداکننده ارتباطی با جداکننده استفاده‌شده در فایل CSV ندارد. باید یک نویسه غیرحرفی\-عددی مانند \f[CR],\f[R] یا \f[CR]|\f[R] باشد که در هیچ کجای دیگر جدول ظاهر نشود (نباید در نام فیلدها، تطبیق‌دهنده‌ها یا مقادیر استفاده شود و نمی‌توان آن را با یک بک‌اسلش گریز داد). .PP هر خط باید تعداد یکسانی جداکننده داشته باشد؛ مقادیر خالی مجاز هستند. می‌توان برای خوانایی بیشتر از نویسه‌های فاصله (whitespace) در خطوط تطبیق‌دهنده استفاده کرد (اما در حال حاضر نه در خط if). می‌توانید از خطوط توضیحات (کامنت) در بدنه جدول استفاده کنید. جدول باید با یک خط خالی (یا پایان فایل) خاتمه یابد. .PP یک جدول if مانند بالا به این صورت تفسیر می‌شود: تمام خطوط دارای تطبیق‌دهنده بررسی می‌شوند؛ هرگاه خطی با تطبیق‌دهنده موفق شود، تمام مقادیر آن خط به فیلدهای متناظر hledger انتساب می‌یابند؛ اگر چندین خط تطبیق یابند، خطوط بعدی فیلدهای انتساب‌یافته توسط خطوط قبلی را بازنویسی (override) خواهند کرد \- دقیقاً همان رفتاری که توالی بلوک‌های \f[CR]if\f[R] دارند. .PP جدول if نشان‌داده‌شده در بالا معادل این توالی از بلوک‌های if است: .IP .EX if MATCHERA HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... if MATCHERB && MATCHERC HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... ; Comment line which explains MATCHERD if MATCHERD HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... .EE .PP مثال: .IP .EX if,account2,comment atm transaction fee,expenses:business:banking,deductible? check it %description groceries,expenses:groceries, ;; Comment line that desribes why this particular date is special 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call\-out .EE .SS \f[CR]balance\-type\f[R] ارزیابی‌های تراز (balance assertions) تولیدشده با مقداردهی به balanceN به‌طور پیش‌فرض از نوع ساده \f[CR]=\f[R] هستند که یک ارزیابی تک‌کالایی و بدون احتساب زیرحساب‌ها است. ممکن است گونه‌های شامل زیرحساب‌ها را کاربردی‌تر بیابید؛ برای مثال اگر برای کمک به بودجه‌بندی، زیرحساب‌های مجازی برای checking ایجاد کرده باشید. می‌توانید با استفاده از قاعده \f[CR]balance\-type\f[R] نوع دیگری از ارزیابی را انتخاب کنید: .IP .EX # balance assertions will consider all commodities and all subaccounts balance\-type ==* .EE .PP انواع ارزیابی تراز برای ارجاع سریع در زیر آورده شده‌اند: .IP .EX = single commodity, exclude subaccounts =* single commodity, include subaccounts == multi commodity, exclude subaccounts ==* multi commodity, include subaccounts .EE.SS \f[CR]include\f[R] .IP .EX include RULESFILE .EE .PP این دستور، محتویات یک فایل قوانین CSV دیگر را در این نقطه وارد می‌کند. \f[CR]RULESFILE\f[R] یک مسیر فایل مطلق یا یک مسیر نسبی به دایرکتوری فایل فعلی است. این قابلیت می‌تواند برای به‌اشتراک‌گذاری قوانین مشترک بین چندین فایل قوانین مفید باشد؛ برای مثال: .IP .EX # someaccount.csv.rules ## someaccount\-specific rules fields date,description,amount account1 assets:someaccount account2 expenses:misc ## common rules include categorisation.rules .EE .SS کار با CSV چند نکته: .SS بازخورد سریع ایده خوبی است که در حین ایجاد یا عیب‌یابی قوانین CSV، بازخورد سریع دریافت کنید. در اینجا یک روش مناسب با استفاده از entr برگرفته از eradman.com/entrproject آورده شده است: .IP .EX $ ls foo.csv* | entr bash \-c \(aqecho \-\-\-\-; hledger \-f foo.csv print desc:SOMEDESC\(aq .EE .PP یک پرس‌وجوی desc: (برای مثال) برای انتخاب تنها یک یا چند تراکنش مورد نظر استفاده می‌شود. از \(dqbash \-c\(dq برای اجرای چندین دستور استفاده شده است تا بتوانیم با هر بار اجرای مجدد دستور یک جداکننده چاپ کنیم و خواندن خروجی آسان‌تر شود. .SS CSV معتبر توجه داشته باشید که hledger فقط CSVهای معتبر منطبق بر RFC 4180 و قالب‌های معادل SSV و TSV (مانند RFC 4180 اما با نقطه\-ویرگول یا تب به‌عنوان جداکننده) را می‌پذیرد. این بدان معناست که برای مثال: .IP \(bu 2 مقادیر ممکن است در علامت نقل‌قول جفتی قرار گیرند یا نگیرند. قرار دادن در علامت نقل‌قول تکی مجاز نیست. (برای مثال \f[CR]\(aqA\(aq,\(aqB\(aq\f[R] رد می‌شود.) .IP \(bu 2 هنگامی که مقادیر در علامت نقل‌قول جفتی قرار می‌گیرند، فاصله‌ها در بیرون علامت نقل‌قول مجاز نیستند. (برای مثال \f[CR]\(dqA\(dq, \(dqB\(dq\f[R] رد می‌شود.) .IP \(bu 2 هنگامی که مقادیر درون علامت نقل‌قول قرار ندارند، نباید شامل علامت نقل‌قول جفتی باشند. (برای مثال \f[CR]A\(dqA, B\f[R] رد می‌شود.) .PP اگر CSV/SSV/TSV شما از این نظر معتبر نیست، لازم است پیش از خواندن آن با hledger، آن را تبدیل کنید. استفاده از sed یا یک تجزیه‌کننده آسان‌گیرتر CSV مانند کتابخانه csv در python را امتحان کنید. .SS پسوند فایل برای کمک به hledger در انتخاب خواننده فایل CSV و نمایش پیام‌های خطای مناسب (و انتخاب نویسه جداکننده فیلد پیش‌فرض به شکل صحیح)، بهتر است فایل‌های CSV/SSV/TSV با پسوند نام فایل \f[CR].csv\f[R]، \f[CR].ssv\f[R] یا \f[CR].tsv\f[R] نام‌گذاری شوند. (اطلاعات بیشتر در این زمینه در بخش قالب‌های داده آمده است.) .PP هنگام خواندن فایل‌هایی با پسوند «اشتباه»، می‌توانید با اضافه کردن پیشوند \f[CR]csv:\f[R]، \f[CR]ssv:\f[R] یا \f[CR]tsv:\f[R] به ابتدای مسیر فایل، از خواننده CSV (و جداکننده فیلد پیش‌فرض) اطمینان حاصل کنید؛ برای مثال: .IP .EX $ hledger \-f ssv:foo.dat print .EE .PP همچنین در صورت نیاز می‌توانید نویسه جداکننده فیلد پیش‌فرض را با یک قاعده separator بازنویسی و لغو کنید. .SS خواندن CSV از ورودی استاندارد هنگام خواندن CSV از stdin نیز به پیشوند قالب فایل نیاز خواهید داشت، چرا که hledger به طور پیش‌فرض قالب journal را در نظر می‌گیرد. برای مثال: .IP .EX $ cat foo.dat | hledger \-f ssv:\- print .EE.SS خواندن چندین فایل CSV اگر برای خواندن هم‌زمان چندین فایل CSV از چندین گزینهٔ \f[CR]\-f\f[R] استفاده کنید، hledger برای هر فایل CSV به دنبال یک فایل قواعد (rules) با نام متناظر خواهد گشت. اما اگر یک فایل قواعد را با \f[CR]\-\-rules\f[R] مشخص کنید، آن فایل قواعد برای همهٔ فایل‌های CSV استفاده خواهد شد. .SS خواندن فایل‌های مشخص‌شده با قاعده به‌جای مشخص کردن یک فایل CSV در خط فرمان، می‌توانید یک فایل قواعد را مشخص کنید، مانند \f[CR]hledger \-f foo.csv.rules CMD\f[R]. به‌طور پیش‌فرض این کار داده‌ها را از foo.csv در همان دایرکتوری می‌خواند، اما می‌توانید یک قاعدهٔ source برای مشخص کردن فایل داده‌ای متفاوت اضافه کنید، که شاید در دایرکتوری بارگیری‌های مرورگر وب شما قرار داشته باشد. .PP این قابلیت در hledger 1.30 اضافه شده است، بنابراین آن را در بیشتر مثال‌های قواعد CSV نخواهید دید. اما این ویژگی به حذف بخشی از کارهای تکراری مدیریت بارگیری‌های CSV کمک می‌کند. نام‌های پیش‌فرض فایل‌های CSV در اکثر مؤسسات مالی شما متفاوت است و با یک الگوی glob قابل شناسایی است. بنابراین می‌توانید قاعده‌ای مانند \f[CR]source Checking1*.csv\f[R] را در foo\-checking.csv.rules قرار دهید و سپس به‌طور دوره‌ای روال کاری‌ای مانند زیر را دنبال کنید: .IP "1." 3 بارگیری CSV از وب‌سایت Foo، با استفاده از پیش‌فرض‌های مرورگرتان .IP "2." 3 اجرای \f[CR]hledger import foo\-checking.csv.rules\f[R] برای وارد کردن هرگونه تراکنش جدید .PP پس از وارد کردن (import)، می‌توانید به دلخواه خود: فایل CSV را دور بیندازید، یا آن را برای مدتی همان‌جا که هست رها کنید، یا آن را به بایگانی‌های خود منتقل کنید. اگر کاری انجام ندهید، دفعهٔ بعد مرورگر شما فایلی مانند Checking1\-2.csv را ذخیره خواهد کرد، و hledger به دلیل نویسهٔ عام (wildcard) \f[CR]*\f[R] و به این دلیل که جدیدترین است، از آن استفاده خواهد کرد. .SS تراکنش‌های معتبر پس از خواندن یک فایل CSV،‏ hledger ورودی‌های دفترکل تولیدشده را همانند یک فایل دفترکل پس‌پردازش و اعتبارسنجی می‌کند \- تراز کردن آن‌ها، اعمال تخصیص‌های تراز (balance assignments)، و استانداردسازی قالب مبالغ. هرگونه خطا در این مرحله به روش معمول با نمایش ورودی مشکل‌دار گزارش خواهد شد. .PP یک استثنا وجود دارد: در صورت ایجاد احکام تراز (balance assertions)، آن‌ها بررسی نخواهند شد، زیرا این احکام معمولاً تنها زمانی عمل می‌کنند که داده‌های CSV بخشی از دفترکل اصلی باشند. اگر نیاز دارید احکام تراز تولیدشده از CSV را فوراً بررسی کنید، آن را با لوله (pipe) به یک hledger دیگر بفرستید: .IP .EX $ hledger \-f file.csv print | hledger \-f\- print .EE .SS حذف موارد تکراری، وارد کردن هنگامی که یک فایل CSV را به‌طور دوره‌ای بارگیری می‌کنید (برای مثال دریافت آخرین تراکنش‌های بانکی‌تان)، فایل جدید ممکن است با فایل قدیمی هم‌پوشانی داشته باشد و شامل برخی از رکوردهای مشابه باشد. .PP دستور import اقدامات زیر را انجام می‌دهد: (الف) تراکنش‌های جدید را شناسایی می‌کند، و (ب) فقط همان تراکنش‌ها را به دفترکل اصلی شما پیوست (append) می‌کند. این دستور خنثی‌اثر (idempotent) است، بنابراین نیازی نیست به یاد داشته باشید که چند بار آن را اجرا کرده‌اید یا با کدام نسخه از CSV. (این دستور وضعیت را در یک فایل پنهان \f[CR].latest.FILE.csv\f[R] نگه می‌دارد.) این آسان‌ترین راه برای وارد کردن داده‌های CSV است. به عنوان مثال: .IP .EX # download the latest CSV files, then run this command. # Note, no \-f flags needed here. $ hledger import *.csv [\-\-dry] .EE .PP این روش برای بیشتر فایل‌های CSV کار می‌کند. (جایی که رکوردها ترتیب زمانی پایداری دارند، و رکوردهای جدید فقط در انتهای جدیدتر ظاهر می‌شوند.) .PP تعدادی ابزار و روال‌های کاری دیگر، چه اختصاصی hledger و چه غیر از آن، برای تبدیل، حذف تکرار، دسته‌بندی و مدیریت داده‌های CSV وجود دارند. ببینید: .IP \(bu 2 https://hledger.org/cookbook.html#setups\-and\-workflows .IP \(bu 2 https://plaintextaccounting.org \-> data import/conversion .SS عبارت‌های منظم در قواعد CSV عبارت‌های منظم در شرط‌های \f[CR]if\f[R] (همچنین معروف به تطبیق‌دهنده‌ها یا matchers) عبارت‌های منظم گسترش‌یافتهٔ POSIX هستند که از مرزهای کلمهٔ گنو (\f[CR]\(rsb\f[R]، \f[CR]\(rsB\f[R]، \f[CR]\(rs<\f[R]، \f[CR]\(rs>\f[R]) نیز پشتیبانی می‌کنند، و نه چیز دیگر. (برای جزئیات بیشتر، Regular expressions را ببینید.) .PP در اینجا چند مثال آورده شده است که ممکن است در قواعد CSV مفید باشند: .IP \(bu 2 آیا فیلد \(dqfoo\(dq واقعاً خالی است؟ \f[CR]if %foo \(ha$\f[R] .IP \(bu 2 آیا خالی است یا فقط شامل نویسه‌های فاصله‌ای (whitespace) است؟ \f[CR]if %foo \(ha *$\f[R] .IP \(bu 2 آیا غیرخالی است؟ \f[CR]if %foo .\f[R] .IP \(bu 2 آیا شامل نویسهٔ غیرفاصله‌ای است؟ \f[CR]if %foo [\(ha ]\f[R] .PP آزمودن مقدار فیلدهای عددی کمی دشوارتر است. نمی‌توانید از پرس‌وجوهای hledger مانند \f[CR]amt:0\f[R] یا \f[CR]amt:>10\f[R] در قواعد CSV استفاده کنید. اما اغلب می‌توانید با یک عبارت منظم به همان نتیجه برسید. .PP توجه داشته باشید که محتوا و چیدمان فیلدهای عددی در CSV متفاوت است، و می‌تواند به مرور زمان تغییر کند (مثلاً اگر ارائه‌دهندهٔ داده را تغییر دهید). بنابراین عبارت‌های منظم عددی همیشه تا حدودی مختص به داده‌های CSV خاص شما هستند؛ و ایدهٔ خوبی است که در صورت امکان آن‌ها را با رویکرد دفاعی و مقاوم (defensive and robust) بنویسید. .PP در اینجا چند مثال آورده شده است: .IP \(bu 2 آیا foo شامل یک عدد غیرصفر است؟ \f[CR]if %foo [1\-9]\f[R] .IP \(bu 2 آیا منفی است؟ \f[CR]if %foo \-\f[R] .IP \(bu 2 آیا نامنفی است؟ \f[CR]if ! %foo \-\f[R] .IP \(bu 2 آیا >= 10 است؟ \f[CR]if %foo [1\-9][0\-9]+\(rs.\f[R] (با فرض ممیز اعشاری نقطه‌ای و بدون صفرهای ابتدایی) .IP \(bu 2 آیا >= 10 و < 20 است؟ \f[CR]if %foo \(rsb1[0\-9]\(rs.\f[R].SS تنظیم مقادیر در ادامهٔ فیلد مقدار در بالا، در اینجا نکات بیشتری برای تنظیم مقادیر آورده شده است: .IP "1." 3 \f[B]اگر مقدار در یک فیلد تکی CSV باشد:\f[R] .PD 0 .P .PD .RS 4 .IP "a." 3 \f[B]اگر علامت آن نشان‌دهندهٔ جهت جریان باشد:\f[R] .PD 0 .P .PD آن را به \f[CR]amountN\f[R] اختصاص دهید تا مقدار ثبت N-ام تنظیم شود. N معمولاً ۱ یا ۲ است اما می‌تواند تا ۹۹ باشد. .IP "b." 3 \f[B]اگر فیلد دیگری نشان‌دهندهٔ جهت جریان باشد:\f[R] .PD 0 .P .PD برای تنظیم علامت مناسب مقدار، از یک یا چند قاعدهٔ شرطی استفاده کنید. برای نمونه: .IP .EX # assume a withdrawal unless Type contains \(dqdeposit\(dq: amount1 \-%Amount if %Type deposit amount1 %Amount .EE .RE .IP "2." 3 \f[B]اگر مقدار در دو فیلد CSV باشد (مانند Debit و Credit، یا In و Out):\f[R] .PD 0 .P .PD .RS 4 .IP "a." 3 \f[B]اگر هر دو فیلد بدون علامت باشند:\f[R] .PD 0 .P .PD یک فیلد را به \f[CR]amountN\-in\f[R] و دیگری را به \f[CR]amountN\-out\f[R] اختصاص دهید. hledger به‌طور خودکار فیلد \(dqout\(dq را منفی می‌کند و مقدار هر فیلدی را که غیرصفر باشد به‌عنوان مقدار ثبت N-ام استفاده خواهد کرد. .IP "b." 3 \f[B]اگر هر یک از فیلدها دارای علامت باشد:\f[R] .PD 0 .P .PD احتمالاً لازم خواهد بود علامت تعیین‌شده توسط hledger را برای یکی از فیلدها بازنویسی کنید، همان‌طور که در مثال زیر آمده است: .IP .EX # Negate the \-out value, but only if it is not empty: fields date, description, amount1\-in, amount1\-out if %amount1\-out [1\-9] amount1\-out \-%amount1\-out .EE .IP "c." 3 \f[B]اگر هر دو فیلد بتوانند شامل مقداری غیرصفر باشند (یا هر دو خالی باشند):\f[R] .PD 0 .P .PD قواعد \-in/\-out معمولاً مقداری را انتخاب می‌کنند که غیرصفر/غیرخالی باشد. برخی جفت‌مقادیر ممکن است مبهم باشند، مانند \f[CR]1\f[R] و \f[CR]none\f[R]. برای چنین مواردی، از قواعد شرطی برای کمک به انتخاب مقدار استفاده کنید. برای مثال، برای مدیریت مورد بالا می‌توانید مقداری را انتخاب کنید که شامل ارقام غیرصفر باشد: .IP .EX fields date, description, in, out if %in [1\-9] amount1 %in if %out [1\-9] amount1 %out .EE .RE .IP "3." 3 \f[B]اگر می‌خواهید مقدار ثبت ۲ به بهای تمام‌شده (cost) تبدیل شود:\f[R] .PD 0 .P .PD از نحو بدون شمارهٔ \f[CR]amount\f[R] (یا \f[CR]amount\-in\f[R] و \f[CR]amount\-out\f[R]) استفاده کنید. .IP "4." 3 \f[B]اگر CSV تنها شامل مقادیر مانده باشد و نه مقادیر تراکنش:\f[R] .PD 0 .P .PD آن را به \f[CR]balanceN\f[R] اختصاص دهید تا یک انتساب مانده روی ثبت N-ام تنظیم شود و باعث محاسبهٔ خودکار مقدار ثبت گردد. \f[CR]balance\f[R] بدون شماره معادل \f[CR]balance1\f[R] است. در این وضعیت احتمال اینکه hledger نام حساب پیش‌فرض را اشتباه حدس بزند بیشتر است، بنابراین ممکن است لازم باشد آن را به‌طور صریح تنظیم کنید..SS علامت‌های مقدار (Amount signs) رفتار ویژه‌ای وجود دارد که تجزیه و معکوس کردن علامت‌های مقدار را آسان‌تر می‌کند. (این قابلیت فقط برای مقادیر کامل کار می‌کند، نه برای مقادیر هزینه مانند COST در \f[CR]amount1 AMT \(at COST\f[R]): .IP \(bu 2 \f[B]اگر مقدار با یک علامت مثبت آغاز شود:\f[R] .PD 0 .P .PD آن علامت حذف خواهد شد: \f[CR]+AMT\f[R] تبدیل می‌شود به \f[CR]AMT\f[R] .IP \(bu 2 \f[B]اگر مقدار درون پرانتز باشد:\f[R] .PD 0 .P .PD پرانتزهای آن حذف شده و علامت آن معکوس می‌شود: \f[CR](AMT)\f[R] تبدیل می‌شود به \f[CR]\-AMT\f[R] .IP \(bu 2 \f[B]اگر مقدار دو علامت منفی داشته باشد (یا دو جفت پرانتز، یا یک علامت منفی و پرانتز):\f[R] .PD 0 .P .PD اثر یکدیگر را خنثی کرده و حذف خواهند شد: \f[CR]\-\-AMT\f[R] یا \f[CR]\-(AMT)\f[R] تبدیل می‌شود به \f[CR]AMT\f[R] .IP \(bu 2 \f[B]اگر مقدار فقط شامل یک علامت باشد (یا فقط یک جفت پرانتز):\f[R] .PD 0 .P .PD آن علامت حذف شده و به یک مقدار خالی تبدیل می‌شود. \f[CR]\(dq+\(dq\f[R] یا \f[CR]\(dq\-\(dq\f[R] یا \f[CR]\(dq()\(dq\f[R] تبدیل می‌شود به \f[CR]\(dq\(dq\f[R]. .PP تنظیم یک مقدار روی قدر مطلق آن، یعنی نادیده گرفتن علامت آن، (بدون پیش‌پردازش CSV) امکان‌پذیر نیست. .SS تنظیم ارز/کالا (Setting currency/commodity) اگر نماد ارز/کالا در فیلد(های) مقدارِ فایل CSV گنجانده شده باشد: .IP .EX 2023\-01\-01,foo,$123.00 .EE .PP نیازی به انجام کار خاصی برای نماد کالا ندارید، این نماد به عنوان بخشی از مقدار تخصیص داده می‌شود. به عنوان مثال: .IP .EX fields date,description,amount .EE .IP .EX 2023\-01\-01 foo expenses:unknown $123.00 income:unknown $\-123.00 .EE .PP اگر ارز به صورت یک فیلد جداگانه در CSV ارائه شده باشد: .IP .EX 2023\-01\-01,foo,USD,123.00 .EE .PP می‌توانید آن را به شبه‌فیلد \f[CR]currency\f[R] تخصیص دهید، که این ویژگی خاص را دارد که به ابتدای هر مقدار در تراکنش اضافه می‌شود (در سمت چپ، بدون فاصله جداکننده): .IP .EX fields date,description,currency,amount .EE .IP .EX 2023\-01\-01 foo expenses:unknown USD123.00 income:unknown USD\-123.00 .EE .PP یا می‌توانید از انتساب فیلد برای ساختن مقدار توسط خودتان و با کنترل بیشتر استفاده کنید. برای مثال، جهت قرار دادن نماد در سمت راست و با یک فاصله جداکننده: .IP .EX fields date,description,cur,amt amount %amt %cur .EE .IP .EX 2023\-01\-01 foo expenses:unknown 123.00 USD income:unknown \-123.00 USD .EE .PP توجه داشته باشید که از نام فیلد موقتی (\f[CR]cur\f[R]) استفاده کردیم که \f[CR]currency\f[R] نیست \- چرا که در غیر این صورت اثر پیش‌افزودن فعال می‌شد، چیزی که در اینجا نمی‌خواهیم..SS ارقام اعشار مبلغ هنگامی که داده‌های CSV را می‌خوانید، مثلاً با دستوری مانند \f[CR]hledger \-f foo.csv print\f[R]، hledger دقت اعشار هر کالا (و دیگر شیوه‌های نمایش آن) را از روی مبالغ استنتاج می‌کند \- بسیار شبیه به خواندن یک فایل دفتر روزنامه بدون دستورالعمل‌های \f[CR]commodity\f[R] (پیوند را ببینید). .PP توجه داشته باشید که شیوه‌های نمایش کالا از اعداد موجود در داده‌های اصلی CSV استنتاج نمی‌شوند؛ بلکه از مبالغ تولیدشده توسط قواعد CSV استنباط می‌گردند. .PP هنگامی که داده‌های CSV را با دستور \f[CR]import\f[R] وارد می‌کنید، به عنوان مثال \f[CR]hledger import foo.csv\f[R]، گام دیگری نیز وجود دارد: \f[CR]import\f[R] تلاش می‌کند مدخل‌های جدید را با شیوه‌های موجود در دفتر روزنامه مطابقت دهد. بنابراین برای هر کالا \- فرض کنید EUR باشد \- دستور \f[CR]import\f[R] موارد زیر را برمی‌گزیند: .IP "1." 3 شیوه اعلان‌شده برای EUR با یک دستورالعمل \f[CR]commodity\f[R] در دفتر روزنامه .IP "2." 3 در غیر این صورت، شیوه استنتاج‌شده از مبالغ EUR در دفتر روزنامه .IP "3." 3 در غیر این صورت، شیوه استنتاج‌شده از مبالغ EUR تولیدشده توسط قواعد CSV. .PP خلاصه (TLDR): اگر \f[CR]import\f[R] دقت‌ها یا شیوه‌های مورد نظر شما را تولید نمی‌کند، یک دستورالعمل \f[CR]commodity\f[R] برای مشخص کردن آن‌ها اضافه کنید. .SS ارجاع به فیلدهای دیگر در انتساب فیلدها، شما تنها می‌توانید فیلدهای CSV را جای‌گذاری کنید، نه فیلدهای hledger را. در مثال زیر، هم یک فیلد CSV و هم یک فیلد hledger به نام amount1 وجود دارد، اما %amount1 همیشه به فیلد CSV اشاره دارد، نه فیلد hledger: .IP .EX # Name the third CSV field \(dqamount1\(dq fields date,description,amount1 # Set hledger\(aqs amount1 to the CSV amount1 field followed by USD amount1 %amount1 USD # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 .EE .PP در اینجا، از آنجا که فیلد amount1 در CSV وجود ندارد، %amount1 مقدار لفظی \(dqamount1\(dq را تولید خواهد کرد: .IP .EX fields date,description,csvamount amount1 %csvamount USD # Can\(aqt interpolate amount1 here comment %amount1 .EE .PP هنگامی که چندین انتساب فیلد به یک فیلد یکسان در hledger وجود دارد، تنها آخرین انتساب اعمال می‌شود. در اینجا، مقدار comment برابر با B خواهد بود، یا اگر عبارت \(dqsomething\(dq تطبیق داده شود مقدار آن C خواهد بود، اما هرگز A نخواهد بود: .IP .EX comment A comment B if something comment C .EE .SS نحوه ارزیابی قواعد CSV در ادامه نحوه ارزیابی قواعد CSV تشریح شده است. اگر هنگام خواندن یک فایل CSV با خطایی نامفهوم مواجه شدید، درک اینکه کدام‌یک از این مراحل با شکست مواجه شده است می‌تواند به شما کمک کند: .IP "1." 3 تمام فایل‌های قواعد الحاق‌شده (included)، از بالا به پایین و به روش اول‌عمق (بررسی بازگشتی هر فایل الحاق‌شده برای الحاق‌های بعدی، پیش از ادامه) درون‌ریزی می‌شوند. .IP "2." 3 قواعد سطح بالا (\f[CR]date\-format\f[R]، \f[CR]fields\f[R]، \f[CR]newest\-first\f[R]، \f[CR]skip\f[R] و غیره) از بالا به پایین خوانده می‌شوند. منظور از \(dqقواعد سطح بالا\(dq قواعد غیرشرطی است. اگر قاعده‌ای بیش از یک بار تکرار شود، آخرین قاعده اعمال می‌شود؛ به استثنای قواعد \f[CR]skip\f[R]/\f[CR]end\f[R] که در آن‌ها اولین قاعده اولویت دارد. .IP "3." 3 فایل CSV به عنوان متن خوانده می‌شود. هر نویسه غیر ASCII با استفاده از کدگذاری متنی تعیین‌شده توسط قاعده \f[CR]encoding\f[R]، و در غیر این صورت با کدگذاری متنی لوکال (locale) سیستم، رمزگشایی خواهد شد. .IP "4." 3 هر قاعده skip یا end در سطح بالا اعمال می‌شود. قاعده \f[CR]skip [N]\f[R] بلافاصله از رکورد فعلی یا N رکورد بعدی CSV صرف‌نظر می‌کند؛ قاعده \f[CR]end\f[R] بلافاصله از تمام رکوردهای باقیمانده CSV صرف‌نظر می‌کند (به طور معمول در سطح بالا استفاده نمی‌شود). .IP "5." 3 اکنون رکوردهای باقیمانده CSV پردازش می‌شوند. برای هر رکورد CSV، به ترتیبی که در فایل آمده است: .RS 4 .IP \(bu 2 آیا قاعده skip/end شرطی وجود دارد که برای این رکورد اعمال شود؟ بلوک‌های \f[CR]if\f[R] را از بالا به پایین برای یافتن بلوک برقراری که حاوی قاعده \f[CR]skip\f[R] یا \f[CR]end\f[R] است جستجو کنید. در صورت یافتن، از تعداد مشخص‌شده رکوردهای CSV صرف‌نظر کرده و سپس از مرحله ۵ ادامه دهید. .PD 0 .P .PD در غیر این صورت... .IP \(bu 2 برخی اعتبارسنجی‌های اولیه را روی این رکورد CSV انجام دهید (مثلاً بررسی اینکه حداقل دارای دو فیلد باشد). .IP \(bu 2 برای هر فیلد hledger (\f[CR]date\f[R]، \f[CR]description\f[R]، \f[CR]account1\f[R] و غیره): .RS 2 .IP "1." 3 مقدار انتساب‌یافته به فیلد را به دست آورید؛ ابتدا در انتساب‌های سطح بالا (که مستقیماً یا توسط قاعده \f[CR]fields\f[R] انجام شده‌اند) و سپس در انتساب‌های انجام‌شده درون بلوک‌های موفق \f[CR]if\f[R] جستجو می‌شود. اگر بیش از یک انتساب وجود داشته باشد، آخرین مورد اعمال می‌شود. .IP "2." 3 مقدار واقعی فیلد (به صورت متن) را با جای‌گذاری هرگونه ارجاع به %CSVFIELD درون مقدار انتساب‌یافته محاسبه کنید؛ یا در صورت عدم وجود انتساب، یک مقدار پیش‌فرض را انتخاب نمایید. .RE .IP \(bu 2 از روی مقادیر فیلدهای hledger یک تراکنش hledger ایجاد کرده و در صورت نیاز آن‌ها را تجزیه کنید (مثلاً تبدیل متن به یک مبلغ). .RE .PP تمام این مراحل توسط خواننده CSV انجام می‌شود؛ یکی از چندین خواننده‌ای که hledger می‌تواند برای خواندن تراکنش‌ها از یک فایل ورودی به کار گیرد. هنگامی که همه فایل‌های ورودی با موفقیت خوانده شدند، تراکنش‌های آن‌ها به هر دستوری از hledger که کاربر مشخص کرده باشد تحویل داده می‌شوند..SS قواعد خوش‌ساختار مواردی که می‌توانند به کاهش تکرار و پیچیدگی در فایل‌های قواعد کمک کنند: .IP \(bu 2 استخراج قواعد مشترک قابل استفاده با چندین فایل CSV درون یک \f[CR]common.rules\f[R]، و افزودن \f[CR]include common.rules\f[R] به فایل قواعد هر CSV. .IP \(bu 2 تقسیم بلوک‌های if به بلوک‌های if کوچک‌تر و استخراج بخش‌های پرکاربرد. .SS مثال‌های قواعد CSV .SS Bank of Ireland در اینجا یک فایل CSV با دو فیلد مبلغ (Debit و Credit) و یک فیلد موجودی (Balance) آمده است که می‌توانیم از آن برای افزودن اعتبارسنجی‌های موجودی (balance assertions) استفاده کنیم؛ این کار الزامی نیست اما امکان بررسی خطای بیشتری را فراهم می‌کند: .IP .EX Date,Details,Debit,Credit,Balance 07/12/2012,LODGMENT 529898,,10.0,131.21 07/12/2012,PAYMENT,5,,126 .EE .IP .EX # bankofireland\-checking.csv.rules # skip the header line skip # name the csv fields, and assign some of them as journal entry fields fields date, description, amount\-out, amount\-in, balance # We generate balance assertions by assigning to \(dqbalance\(dq # above, but you may sometimes need to remove these because: # # \- the CSV balance differs from the true balance, # by up to 0.0000000000005 in my experience # # \- it is sometimes calculated based on non\-chronological ordering, # eg when multiple transactions clear on the same day # date is in UK/Ireland format date\-format %d/%m/%Y # set the currency currency EUR # set the base account for all txns account1 assets:bank:boi:checking .EE .IP .EX $ hledger \-f bankofireland\-checking.csv print 2012\-12\-07 LODGMENT 529898 assets:bank:boi:checking EUR10.0 = EUR131.2 income:unknown EUR\-10.0 2012\-12\-07 PAYMENT assets:bank:boi:checking EUR\-5.0 = EUR126.0 expenses:unknown EUR5.0 .EE .PP اعتبارسنجی‌های موجودی در بالا خطایی ایجاد نمی‌کنند، زیرا خواندن مستقیماً از CSV انجام می‌شود، اما اگر این مدخل‌ها به یک فایل journal وارد شوند، بررسی خواهند شد. .SS Coinbase یک مثال ساده با داده‌های CSV از Coinbase. قیمت لحظه‌ای (spot price) با استفاده از نمادگذاری هزینه (cost notation) ثبت شده است. نام فیلد قدیمی \f[CR]amount\f[R] به‌راحتی مبلغ ۲ (مبلغ posting دوم) را برابر با هزینه کل قرار می‌دهد. .IP .EX # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes # 2021\-12\-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,\(dq\(dq,\(dq\(dq,\(dq\(dq,\(dqReceived 100.00 USDC from an external account\(dq .EE .IP .EX # coinbase.csv.rules skip 1 fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes date %Timestamp date\-format %Y\-%m\-%dT%T%Z description %Notes account1 assets:coinbase:cc amount %Quantity_Transacted %Asset \(at %Spot_Price_at_Transaction %Spot_Price_Currency .EE .IP .EX $ hledger print \-f coinbase.csv 2021\-12\-30 Received 100.00 USDC from an external account assets:coinbase:cc 100 USDC \(at 0.740000 GBP income:unknown \-74.000000 GBP .EE.SS Amazon در اینجا تاریخچهٔ سفارش‌های amazon.com را تبدیل کرده و از یک بلوک if برای ایجاد یک ثبت (posting) سوم در صورت وجود کارمزد استفاده می‌کنیم. (در عمل احتمالاً این داده‌ها را به جای آن از بانک خود دریافت خواهید کرد، اما این فقط یک مثال است.) .IP .EX \(dqDate\(dq,\(dqType\(dq,\(dqTo/From\(dq,\(dqName\(dq,\(dqStatus\(dq,\(dqAmount\(dq,\(dqFees\(dq,\(dqTransaction ID\(dq \(dqJul 29, 2012\(dq,\(dqPayment\(dq,\(dqTo\(dq,\(dqFoo.\(dq,\(dqCompleted\(dq,\(dq$20.00\(dq,\(dq$0.00\(dq,\(dq16000000000000DGLNJPI1P9B8DKPVHL\(dq \(dqJul 30, 2012\(dq,\(dqPayment\(dq,\(dqTo\(dq,\(dqAdapteva, Inc.\(dq,\(dqCompleted\(dq,\(dq$25.00\(dq,\(dq$1.00\(dq,\(dq17LA58JSKRD4HDGLNJPI1P9B8DKPVHL\(dq .EE .IP .EX # amazon\-orders.csv.rules # رد کردن یک خط سربرگ skip 1 # نام‌گذاری فیلدهای csv، و انتساب تاریخ، مبلغ و کد تراکنش. # برای جلوگیری از سردرگمی، از نام‌های فیلد hledger یعنی \(dqstatus\(dq و \(dqamount\(dq پرهیز شد. fields date, _, toorfrom, name, amzstatus, amzamount, fees, code # نحوهٔ تجزیهٔ تاریخ date\-format %b %\-d, %Y # ترکیب دو فیلد برای ساخت description description %toorfrom %name # ذخیرهٔ وضعیت به عنوان یک برچسب (tag) comment status:%amzstatus # تنظیم حساب پایه برای تمام تراکنش‌ها account1 assets:amazon # خالی گذاشتن amount1 تا بتواند مورد(های) دیگر را تراز کند. # فرض می‌کنم amzamount کارمزدها را شامل نمی‌شود، دقیقاً به خاطر ندارم # تنظیم یک account2 عمومی account2 expenses:misc amount2 %amzamount # و شاید پالایش بیشتر آن: #include categorisation.rules # افزودن ثبت سوم برای کارمزدها، اما فقط در صورتی که غیرصفر باشند. if %fees [1\-9] account3 expenses:fees amount3 %fees .EE .IP .EX $ hledger \-f amazon\-orders.csv print 2012\-07\-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed assets:amazon expenses:misc $20.00 2012\-07\-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed assets:amazon expenses:misc $25.00 expenses:fees $1.00 .EE .SS Paypal در اینجا یک فایل قوانین واقعی برای CSV (سفارشی‌شدهٔ) Paypal، همراه با برخی قوانین ویژهٔ Paypal و یک فایل قوانین دوم گنجانده‌شده آمده است: .IP .EX \(dqDate\(dq,\(dqTime\(dq,\(dqTimeZone\(dq,\(dqName\(dq,\(dqType\(dq,\(dqStatus\(dq,\(dqCurrency\(dq,\(dqGross\(dq,\(dqFee\(dq,\(dqNet\(dq,\(dqFrom Email Address\(dq,\(dqTo Email Address\(dq,\(dqTransaction ID\(dq,\(dqItem Title\(dq,\(dqItem ID\(dq,\(dqReference Txn ID\(dq,\(dqReceipt ID\(dq,\(dqBalance\(dq,\(dqNote\(dq \(dq10/01/2019\(dq,\(dq03:46:20\(dq,\(dqPDT\(dq,\(dqCalm Radio\(dq,\(dqSubscription Payment\(dq,\(dqCompleted\(dq,\(dqUSD\(dq,\(dq\-6.99\(dq,\(dq0.00\(dq,\(dq\-6.99\(dq,\(dqsimon\(atjoyful.com\(dq,\(dqmemberships\(atcalmradio.com\(dq,\(dq60P57143A8206782E\(dq,\(dqMONTHLY \- $1 for the first 2 Months: Me \- Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month\(dq,\(dq\(dq,\(dqI\-R8YLY094FJYR\(dq,\(dq\(dq,\(dq\-6.99\(dq,\(dq\(dq \(dq10/01/2019\(dq,\(dq03:46:20\(dq,\(dqPDT\(dq,\(dq\(dq,\(dqBank Deposit to PP Account \(dq,\(dqPending\(dq,\(dqUSD\(dq,\(dq6.99\(dq,\(dq0.00\(dq,\(dq6.99\(dq,\(dq\(dq,\(dqsimon\(atjoyful.com\(dq,\(dq0TU1544T080463733\(dq,\(dq\(dq,\(dq\(dq,\(dq60P57143A8206782E\(dq,\(dq\(dq,\(dq0.00\(dq,\(dq\(dq \(dq10/01/2019\(dq,\(dq08:57:01\(dq,\(dqPDT\(dq,\(dqPatreon\(dq,\(dqPreApproved Payment Bill User Payment\(dq,\(dqCompleted\(dq,\(dqUSD\(dq,\(dq\-7.00\(dq,\(dq0.00\(dq,\(dq\-7.00\(dq,\(dqsimon\(atjoyful.com\(dq,\(dqsupport\(atpatreon.com\(dq,\(dq2722394R5F586712G\(dq,\(dqPatreon* Membership\(dq,\(dq\(dq,\(dqB\-0PG93074E7M86381M\(dq,\(dq\(dq,\(dq\-7.00\(dq,\(dq\(dq \(dq10/01/2019\(dq,\(dq08:57:01\(dq,\(dqPDT\(dq,\(dq\(dq,\(dqBank Deposit to PP Account \(dq,\(dqPending\(dq,\(dqUSD\(dq,\(dq7.00\(dq,\(dq0.00\(dq,\(dq7.00\(dq,\(dq\(dq,\(dqsimon\(atjoyful.com\(dq,\(dq71854087RG994194F\(dq,\(dqPatreon* Membership\(dq,\(dq\(dq,\(dq2722394R5F586712G\(dq,\(dq\(dq,\(dq0.00\(dq,\(dq\(dq \(dq10/19/2019\(dq,\(dq03:02:12\(dq,\(dqPDT\(dq,\(dqWikimedia Foundation, Inc.\(dq,\(dqSubscription Payment\(dq,\(dqCompleted\(dq,\(dqUSD\(dq,\(dq\-2.00\(dq,\(dq0.00\(dq,\(dq\-2.00\(dq,\(dqsimon\(atjoyful.com\(dq,\(dqtle\(atwikimedia.org\(dq,\(dqK9U43044RY432050M\(dq,\(dqMonthly donation to the Wikimedia Foundation\(dq,\(dq\(dq,\(dqI\-R5C3YUS3285L\(dq,\(dq\(dq,\(dq\-2.00\(dq,\(dq\(dq \(dq10/19/2019\(dq,\(dq03:02:12\(dq,\(dqPDT\(dq,\(dq\(dq,\(dqBank Deposit to PP Account \(dq,\(dqPending\(dq,\(dqUSD\(dq,\(dq2.00\(dq,\(dq0.00\(dq,\(dq2.00\(dq,\(dq\(dq,\(dqsimon\(atjoyful.com\(dq,\(dq3XJ107139A851061F\(dq,\(dq\(dq,\(dq\(dq,\(dqK9U43044RY432050M\(dq,\(dq\(dq,\(dq0.00\(dq,\(dq\(dq \(dq10/22/2019\(dq,\(dq05:07:06\(dq,\(dqPDT\(dq,\(dqNoble Benefactor\(dq,\(dqSubscription Payment\(dq,\(dqCompleted\(dq,\(dqUSD\(dq,\(dq10.00\(dq,\(dq\-0.59\(dq,\(dq9.41\(dq,\(dqnoble\(atbene.fac.tor\(dq,\(dqsimon\(atjoyful.com\(dq,\(dq6L8L1662YP1334033\(dq,\(dqJoyful Systems\(dq,\(dq\(dq,\(dqI\-KC9VBGY2GWDB\(dq,\(dq\(dq,\(dq9.41\(dq,\(dq\(dq .EE .IP .EX # paypal\-custom.csv.rules # نکته‌ها: # برون‌بری از Activity \-> Statements \-> Custom \-> Activity download # نوع تراکنش پیشنهادی: \(dqBalance affecting\(dq # فیلدهای پیش‌فرض Paypal در سال ۲۰۱۸ عبارت بودند از: # \(dqDate\(dq,\(dqTime\(dq,\(dqTimeZone\(dq,\(dqName\(dq,\(dqType\(dq,\(dqStatus\(dq,\(dqCurrency\(dq,\(dqGross\(dq,\(dqFee\(dq,\(dqNet\(dq,\(dqFrom Email Address\(dq,\(dqTo Email Address\(dq,\(dqTransaction ID\(dq,\(dqShipping Address\(dq,\(dqAddress Status\(dq,\(dqItem Title\(dq,\(dqItem ID\(dq,\(dqShipping and Handling Amount\(dq,\(dqInsurance Amount\(dq,\(dqSales Tax\(dq,\(dqOption 1 Name\(dq,\(dqOption 1 Value\(dq,\(dqOption 2 Name\(dq,\(dqOption 2 Value\(dq,\(dqReference Txn ID\(dq,\(dqInvoice Number\(dq,\(dqCustom Number\(dq,\(dqQuantity\(dq,\(dqReceipt ID\(dq,\(dqBalance\(dq,\(dqAddress Line 1\(dq,\(dqAddress Line 2/District/Neighborhood\(dq,\(dqTown/City\(dq,\(dqState/Province/Region/County/Territory/Prefecture/Republic\(dq,\(dqZip/Postal Code\(dq,\(dqCountry\(dq,\(dqContact Phone Number\(dq,\(dqSubject\(dq,\(dqNote\(dq,\(dqCountry Code\(dq,\(dqBalance Impact\(dq # این فایل قوانین، فیلدهای دقیق‌تر زیر را که در \(dqCustomize report fields\(dq پیکربندی شده‌اند، فرض می‌کند: # \(dqDate\(dq,\(dqTime\(dq,\(dqTimeZone\(dq,\(dqName\(dq,\(dqType\(dq,\(dqStatus\(dq,\(dqCurrency\(dq,\(dqGross\(dq,\(dqFee\(dq,\(dqNet\(dq,\(dqFrom Email Address\(dq,\(dqTo Email Address\(dq,\(dqTransaction ID\(dq,\(dqItem Title\(dq,\(dqItem ID\(dq,\(dqReference Txn ID\(dq,\(dqReceipt ID\(dq,\(dqBalance\(dq,\(dqNote\(dq fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note skip 1 date\-format %\-m/%\-d/%Y # نادیده گرفتن برخی رویدادهای paypal if In Progress Temporary Hold Update to skip # افزودن فیلدهای بیشتر به description description %description_ %itemtitle # ذخیرهٔ برخی فیلدهای دیگر به عنوان برچسب (tag) comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ # تبدیل به نمادهای کوتاه یکای پول if %currency USD currency $ if %currency EUR currency E if %currency GBP currency P # ایجاد ثبت‌ها (postings) # ثبت نخست، پولی خواهد بود که از حساب paypal من خارج یا به آن وارد می‌شود # (در تمام فیلدهای مبلغ، منفی به معنای خروج از حساب من است) account1 assets:online:paypal amount1 %netamount # ثبت دوم، پول ارسال‌شده به یا دریافت‌شده از طرف دیگر خواهد بود # (account2 در پایین تنظیم می‌شود) amount2 \-%grossamount # اگر کارمزدی وجود دارد، یک ثبت سوم برای پول برداشت‌شده توسط paypal اضافه کن. if %feeamount [1\-9] account3 expenses:banking:paypal amount3 \-%feeamount comment3 business: # انتخاب یک حساب برای ثبت دوم # بازنویسی نام‌های پیش‌فرض حساب: # اگر مبلغ مثبت باشد، درآمد است (یک بدهکار) if %grossamount \(ha[\(ha\-] account2 income:unknown # اگر منفی باشد، هزینه است (یک بستانکار) if %grossamount \(ha\- account2 expenses:unknown # اعمال قوانین مشترک برای تنظیم account2 و سایر تغییرات جزئی include common.rules # اعمال برخی بازنویسی‌های ویژهٔ این csv # انتقال‌ها از/به بانک. این‌ها معمولاً با عنوان Pending علامت‌گذاری می‌شوند، # که در این مورد می‌توان آن‌ها را نادیده گرفت. if Bank Account Bank Deposit to PP Account description %type for %referencetxnid %itemtitle account2 assets:bank:wf:pchecking account1 assets:online:paypal # تبدیل‌های یکای پول if Currency Conversion account2 equity:currency conversion .EE .IP .EX # common.rules if darcs noble benefactor account2 revenues:foss donations:darcshub comment2 business: if Calm Radio account2 expenses:online:apps if electronic frontier foundation Patreon wikimedia Advent of Code account2 expenses:dues if Google account2 expenses:online:apps description google | music .EE.IP .EX $ hledger \-f paypal\-custom.csv print 2019\-10\-01 (60P57143A8206782E) Calm Radio MONTHLY \- $1 for the first 2 Months: Me \- Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon\(atjoyful.com, toemail:memberships\(atcalmradio.com, time:03:46:20, type:Subscription Payment, status:Completed assets:online:paypal $\-6.99 = $\-6.99 expenses:online:apps $6.99 2019\-10\-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon\(atjoyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $6.99 = $0.00 assets:bank:wf:pchecking $\-6.99 2019\-10\-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon\(atjoyful.com, toemail:support\(atpatreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed assets:online:paypal $\-7.00 = $\-7.00 expenses:dues $7.00 2019\-10\-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon\(atjoyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $7.00 = $0.00 assets:bank:wf:pchecking $\-7.00 2019\-10\-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon\(atjoyful.com, toemail:tle\(atwikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed assets:online:paypal $\-2.00 = $\-2.00 expenses:dues $2.00 expenses:banking:paypal ; business: 2019\-10\-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon\(atjoyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $2.00 = $0.00 assets:bank:wf:pchecking $\-2.00 2019\-10\-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble\(atbene.fac.tor, toemail:simon\(atjoyful.com, time:05:07:06, type:Subscription Payment, status:Completed assets:online:paypal $9.41 = $9.41 revenues:foss donations:darcshub $\-10.00 ; business: expenses:banking:paypal $0.59 ; business: .EE .PP .SH "ثبت زمان (Timeclock)" برنامهٔ hledger می‌تواند لاگ‌های زمان را در قالب ثبت زمان timeclock.el بخواند. همانند Ledger، قالب timeclock در hledger یک زیرمجموعه/گونه از قالب timeclock.el است. .PP قالب timeclock در hledger در نسخه‌های 1.43 و 1.50 به‌روزرسانی شد. اگر لاگ‌های زمانی قدیمی شما پذیرفته نمی‌شوند، باید آن‌ها را با hledger امروزی سازگار کنید؛ برای اکنون، می‌توانید رفتار پیش از 1.43 را با پرچم \f[CR]\-\-old\-timeclock\f[R] بازیابی کنید. .PP در اینجا قالب timeclock در hledger 1.50+ آورده شده است: .IP .EX # Comment lines like these, and blank lines, are ignored: # comment line ; comment line * comment line # Lines beginning with b, h, or capital O are also ignored, for compatibility: b SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT] h SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT] O SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT] # Lines beginning with i or o are are clock\-in / clock\-out entries: i SIMPLEDATE HH:MM[:SS][+\-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]] o SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ ACCOUNT][;COMMENT] .EE .PP تاریخ، یک تاریخ ساده در hledger است (YYYY\-MM\-DD یا مشابه آن). بخش‌های زمان باید از دو رقم استفاده کنند. ثانیه‌ها اختیاری هستند. یک منطقه زمانی چهار رقمی با + یا \- جهت سازگاری پذیرفته می‌شود، اما در حال حاضر نادیده گرفته می‌شود؛ زمان‌ها همواره به صورت زمان محلی تفسیر می‌شوند. .PP در مدخل‌های ثبت ورود (\f[CR]i\f[R])، نام حساب الزامی است. توضیحات تراکنش، که با ۲ فاصله یا بیشتر از نام حساب جدا می‌شود، اختیاری است. یادداشت تراکنش، که با \f[CR];\f[R] آغاز می‌شود نیز اختیاری است. (خطوط یادداشت تورفتهٔ پسین نیز مجاز هستند، همانند آنچه در قالب دفتر روزنامه (journal) مرسوم است.) .PP در مدخل‌های ثبت خروج (\f[CR]o\f[R]) توضیحی وجود ندارد، اما در صورت تمایل می‌توانند یک یادداشت داشته باشند. یک جفت ورود و خروج، یک \(dqتراکنش\(dq تشکیل می‌دهند که تعدادی ساعت را در یک حساب ثبت می‌کند \- که به عنوان یک نشست (session) نیز شناخته می‌شود. برای نمونه: .IP .EX i 2015/03/30 09:00:00 session1 o 2015/03/30 10:00:00 .EE .IP .EX $ hledger \-f a.timeclock print 2015\-03\-30 * 09:00\-10:00 (session1) 1.00h .EE .PP ورودها و خروج‌ها بر اساس نام حساب/نشست خود تطبیق داده می‌شوند. اگر یک خروج نامی را تعیین نکند، تازه‌ترین ورودِ بسته‌نشده بسته می‌شود. می‌توانید چندین نشست فعال هم‌زمان داشته باشید. مدخل‌ها به ترتیبی که تجزیه می‌شوند پردازش خواهند شد. نشست‌هایی که بیش از یک روز به درازا می‌کشند، به‌طور خودکار در مرز روزها تقسیم می‌شوند. .PP برای نمونه، لاگ زمانی زیر: .IP .EX i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: o 2015/03/30 09:20:00 i 2015/03/31 22:21:45 another:account o 2015/04/01 02:00:34 i 2015/04/02 12:00:00 another:account ; this demonstrates multple sessions being clocked in i 2015/04/02 13:00:00 some account o 2015/04/02 14:00:00 o 2015/04/02 15:00:00 another:account .EE .PP این تراکنش‌ها را تولید می‌کند: .IP .EX $ hledger \-f t.timeclock print 2015\-03\-30 * optional description after 2 spaces ; optional comment, tags: (some account) 0.33h 2015\-03\-31 * 22:21\-23:59 (another:account) 1.64h 2015\-04\-01 * 00:00\-02:00 (another:account) 2.01h 2015\-04\-02 * 12:00\-15:00 ; this demonstrates multiple sessions being clocked in (another:account) 3.00h 2015\-04\-02 * 13:00\-14:00 (some account) 1.00h .EE .PP در اینجا یک sample.timeclock برای دریافت و چند پرسمان برای آزمایش قرار دارد: .IP .EX $ hledger \-f sample.timeclock balance # current time balances $ hledger \-f sample.timeclock register \-p 2009/3 # sessions in march 2009 $ hledger \-f sample.timeclock register \-p weekly \-\-depth 1 \-\-empty # time summary by week .EE .PP برای تولید لاگ‌های زمان، یعنی برای ثبت ورود و خروج، می‌توانید: .IP \(bu 2 از این نام‌های مستعار پوسته در خط فرمان استفاده کنید: .RS 2 .IP .EX alias ti=\(aqecho i \(gadate \(dq+%Y\-%m\-%d %H:%M:%S\(dq\(ga $* >>$TIMELOG\(aq alias to=\(aqecho o \(gadate \(dq+%Y\-%m\-%d %H:%M:%S\(dq\(ga >>$TIMELOG\(aq .EE .RE .IP \(bu 2 یا از timeclock.el توکار Emacs، یا نسخهٔ گسترش‌یافتهٔ timeclock\-x.el، و احتمالاً امکانات جانبی در ledgerutils.el استفاده کنید .IP \(bu 2 یا از اسکریپت‌های قدیمی \f[CR]ti\f[R] و \f[CR]to\f[R] در مخزن ledger 2.x بهره ببرید. این اسکریپت‌ها به یک فایل اجرایی \(dqtimeclock\(dq متکی هستند که به نظر می‌رسد همان فایل اجرایی ledger 2 با نام تغییریافته باشد. .PP.SH Timedot قالب \f[CR]timedot\f[R]، قالب ثبت زمانِ انسان‌فهم در hledger است. در مقایسه با قالب \f[CR]timeclock\f[R]، این قالب برای ثبت زمانِ سریع، تقریبی و گذشته‌نگر مناسب‌تر بوده و برای انسان خواناتر است (می‌توانید در یک نگاه ببینید زمان کجا صرف شده است). یک مثال سریع: .IP .EX 2023\-05\-01 hom:errands .... .... ; two hours; the space is ignored fos:hledger:timedot .. ; half an hour per:admin:finance ; no time spent yet .EE .PP hledger این مورد را به‌عنوان یک تراکنش در این روز با سه ثبت (ترازنشده) می‌خواند، که در آن هر نقطه نمایانگر \(dq0.25\(dq است. هیچ نماد کالایی در نظر گرفته نمی‌شود، اما معمولاً آن را به‌عنوان ساعت تفسیر می‌کنیم. .IP .EX $ hledger \-f a.timedot print # .timedot file extension (or timedot: prefix) is required 2023\-05\-01 * (hom:errands) 2.00 ; two hours (fos:hledger:timedot) 0.50 ; half an hour (per:admin:finance) 0 .EE .PP یک فایل timedot شامل مجموعه‌ای از تراکنش‌ها است (معمولاً یکی در هر روز). هر تراکنش با یک \f[B]تاریخ ساده\f[R] (Y\-M\-D،‏ Y/M/D یا Y.M.D) آغاز می‌شود، و می‌تواند به صورت اختیاری در همان خط با توضیحات تراکنش، و/یا یک کامنت تراکنش پس از یک سیمی‌کالن دنبال شود. .PP پس از خط تاریخ، صفر یا چند ثبتِ زمانی قرار می‌گیرد که شامل موارد زیر است: .IP \(bu 2 \f[B]نام حساب\f[R] \- هر نام حسابی به سبک hledger، با تورفتگی اختیاری. .IP \(bu 2 \f[B]دو یا چند فاصله\f[R] \- در صورت وجود مقدار، الزامی است (همانند قالب journal). .IP \(bu 2 \f[B]یک مقدار timedot\f[R]، که می‌تواند شامل موارد زیر باشد: .RS 2 .IP \(bu 2 خالی (بیانگر صفر) .IP \(bu 2 یک عدد، به صورت اختیاری به همراه یکی از یکاهای \f[CR]s\f[R]، \f[CR]m\f[R]، \f[CR]h\f[R]، \f[CR]d\f[R]، \f[CR]w\f[R]، \f[CR]mo\f[R] یا \f[CR]y\f[R]، بیانگر تعداد دقیقی از ثانیه‌ها، دقیقه‌ها، ساعت‌ها، روزها، هفته‌ها، ماه‌ها یا سال‌ها (به‌طور پیش‌فرض ساعت در نظر گرفته می‌شود)، که طبق روابط 60s = 1m،‏ 60m = 1h،‏ 24h = 1d،‏ 7d = 1w،‏ 30d = 1mo و 365d = 1y به ساعت تبدیل خواهند شد. .IP \(bu 2 یک یا چند نقطه (نویسه‌های نقطه)، که هر کدام بیانگر 0.25 هستند. این‌ها همان نقطه‌ها در \(dqtimedot\(dq هستند. فاصله‌ها نادیده گرفته می‌شوند و می‌توان از آن‌ها برای گروه‌بندی یا تراز کردن استفاده کرد. .IP \(bu 2 \f[I]اضافه‌شده در 1.32\f[R] یک یا چند حرف. این‌ها مانند نقطه‌ها هستند، اما برچسبی به نام \f[CR]t:\f[R] (مخفف \(dqtype\(dq) نیز با آن حرف به‌عنوان مقدارش تولید می‌کنند، و برای هر یک از مقادیر یک ثبت جداگانه ایجاد می‌شود. این ویژگی بعد دومی از دسته‌بندی را فراهم می‌کند که در گزارش‌ها با \f[CR]\-\-pivot t\f[R] قابل مشاهده است. .RE .IP \(bu 2 \f[B]یک کامنت اختیاری\f[R] پس از سیمی‌کالن (یک کامنتِ ثبت به سبک hledger). .PP انعطاف‌پذیری‌هایی وجود دارد تا به نگهداری داده‌های لاگ زمان و یادداشت‌ها در همان فایل کمک کند: .IP \(bu 2 خطوط خالی و خطوطی که با \f[CR]#\f[R] یا \f[CR];\f[R] آغاز می‌شوند نادیده گرفته می‌شوند. .IP \(bu 2 پس از نخستین خط تاریخ، خطوطی که شامل دو فاصله نیستند، به‌عنوان ثبت‌هایی با مقدار صفر پردازش می‌شوند. (گزارش‌های register در hledger در صورت افزودن \-E این موارد را نمایش خواهند داد). .IP \(bu 2 پیش از نخستین خط تاریخ، خطوطی که با \f[CR]*\f[R] آغاز می‌شوند (مانند سربرگ‌های org) نادیده گرفته می‌شوند. و از نخستین خط تاریخ به بعد، پیشوندهای سربرگ Emacs org mode در ابتدای خطوط (یک یا چند \f[CR]*\f[R] که پس از آن‌ها یک فاصله آمده است) نادیده گرفته خواهند شد. این بدان معناست که لاگ زمان می‌تواند یک رئوس مطالب org (org outline) نیز باشد. .PP فایل‌های timedot بر خلاف فایل‌های journal از دستورالعمل‌ها (directives) پشتیبانی نمی‌کنند. بنابراین یک الگوی رایج این است که یک فایل journal اصلی (مانند \f[CR]time.journal\f[R]) داشته باشید که شامل دستورالعمل‌های مورد نیاز باشد، و سپس فایل timedot را در بر بگیرد (\f[CR]include time.timedot\f[R])..SS مثال‌های Timedot اعداد: .IP .EX 2016/2/3 inc:client1 4 fos:hledger 3h biz:research 60m .EE .PP نقطه‌ها: .IP .EX # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. 2016/2/1 inc:client1 .... .... .... .... .... .... fos:haskell .... .. biz:research . 2016/2/2 inc:client1 .... .... biz:research . .EE .IP .EX $ hledger \-f a.timedot print date:2016/2/2 2016\-02\-02 * (inc:client1) 2.00 2016\-02\-02 * (biz:research) 0.25 .EE .IP .EX $ hledger \-f a.timedot bal \-\-daily \-\-tree Balance changes in 2016\-02\-01\-2016\-02\-03: || 2016\-02\-01d 2016\-02\-02d 2016\-02\-03d ============++======================================== biz || 0.25 0.25 1.00 research || 0.25 0.25 1.00 fos || 1.50 0 3.00 haskell || 1.50 0 0 hledger || 0 0 3.00 inc || 6.00 2.00 4.00 client1 || 6.00 2.00 4.00 \-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || 7.75 2.25 8.00 .EE .PP حروف: .IP .EX # Activity types: # c cleanup/catchup/repair # e enhancement # s support # l learning/research 2023\-11\-01 work:adm ccecces .EE .IP .EX $ hledger \-f a.timedot print 2023\-11\-01 (work:adm) 1 ; t:c (work:adm) 0.5 ; t:e (work:adm) 0.25 ; t:s .EE .IP .EX $ hledger \-f a.timedot bal 1.75 work:adm \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 1.75 .EE .IP .EX $ hledger \-f a.timedot bal \-\-pivot t 1.00 c 0.50 e 0.25 s \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 1.75 .EE .PP Org: .IP .EX * 2023 Work Diary ** Q1 *** 2023\-02\-29 **** DONE 0700 yoga **** UNPLANNED **** BEGUN hom:chores cleaning ... water plants outdoor \- one full watering can indoor \- light watering **** TODO adm:planning: trip *** LATER .EE .PP استفاده از \f[CR].\f[R] به‌‌عنوان جداکننده نام حساب: .IP .EX 2016/2/4 fos.hledger.timedot 4h fos.ledger .. .EE .IP .EX $ hledger \-f a.timedot \-\-alias \(aq/\(rs./=:\(aq bal \-t 4.50 fos 4.00 hledger:timedot 0.50 ledger \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 4.50 .EE.SH "بخش ۳: مفاهیم گزارش‌گیری (PART 3: REPORTING CONCEPTS)" .SH "دوره‌های زمانی (Time periods)" .SS "تاریخ آغاز و پایان گزارش (Report start & end date)" بیشتر گزارش‌های hledger به‌طور پیش‌فرض کل دورهٔ زمانی بازنمایی‌شده توسط journal را نمایش می‌دهند. تاریخ آغاز گزارش، کهن‌ترین تاریخ تراکنش یا posting خواهد بود، و تاریخ پایان گزارش، تازه‌ترین تاریخ تراکنش، posting، یا قیمت بازار خواهد بود. .PP اغلب مایل خواهید بود دورهٔ کوتاه‌تری مانند ماه جاری را مشاهده کنید. می‌توانید تاریخ آغاز و/یا پایان را با گزینه‌های \f[CR]\-b/\-\-begin\f[R]، \f[CR]\-e/\-\-end\f[R]، یا \f[CR]\-p/\-\-period\f[R]، یا یک آرگومان پرس‌وجوی \f[CR]date:\f[R] که در ادامه توضیح داده شده‌اند مشخص کنید. همهٔ این‌ها ساختار نحو تاریخ هوشمند (smart date) را که آن نیز در ادامه شرح داده شده می‌پذیرند. .PP تاریخ‌های پایان شاملِ خود آن روز نمی‌شوند (exclusive هستند)؛ روز بعد از آخرین روزی را که می‌خواهید در گزارش ببینید مشخص کنید. .PP هنگامی که تاریخ‌ها توسط چندین گزینه مشخص شوند، آخرین گزینه (راست‌ترین) اعمال می‌شود. و هنگامی که پرس‌وجوهای \f[CR]date:\f[R] و گزینه‌های تاریخ ترکیب شوند، دورهٔ گزارش اشتراک آن‌ها خواهد بود. .PP مثال‌ها: .TP \f[CR]\-b 2016/3/17\f[R] شروع از روز سنت پاتریک ۲۰۱۶ .TP \f[CR]\-e 12/1\f[R] پایان در ابتدای ۱ دسامبر سال جاری .TP \f[CR]\-p \(aqthis month\(aq\f[R] در طول ماه جاری .TP \f[CR]\-p thismonth\f[R] مشابه بالا، فاصله‌ها اختیاری هستند .TP \f[CR]\-b 2023\f[R] شروع از نخستین روز ۲۰۲۳ .TP \f[CR]date:2023..\f[R] یا \f[CR]date:2023\-\f[R] مشابه بالا .PP \f[CR]\-b 2024 \-e 2025 \-p \(aq2000 to 2030\(aq date:2020\-01 date:2020\f[R] : .PD 0 .P .PD در طول ژانویهٔ ۲۰۲۰ (کوچک‌ترین دورهٔ مشترک، با تقدم \-p بر \-b و \-e) .SS "تاریخ‌های هوشمند (Smart dates)" در رابط‌های کاربری hledger (البته نه در فایل journal)، می‌توانید به‌صورت اختیاری از نحو \(dqsmart date\(dq استفاده کنید. تاریخ‌های هوشمند می‌توانند با کلمات انگلیسی نوشته شوند، نسبی باشند، و بخش‌هایی از آن‌ها حذف شده باشد. بخش‌های جاافتاده در صورت نیاز ۱ در نظر گرفته می‌شوند. بسته به زمینه، تاریخ‌های هوشمند می‌توانند به عنوان تاریخ‌ها یا دوره‌ها تفسیر شوند. .PP مثال‌ها: .PP \f[CR]2004\-01\-01\f[R]، \f[CR]2004/10/1\f[R]، \f[CR]2004.9.1\f[R]، \f[CR]20240504\f[R]، \f[CR]2024Q1\f[R] : .PD 0 .P .PD تاریخ‌های دقیق. سال باید دست‌کم چهار رقم داشته باشد، ماه باید ۱\-۱۲ باشد، روز باید ۱\-۳۱ باشد، جداکننده می‌تواند \f[CR]\-\f[R] یا \f[CR]/\f[R] یا \f[CR].\f[R] یا بدون جداکننده باشد. حرف q می‌تواند بزرگ یا کوچک باشد و شمارهٔ سه‌ماهه باید ۱\-۴ باشد. .TP \f[CR]2004\-10\f[R] ابتدای ماه .TP \f[CR]2004q3\f[R] ابتدای سه‌ماههٔ سوم سال ۲۰۰۴ .TP \f[CR]q3\f[R] ابتدای سه‌ماههٔ سوم سال جاری .TP \f[CR]2004\f[R] ابتدای سال .TP \f[CR]10/1\f[R] یا \f[CR]oct\f[R] یا \f[CR]october\f[R] ۱ اکتبر در سال جاری .TP \f[CR]21\f[R] روز ۲۱ام در ماه جاری .TP \f[CR]yesterday, today, tomorrow\f[R] \-1، 0، 1 روز از امروز .TP \f[CR]last/this/next day/week/month/quarter/year\f[R] \-1، 0، 1 دوره از دورهٔ جاری .TP \f[CR]last/this/next tuesday\f[R] رخداد قبلی روز نام‌برده، یا رخداد بعدیِ پس از امروز .TP \f[CR]last/this/next february\f[R] رخداد قبلی روز ۱امِ ماه نام‌برده، یا رخداد بعدیِ پس از ماه جاری .TP \f[CR]in n days/weeks/months/quarters/years\f[R] n دوره از دورهٔ جاری .TP \f[CR]n days/weeks/months/quarters/years ahead\f[R] n دوره پس از دورهٔ جاری .TP \f[CR]n days/weeks/months/quarters/years ago\f[R] \-n دوره از دورهٔ جاری .TP \f[CR]20181201\f[R] ۸ رقم YYYYMMDD با سال، ماه و روز معتبر .TP \f[CR]201812\f[R] ۶ رقم YYYYMM با سال و ماه معتبر .PP تاریخ‌های بدون جداکننده مجاز هستند اما در صورت اشتباه تایپی ممکن است نتایج غیرمنتظره‌ای ایجاد کنند: .IP \(bu 2 \f[CR]20181301\f[R] (YYYYMMDD با ماه نامعتبر) به عنوان یک سال هشت‌رقمی تجزیه می‌شود .IP \(bu 2 \f[CR]20181232\f[R] (YYYYMMDD با روز نامعتبر) خطای تجزیه می‌دهد .IP \(bu 2 \f[CR]201801012\f[R] (یک YYYYMMDD معتبر که در ادامهٔ آن ارقام اضافه آمده است) خطای تجزیه می‌دهد .PP معنای تاریخ‌های نسبی به تاریخ امروز (today) بستگی دارد. اگر نیاز به آزمایش یا بازتولید گزارش‌های قدیمی دارید، می‌توانید از گزینهٔ \f[CR]\-\-today\f[R] برای بازنویسی آن استفاده کنید. (به استثنای قواعد تراکنش‌های دوره‌ای، که تحت تأثیر \f[CR]\-\-today\f[R] قرار نمی‌گیرند.).SS بازه‌های گزارش می‌توان یک بازه گزارش مشخص کرد تا گزارش‌هایی مانند register، balance یا activity چنددوره‌ای شوند و هر زیردوره را در قالب یک سطر یا ستون جداگانه نمایش دهند. .PP بازه‌های استاندارد زیر را می‌توان با پرچم‌های خط فرمان فعال کرد: .IP \(bu 2 \f[CR]\-D/\-\-daily\f[R] .IP \(bu 2 \f[CR]\-W/\-\-weekly\f[R] .IP \(bu 2 \f[CR]\-M/\-\-monthly\f[R] .IP \(bu 2 \f[CR]\-Q/\-\-quarterly\f[R] .IP \(bu 2 \f[CR]\-Y/\-\-yearly\f[R] .PP بازه‌های پیچیده‌تر را می‌توان با استفاده از \f[CR]\-p/\-\-period\f[R] مشخص کرد که در ادامه شرح داده شده‌اند. .SS تنظیمات تاریخ .SS تنظیم تاریخ شروع اگر به hledger اجازه دهید تاریخ شروع یک گزارش را استنباط کند، آن را برای راحتی در گزارش‌های دوره‌ای، به مرز طبیعی پیشینِ بازه گزارش تنظیم می‌کند. (اگر چنین چیزی را نمی‌خواهید، یک تاریخ شروع مشخص کنید.) .PP برای نمونه، اگر نخستین تراکنش در دفتر روزنامه در ۱۰ ژانویه باشد: .IP \(bu 2 دستور \f[CR]hledger register\f[R] (بدون بازه گزارش) گزارش را در ۱۰ ژانویه آغاز خواهد کرد. .IP \(bu 2 دستور \f[CR]hledger register \-\-monthly\f[R] گزارش را در مرز ماه پیشین، یعنی ۱ ژانویه آغاز می‌کند. .IP \(bu 2 دستور \f[CR]hledger register \-\-monthly \-\-begin 1/5\f[R] گزارش را در ۵ ژانویه آغاز می‌کند [1]. .PP همچنین اگر با قواعد تراکنش دوره‌ای در حال تولید تراکنش‌ها یا اهداف بودجه هستید، ممکن است تاریخ شروع آن‌ها نیز به روش مشابهی (در شرایط معین) تنظیم شود. .SS تنظیم تاریخ پایان تاریخ پایان یک گزارش همیشه طوری تنظیم می‌شود که شامل تعداد کاملی از بازه‌ها باشد، به‌گونه‌ای که آخرین زیردوره دارای طولی یکسان با سایر زیردوره‌ها باشد. .PP برای نمونه، اگر آخرین تراکنش دفتر روزنامه در ۲۰ فوریه باشد: .IP \(bu 2 دستور \f[CR]hledger register\f[R] گزارش را در ۲۰ فوریه به پایان می‌رساند. .IP \(bu 2 دستور \f[CR]hledger register \-\-monthly\f[R] گزارش را در پایان فوریه به پایان می‌رساند. .IP \(bu 2 دستور \f[CR]hledger register \-\-monthly \-\-end 2/14\f[R] نیز گزارش را در پایان فوریه به پایان می‌رساند (نادیده گرفتن تاریخ پایان درخواست‌شده). .IP \(bu 2 دستور \f[CR]hledger register \-\-monthly \-\-begin 1/5 \-\-end 2/14\f[R] گزارش را در ۴ مارس به پایان می‌رساند [1]. .PP [1] از hledger نسخه 1.29 به بعد. .SS سربرگ‌های دوره در زیردوره‌های غیر استاندارد، hledger سربرگ‌های \(dqSTARTDATE..ENDDATE\(dq را نشان می‌دهد. در زیردوره‌های استاندارد (یعنی شروع در یک مرز بازه طبیعی)، سربرگ‌های فشرده‌تری را خواهید دید که معمولاً مطلوب‌تر هستند. (اگرچه در حال حاضر، نام ماه‌ها به انگلیسی خواهد بود.) .PP بنابراین اگر تاریخ شروع را مشخص می‌کنید و سربرگ‌های فشرده می‌خواهید: شروع سال را برای گزارش‌های سالانه، شروع فصل را برای گزارش‌های سه‌ماهه، شروع ماه را برای گزارش‌های ماهانه و غیره انتخاب کنید. (به یاد داشته باشید، می‌توانید مثلاً \f[CR]\-b 2024\f[R] یا \f[CR]1/1\f[R] را به عنوان میان‌بری برای شروع سال، یا \f[CR]2024\-04\f[R] یا \f[CR]202404\f[R] یا \f[CR]Apr\f[R] را برای شروع ماه یا فصل بنویسید.) .PP برای گزارش‌های هفتگی، تاریخی را انتخاب کنید که دوشنبه (Monday) باشد. (می‌توانید تاریخ‌های متفاوتی را امتحان کنید تا زمانی که سربرگ‌های کوتاه را ببینید، یا مثلاً بنویسید \f[CR]\-b \(aq3 weeks ago\(aq\f[R].) .SS عبارت‌های دوره گزینه \f[CR]\-p/\-\-period\f[R] یک عبارت دوره را مشخص می‌کند، که روشی فشرده برای بیان تاریخ شروع، تاریخ پایان و/یا بازه گزارش است. .PP در اینجا نمونه‌ای از یک عبارت دوره با تاریخ شروع و پایان آورده شده است (مشخص‌کننده فصل نخست سال ۲۰۰۹): .PP .TS tab(@); l. T{ \f[CR]\-p \(dqfrom 2009/1/1 to 2009/4/1\(dq\f[R] T} .TE .PP چندین کلیدواژه مانند \(dqfrom\(dq و \(dqto\(dq برای خوانایی بهتر پشتیبانی می‌شوند؛ این کلیدواژه‌ها اختیاری هستند. \(dqto\(dq می‌تواند به صورت \(dq..\(dq یا \(dq\-\(dq نیز نوشته شود. فاصله‌ها نیز اختیاری هستند، تا زمانی که دو تاریخ به هم نچسبند. بنابراین موارد زیر معادل عبارت بالا هستند: .PP .TS tab(@); l. T{ \f[CR]\-p \(dq2009/1/1 2009/4/1\(dq\f[R] T} T{ \f[CR]\-p2009/1/1to2009/4/1\f[R] T} T{ \f[CR]\-p2009/1/1..2009/4/1\f[R] T} .TE .PP تاریخ‌ها از نوع تاریخ‌های هوشمند (smart dates) هستند، بنابراین اگر سال جاری ۲۰۰۹ باشد، موارد زیر نیز معادل عبارت بالا خواهند بود: .PP .TS tab(@); l. T{ \f[CR]\-p \(dq1/1 4/1\(dq\f[R] T} T{ \f[CR]\-p \(dqjan\-apr\(dq\f[R] T} T{ \f[CR]\-p \(dqthis year to 4/1\(dq\f[R] T} .TE .PP اگر تنها یک تاریخ را مشخص کنید، تاریخ شروع یا پایان ناموجود برابر با زودترین یا دیرترین تاریخ تراکنش در دفتر روزنامه خواهد بود: .PP .TS tab(@); l l. T{ \f[CR]\-p \(dqfrom 2009/1/1\(dq\f[R] T}@T{ همه موارد پس از ۱ ژانویه ۲۰۰۹ T} T{ \f[CR]\-p \(dqsince 2009/1\(dq\f[R] T}@T{ همان، since یک مترادف است T} T{ \f[CR]\-p \(dqfrom 2009\(dq\f[R] T}@T{ همان T} T{ \f[CR]\-p \(dqto 2009\(dq\f[R] T}@T{ همه موارد پیش از ۱ ژانویه ۲۰۰۹ T} .TE .PP همچنین می‌توانید با نوشتن یک تاریخ تکی جزئی یا کامل، یک دوره را مشخص کنید: .PP .TS tab(@); lw(14.5n) lw(55.5n). T{ \f[CR]\-p \(dq2009\(dq\f[R] T}@T{ سال ۲۰۰۹؛ معادل \(lq2009/1/1 to 2010/1/1\(rq T} T{ \f[CR]\-p \(dq2009/1\(dq\f[R] T}@T{ ماه ژانویه ۲۰۰۹؛ معادل \(lq2009/1/1 to 2009/2/1\(rq T} T{ \f[CR]\-p \(dq2009/1/1\(dq\f[R] T}@T{ روز نخست سال ۲۰۰۹؛ معادل \(lq2009/1/1 to 2009/1/2\(rq T} .TE .PP یا با استفاده از ساختار فصلی \(dqQ\(dq (غیرحساس به حروف کوچک و بزرگ):.PP .TS tab(@); lw(15.3n) lw(54.7n). T{ \f[CR]\-p \(dq2009Q1\(dq\f[R] T}@T{ سه‌ماهه نخست ۲۰۰۹، معادل با \(lq2009/1/1 to 2009/4/1\(rq T} T{ \f[CR]\-p \(dqq4\(dq\f[R] T}@T{ سه‌ماهه چهارم سال جاری T} .TE .SS عبارت‌های دوره به همراه بازه گزارش (Period expressions with a report interval) یک عبارت دوره می‌تواند با یک بازه گزارش نیز آغاز شود، که با یک فاصله یا کلمه \f[CR]in\f[R] از تاریخ‌های شروع/پایان (در صورت وجود) جدا می‌شود: .PP .TS tab(@); l. T{ \f[CR]\-p \(dqweekly from 2009/1/1 to 2009/4/1\(dq\f[R] T} T{ \f[CR]\-p \(dqmonthly in 2008\(dq\f[R] T} T{ \f[CR]\-p \(dqquarterly\(dq\f[R] T} .TE .SS بازه‌های گزارش پیچیده‌تر (More complex report intervals) برخی بازه‌های پیچیده‌تر را می‌توان در عبارت‌های دوره مشخص کرد، مانند: .IP \(bu 2 \f[CR]biweekly\f[R] (هر دو هفته یک‌بار) .IP \(bu 2 \f[CR]fortnightly\f[R] .IP \(bu 2 \f[CR]bimonthly\f[R] (هر دو ماه یک‌بار) .IP \(bu 2 \f[CR]every day|week|month|quarter|year\f[R] .IP \(bu 2 \f[CR]every N days|weeks|months|quarters|years\f[R] .PP هفتگی در یک روز دلخواه: .IP \(bu 2 \f[CR]every Nth day of week\f[R] (پسوندهای \f[CR]th\f[R]، \f[CR]nd\f[R]، \f[CR]rd\f[R] یا \f[CR]st\f[R] همگی پس از عدد پذیرفته می‌شوند) .IP \(bu 2 \f[CR]every WEEKDAYNAME\f[R] (نام انگلیسی روز هفته به‌صورت کامل یا سه‌حرفی، بدون حساسیت به حروف بزرگ و کوچک) .PP ماهانه در یک روز دلخواه: .IP \(bu 2 \f[CR]every Nth day [of month]\f[R] (\f[CR]31st day\f[R] با آخرین روز هر ماه تطبیق داده خواهد شد) .IP \(bu 2 \f[CR]every Nth WEEKDAYNAME [of month]\f[R] .PP سالانه در یک ماه و روز دلخواه: .IP \(bu 2 \f[CR]every MM/DD [of year]\f[R] (شماره ماه و شماره روزِ ماه) .IP \(bu 2 \f[CR]every MONTHNAME DDth [of year]\f[R] (نام انگلیسی ماه به‌صورت کامل یا سه‌حرفی، بدون حساسیت به حروف بزرگ و کوچک، و شماره روزِ ماه) .IP \(bu 2 \f[CR]every DDth MONTHNAME [of year]\f[R] (معادل با مورد بالا) .PP مثال‌ها: .PP .TS tab(@); lw(26.8n) lw(43.2n). T{ \f[CR]\-p \(dqbimonthly from 2008\(dq\f[R] T}@T{ T} T{ \f[CR]\-p \(dqevery 2 weeks\(dq\f[R] T}@T{ T} T{ \f[CR]\-p \(dqevery 5 months from 2009/03\(dq\f[R] T}@T{ T} T{ \f[CR]\-p \(dqevery 2nd day of week\(dq\f[R] T}@T{ دوره‌ها از سه‌شنبه تا سه‌شنبه خواهند بود T} T{ \f[CR]\-p \(dqevery Tue\(dq\f[R] T}@T{ همان T} T{ \f[CR]\-p \(dqevery 15th day\(dq\f[R] T}@T{ مرزهای دوره در پانزدهم هر ماه خواهند بود T} T{ \f[CR]\-p \(dqevery 2nd Monday\(dq\f[R] T}@T{ مرزهای دوره در دومین دوشنبه هر ماه خواهند بود T} T{ \f[CR]\-p \(dqevery 11/05\(dq\f[R] T}@T{ دوره‌های سالانه با مرزهایی در پنجم نوامبر T} T{ \f[CR]\-p \(dqevery 5th November\(dq\f[R] T}@T{ همان T} T{ \f[CR]\-p \(dqevery Nov 5th\(dq\f[R] T}@T{ همان T} .TE .PP نمایش ترازهای تاریخی در پایان روز پانزدهم هر ماه (N تاریخ پایان است و طبق معمول، خود آن روز شامل نمی‌شود): .IP .EX $ hledger balance \-H \-p \(dqevery 16th day\(dq .EE .PP دسته‌بندی ثبت‌ها از ابتدای چهارشنبه تا انتهای سه‌شنبه بعد (N هم تاریخ شروع (شامل) و هم تاریخ پایان (غیرشامل) است): .IP .EX $ hledger register checking \-p \(dqevery 3rd day of week\(dq .EE.SS "بازه‌های چندگانه روزهای هفته" این شکل ویژه نیز پشتیبانی می‌شود: .IP \(bu 2 \f[CR]every WEEKDAYNAME,WEEKDAYNAME,...\f[R] (نام‌های کامل یا سه‌حرفی روزهای هفته به انگلیسی، بدون حساسیت به بزرگی و کوچکی حروف) .PP همچنین، \f[CR]weekday\f[R] و \f[CR]weekendday\f[R] کوتاه‌نوشت‌هایی برای \f[CR]mon,tue,wed,thu,fri\f[R] و \f[CR]sat,sun\f[R] هستند. .PP این قابلیت عمدتاً برای استفاده با \f[CR]\-\-forecast\f[R] در نظر گرفته شده است، تا تراکنش‌های دوره‌ای را در روزهای دلخواهی از هفته ایجاد کند. استفاده از آن با \f[CR]\-p\f[R] ممکن است کاربرد کمتری داشته باشد، زیرا هر هفته را به زیردوره‌هایی با طول نابرابر تقسیم می‌کند که غیرمعمول است. (مرتبط: #1632) .PP مثال‌ها: .PP .TS tab(@); lw(17.8n) lw(52.2n). T{ \f[CR]\-p \(dqevery mon,wed,fri\(dq\f[R] T}@T{ تاریخ‌ها Mon، Wed، Fri خواهند بود؛ دوره‌ها Mon\-Tue، Wed\-Thu، Fri\-Sun خواهند بود T} T{ \f[CR]\-p \(dqevery weekday\(dq\f[R] T}@T{ تاریخ‌ها Mon، Tue، Wed، Thu، Fri خواهند بود؛ دوره‌ها Mon، Tue، Wed، Thu، Fri\-Sun خواهند بود T} T{ \f[CR]\-p \(dqevery weekendday\(dq\f[R] T}@T{ تاریخ‌ها Sat، Sun خواهند بود؛ دوره‌ها Sat، Sun\-Fri خواهند بود T} .TE .SH "عمق (DEPTH)" با گزینه \f[CR]\-\-depth NUM\f[R] (شکل کوتاه، که معمولاً ترجیح داده می‌شود: \f[CR]\-NUM\f[R])، گزارش‌ها حساب‌ها را تنها تا عمق تعیین‌شده نمایش می‌دهند و زیرحساب‌های عمیق‌تر را پنهان می‌کنند. زمانی که خلاصه‌ای با جزئیات کمتر می‌خواهید از این گزینه استفاده کنید. این پرچم همان تأثیر آرگومان پرس‌وجوی \f[CR]depth:\f[R] را دارد. بنابراین همه این موارد معادل یکدیگرند: \f[CR]depth:2\f[R]، \f[CR]\-\-depth=2\f[R]، \f[CR]\-2\f[R]. .PP همچنین می‌توانید به جای تنها \f[CR]NUM\f[R]، با ارائه یک آرگومان \f[CR]REGEX=NUM\f[R] عمق‌های سفارشی را برای حساب‌های خاص تعیین کنید \f[I](از نسخه 1.41)\f[R]. برای مثال، \f[CR]\-\-depth assets=2\f[R] (یا \f[CR]depth:assets=2\f[R]) حساب‌های منطبق با عبارت منظم \(dqassets\(dq را تا عمق ۲ جمع (خلاصه) می‌کند. بنابراین \f[CR]assets:bank:savings\f[R] به \f[CR]assets:bank\f[R] جمع می‌شود، اما \f[CR]liabilities:bank:credit card\f[R] تحت تأثیر قرار نخواهد گرفت. .PP اگر REGEX شامل فاصله یا دیگر نویسه‌های خاص است، طبق معمول آن را داخل نقل‌قول قرار دهید. مانند: \f[CR]\-\-depth \(aqcredit card=2\(aq\f[R] .SS "ترکیب گزینه‌های عمق" اگر یک خط فرمان شامل چندین گزینه عمومی عمق باشد، آخرین گزینه اعمال می‌شود. (برای بازنویسی و نادیده‌گرفتن عمق مشخص‌شده توسط اسکریپت‌ها مفید است.) .PP یا ممکن است یک دستور شامل ترکیبی از گزینه‌های عمومی و سفارشی عمق باشد. در این حالت، گزینه‌ای که خاص‌ترین (عمیق‌ترین) تطابق را داشته باشد اعمال می‌شود. چند مثال: .IP \(bu 2 دستور \f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] حساب‌های حاوی \(dqassets\(dq را تا عمق ۳، حساب‌های حاوی \(dqexpenses\(dq را تا عمق ۲، و تمام حساب‌های دیگر را تا عمق ۱ جمع می‌کند. .IP \(bu 2 دستور \f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R] حساب \f[CR]assets:bank:savings\f[R] را تا عمق ۲ جمع می‌کند (نه عمق ۱؛ زیرا \(dqsavings\(dq نسبت به \(dqassets\(dq با بخش عمیق‌تری از نام حساب تطابق دارد). .PP توجه داشته باشید که در حال حاضر، برای لغو یک گزینه سفارشی عمق \f[CR]\-\-depth REGEX=NUM\f[R] با گزینه‌ای پس از آن، گزینه بعدی باید از همان REGEX استفاده کند..SH "پرس‌وجوها (QUERIES)" بسیاری از دستورهای hledger آرگومان‌های پرس‌وجو را می‌پذیرند که دامنهٔ عملکرد آن‌ها را محدود کرده و امکان گزارش‌گیری از زیرمجموعهٔ دقیقی از داده‌هایتان را فراهم می‌کنند. در اینجا یک نمای کلی و سریع از پرس‌وجوهای hledger آمده است: .IP \(bu 2 به‌طور پیش‌فرض، یک آرگومان پرس‌وجو به عنوان یک الگوی زیررشته‌ای نا‌وابسته به بزرگی و کوچکی حروف برای تطبیق نام حساب‌ها در نظر گرفته می‌شود. برای نمونه: .RS 2 .PP \f[CR]dining groceries\f[R] .PD 0 .P .PD \f[CR]car:fuel\f[R] .PD 0 .P .PD .RE .IP \(bu 2 الگوهایی که شامل فاصله یا نویسه‌های خاص دیگر هستند باید درون نقل‌قول تکی یا دوتایی قرار گیرند: .RS 2 .PP \f[CR]\(aqpersonal care\(aq\f[R] .PD 0 .P .PD .RE .IP \(bu 2 الگوها در واقع عبارات باقاعده (regular expressions) هستند، بنابراین می‌توانید برای دقت بیشتر فرانویسه‌های عبارت باقاعده را اضافه کنید (یا ممکن است لازم باشد نویسه‌های خاصی را با بک‌اسلش فراردهی کنید؛ بخش \(dqRegular expressions\(dq در بالا را ببینید): .RS 2 .PP \f[CR]\(aq\(haexpenses\(rsb\(aq\f[R] .PD 0 .P .PD \f[CR]\(aqfood$\(aq\f[R] .PD 0 .P .PD \f[CR]\(aqfuel|repair\(aq\f[R] .PD 0 .P .PD \f[CR]\(aqaccounts (payable|receivable)\(aq\f[R] .PD 0 .P .PD .RE .IP \(bu 2 برای تطبیق چیزی به جز نام حساب، می‌توانید یک پیشوند نوع پرس‌وجو اضافه کنید، مانند: .RS 2 .PP \f[CR]date:202312\-\f[R] .PD 0 .P .PD \f[CR]status:\f[R] .PD 0 .P .PD \f[CR]desc:amazon\f[R] .PD 0 .P .PD \f[CR]cur:USD\f[R] .PD 0 .P .PD \f[CR]cur:\(rs\(rs$\f[R] .PD 0 .P .PD \f[CR]amt:\(aq>0\(aq\f[R] .PD 0 .P .PD \f[CR]acct:groceries\f[R] (اما \f[CR]acct:\f[R] حالت پیش‌فرض است، بنابراین معمولاً نیازی به نوشتن آن نیست) .PD 0 .P .PD .RE .IP \(bu 2 برای نفی یک پرس‌وجو، پیشوند \f[CR]not:\f[R] را اضافه کنید: .RS 2 .PP \f[CR]not:status:\(aq*\(aq\f[R] .PD 0 .P .PD \f[CR]not:desc:\(aqopening|closing\(aq\f[R] .PD 0 .P .PD \f[CR]not:cur:USD\f[R] .PD 0 .P .PD .RE .IP \(bu 2 چندین عبارت پرس‌وجو را می‌توان به صورت پرس‌وجوهای جداشده با فاصله ترکیب کرد؛ برای نمونه: \f[CR]hledger print date:2022 desc:amazon desc:amzn\f[R] (نمایش تراکنش‌های با تاریخ سال 2022 که شرح آن‌ها شامل \(dqamazon\(dq یا \(dqamzn\(dq است). .PD 0 .P .PD .IP \(bu 2 یا با انعطاف‌پذیری بیشتر به صورت پرس‌وجوهای بولی (boolean). برای نمونه: \f[CR]hledger print expr:\(aqdate:2022 and (desc:amazon or desc:amzn) and not date:202210\(aq\f[R] .PD 0 .P .PD .PP تمامی دستورهای hledger از یک زبان پرس‌وجوی یکسان استفاده می‌کنند، اما دستورهای مختلف ممکن است پرس‌وجو را به روش‌های گوناگونی تفسیر کنند. ما هنوز دستورها را شرح نداده‌ایم (این مورد در «بخش ۴: دستورها» (PART 4: COMMANDS) در ادامه خواهد آمد) اما اساس کار به شرح زیر است: .IP \(bu 2 دستورهای تراکنش‌محور (\f[CR]print\f[R]، \f[CR]aregister\f[R]، \f[CR]close\f[R]، \f[CR]import\f[R]، \f[CR]descriptions\f[R]...) تلاش می‌کنند تراکنش‌ها (شامل ثبت‌های تراکنش) را تطبیق دهند. .IP \(bu 2 دستورهای ثبت‌محور (\f[CR]register\f[R]، \f[CR]balance\f[R]، \f[CR]balancesheet\f[R]، \f[CR]incomestatement\f[R]، \f[CR]accounts\f[R]...) تلاش می‌کنند ثبت‌ها (postings) را تطبیق دهند. ثبت‌ها ویژگی‌های تراکنش خود را برای اهداف پرس‌وجو به ارث می‌برند، بنابراین فیلدهای تراکنش مانند تاریخ یا شرح همچنان می‌توانند در یک پرس‌وجوی ثبت مورد ارجاع قرار گیرند. .IP \(bu 2 تعداد کمی از دستورها به روش‌های خاص‌تری تطبیق می‌دهند. (مانند \f[CR]aregister\f[R]، که یک آرگومان اول ویژه دارد.).SS انواع پرس‌وجو (Query types) انواع پرس‌وجوهای موجود در زیر آمده است: .SS پرس‌وجوی acct: \f[B]\f[CB]acct:REGEX\f[B]\f[R]، یا صرفاً \f[B]\f[CB]REGEX\f[B]\f[R] .PD 0 .P .PD نام‌های حسابی را که شامل این عبارت باقاعده (غیرحساس به حروف بزرگ و کوچک) باشند مطابقت می‌دهد. .PD 0 .P .PD این نوع پرس‌وجوی پیش‌فرض است، بنابراین معمولاً نیازی به نوشتن پیشوند \(dqacct:\(dq نیست. .SS پرس‌وجوی amt: \f[B]\f[CB]amt:N, amt:\(aqN\(aq, amt:\(aq>=N\(aq\f[B]\f[R] .PD 0 .P .PD ثبت‌های با مقدار تک‌کالایی برابر، کمتر، یا بیشتر از N را تطبیق می‌دهد. (ثبت‌های دارای مقادیر چندکالایی بررسی نمی‌شوند و همیشه مطابقت خواهند داشت.) برای پنهان کردن علامت‌های کوچکتری/بزرگتری از پوسته خط فرمان، \f[CR]amt:\f[R] نیازمند علامت نقل‌قول است. .PP این مقایسه دو حالت دارد: اگر پیش از N علامت + یا \- آمده باشد (یا ۰ باشد)، دو عدد دارای علامت با یکدیگر مقایسه می‌شوند. در غیر این صورت، اندازه قدر مطلق اعداد بدون در نظر گرفتن علامت مقایسه خواهد شد. .PP به یاد داشته باشید که \f[CR]amt:\f[R] مقادیر ثبت‌ها را مطابقت می‌دهد، نه تراز حساب‌ها را. .SS پرس‌وجوی code: \f[B]\f[CB]code:REGEX\f[B]\f[R] .PD 0 .P .PD تطبیق بر اساس کد تراکنش (مانند شماره چک). .SS پرس‌وجوی cur: \f[B]\f[CB]cur:REGEX\f[B]\f[R] .PD 0 .P .PD ثبت‌ها یا تراکنش‌هایی را تطبیق می‌دهد که شامل هر مقداری باشند که نماد ارز/کالای آن به‌طور کامل با REGEX تطبیق یابد. (برخلاف روش معمول تطبیق میانی در hledger. برای انجام تطبیق میانی، \f[CR].*REGEX.*\f[R] را وارد کنید.) توجه داشته باشید که برای تطبیق نویسه‌های خاصی که در عبارت باقاعده معنای ویژه دارند، باید آن‌ها را با \f[CR]\(rs\f[R] گریزدهی (escape) کنید. و برای نویسه‌هایی که برای پوسته شما معنای خاص دارند، معمولاً به یک سطح گریزدهی بیشتر نیاز خواهید داشت. به عنوان مثال برای تطبیق علامت دلار: \f[CR]cur:\(rs\(rs$\f[R] یا \f[CR]cur:\(aq\(rs$\(aq\f[R] .SS پرس‌وجوی desc: \f[B]\f[CB]desc:REGEX\f[B]\f[R] .PD 0 .P .PD توضیحات تراکنش را مطابقت می‌دهد. .SS پرس‌وجوی date: \f[B]\f[CB]date:PERIODEXPR\f[B]\f[R] .PD 0 .P .PD تاریخ‌ها (یا با پرچم \f[CR]\-\-date2\f[R]، تاریخ‌های ثانویه) را در دوره زمانی مشخص‌شده مطابقت می‌دهد. عبارت PERIODEXPR یک عبارت دوره زمانی است. مثال‌ها: .PD 0 .P .PD \f[CR]date:2016\f[R]، \f[CR]date:thismonth\f[R]، \f[CR]date:2/1\-2/15\f[R]، \f[CR]date:2021\-07\-27..nextquarter\f[R]. .PP عبارت PERIODEXPR می‌تواند شامل یک بازه گزارش‌گیری باشد (از نسخه 1.52). در خط فرمان، این معادل تعیین یک بازه گزارش‌گیری با استفاده از گزینه‌های خط فرمان است. در سایر محیط‌ها (مانند hledger\-ui و hledger\-web)، بازه گزارش‌گیری ممکن است نادیده گرفته شود. .SS پرس‌وجوی date2: \f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R] .PD 0 .P .PD اگر از تاریخ‌های ثانویه استفاده می‌کنید: این پرس‌وجو تاریخ‌های ثانویه را در دوره زمانی مشخص‌شده تطبیق می‌دهد. این پرس‌وجو تحت تأثیر پرچم \f[CR]\-\-date2\f[R] قرار نمی‌گیرد. هرگونه بازه گزارش‌گیری در PERIODEXPR نادیده گرفته خواهد شد..SS پرس‌وجوی depth: \f[B]\f[CB]depth:[REGEXP=]N\f[B]\f[R] .PD 0 .P .PD تطبیق (یا بسته به دستور، نمایش) حساب‌ها در این عمق یا بالاتر از آن؛ به صورت اختیاری تنها برای حساب‌هایی که با یک عبارت باقاعده ارائه‌شده مطابقت دارند. برای قوانین دقیق، بخش Depth را ببینید. .SS پرس‌وجوی note: \f[B]\f[CB]note:REGEX\f[B]\f[R] .PD 0 .P .PD تطبیق یادداشت‌های تراکنش (بخشی از توضیحات که در سمت راست \f[CR]|\f[R] قرار دارد، یا کل توضیحات در صورتی که نویسهٔ \f[CR]|\f[R] وجود نداشته باشد). .SS پرس‌وجوی payee: \f[B]\f[CB]payee:REGEX\f[B]\f[R] .PD 0 .P .PD تطبیق نام‌های دریافت‌کننده/پرداخت‌کنندهٔ تراکنش (بخشی از توضیحات که در سمت چپ \f[CR]|\f[R] قرار دارد، یا کل توضیحات در صورتی که نویسهٔ \f[CR]|\f[R] وجود نداشته باشد). .SS پرس‌وجوی real: \f[B]\f[CB]real:, real:0\f[B]\f[R] .PD 0 .P .PD تطبیق ثبت‌های (postings) واقعی یا مجازی، به ترتیب. .SS پرس‌وجوی status: \f[B]\f[CB]status:, status:!, status:*\f[B]\f[R] .PD 0 .P .PD تطبیق تراکنش‌های بدون علامت، در انتظار یا تسویه‌شده، به ترتیب. .SS پرس‌وجوی type: \f[B]\f[CB]type:TYPECODES\f[B]\f[R] .PD 0 .P .PD تطبیق بر اساس نوع حساب (بخش Declaring accounts > Account types را ببینید). \f[CR]TYPECODES\f[R] یک یا چند کد تک‌حرفی نوع حساب از \f[CR]ALERXCVG\f[R]، بدون حساسیت به بزرگی و کوچکی حروف است. توجه داشته باشید که \f[CR]type:A\f[R]، \f[CR]type:E\f[R] و \f[CR]type:R\f[R] با زیرنوع‌های مربوط به خود یعنی \f[CR]C\f[R] (نقدینگی - Cash)، \f[CR]V\f[R] (تبدیل - Conversion) و \f[CR]G\f[R] (سود - Gain) نیز تطبیق خواهند یافت. انواع خاصی از نام‌های مستعار حساب (alias) می‌توانند انواع حساب را مختل کنند؛ بخش Rewriting accounts > Aliases and account types را ببینید. .SS پرس‌وجوی tag: \f[B]\f[CB]tag:NAMEREGEX[=VALREGEX]\f[B]\f[R] .PD 0 .P .PD تطبیق بر اساس نام برچسب، و به‌طور اختیاری بر اساس مقدار برچسب نیز. نکته: .IP \(bu 2 هر دو عبارت باقاعده تطبیق میانی انجام می‌دهند. اگر به تطبیق کامل نیاز دارید، از \f[CR]\(ha\f[R] و \f[CR]$\f[R] استفاده کنید. .PD 0 .P .PD برای مثال: \f[CR]tag:\(aq\(hafullname$\(aq\f[R]، \f[CR]tag:\(aq\(hafullname$=\(hafullvalue$\f[R] .IP \(bu 2 برای تطبیق مقادیر با نادیده گرفتن نام‌ها، از \f[CR]tag:.=VALREGEX\f[R] استفاده کنید. .IP \(bu 2 حساب‌ها برچسب‌های حساب‌های والد خود را نیز به ارث می‌برند. .IP \(bu 2 ثبت‌ها برچسب‌های حساب و تراکنش خود را نیز به ارث می‌برند. .IP \(bu 2 تراکنش‌ها نیز برچسب‌های ثبت‌های خود را دریافت می‌کنند. .SS پرس‌وجوهای منفی .SS پرس‌وجوی not: \f[B]\f[CB]not:QUERY\f[B]\f[R] .PD 0 .P .PD می‌توانید \f[B]\f[CB]not:\f[B]\f[R] را به ابتدای یک پرس‌وجو اضافه کنید تا تطبیق نقیض شود. .PD 0 .P .PD برای مثال: \f[CR]not:equity\f[R]، \f[CR]not:desc:apple\f[R] .PD 0 .P .PD (همچنین، یک ترفند: عبارت \f[CR]not:not:...\f[R] گاهی اوقات می‌تواند مشکلات پرس‌وجو را به‌سادگی برطرف کند.).SS پرس‌وجوهای جداشده با فاصله هنگامی که چندین عبارت پرس‌وجوی جداشده با فاصله داده می‌شود، بیشتر دستورها مواردی را انتخاب می‌کنند که با این شرایط مطابقت داشته باشند: .IP \(bu 2 هر یک از عبارت‌های شرح AND .IP \(bu 2 هر یک از عبارت‌های حساب AND .IP \(bu 2 هر یک از عبارت‌های وضعیت AND .IP \(bu 2 تمام عبارت‌های دیگر. .PP دستور print کمی متفاوت است و تراکنش‌هایی را نمایش می‌دهد که: .IP \(bu 2 با هر یک از عبارت‌های شرح مطابقت داشته باشند AND .IP \(bu 2 دارای ثبت‌هایی باشند که با هر یک از عبارت‌های مثبت حساب مطابقت دارند AND .IP \(bu 2 هیچ ثبتی نداشته باشند که با هر یک از عبارت‌های منفی حساب مطابقت داشته باشد AND .IP \(bu 2 با تمام عبارت‌های دیگر مطابقت داشته باشند. .SS پرس‌وجوهای بولی می‌توانید عبارت‌های پرس‌وجوی پیچیده‌تر \(dqبولی\(dq بنویسید که در گیومه قرار گرفته و پیشوند \f[CR]expr:\f[R] دارند. این عبارت‌ها می‌توانند زیرپرس‌وجوها را با عملگرهای NOT،‏ AND و OR (غیرحساس به حروف بزرگ و کوچک) و پرانتزها برای گروه‌بندی ترکیب کنند. برای مثال، جهت نمایش تراکنش‌هایی که هم شامل حساب‌های cash و هم expenses هستند: .IP .EX hledger print expr:\(aqcash AND expenses\(aq .EE .PP پیشوند و گیومه‌های دربرگیرنده الزامی هستند، بنابراین \f[CR]hledger print cash AND expenses\f[R] را ننویسید. این حالت یک پرس‌وجوی جداشده با فاصله خواهد بود که تراکنش‌های شامل حساب‌هایی با هر یک از \(dqcash\(dq،‏ \(dqand\(dq یا \(dqexpenses\(dq در نامشان را نشان می‌دهد. .PP می‌توانید پرس‌وجوهای جداشده با فاصله را \f[I]درون\f[R] یک پرس‌وجوی بولی بنویسید، و آن‌ها همان‌طور که در بالا توضیح داده شد ترکیب خواهند شد، اما این کار ممکن است گیج‌کننده باشد و بهتر است از آن اجتناب شود. برای مثال موارد زیر معادل هستند و تراکنش‌های شامل حساب‌های cash یا expenses را نمایش می‌دهند: .IP .EX hledger print expr:\(aqcash expenses\(aq hledger print cash expenses .EE .PP محدودیتی در مورد پرس‌وجوهای \f[CR]date:\f[R] وجود دارد: آن‌ها را نمی‌توان درون عبارت‌های OR استفاده کرد. .PP در واقع، سه نوع پرس‌وجوی بولی وجود دارد: \f[CR]expr:\f[R] برای استفادهٔ عمومی، و گونه‌های \f[CR]any:\f[R] و \f[CR]all:\f[R] که می‌توانند همراه با \f[CR]print\f[R] مفید باشند. .SS پرس‌وجوی expr: \f[B]\f[CB]expr:\(aqQUERYEXPR\(aq\f[B]\f[R] .PD 0 .P .PD برای مثال، \f[CR]expr:\(aqdate:lastmonth AND NOT (food OR rent)\(aq\f[R] به این معنی است: \(dqتطبیق مواردی که تاریخ آن‌ها در ماه گذشته است و food یا rent در نام حساب آن‌ها وجود ندارد\(dq. .PP هنگام استفاده از \f[CR]expr:\f[R] با دستورهای مبتنی بر تراکنش مانند \f[CR]print\f[R]، عبارت‌های پرس‌وجوی مبتنی بر ثبت مانند \f[CR]acct:\f[R] و \f[CR]amt:\f[R] در صورتی منطبق بر تراکنش در نظر گرفته می‌شوند که با هر یک از ثبت‌های آن مطابقت داشته باشند. .PD 0 .P .PD بنابراین، \f[CR]hledger print expr:\(aqcash and amt:>0\(aq\f[R] به این معنی است: \(dqنمایش تراکنش‌هایی با (حداقل یک ثبت شامل یک حساب cash) و (حداقل یک ثبت با مبلغ مثبت)\(dq. .SS پرس‌وجوی any: \f[B]\f[CB]any:\(aqQUERYEXPR\(aq\f[B]\f[R] .PD 0 .P .PD مانند \f[CR]expr:\f[R] است، اما هنگامی که با دستورهای مبتنی بر تراکنش مانند \f[CR]print\f[R] استفاده می‌شود، تراکنش را تنها در صورتی مطابقت می‌دهد که یک ثبت بتواند با تمام QUERYEXPR مطابقت داشته باشد. .PD 0 .P .PD بنابراین، \f[CR]hledger print any:\(aqcash and amt:>0\(aq\f[R] به این معنی است: \(dqنمایش تراکنش‌هایی که در آن‌ها حداقل یک ثبت، مبلغ مثبتی را به یک حساب cash منظور می‌کند\(dq..SS پرسمان all: \f[B]\f[CB]all:\(aqQUERYEXPR\(aq\f[B]\f[R] .PD 0 .P .PD مشابه \f[CR]expr:\f[R] است، اما هنگامی که با دستورهای تراکنش‌محور مانند \f[CR]print\f[R] استفاده می‌شود، تراکنش را تنها در صورتی مطابقت می‌دهد که تمام ثبت‌ها (postings) با تمام بخش‌های QUERYEXPR مطابقت داشته باشند (و حداقل یک ثبت وجود داشته باشد). .PD 0 .P .PD بنابراین، \f[CR]hledger print all:\(aqcash and amt:0\(aq\f[R] به این معنی است: \(dqتراکنش‌هایی را نشان بده که در آن‌ها همهٔ ثبت‌ها مربوط به یک حساب نقدی (cash) بوده و مقدار مبلغ آن‌ها صفر باشد\(dq. .PD 0 .P .PD یا \f[CR]hledger print all:\(aqcash or checking\(aq\f[R] یعنی \(dqتراکنش‌هایی را نشان بده که تنها به حساب‌های نقدی (cash) و/یا جاری (checking) مربوط می‌شوند\(dq. .SS پرسمان‌ها و گزینه‌های دستور برخی پرسمان‌ها را می‌توان به صورت گزینه‌های خط فرمان نیز بیان کرد: \f[CR]depth:2\f[R] معادل \f[CR]\-\-depth 2\f[R] است، \f[CR]date:2023\f[R] معادل \f[CR]\-p 2023\f[R] است، و غیره. هنگامی که گزینه‌های دستور و آرگومان‌های پرسمان را با هم ترکیب می‌کنید، عموماً پرسمان حاصل اشتراک آن‌ها خواهد بود. .SS پرسمان‌ها و نام‌های مستعار حساب هنگامی که نام‌های حساب با \f[CR]\-\-alias\f[R] یا \f[CR]alias\f[R] بازنویسی می‌شوند، \f[CR]acct:\f[R] با نام قدیم یا جدید حساب مطابقت خواهد داشت. .SS پرسمان‌ها و ارزش‌گذاری هنگامی که مبالغ در گزارش‌های بهای تمام‌شده یا ارزش به کالاها/ارزهای دیگر تبدیل می‌شوند، \f[CR]cur:\f[R] و \f[CR]amt:\f[R] با نماد کالای قدیمی و مقدار مبلغ پیشین مطابقت داده می‌شوند، نه موارد جدید. (به‌جز در hledger 1.22، شمارهٔ #1625.) .SH "محورسازی (PIVOTING)" به طور معمول، hledger مبالغ را گروه‌بندی کرده و مجموع آن‌ها را بر اساس (نام) حساب نمایش می‌دهد. با گزینهٔ \f[CR]\-\-pivot PIVOTEXPR\f[R]، مقدار یک فیلد دیگر (یا چند فیلد) به عنوان نام حساب ساختگی استفاده می‌شود که باعث گروه‌بندی و نمایش متفاوتی می‌گردد. PIVOTEXPR می‌تواند موارد زیر باشد: .IP \(bu 2 هر یک از این فیلدهای استاندارد تراکنش یا ثبت (که مقدار آن‌ها جایگزین می‌شود): \f[CR]status\f[R]، \f[CR]code\f[R]، \f[CR]desc\f[R]، \f[CR]payee\f[R]، \f[CR]note\f[R]، \f[CR]acct\f[R]، \f[CR]comm\f[R]/\f[CR]cur\f[R]، \f[CR]amt\f[R]، \f[CR]cost\f[R] .IP \(bu 2 یا نام یک برچسب (tag) .IP \(bu 2 یا هر ترکیبی از این موارد، جداشده با دونقطه (colon\-separated). .PP برخی موارد خاص: .IP \(bu 2 دونقطه‌هایی که در PIVOTEXPR یا در مقدار یک برچسب محورسازی‌شده ظاهر شوند، سلسله‌مراتب حساب ایجاد خواهند کرد. .IP \(bu 2 هنگام محورسازی ثبتی که چندین مقدار برای یک برچسب دارد، نخستین مقدار آن برچسب به عنوان مقدار محورسازی‌شده استفاده خواهد شد. .IP \(bu 2 هنگامی که یک ثبت دارای چندین کالا/ارز باشد، مقدار محورسازی‌شدهٔ \(dqcomm\(dq/\(dqcur\(dq برابر \(dq\(dq خواهد بود. همچنین هنگامی که یک نام برچسب یا فیلد ناشناخته ارائه شود، مقدار محورسازی‌شدهٔ آن \(dq\(dq خواهد بود. (اگر این مسئله باعث ایجاد خروجی گیج‌کننده می‌شود، خارج کردن آن ثبت‌ها از گزارش را در نظر بگیرید.) .PP مثال‌ها: .IP .EX 2016/02/16 Yearly Dues Payment assets:bank account 2 EUR income:dues \-2 EUR ; member: John Doe, kind: Lifetime .EE .PP گزارش تراز عادی که نام‌های حساب را نشان می‌دهد: .IP .EX $ hledger balance 2 EUR assets:bank account \-2 EUR income:dues \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP گزارش تراز محورسازی‌شده، با استفاده از مقادیر برچسب member: به جای نام حساب: .IP .EX $ hledger balance \-\-pivot member 2 EUR \-2 EUR John Doe \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP یک روش برای نمایش تنها مبالغی که دارای مقدار member: هستند (با استفاده از یک پرسمان): .IP .EX $ hledger balance \-\-pivot member tag:member=. \-2 EUR John Doe \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-2 EUR .EE .PP روشی دیگر (پرسمان acct: با \(dqنام حساب\(dq محورسازی‌شده مطابقت داده می‌شود): .IP .EX $ hledger balance \-\-pivot member acct:. \-2 EUR John Doe \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-2 EUR .EE .PP گزارش‌های سلسله‌مراتبی می‌توانند با مقادیر محوری چندگانه تولید شوند: .IP .EX $ hledger balance Income:Dues \-\-pivot kind:member \-2 EUR Lifetime:John Doe \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-2 EUR .EE.SH "تولید داده (Generating data)" برنامهٔ hledger می‌تواند داده‌های ارائه‌شده به آن را غنی‌تر کند، یا به چندین روش داده‌های جدیدی تولید نماید. در بیشتر موارد، این کار تنها در صورتی انجام می‌شود که شما درخواست کنید: .IP \(bu 2 مبالغ یا هزینه‌های ناموجود در تراکنش‌ها در صورت امکان به‌طور خودکار استنباط می‌شوند. .IP \(bu 2 پرچم \f[CR]\-\-infer\-equity\f[R] ثبت‌های حقوق صاحبان سهام تبدیل (conversion equity postings) ناموجود را از روی هزینه‌های \(at/\(at\(at استنباط می‌کند. .IP \(bu 2 پرچم \f[CR]\-\-infer\-costs\f[R] هزینه‌های ناموجود را از روی ثبت‌های حقوق صاحبان سهام تبدیل استنباط می‌کند. .IP \(bu 2 پرچم \f[CR]\-\-infer\-market\-prices\f[R] دستورالعمل‌های قیمت \f[CR]P\f[R] را از روی هزینه‌ها استنباط می‌کند. .IP \(bu 2 پرچم \f[CR]\-\-auto\f[R] ثبت‌های اضافی را به تراکنش‌هایی که با قوانین ثبت خودکار مطابقت دارند، اضافه می‌کند. .IP \(bu 2 گزینهٔ \f[CR]\-\-forecast\f[R] تراکنش‌ها را از روی قوانین تراکنش‌های دوره‌ای تولید می‌کند. .IP \(bu 2 گزارش \f[CR]balance \-\-budget\f[R] اهداف بودجه را از روی قوانین تراکنش‌های دوره‌ای استنباط می‌کند. .IP \(bu 2 دستوراتی مانند \f[CR]close\f[R]، \f[CR]rewrite\f[R] و \f[CR]hledger\-interest\f[R] تراکنش‌ها یا ثبت‌ها را تولید می‌کنند. .IP \(bu 2 داده‌های CSV با اِعمال قوانین تبدیل CSV به تراکنش‌ها تبدیل می‌شوند... و غیره. .PP چنین داده‌های تولیدشده‌ای موقتی بوده و تنها در زمان گزارش‌گیری وجود دارند. می‌توانید با کارهایی نظیر دریافت خروجی \f[CR]hledger print\f[R] و ذخیرهٔ آن در فایل دفتر روزنامه (journal) خود، آن را به داده‌های ثبت‌شدهٔ دائمی تبدیل کنید. این قابلیت گاهی می‌تواند به عنوان ابزار کمکی برای ورود داده‌ها مفید باشد. .PP اگر کنجکاوید بدانید چه داده‌هایی و به چه دلیلی در حال تولید هستند، دستور \f[CR]hledger print \-x \-\-verbose\-tags\f[R] را اجرا کنید. گزینهٔ \f[CR]\-x/\-\-explicit\f[R] مبالغ استنباط‌شده را نشان می‌دهد و \f[CR]\-\-verbose\-tags\f[R] برچسب‌هایی مانند \f[CR]generated\-transaction\f[R] (از قوانین دوره‌ای) و \f[CR]generated\-posting\f[R]، \f[CR]modified\f[R] (از قوانین ثبت خودکار) را اضافه می‌کند. برچسب‌های پنهان مشابهی (با پیشوند خط زیرین _) نیز همواره وجود دارند، بنابراین همیشه می‌توانید با پرس‌وجوهایی مانند \f[CR]tag:generated\f[R] یا \f[CR]tag:modified\f[R] این داده‌ها را تطبیق دهید. .SH "پیش‌بینی (Forecasting)" پیش‌بینی یا گزارش‌گیری حدسی از آینده، می‌تواند برای برآورد موجودی‌های آتی، یا برای بررسی سناریوهای مختلف آینده مفید باشد. .PP ساده‌ترین و منعطف‌ترین راه برای انجام این کار در hledger، ثبت دستی مجموعه‌ای از تراکنش‌های با تاریخ آینده است. می‌توانید این تراکنش‌ها را در یک فایل \f[CR]future.journal\f[R] جداگانه نگه داشته و تنها زمانی که می‌خواهید آنها را مشاهده کنید، با \f[CR]\-f\f[R] آن را وارد نمایید. .SS \-\-forecast روش دیگری نیز وجود دارد: با گزینهٔ \f[CR]\-\-forecast\f[R]، ابزار hledger می‌تواند بر اساس قوانین تراکنش‌های دوره‌ای تعریف‌شده در دفتر روزنامه، \(dqتراکنش‌های پیش‌بینی\(dq موقتی را برای اهداف گزارش‌گیری تولید کند. هر قاعده می‌تواند چندین تراکنش تکرارشونده ایجاد کند، بنابراین با تغییر یک قاعده می‌توانید تعداد زیادی از تراکنش‌های پیش‌بینی‌شده را دگرگون کنید. .PP تراکنش‌های پیش‌بینی معمولاً پس از پایان تراکنش‌های عادی آغاز می‌شوند. به‌طور پیش‌فرض، آنها بعد از آخرین تاریخ تراکنش عادی شما، یا امروز (هر کدام که دیرتر باشد) شروع شده و شش ماه پس از امروز خاتمه می‌یابند. (قوانین دقیق کمی پیچیده‌تر هستند و در ادامه ارائه شده‌اند.) .PP این بازه، \(dqدورهٔ پیش‌بینی\(dq نامیده می‌شود که لزومی ندارد با دورهٔ گزارش‌گیری یکسان باشد. می‌توانید با دادن یک آرگومان عبارت دوره به گزینهٔ \-\-forecast آن را بازنویسی کنید \- برای مثال جهت پیش‌بینی برای آینده‌ای دورتر، یا اجبار تراکنش‌های پیش‌بینی به هم‌پوشانی با تراکنش‌های عادی خود \- مانند \f[CR]\-\-forecast=..2099\f[R] یا \f[CR]\-\-forecast=2023\-02\-15..\f[R]. توجه داشته باشید که علامت \f[CR]=\f[R] الزامی است. .SS "بررسی تراکنش‌های پیش‌بینی (Inspecting forecast transactions)" دستور \f[CR]print\f[R] بهترین دستور برای بررسی و عیب‌یابی تراکنش‌های پیش‌بینی است. برای مثال: .IP .EX \(ti monthly from 2022\-12\-20 rent assets:bank:checking expenses:rent $1000 .EE .IP .EX $ hledger print \-\-forecast \-\-today=2023/4/21 2023\-05\-20 rent ; generated\-transaction: \(ti monthly from 2022\-12\-20 assets:bank:checking expenses:rent $1000 2023\-06\-20 rent ; generated\-transaction: \(ti monthly from 2022\-12\-20 assets:bank:checking expenses:rent $1000 2023\-07\-20 rent ; generated\-transaction: \(ti monthly from 2022\-12\-20 assets:bank:checking expenses:rent $1000 2023\-08\-20 rent ; generated\-transaction: \(ti monthly from 2022\-12\-20 assets:bank:checking expenses:rent $1000 2023\-09\-20 rent ; generated\-transaction: \(ti monthly from 2022\-12\-20 assets:bank:checking expenses:rent $1000 .EE .PP در اینجا هیچ تراکنش عادی وجود ندارد، بنابراین تراکنش‌های پیش‌بینی‌شده از اولین موعد پس از تاریخ امروز آغاز می‌شوند. (شما در حالت معمول از \f[CR]\-\-today\f[R] استفاده نخواهید کرد؛ این گزینه صرفاً برای تکرارپذیر ساختن این مثال‌ها آورده شده است.).SS "گزارش‌های پیش‌بینی (Forecast reports)" تراکنش‌های پیش‌بینی همان‌طور که انتظار می‌رود بر تمام گزارش‌ها تأثیر می‌گذارند. برای نمونه: .IP .EX $ hledger areg rent \-\-forecast \-\-today=2023/4/21 Transactions in expenses:rent and subaccounts: 2023\-05\-20 rent as:ba:checking $1000 $1000 2023\-06\-20 rent as:ba:checking $1000 $2000 2023\-07\-20 rent as:ba:checking $1000 $3000 2023\-08\-20 rent as:ba:checking $1000 $4000 2023\-09\-20 rent as:ba:checking $1000 $5000 .EE .IP .EX $ hledger bal \-M expenses \-\-forecast \-\-today=2023/4/21 Balance changes in 2023\-05\-01..2023\-09\-30: || May Jun Jul Aug Sep ===============++=================================== expenses:rent || $1000 $1000 $1000 $1000 $1000 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || $1000 $1000 $1000 $1000 $1000 .EE .SS "برچسب‌های پیش‌بینی (Forecast tags)" تراکنش‌های پیش‌بینی ایجادشده با \-\-forecast دارای یک برچسب پنهان، \f[CR]_generated\-transaction\f[R] هستند. بنابراین اگر زمانی نیاز به تطبیق تراکنش‌های پیش‌بینی داشتید، می‌توانید از \f[CR]tag:_generated\-transaction\f[R] (یا صرفاً \f[CR]tag:generated\f[R]) در یک پرس‌وجو استفاده کنید. .PP برای عیب‌یابی، می‌توانید پرچم \f[CR]\-\-verbose\-tags\f[R] را اضافه کنید. سپس، برچسب‌های آشکار \f[CR]generated\-transaction\f[R] نیز افزوده خواهند شد، به‌گونه‌ای که می‌توانید آن‌ها را با دستور \f[CR]print\f[R] مشاهده کنید. مقدار آن‌ها مشخص می‌کند کدام قاعده دوره‌ای عامل ایجاد آن بوده است. .SS "دوره پیش‌بینی، با جزئیات (Forecast period, in detail)" تاریخ‌های آغاز و پایان پیش‌بینی به‌گونه‌ای انتخاب می‌شوند که به‌طور پیش‌فرض در تقریباً همه موقعیت‌ها عملکرد مفیدی داشته باشند، در عین حال که انعطاف‌پذیر نیز باقی بمانند. در اینجا قواعد دقیق (به‌امید خدا) برای کمک به عیب‌یابی آورده شده است: .PP دوره پیش‌بینی از تاریخ زیر آغاز می‌شود: .IP \(bu 2 تاریخ متأخرتر بین .RS 2 .IP \(bu 2 تاریخ آغاز در قاعده تراکنش دوره‌ای .IP \(bu 2 تاریخ آغاز در آرگومان \f[CR]\-\-forecast\f[R] .RE .IP \(bu 2 در غیر این صورت (اگر آن موارد در دسترس نباشند): تاریخ متأخرتر بین .RS 2 .IP \(bu 2 تاریخ آغاز گزارش مشخص‌شده با \f[CR]\-b\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R] .IP \(bu 2 روز بعد از آخرین تراکنش عادی در دفترکل (journal) .RE .IP \(bu 2 در غیر این صورت (اگر هیچ‌یک از این‌ها موجود نباشد): امروز. .PP دوره پیش‌بینی در تاریخ زیر پایان می‌یابد: .IP \(bu 2 تاریخ متقدم‌تر بین .RS 2 .IP \(bu 2 تاریخ پایان در قاعده تراکنش دوره‌ای .IP \(bu 2 تاریخ پایان در آرگومان \f[CR]\-\-forecast\f[R] .RE .IP \(bu 2 در غیر این صورت: تاریخ پایان گزارش مشخص‌شده با \f[CR]\-e\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R] .IP \(bu 2 در غیر این صورت: ۱۸۰ روز (\(ti۶ ماه) پس از امروز. .SS "عیب‌یابی پیش‌بینی (Forecast troubleshooting)" هنگامی که \-\-forecast آن‌طور که انتظار دارید عمل نمی‌کند، یکی از این نکات باید مفید باشد: .IP \(bu 2 به یاد داشته باشید که از گزینه \f[CR]\-\-forecast\f[R] استفاده کنید. .IP \(bu 2 به یاد داشته باشید که حداقل یک قاعده تراکنش دوره‌ای در دفترکل خود داشته باشید. .IP \(bu 2 با دستور \f[CR]print \-\-forecast\f[R] آزمایش کنید. .IP \(bu 2 خطاهای نگارشی یا تاریخ‌های آغاز/پایان بیش از حد محدودکننده را در قاعده تراکنش دوره‌ای خود بررسی کنید. .IP \(bu 2 حداقل ۲ فاصله بین عبارت دوره قاعده و فیلدهای توضیحات قرار دهید. .IP \(bu 2 بررسی کنید که آیا تراکنش‌های عادی دارای تاریخ آینده مانع از نمایش تراکنش‌های پیش‌بینی‌شده شده‌اند یا خیر. .IP \(bu 2 تنظیم صریح تاریخ‌های آغاز و/یا پایان گزارش را با \f[CR]\-b\f[R]، \f[CR]\-e\f[R]، \f[CR]\-p\f[R] یا \f[CR]date:\f[R] امتحان کنید. .IP \(bu 2 افزودن پرچم \f[CR]\-E\f[R] را برای تشویق به نمایش دوره‌های خالی/تراکنش‌های صفر امتحان کنید. .IP \(bu 2 تنظیم صریح تاریخ‌های آغاز و/یا پایان پیش‌بینی را با \f[CR]\-\-forecast=START..END\f[R] امتحان کنید. .IP \(bu 2 به بخش «دوره پیش‌بینی، با جزئیات» در بالا مراجعه کنید. .IP \(bu 2 بررسی درون موتور: به عنوان نمونه \f[CR]\-\-debug=2\f[R] را اضافه کنید..SH بودجه‌بندی با گزارش \f[CR]\-\-budget\f[R] در دستور balance، هر قاعده تراکنش دوره‌ای، اهداف بودجه‌ای تکرارشونده را در حساب‌های مشخص‌شده تولید می‌کند و می‌توان اهداف و عملکرد واقعی را با یکدیگر مقایسه کرد. مستندات دستور balance را در ادامه ببینید. .PP می‌توانید اهداف بودجه و تراکنش‌های پیش‌بینی را به‌طور هم‌زمان، از یک قاعده یا قواعد تراکنش دوره‌ای متفاوت ایجاد کنید: \f[CR]hledger bal \-M \-\-budget \-\-forecast ...\f[R] .PP همچنین ببینید: بودجه‌بندی و پیش‌بینی (Budgeting and Forecasting). .SH "قالب‌بندی مبالغ" .SS "سبک نمایش کالا" برای مبالغ هر کالا (commodity)، hledger یک سبک نمایش یکدست (محل قرارگیری نماد، نشانگر اعشار و نشانگرهای گروه‌بندی ارقام، تعداد ارقام اعشار) را برای استفاده در بیشتر گزارش‌ها انتخاب می‌کند. این مورد به‌صورت زیر استنتاج می‌شود: .PP نخست، اگر یک دستورالعمل \f[CR]D\f[R] وجود داشته باشد که کالای پیش‌فرض را اعلان می‌کند، نماد آن کالا و قالب مبلغ به تمام مبالغ بدون نماد در دفتر روزنامه (journal) اعمال می‌شود. .PP سپس سبک نمایش هر کالا بر اساس دستورالعمل \f[CR]commodity\f[R] آن تعیین می‌شود. توصیه می‌کنیم همیشه کالاها را با دستورالعمل‌های \f[CR]commodity\f[R] اعلان کنید، زیرا به اطمینان از یکدست بودن سبک‌های نمایش و دقت‌ها کمک می‌کنند و مزایای دیگری مانند بررسی خطای نمادهای کالا را به همراه دارند. در اینجا یک مثال آورده شده است: .IP .EX # Set display styles (and decimal marks, for parsing, if there is no decimal\-mark directive) # for the $, EUR, INR and no\-symbol commodities: commodity $1,000.00 commodity EUR 1.000,00 commodity INR 9,99,99,999.00 commodity 1 000 000.9455 .EE .PP اما برای راحتی، در صورتی که دستورالعمل \f[CR]commodity\f[R] وجود نداشته باشد، hledger سبک‌های نمایش کالا را از مبالغ آن به همان صورت که در دفتر روزنامه نوشته شده‌اند استنتاج می‌کند (به‌استثنای مبالغ بهای تمام‌شده و مبالغ موجود در قواعد تراکنش دوره‌ای یا قواعد ثبت خودکار). برنامه از موارد زیر استفاده می‌کند: .IP \(bu 2 محل قرارگیری نماد و نشانگر اعشار اولین مبلغ دیده‌شده .IP \(bu 2 نشانگرهای گروه‌بندی ارقامِ اولین مبلغی که دارای نشانگرهای گروه‌بندی ارقام باشد .IP \(bu 2 و بیشترین تعداد ارقام اعشار دیده‌شده در تمام مبالغ. .PP و به‌عنوان راه‌حل جایگزین (fallback)، اگر هیچ مبلغ مناسبی یافت نشود، از یک سبک پیش‌فرض استفاده خواهد کرد، مانند \f[CR]$1000.00\f[R] (نماد در سمت چپ بدون فاصله، نقطه به‌عنوان نشانگر اعشار، و دو رقم اعشار). .PP در نهایت، سبک‌های کالا را می‌توان با گزینه خط فرمان \f[CR]\-c/\-\-commodity\-style\f[R] بازنویسی کرد. .SS "گرد کردن" مبالغ در داخل برنامه به‌صورت اعداد اعشاری تا ۲۵۵ رقم اعشار ذخیره می‌شوند. آن‌ها در گزارش‌های print و گزارش‌های مشابه print با دقت اصلی‌شان در دفتر روزنامه نمایش داده می‌شوند، و در سایر گزارش‌ها به دقت نمایشی خود (تعداد ارقام اعشار مشخص‌شده توسط سبک نمایش کالا) گرد می‌شوند. هنگام گرد کردن، hledger از گرد کردن بانکی (banker\(aqs rounding؛ گرد کردن به نزدیک‌ترین رقم زوج) استفاده می‌کند. بنابراین برای مثال 0.5 در صورت نمایش با صفر رقم اعشار به‌صورت \(dq0\(dq ظاهر می‌شود. .SS "نشانگرهای اعشار پایانی" اگر تعجب می‌کنید که چرا گزارش \f[CR]print\f[R] شما گاهی نشانگرهای اعشار پایانی را بدون هیچ رقم اعشاری نشان می‌دهد؛ این کار را هنگام نمایش مبالغی انجام می‌دهد که نشانگرهای گروه‌بندی ارقام دارند اما رقم اعشار ندارند، تا ابهام‌زدایی شده و امکان بازخوانی مطمئن آن‌ها فراهم شود (بخش Decimal marks را ببینید). برای مثال: .IP .EX commodity $1,000.00 2023\-01\-02 (a) $1000 .EE .IP .EX $ hledger print 2023\-01\-02 (a) $1,000. .EE .PP اگر این موضوع مشکلی ایجاد می‌کند (مثلاً هنگام برون‌بری به Ledger)، می‌توانید با غیرفعال کردن نشانگرهای گروه‌بندی ارقام، مثلاً با \-c/\-\-commodity (برای هر کالای متأثر)، از آن جلوگیری کنید: .IP .EX $ hledger print \-c \(aq$1000.00\(aq 2023\-01\-02 (a) $1000 .EE .PP یا با وادار کردن print به نمایش همیشگی ارقام اعشار، با \-\-round: .IP .EX $ hledger print \-c \(aq$1,000.00\(aq \-\-round=soft 2023\-01\-02 (a) $1,000.00 .EE.SS "تجزیه‌پذیری مبالغ (Amount parseability)" به‌طور کلی‌تر، خروجی hledger به سه دسته کلی تقسیم می‌شود که مبالغ را برای سازگاری با مصرف‌کنندگان گوناگون، کمی متفاوت قالب‌بندی می‌کنند: .PP \f[B]۱. \(dqخروجی قابل خواندن برای hledger\(dq \- باید برای hledger (و انسان‌ها) قابل خواندن باشد\f[R] .IP \(bu 2 این خروجی توسط گزارش‌هایی تولید می‌شود که مدخل‌های کامل دفتر روزنامه را نشان می‌دهند: \f[CR]print\f[R]، \f[CR]import\f[R]، \f[CR]close\f[R]، \f[CR]rewrite\f[R] و غیره. .IP \(bu 2 مبالغ را با دقت اصلی آن‌ها در دفتر روزنامه نمایش می‌دهد، که ممکن است از یک مبلغ تا مبلغ دیگر یکدست نباشد. .IP \(bu 2 در صورت نیاز، یک نشانگر اعشار پایانی اضافه می‌کند تا از نمایش مبالغ مبهم جلوگیری شود. .IP \(bu 2 می‌تواند به‌طور قابل اطمینان تجزیه شود (دست‌کم توسط hledger و ledger2beancount، اما شاید نه توسط Ledger..). .PP \f[B]۲. \(dqخروجی خوانا برای انسان\(dq \- معمولاً برای انسان‌ها\f[R] .IP \(bu 2 این خروجی توسط تمام گزارش‌های دیگر تولید می‌شود. .IP \(bu 2 مبالغ را با دقت‌های نمایش استاندارد نشان می‌دهد، که در هر کالا (commodity) یکدست خواهد بود. .IP \(bu 2 مبالغ مبهم را بدون تغییر نمایش می‌دهد. .IP \(bu 2 می‌توان آن را در بستر یک گزارش شناخته‌شده به‌طور قابل اطمینان تجزیه کرد (وقتی می‌دانید که اعشارها به‌طور مداوم نمایش داده نمی‌شوند، می‌توانید فرض کنید یک علامت منفرد، نشانگر جداساز ارقام است). .PP \f[B]۳. \(dqخروجی ماشین‌خوان\(dq \- معمولاً برای سایر نرم‌افزارها\f[R] .IP \(bu 2 این خروجی توسط تمام گزارش‌ها هنگامی که قالب خروجی‌ای مانند \f[CR]csv\f[R]، \f[CR]tsv\f[R]، \f[CR]json\f[R] یا \f[CR]sql\f[R] انتخاب شده باشد، تولید می‌شود. .IP \(bu 2 مبالغ را مانند ۱ یا ۲ نشان می‌دهد، اما بدون نشانگرهای جداساز ارقام. .IP \(bu 2 می‌تواند به‌طور قابل اطمینان تجزیه شود (در صورت نیاز، نشانگر اعشار می‌تواند با \-c/\-\-commodity\-style تغییر داده شود). .SH "گزارش بهای تمام‌شده (Cost reporting)" در برخی تراکنش‌ها \- برای مثال تبدیل ارز، یا خرید یا فروش سهام \- یک کالا با کالایی دیگر مبادله می‌شود. در این تراکنش‌ها یک نرخ تبدیل وجود دارد که بهای تمام‌شده (cost، هنگام خرید) یا قیمت فروش (selling price، هنگام فروش) نیز نامیده می‌شود. (در مستندات hledger، صرفاً برای سهولت کار به‌طور کلی از واژه \(dqcost\(dq استفاده می‌کنیم.) با پرچم \f[CR]\-B/\-\-cost\f[R]، ابزار hledger می‌تواند مبالغ را \(dqبا بهای تمام‌شده\(dq (at cost)، تبدیل‌شده به کالای بهای تمام‌شده نمایش دهد. .SS "ثبت بهای تمام‌شده (Recording costs)" ما چندین روش برای ثبت تراکنش‌های شامل بهای تمام‌شده را بررسی خواهیم کرد. این روش‌ها همچنین در بخش hledger Cookbook > Cost notation خلاصه شده‌اند. .PP بهای تمام‌شده را می‌توان به‌صورت صریح در دفتر روزنامه، با استفاده از نمادگذاری \f[CR]\(at UNITCOST\f[R] یا \f[CR]\(at\(at TOTALCOST\f[R] که در Journal > Costs شرح داده شده است، ثبت کرد: .PP \f[B]حالت ۱\f[R] .IP .EX 2022\-01\-01 assets:dollars $\-135 assets:euros €100 \(at $1.35 ; $1.35 per euro (unit cost) .EE .PP \f[B]حالت ۲\f[R] .IP .EX 2022\-01\-01 assets:dollars $\-135 assets:euros €100 \(at\(at $135 ; $135 total cost .EE .PP معمولاً نوشتن بهای تمام‌شده واحد (حالت ۱) ترجیح داده می‌شود؛ این کار ممکن است زحمت بیشتری داشته باشد و نیازمند توجه بیشتر به ارقام اعشار باشد؛ اما مبنای بهای تمام‌شده هر واحد را مشخص می‌کند و فروش سهام را آسان‌تر می‌سازد. .PP بهای تمام‌شده را همچنین می‌توان به‌صورت ضمنی رها کرد، و hledger بهایی را که با یک تراکنش تراز (balanced) همخوانی داشته باشد استنتاج خواهد کرد: .PP \f[B]حالت ۳\f[R] .IP .EX 2022\-01\-01 assets:dollars $\-135 assets:euros €100 .EE .PP در اینجا، hledger بهای \f[CR]\(at\(at €100\f[R] را به مبلغ نخست پیوست می‌کند (می‌توانید آن را با \f[CR]hledger print \-x\f[R] مشاهده کنید). این شکل از ثبت راحت به نظر می‌رسد، اما معایبی دارد: .IP \(bu 2 برخی از بررسی‌های خطا را فدا می‌کند. برای نمونه، اگر تصادفاً به‌جای €100 مقدار €10 را می‌نوشتید، hledger قادر به تشخیص این اشتباه نبود. .IP \(bu 2 نسبت به ترتیب ثبت‌ها (postings) حساس است \- اگر ترتیب معکوس می‌شد، مدخل متفاوتی استنتاج می‌شد و گزارش‌ها متفاوت می‌بودند. .IP \(bu 2 خواندن مبنای بهای تمام‌شده به ازای هر واحد آسان نیست. .PP بنابراین عموماً این نوع مدخل توصیه نمی‌شود. می‌توانید با استفاده از \f[CR]\-s\f[R] (حالت strict)، یا با اجرای \f[CR]hledger check balanced\f[R] اطمینان حاصل کنید که هیچ‌یک از این موارد را ندارید..SS گزارش‌گیری به بهای تمام‌شده (Reporting at cost) اکنون هنگامی که پرچم \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R] را به گزارش‌ها اضافه می‌کنید (\(dqB\(dq برگرفته از پرچم \-B/\-\-basis/\-\-cost در Ledger است)، هر مقداری که با بهای تمام‌شده نشانه‌گذاری شده باشد، (در خروجی گزارش) به کالای بهای تمام‌شده‌اش تبدیل خواهد شد. یعنی آن‌ها \(dqبه بهای تمام‌شده\(dq یا \(dqبه قیمت فروش\(dq نمایش داده خواهند شد. .PP چند نکته که باید توجه داشت: .IP \(bu 2 بهای تمام‌شده به مقادیر ثبت مشخصی در تراکنش‌های معین پیوست شده است و پس از ثبت، تغییر نمی‌کند. این برخلاف قیمت‌های بازار است که محیطی و در حال نوسان هستند. .IP \(bu 2 تبدیل به بهای تمام‌شده پیش از تبدیل به ارزش بازار (که در ادامه شرح داده شده) انجام می‌شود. .SS ثبت‌های تبدیل سرمایه (Equity conversion postings) در ورودی‌های بالا مشکلی وجود دارد \- آن‌ها نمادگذاری مرسوم دفترداری دوطرفه (DEB) نیستند، و به دلیل تبدیل \(dqجادویی\(dq یک کالا به کالای دیگر، باعث عدم تعادل در معادله حسابداری می‌شوند. این مسئله به صورت یک جمع کل غیرصفر در گزارش‌های تراز مانند \f[CR]hledger bse\f[R] نشان داده می‌شود. .PP برای بیشتر کاربران hledger، این موضوع در عمل اهمیتی ندارد و می‌توان با خیال آسوده آن را نادیده گرفت! اما اگر می‌خواهید بیشتر بدانید، به خواندن ادامه دهید. .PP دفترداری دوطرفه (DEB) مرسوم، از یک جفت ثبت سرمایه (equity posting) اضافی برای متوازن ساختن تراکنش استفاده می‌کند. البته می‌توانید این کار را در hledger نیز انجام دهید: .PP \f[B]حالت ۴\f[R] .IP .EX 2022\-01\-01 assets:dollars $\-135 assets:euros €100 equity:conversion $135 equity:conversion €\-100 .EE .PP اکنون تراکنش طبق DEB استاندارد کاملاً متوازن است و مجموع کل در \f[CR]hledger bse\f[R] به هم نخواهد ریخت. .PP همچنین، hledger همچنان می‌تواند بهای تمام‌شده را برای گزارش‌گیری بهای تمام‌شده استنتاج کند، اما این کار به طور پیش‌فرض انجام نمی‌شود \- باید پرچم \f[CR]\-\-infer\-costs\f[R] را به این شکل اضافه کنید: .IP .EX $ hledger print \-\-infer\-costs 2022\-01\-01 one hundred euros purchased at $1.35 each assets:dollars $\-135 \(at\(at €100 assets:euros €100 equity:conversion $135 equity:conversion €\-100 .EE .IP .EX $ hledger bal \-\-infer\-costs \-B €\-100 assets:dollars €100 assets:euros \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP در ادامه برخی از معایب این نوع ورودی آورده شده است: .IP \(bu 2 مبنای بهای تمام‌شده به ازای هر واحد به آسانی خوانا نیست. .IP \(bu 2 به جای \f[CR]\-B\f[R] باید به خاطر داشته باشید که \f[CR]\-B \-\-infer\-costs\f[R] را وارد کنید. .IP \(bu 2 گزینه \f[CR]\-\-infer\-costs\f[R] تنها زمانی کار می‌کند که hledger بتواند دو ثبت equity:conversion را شناسایی کرده و آن‌ها را با دو ثبت غیرسرمایه‌ای تطبیق دهد. بنابراین نوشتن مدخل روزنامه در یک قالب خاص اهمیت بیشتری پیدا می‌کند. توضیحات بیشتر در این باره در زیر آمده است. .SS استنتاج ثبت‌های تبدیل سرمایه (Inferring equity conversion postings) آیا می‌توان در جهت دیگر عمل کرد؟ بله، اگر تراکنش‌هایی دارید که با نمادگذاری بهای تمام‌شده \(at/\(at\(at نوشته شده‌اند، در صورت افزودن پرچم \f[CR]\-\-infer\-equity\f[R]، hledger می‌تواند ثبت‌های سرمایه غایب را استنتاج کند. به عنوان مثال: .IP .EX 2022\-01\-01 assets:dollars \-$135 assets:euros €100 \(at $1.35 .EE .IP .EX $ hledger print \-\-infer\-equity 2022\-01\-01 assets:dollars $\-135 assets:euros €100 \(at $1.35 equity:conversion:$\-€:€ €\-100 equity:conversion:$\-€:$ $135.00 .EE .PP نام‌های حساب سرمایه به صورت \(dqequity:conversion:A\-B:A\(dq و \(dqequity:conversion:A\-B:B\(dq خواهند بود که در آن A نماد کالایی است که به ترتیب الفبایی اول است. می‌توانید بخش \(dqequity:conversion\(dq را با اعلان حسابی با نوع حساب \f[CR]V\f[R]/\f[CR]Conversion\f[R] سفارشی‌سازی کنید. .PP توجه داشته باشید اگر از \f[CR]check accounts\f[R] یا \f[CR]check \-\-strict\f[R] استفاده می‌کنید، باید اعلان‌های حساب را برای این موارد به روزنامه خود اضافه کنید. (و برخلاف ثبت‌های عادی، ثبت‌های سرمایه تولیدشده برچسب‌ها را از اعلان‌های حساب به ارث نمی‌برند.).SS ترکیب هزینه‌ها و ثبت‌های تبدیل حقوق صاحبان سهام در نهایت، می‌توانید هم‌زمان از هر دو نماد هزینه \(at/\(at\(at و ثبت‌های حقوق صاحبان سهام (equity) استفاده کنید. این کار در تئوری بهترین حالت ممکن را فراهم می‌کند \- حفظ معادله حسابداری، آشکار ساختن بهای تمام‌شده بر مبنای هر واحد، و ارائه انعطاف‌پذیری بیشتر در نحوه نوشتن مدخل: .PP \f[B]حالت ۵\f[R] .IP .EX 2022\-01\-01 one hundred euros purchased at $1.35 each assets:dollars $\-135 equity:conversion $135 equity:conversion €\-100 assets:euros €100 \(at $1.35 .EE .PP تمام حالت‌های دیگر بالا (معمولاً) می‌توانند با دستور زیر به این فرم نهایی بازنویسی شوند: .IP .EX $ hledger print \-x \-\-infer\-costs \-\-infer\-equity .EE .PP معایب: .IP \(bu 2 قالب دقیق مدخل دفتر روزنامه اهمیت بیشتری پیدا می‌کند. اگر hledger نتواند ثبت‌های هزینه و equity را تشخیص داده و با یکدیگر تطبیق دهد، خطای تراز نبودن تراکنش صادر خواهد کرد. .IP \(bu 2 دستور add هنوز این نوع مدخل را نمی‌پذیرد (#2056). .IP \(bu 2 این پرجزئیات‌ترین قالب است. .SS پیش‌نیازهای تشخیص ثبت‌های تبدیل حقوق صاحبان سهام گزینه \f[CR]\-\-infer\-costs\f[R] نیازمندی‌های خاصی دارد (برخلاف \f[CR]\-\-infer\-equity\f[R] که همیشه کار می‌کند). این گزینه هزینه‌ها را فقط در تراکنش‌هایی استنتاج می‌کند که دارای موارد زیر باشند: .IP \(bu 2 دو ثبت غیر از حقوق صاحبان سهام (non\-equity)، با کالاهای (commodities) متفاوت. ترتیب آن‌ها مهم است: هزینه به اولین مورد از آن‌ها افزوده خواهد شد. .IP \(bu 2 دو ثبت در حساب‌های تبدیل equity، در کنار یکدیگر، که دو ثبتِ غیر از equity را تراز کنند. این تراز بودن با همان دقتی (تعداد ارقام اعشار) بررسی می‌شود که در مقدار ثبتِ تبدیل استفاده شده است. حساب‌های تبدیل equity عبارت‌اند از: .RS 2 .IP \(bu 2 هر حسابی که با نوع حساب \f[CR]V\f[R]/\f[CR]Conversion\f[R] اعلان شده باشد، یا زیرحساب‌های آن‌ها .IP \(bu 2 در غیر این صورت، حساب‌هایی با نام \f[CR]equity:conversion\f[R]، \f[CR]equity:trade\f[R]، یا \f[CR]equity:trading\f[R]، یا زیرحساب‌های آن‌ها. .RE .PP و چندین گروه چهارثبتی از این دست می‌توانند در یک تراکنش واحد در کنار یکدیگر قرار گیرند. هنگامی که \f[CR]\-\-infer\-costs\f[R] ناموفق باشد، هزینه‌ای را در آن تراکنش استنتاج نمی‌کند و خطایی نیز صادر نمی‌کند (یعنی تا جایی که بتواند هزینه‌ها را استنتاج می‌کند). .PP خواندن مدخل‌های حالت ۵ دفتر روزنامه، که نماد هزینه و ثبت‌های حقوق صاحبان سهام را ترکیب می‌کنند، دقیقاً همین نیازمندی‌ها را دارد. هنگامی که خواندن چنین مدخلی ناموفق باشد، hledger خطای \(dqunbalanced transaction\(dq (تراکنش ناتراز) صادر می‌کند. .SS استنتاج هزینه و حقوق صاحبان سهام به‌صورت پیش‌فرض؟ آیا \f[CR]\-\-infer\-costs\f[R] و \f[CR]\-\-infer\-equity\f[R] باید به‌طور پیش‌فرض فعال باشند؟ استفاده همیشگی از آن‌ها را امتحان کنید، برای مثال با یک نام مستعار پوسته (alias): .IP .EX alias h=\(dqhledger \-\-infer\-equity \-\-infer\-costs\(dq .EE .PP و مشکلاتی که می‌یابید را به ما اطلاع دهید. .PP .SH "گزارش ارزش (VALUE REPORTING)" برنامه hledger همچنین می‌تواند مبالغ را «به ارزش بازار» (\(dqat market value\(dq)، تبدیل‌شده به کالایی دیگر با استفاده از قیمت بازار یا نرخ تبدیل در تاریخی مشخص، نمایش دهد. .PP این رفتار با گزینه \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] کنترل می‌شود. ما همچنین نام‌های مستعار ساده‌تر \f[CR]\-V\f[R] و \f[CR]\-X COMMODITY\f[R] را برای این منظور ارائه می‌دهیم که اغلب کافی هستند. قیمت‌های بازار با یک دستورالعمل ویژه \f[CR]P\f[R] اعلان می‌شوند، و/یا می‌توان آن‌ها را با استفاده از پرچم \f[CR]\-\-infer\-market\-prices\f[R] از هزینه‌های ثبت‌شده در تراکنش‌ها استنتاج کرد..SS \-X: ارزش در کالای مشخص‌شده گزینهٔ \f[CR]\-X COMM\f[R] (یا \f[CR]\-\-exchange=COMM\f[R]) مقادیر را با استفاده از قیمت‌های بازار معتبر در \f[I]تاریخ(های) ارزش‌گذاری\f[R] (در صورت وجود)، به ارزش بازار آن‌ها در کالای مشخص‌شده تبدیل می‌کند. (در ادامه بیشتر به این موضوع پرداخته می‌شود.) .PP از این گزینه زمانی استفاده کنید که می‌خواهید (برای مثال) تا حد امکان همه چیز را بر حسب ارز پایهٔ خود نمایش دهید. (کالاهایی که هیچ نرخ تبدیلی برای آن‌ها پیدا نشود، تبدیل نخواهند شد.) .PP مقدار COMM باید نماد یا نام کامل کالا باشد. به یاد داشته باشید که در صورت نیاز، نویسه‌های ویژهٔ پوسته را درون نقل‌قول قرار دهید. چند مثال: .IP \(bu 2 \f[CR]\-X€\f[R] .IP \(bu 2 \f[CR]\-X$\f[R] (چیزی پس از $ نیست، نیازی به نقل‌قول نیست) .IP \(bu 2 \f[CR]\-X CNY\f[R] (فاصلهٔ بعد از \-X اختیاری است) .IP \(bu 2 \f[CR]\-X \(aqred apples\(aq\f[R] .IP \(bu 2 \f[CR]\-X \(aqr&r\(aq\f[R] .SS \-V: ارزش در کالا(های) پیش‌فرض پرچم \f[CR]\-V/\-\-market\f[R] گونه‌ای از \f[CR]\-X\f[R] است که در آن نیازی نیست COMM را مشخص کنید. در عوض تلاش می‌کند بر اساس قیمت‌های بازار معتبر در تاریخ(های) ارزش‌گذاری، یک \f[I]کالای ارزش‌گذاری پیش‌فرض\f[R] را برای هر کالای اصلی حدس بزند. .PP گزینهٔ \f[CR]\-V\f[R] اغلب می‌تواند میان‌بر مناسبی برای \f[CR]\-X MYCURRENCY\f[R] باشد، اما نه همیشه؛ بسته به داده‌های شما ممکن است چندین کالای ارزش‌گذاری را حدس بزند. معمولاً هدف تبدیل به یک کالای واحد است، بنابراین بهتر است از \f[CR]\-X\f[R] استفاده کنید، مگر اینکه مطمئن باشید \f[CR]\-V\f[R] همان کاری را انجام می‌دهد که می‌خواهید. .SS تاریخ ارزش‌گذاری قیمت‌های بازار می‌توانند روز به روز تغییر کنند. دستور hledger از قیمت‌های موجود در یک تاریخ ارزش‌گذاری مشخص (یا در بیش از یک تاریخ) استفاده خواهد کرد. به‌طور پیش‌فرض، hledger از تاریخ‌های \(dqend\(dq (پایان) برای ارزش‌گذاری استفاده می‌کند. به‌طور دقیق‌تر: .IP \(bu 2 برای گزارش‌های تک‌دوره‌ای (از جمله گزارش‌های عادی print و register): .RS 2 .IP \(bu 2 اگر تاریخ پایان صریحی برای گزارش مشخص شده باشد، همان به کار می‌رود. .IP \(bu 2 در غیر این صورت، تاریخ آخرین تراکنش یا تاریخ دستورالعمل P غیرآینده استفاده می‌شود. .RE .IP \(bu 2 برای گزارش‌های چنددوره‌ای، ارزش‌گذاری هر دوره بر اساس آخرین روز آن انجام می‌شود. .PP این رفتار را می‌توان با گزینهٔ \-\-value که در ادامه توضیح داده شده سفارشی کرد؛ این گزینه می‌تواند یکی از تاریخ‌های \(dqthen\(dq،‏ \(dqend\(dq،‏ \(dqnow\(dq یا \(dqcustom\(dq را انتخاب کند. .SS یافتن قیمت بازار برای تبدیل کالای A به ارزش بازار آن در کالای دیگر B، برنامهٔ hledger به ترتیب اولویت زیر به دنبال یک قیمت بازار (نرخ تبدیل) مناسب می‌گردد: .IP "1." 3 یک \f[I]قیمت بازار اعلام‌شده\f[R] یا \f[I]قیمت بازار استنتاج‌شده\f[R]: آخرین قیمت بازار A در B در تاریخ ارزش‌گذاری یا پیش از آن، همان‌طور که با یک دستورالعمل P اعلام شده، یا (با پرچم \f[CR]\-\-infer\-market\-prices\f[R]) از هزینه‌ها استنتاج شده است. \ .IP "2." 3 یک \f[I]قیمت بازار معکوس\f[R]: معکوس یک قیمت بازار اعلام‌شده یا استنتاج‌شده از B به A. .IP "3." 3 یک \f[I]زنجیرهٔ مستقیم از قیمت‌های بازار\f[R]: قیمتی ترکیبی که از ترکیب کوتاه‌ترین زنجیره از قیمت‌های بازار «مستقیم» (\(dqforward\(dq، تنها مورد ۱ در بالا) که از A به B می‌رسد تشکیل شده است. .IP "4." 3 \f[I]هر زنجیره‌ای از قیمت‌های بازار\f[R]: زنجیره‌ای از هر نوع قیمت بازار، شامل هر دو نوع قیمت مستقیم و معکوس (موارد ۱ و ۲ در بالا)، که از A به B منتهی می‌شوند. .PP طول این زنجیره‌های قیمت محدودیت دارد؛ اگر hledger بدون یافتن یک زنجیرهٔ کامل یا تمام کردن همهٔ احتمالات به آن حد برسد، متوقف خواهد شد (همراه با پیام \(dqgave up\(dq که در خروجی \f[CR]\-\-debug=2\f[R] قابل مشاهده است). این محدودیت در حال حاضر ۱۰۰۰ است. .PP مبالغی که هیچ قیمت بازار مناسبی برای آن‌ها پیدا نشود، تبدیل نخواهند شد..SS \-\-infer\-market\-prices: قیمت‌های بازار از روی تراکنش‌ها به‌طور معمول، ارزش بازار در hledger کاملاً توسط دستورالعمل‌های P در دفتر روزنامه شما کنترل شده و به آن‌ها نیازمند است. از آن‌جا که افزودن و به‌روزرسانی آن‌ها می‌تواند کاری خسته‌کننده باشد، و از آن‌جا که تراکنش‌ها معمولاً با قیمتی نزدیک به ارزش بازار انجام می‌شوند، چرا از بهاهای ثبت‌شده به‌عنوان قیمت‌های بازار اضافی (همان‌طور که Ledger انجام می‌دهد) استفاده نکنیم؟ افزودن پرچم \f[CR]\-\-infer\-market\-prices\f[R] به \f[CR]\-V\f[R]، \f[CR]\-X\f[R] یا \f[CR]\-\-value\f[R] این قابلیت را فعال می‌کند. .PP بنابراین برای نمونه، \f[CR]hledger bs \-V \-\-infer\-market\-prices\f[R] قیمت‌های بازار را هم از دستورالعمل‌های P و هم از تراکنش‌ها دریافت خواهد کرد. اگر هر دو در یک روز رخ دهند، دستورالعمل P اولویت دارد. .PP یک نکته منفی وجود دارد: گزارش‌های ارزش ممکن است گاهی اوقات به شیوه‌هایی گیج‌کننده یا ناخواسته تحت تأثیر ورودی‌های دفتر روزنامه قرار گیرند. اگر این اتفاق برای شما رخ داد، تمام این بخش «گزارش ارزش» (Value reporting) را با دقت بخوانید، و برای عیب‌یابی سعی کنید \f[CR]\-\-debug\f[R] یا \f[CR]\-\-debug=2\f[R] را اضافه کنید. .PP گزینه \f[CR]\-\-infer\-market\-prices\f[R] می‌تواند قیمت‌های بازار را از موارد زیر استنتاج کند: .IP \(bu 2 تراکنش‌های چندکالایی با قیمت‌های صریح (\f[CR]\(at\f[R]/\f[CR]\(at\(at\f[R]) .IP \(bu 2 تراکنش‌های چندکالایی با قیمت‌های ضمنی (بدون \f[CR]\(at\f[R]، دو کالا، نامتوازن). (در این موارد، ترتیب ثبت‌ها اهمیت دارد. \f[CR]hledger print \-x\f[R] می‌تواند برای عیب‌یابی مفید باشد.) .IP \(bu 2 تراکنش‌های چندکالایی با ثبت‌های سرمایه (equity postings)، در صورتی که بها با \f[CR]\-\-infer\-costs\f[R] استنتاج شده باشد. .PP در حال حاضر یک محدودیت (باگ) وجود دارد: هنگامی که کالای ارزش‌گذاری مشخص نشده باشد، قیمت‌های استنتاج‌شده با \f[CR]\-\-infer\-market\-prices\f[R] بر خلاف قیمت‌های \f[CR]P\f[R]، به انتخاب کالای ارزش‌گذاری پیش‌فرض کمکی نمی‌کنند. بنابراین ممکن است تبدیل صورت نگیرد زیرا هیچ کالای ارزش‌گذاری شناسایی نشده است (\f[CR]\-\-debug=2\f[R] این موضوع را نشان خواهد داد). برای اطمینان، کالای ارزش‌گذاری را مشخص کنید، برای نمونه: .IP \(bu 2 \f[CR]\-X EUR \-\-infer\-market\-prices\f[R]، نه \f[CR]\-V \-\-infer\-market\-prices\f[R] .IP \(bu 2 \f[CR]\-\-value=then,EUR \-\-infer\-market\-prices\f[R]، نه \f[CR]\-\-value=then \-\-infer\-market\-prices\f[R] .PP بهاها و قیمت‌های بازار علامت‌دار می‌توانند گیج‌کننده باشند. برای مرجع، رفتار فعلی از hledger 1.25 به بعد در این‌جا آورده شده است. (اگر فکر می‌کنید باید طور دیگری کار کند، شماره ۱۸۷۰# را ببینید.) .IP .EX 2022\-01\-01 Positive Unit prices a A 1 b B \-1 \(at A 1 2022\-01\-01 Positive Total prices a A 1 b B \-1 \(at\(at A 1 2022\-01\-02 Negative unit prices a A 1 b B 1 \(at A \-1 2022\-01\-02 Negative total prices a A 1 b B 1 \(at\(at A \-1 2022\-01\-03 Double Negative unit prices a A \-1 b B \-1 \(at A \-1 2022\-01\-03 Double Negative total prices a A \-1 b B \-1 \(at\(at A \-1 .EE .PP همه تراکنش‌های بالا متوازن در نظر گرفته می‌شوند (و در هر روز، آن دو تراکنش معادل یکدیگر به شمار می‌آیند). قیمت‌های بازار استنتاج‌شده برای B به شرح زیر است: .IP .EX $ hledger \-f\- \-\-infer\-market\-prices prices P 2022\-01\-01 B A 1 P 2022\-01\-01 B A 1.0 P 2022\-01\-02 B A \-1 P 2022\-01\-02 B A \-1.0 P 2022\-01\-03 B A \-1 P 2022\-01\-03 B A \-1.0 .EE.SS کالای ارزش‌گذاری \f[B]هنگامی که یک کالای ارزش‌گذاری مشخص می‌کنید (\f[CB]\-X COMM\f[B] یا \f[CB]\-\-value TYPE,COMM\f[B]):\f[R] .PD 0 .P .PD دستور hledger تمام مبالغ را به COMM تبدیل می‌کند، هر جا که بتواند قیمت بازار مناسبی بیابد (از جمله با معکوس کردن یا زنجیره‌سازی قیمت‌ها). .PP \f[B]هنگامی که کالای ارزش‌گذاری را نامشخص رها می‌کنید (\f[CB]\-V\f[B] یا \f[CB]\-\-value TYPE\f[B]):\f[R] .PD 0 .P .PD برای هر کالای A، برنامه hledger یک کالای ارزش‌گذاری پیش‌فرض را به شرح زیر و به ترتیب اولویت انتخاب می‌کند: .IP "1." 3 کالای قیمتی از آخرین قیمت بازار اعلام‌شده با دستور P برای A در تاریخ ارزش‌گذاری یا پیش از آن. .IP "2." 3 کالای قیمتی از آخرین قیمت بازار اعلام‌شده با دستور P برای A در هر تاریخی. (این مورد امکان تبدیل را در صورتی که قیمت‌های استنباط‌شده قبل از تاریخ ارزش‌گذاری وجود داشته باشند فراهم می‌کند.) .IP "3." 3 اگر اصلاً هیچ دستور P وجود نداشته باشد (برای هر کالا یا تاریخی) و پرچم \f[CR]\-\-infer\-market\-prices\f[R] استفاده شده باشد: کالای قیمتی از آخرین قیمت استنباط‌شده از تراکنش برای A در تاریخ ارزش‌گذاری یا پیش از آن. .PP این بدان معناست که: .IP \(bu 2 اگر دستورهای P داشته باشید، آن‌ها تعیین می‌کنند که \f[CR]\-V\f[R] کدام کالاها را و به چه چیزی تبدیل کند. .IP \(bu 2 اگر هیچ دستور P نداشته باشید و از پرچم \f[CR]\-\-infer\-market\-prices\f[R] استفاده کنید، بهای تمام‌شده آن را تعیین می‌کند. .PP مبالغی که هیچ کالای ارزش‌گذاری برای آن‌ها یافت نشود تبدیل نخواهند شد. .SS \-\-value: ارزش‌گذاری منعطف گزینه‌های \f[CR]\-V\f[R] و \f[CR]\-X\f[R] حالت‌های خاصی از گزینه جامع‌تر \f[CR]\-\-value\f[R] هستند: .IP .EX \-\-value=TYPE[,COMM] TYPE is then, end, now or YYYY\-MM\-DD. COMM is an optional commodity symbol. Shows amounts converted to: \- default valuation commodity (or COMM) using market prices at posting dates \- default valuation commodity (or COMM) using market prices at period end(s) \- default valuation commodity (or COMM) using current market prices \- default valuation commodity (or COMM) using market prices at some date .EE .PP بخش TYPE هزینه یا ارزش، و تاریخ ارزش‌گذاری را انتخاب می‌کند: .TP \f[CR]\-\-value=then\f[R] تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض، با استفاده از قیمت‌های بازار در تاریخ هر ثبت (posting). .TP \f[CR]\-\-value=end\f[R] تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض، با استفاده از قیمت‌های بازار در آخرین روز دوره گزارش (یا در صورت نامشخص بودن، تاریخ پایان دفتر روزنامه)؛ یا در گزارش‌های چنددوره‌ای، قیمت‌های بازار در آخرین روز هر زیردوره. .TP \f[CR]\-\-value=now\f[R] تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض با استفاده از قیمت‌های جاری بازار (در زمان تولید گزارش). .TP \f[CR]\-\-value=YYYY\-MM\-DD\f[R] تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض با استفاده از قیمت‌های بازار در این تاریخ. .PP برای انتخاب یک کالای ارزش‌گذاری متفاوت، بخش اختیاری \f[CR],COMM\f[R] را اضافه کنید: یک ویرگول، سپس نماد کالای مقصد. برای مثال: \f[B]\f[CB]\-\-value=now,EUR\f[B]\f[R]. برنامه hledger نهایت تلاش خود را برای تبدیل مبالغ به این کالا، با استنباط قیمت‌های بازار طبق توضیحات بالا، انجام خواهد داد. .SS مثال‌های ارزش‌گذاری در اینجا چند مثال سریع از \f[CR]\-V\f[R] آورده شده است: .IP .EX ; one euro is worth this many dollars from nov 1 P 2016/11/01 € $1.10 ; purchase some euros on nov 3 2016/11/3 assets:euros €100 assets:checking ; the euro is worth fewer dollars by dec 21 P 2016/12/21 € $1.03 .EE .PP چه مقدار یورو دارم؟ .IP .EX $ hledger \-f t.j bal \-N euros €100 assets:euros .EE .PP ارزش آن‌ها در پایان ۳ نوامبر چقدر است؟ .IP .EX $ hledger \-f t.j bal \-N euros \-V \-e 2016/11/4 $110.00 assets:euros .EE .PP ارزش آن‌ها پس از 2016/12/21 چقدر است؟ (هیچ تاریخ پایان گزارشی مشخص نشده است، پیش‌فرض امروز است) .IP .EX $ hledger \-f t.j bal \-N euros \-V $103.00 assets:euros .EE .PP در اینجا چند مثال آورده شده است که اثر \f[CR]\-\-value\f[R] را، آن‌گونه که با \f[CR]print\f[R] دیده می‌شود، نشان می‌دهند: .IP .EX P 2000\-01\-01 A 1 B P 2000\-02\-01 A 2 B P 2000\-03\-01 A 3 B P 2000\-04\-01 A 4 B 2000\-01\-01 (a) 1 A \(at 5 B 2000\-02\-01 (a) 1 A \(at 6 B 2000\-03\-01 (a) 1 A \(at 7 B .EE .PP نمایش بهای تمام‌شده هر ثبت: .IP .EX $ hledger \-f\- print \-\-cost 2000\-01\-01 (a) 5 B 2000\-02\-01 (a) 6 B 2000\-03\-01 (a) 7 B .EE .PP نمایش ارزش در آخرین روز دوره گزارش (2000\-02\-29): .IP .EX $ hledger \-f\- print \-\-value=end date:2000/01\-2000/03 2000\-01\-01 (a) 2 B 2000\-02\-01 (a) 2 B .EE .PP بدون تعیین دوره گزارش، آخرین تاریخ تراکنش یا تاریخ قیمت به عنوان تاریخ ارزش‌گذاری استفاده می‌شود (2000\-04\-01): .IP .EX $ hledger \-f\- print \-\-value=end 2000\-01\-01 (a) 3 B 2000\-02\-01 (a) 3 B 2000\-03\-01 (a) 3 B .EE .PP ارزش امروز نیز یکسان است (قیمت 2000\-04\-01 همچنان معتبر است): .IP .EX $ hledger \-f\- print \-\-value=now 2000\-01\-01 (a) 4 B 2000\-02\-01 (a) 4 B 2000\-03\-01 (a) 4 B .EE.PP نمایش ارزش در 2000/01/15: .IP .EX $ hledger \-f\- print \-\-value=2000\-01\-15 2000\-01\-01 (a) 1 B 2000\-02\-01 (a) 1 B 2000\-03\-01 (a) 1 B .EE .SS تعامل ارزش‌گذاری و پرس‌وجوها هنگام تطبیق ثبت‌ها بر اساس پرس‌وجوها در حضور ارزش‌گذاری، رویدادهای زیر رخ می‌دهد: .IP "1." 3 پرس‌وجو به دو بخش تقسیم می‌شود: .RS 4 .IP "1." 3 ارز (\f[CR]cur:\f[R]) یا مبلغ (\f[CR]amt:\f[R]). .IP "2." 3 تمام بخش‌های دیگر. .RE .IP "2." 3 ثبت‌ها بر اساس مبالغ پیش از ارزش‌گذاری با پرس‌وجوهای ارز و مبلغ تطبیق داده می‌شوند. .IP "3." 3 ارزش‌گذاری روی ثبت‌ها اعمال می‌شود. .IP "4." 3 ثبت‌ها بر اساس مبالغ پس از ارزش‌گذاری با سایر بخش‌های پرس‌وجو تطبیق داده می‌شوند. .PP مرتبط: #1625 .SS اثر ارزش‌گذاری بر گزارش‌ها در اینجا مرجعی برای چگونگی تأثیر ارزش‌گذاری بر هر بخش از گزارش‌های hledger\(aq آورده شده است. این بخش ممکن است هنگام عیب‌یابی مفید باشد. اگر مشکلی یافتید، لطفاً آن را گزارش دهید؛ در حالت ایده‌آل همراه با یک نمونهٔ قابل بازتولید. مرتبط: #329، #1083. .PP نخست، یک واژه‌نامهٔ کوتاه: .TP \f[I]cost (بهای تمام‌شده)\f[R] با استفاده از قیمت(های) ثبت‌شده در تراکنش(ها) محاسبه می‌شود. .TP \f[I]value (ارزش)\f[R] ارزش بازار با استفاده از اعلان‌های قیمت بازار موجود، یا مقدار بدون تغییر در صورت پیدا نشدن نرخ تبدیل. .TP \f[I]report start (آغاز گزارش)\f[R] نخستین روز از دورهٔ گزارش مشخص‌شده با \-b یا \-p یا date:، در غیر این صورت امروز. .TP \f[I]report or journal start (آغاز گزارش یا دفتر روزنامه)\f[R] نخستین روز از دورهٔ گزارش مشخص‌شده با \-b یا \-p یا date:، در غیر این صورت نخستین تاریخ تراکنش در دفتر روزنامه، در غیر این صورت امروز. .TP \f[I]report end (پایان گزارش)\f[R] آخرین روز از دورهٔ گزارش مشخص‌شده با \-e یا \-p یا date:، در غیر این صورت امروز. .TP \f[I]report or journal end (پایان گزارش یا دفتر روزنامه)\f[R] آخرین روز از دورهٔ گزارش مشخص‌شده با \-e یا \-p یا date:، در غیر این صورت آخرین تاریخ تراکنش در دفتر روزنامه، در غیر این صورت امروز. .TP \f[I]report interval (بازهٔ گزارش)\f[R] یک پرچم (\-D/\-W/\-M/\-Q/\-Y) یا عبارت دوره که حالت چنددوره‌ای گزارش را فعال می‌کند (خواه یک زیردوره یا چندین زیردوره را نشان دهد). .PP .TS tab(@); lw(9.5n) lw(11.8n) lw(12.0n) lw(17.2n) lw(12.0n) lw(7.4n). T{ نوع گزارش T}@T{ \f[CR]\-B\f[R], \f[CR]\-\-cost\f[R] T}@T{ \f[CR]\-V\f[R], \f[CR]\-X\f[R] T}@T{ \f[CR]\-\-value=then\f[R] T}@T{ \f[CR]\-\-value=end\f[R] T}@T{ \f[CR]\-\-value=DATE\f[R], \f[CR]\-\-value=now\f[R] T} _ T{ \f[B]print\f[R] T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T} T{ مبالغ ثبت‌ها T}@T{ بهای تمام‌شده T}@T{ ارزش در پایان گزارش یا امروز T}@T{ ارزش در تاریخ ثبت T}@T{ ارزش در پایان گزارش یا دفتر روزنامه T}@T{ ارزش در DATE/امروز T} T{ تأییدیه‌ها/تخصیص‌های تراز T}@T{ بدون تغییر T}@T{ بدون تغییر T}@T{ بدون تغییر T}@T{ بدون تغییر T}@T{ بدون تغییر T} T{ T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T} T{ \f[B]register\f[R] T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T} T{ تراز آغازین (\-H) T}@T{ بهای تمام‌شده T}@T{ ارزش در پایان گزارش یا دفتر روزنامه T}@T{ ارزش‌گذاری‌شده در روز انجام هر ثبت تاریخی T}@T{ ارزش در پایان گزارش یا دفتر روزنامه T}@T{ ارزش در DATE/امروز T} T{ تراز آغازین (\-H) با بازهٔ گزارش T}@T{ بهای تمام‌شده T}@T{ ارزش در روز پیش از آغاز گزارش یا دفتر روزنامه T}@T{ ارزش‌گذاری‌شده در روز انجام هر ثبت تاریخی T}@T{ ارزش در روز پیش از آغاز گزارش یا دفتر روزنامه T}@T{ ارزش در DATE/امروز T} T{ مبالغ ثبت‌ها T}@T{ بهای تمام‌شده T}@T{ ارزش در پایان گزارش یا دفتر روزنامه T}@T{ ارزش در تاریخ ثبت T}@T{ ارزش در پایان گزارش یا دفتر روزنامه T}@T{ ارزش در DATE/امروز T} T{ خلاصهٔ مبالغ ثبت‌ها با بازهٔ گزارش T}@T{ بهای تمام‌شدهٔ خلاصه‌شده T}@T{ ارزش در پایان دوره‌ها T}@T{ مجموع ثبت‌ها در بازه، ارزش‌گذاری‌شده در آغاز بازه T}@T{ ارزش در پایان دوره‌ها T}@T{ ارزش در DATE/امروز T} T{ مجموع/میانگین تجمعی T}@T{ مجموع/میانگین مقادیر نمایش‌یافته T}@T{ مجموع/میانگین مقادیر نمایش‌یافته T}@T{ مجموع/میانگین مقادیر نمایش‌یافته T}@T{ مجموع/میانگین مقادیر نمایش‌یافته T}@T{ مجموع/میانگین مقادیر نمایش‌یافته T} T{ T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T} T{ \f[B]balance (bs, bse, cf, is)\f[R] T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T} T{ تغییرات تراز T}@T{ مجموع بهای تمام‌شده T}@T{ ارزش در پایان گزارش یا امروز برای مجموع ثبت‌ها T}@T{ ارزش در تاریخ ثبت T}@T{ ارزش در پایان گزارش یا دفتر روزنامه برای مجموع ثبت‌ها T}@T{ ارزش در DATE/امروز برای مجموع ثبت‌ها T} T{ مبالغ بودجه (\-\-budget) T}@T{ مانند تغییرات تراز T}@T{ مانند تغییرات تراز T}@T{ مانند تغییرات تراز T}@T{ مانند ترازها T}@T{ مانند تغییرات تراز T} T{ مجموع کل T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T} T{ T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T} T{ \f[B]balance (bs, bse, cf, is)\f[R] با بازهٔ گزارش T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T} T{ ترازهای آغازین (\-H) T}@T{ مجموع بهای تمام‌شدهٔ ثبت‌های پیش از آغاز گزارش T}@T{ ارزش در آغاز گزارش برای مجموع تمام ثبت‌های پیش از آغاز گزارش T}@T{ مجموع ارزش‌های ثبت‌های پیش از آغاز گزارش در تاریخ‌های ثبت مربوطه T}@T{ ارزش در آغاز گزارش برای مجموع تمام ثبت‌های پیش از آغاز گزارش T}@T{ مجموع ثبت‌های پیش از آغاز گزارش T} T{ تغییرات تراز (bal, is, bs \-\-change, cf \-\-change) T}@T{ مجموع بهای تمام‌شدهٔ ثبت‌ها در دوره T}@T{ مشابه \-\-value=end T}@T{ مجموع ارزش‌های ثبت‌ها در دوره در تاریخ‌های ثبت مربوطه T}@T{ تغییر تراز در هر دوره، ارزش‌گذاری‌شده در پایان دوره‌ها T}@T{ ارزش در DATE/امروز برای مجموع ثبت‌ها T} T{ ترازهای پایانی (bal \-H, is \-\-H, bs, cf) T}@T{ مجموع بهای تمام‌شدهٔ ثبت‌ها از پیش از آغاز گزارش تا پایان دوره T}@T{ مشابه \-\-value=end T}@T{ مجموع ارزش‌های ثبت‌ها از پیش از آغاز دوره تا پایان دوره در تاریخ‌های ثبت مربوطه T}@T{ ترازهای پایان دوره، ارزش‌گذاری‌شده در پایان دوره‌ها T}@T{ ارزش در DATE/امروز برای مجموع ثبت‌ها T} T{ مبالغ بودجه (\-\-budget) T}@T{ مانند تغییرات تراز/ترازهای پایانی T}@T{ مانند تغییرات تراز/ترازهای پایانی T}@T{ مانند تغییرات تراز/ترازهای پایانی T}@T{ مانند ترازها T}@T{ مانند تغییرات تراز/ترازهای پایانی T} T{ مجموع سطرها، میانگین سطرها (\-T, \-A) T}@T{ مجموع‌ها، میانگین‌های مقادیر نمایش‌یافته T}@T{ مجموع‌ها، میانگین‌های مقادیر نمایش‌یافته T}@T{ مجموع‌ها، میانگین‌های مقادیر نمایش‌یافته T}@T{ مجموع‌ها، میانگین‌های مقادیر نمایش‌یافته T}@T{ مجموع‌ها، میانگین‌های مقادیر نمایش‌یافته T} T{ مجموع ستون‌ها T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T}@T{ مجموع مقادیر نمایش‌یافته T} T{ مجموع کل، میانگین کل T}@T{ مجموع، میانگین مجموع ستون‌ها T}@T{ مجموع، میانگین مجموع ستون‌ها T}@T{ مجموع، میانگین مجموع ستون‌ها T}@T{ مجموع، میانگین مجموع ستون‌ها T}@T{ مجموع، میانگین مجموع ستون‌ها T} T{ T}@T{ T}@T{ T}@T{ T}@T{ T}@T{ T}.TE .PP گزینهٔ \f[CR]\-\-cumulative\f[R] برای صرفه‌جویی در فضا حذف شده است؛ این گزینه مانند \f[CR]\-H\f[R] اما با تراز آغازین صفر عمل می‌کند. .SH "بخش ۴: دستورها (PART 4: COMMANDS)" .PP در اینجا زیردستورهای استاندارد hledger آورده شده‌اند. می‌توانید با اجرای \f[CR]hledger\f[R] این دستورها را فهرست کنید. اگر دستورهای افزودنی بیشتری نصب کرده باشید، آن‌ها نیز فهرست خواهند شد. .PP در مستندات دستورهای زیر، گزینه‌های ویژهٔ هر دستور نمایش داده شده است. بیشتر دستورها همچنین از گزینه‌های عمومی که در بالا توضیح داده شد پشتیبانی می‌کنند، اگرچه ممکن است برخی از آن‌ها بی‌اثر باشند. (معمولاً اگر روش معقولی وجود داشته باشد که یک گزینهٔ عمومی بر دستوری اثر بگذارد، اثر خواهد گذاشت.) می‌توانید تمام گزینه‌های یک دستور را با اجرای \f[CR]hledger CMD \-h\f[R] فهرست کنید. .PP \f[B]دستورهای راهنما\f[R] .IP \(bu 2 commands \- نمایش فهرست دستورهای hledger (پیش‌فرض) .IP \(bu 2 demo \- نمایش پیش‌نمایش‌های کوتاه hledger در ترمینال .IP \(bu 2 help \- نمایش راهنمای hledger با info، man یا صفحه‌بند (pager) .PP \f[B]دستورهای رابط کاربری\f[R] .IP \(bu 2 repl \- اجرای دستورها از یک اعلان تعاملی .IP \(bu 2 run \- اجرای دستورها از یک اسکریپت .IP \(bu 2 ui \- (در صورت نصب بودن) اجرای رابط کاربری ترمینالی hledger .IP \(bu 2 web \- (در صورت نصب بودن) اجرای رابط کاربری وب hledger .PP \f[B]دستورهای ورود داده\f[R] .IP \(bu 2 add \- افزودن تراکنش‌ها با استفاده از اعلان‌های ترمینال .IP \(bu 2 import \- افزودن تراکنش‌های جدید از فایل‌های دیگر، مانند فایل‌های CSV .PP \f[B]دستورهای گزارش پایه\f[R] .IP \(bu 2 accounts \- نمایش نام حساب‌ها .IP \(bu 2 codes \- نمایش کدهای تراکنش .IP \(bu 2 commodities \- نمایش نمادهای کالا/ارز .IP \(bu 2 descriptions \- نمایش توضیحات تراکنش .IP \(bu 2 files \- نمایش مسیرهای فایل ورودی .IP \(bu 2 notes \- نمایش بخش یادداشت‌های توضیحات تراکنش .IP \(bu 2 payees \- نمایش بخش دریافت‌کنندگان وجه در توضیحات تراکنش .IP \(bu 2 prices \- نمایش قیمت‌های بازار .IP \(bu 2 stats \- نمایش آمار دفتر روزنامه .IP \(bu 2 tags \- نمایش نام برچسب‌ها .PP \f[B]دستورهای گزارش استاندارد\f[R] .IP \(bu 2 print \- نمایش تراکنش‌ها یا برون‌بری داده‌های دفتر روزنامه .IP \(bu 2 aregister (areg) \- نمایش تراکنش‌ها در یک حساب مشخص .IP \(bu 2 register (reg) \- نمایش ثبت‌ها در یک یا چند حساب و مجموع جاری .IP \(bu 2 balancesheet (bs) \- نمایش دارایی‌ها، بدهی‌ها و ارزش خالص .IP \(bu 2 balancesheetequity (bse) \- نمایش دارایی‌ها، بدهی‌ها و حقوق صاحبان سهام .IP \(bu 2 cashflow (cf) \- نمایش تغییرات در دارایی‌های نقد .IP \(bu 2 incomestatement (is) \- نمایش درآمدها و هزینه‌ها .PP \f[B]دستورهای گزارش پیشرفته\f[R] .IP \(bu 2 balance (bal) \- نمایش تغییرات تراز، ترازهای پایانی، بودجه‌ها، سودها... .IP \(bu 2 roi \- نمایش بازده سرمایه‌گذاری (ROI) .PP \f[B]دستورهای نمودار\f[R] .IP \(bu 2 activity \- نمایش نمودارهای میله‌ای از تعداد ثبت‌ها در هر دوره .PP \f[B]دستورهای تولید داده\f[R] .IP \(bu 2 close \- تولید تراکنش‌های صفر کردن/بازیابی تراز .IP \(bu 2 rewrite \- تولید ثبت‌های خودکار، مانند print \-\-auto .PP \f[B]دستورهای نگهداری\f[R] .IP \(bu 2 check \- بررسی انواع مختلف خطا در داده‌ها .IP \(bu 2 diff \- مقایسه تراکنش‌های حساب در دو فایل دفتر روزنامه .IP \(bu 2 setup \- بررسی و نمایش وضعیت نصب hledger .IP \(bu 2 test \- اجرای آزمون‌های داخلی (self tests) .PP در ادامه، این دستورها به تفصیل شرح داده شده‌اند..SH "دستورهای راهنما (Help commands)" .SS commands نمایش فهرست دستورهای hledger. .IP .EX گزینه‌ها: \-\-builtin فقط نمایش دستورهای توکار، نه افزونه‌ها .EE .SS demo پخش دموهای نحوه استفاده از hledger در ترمینال، در صورت نصب بودن asciinema. .IP .EX گزینه‌ها: \-s \-\-speed=SPEED سرعت پخش (1 سرعت اصلی است، 0.5 نصف، 2 دو برابر و غیره (پیش‌فرض: 2)) .EE .PP این دستور را بدون هیچ آرگومانی اجرا کنید تا دموها فهرست شوند. برای پخش یک دمو، شماره آن یا یک پیشوند یا زیررشته‌ای از عنوان آن را بنویسید. نکات: .PP پنجره ترمینال خود را به اندازه کافی بزرگ کنید تا دمو را به وضوح ببینید. .PP از گزینه \-s/\-\-speed SPEED برای تعیین سرعت پخش دلخواه خود استفاده کنید، برای نمونه \f[CR]\-s4\f[R] برای پخش با 4 برابر سرعت اصلی یا \f[CR]\-s.5\f[R] برای پخش با نصف سرعت. سرعت پیش‌فرض 2x است. .PP هنگام پخش، چند کلید در دسترس است: SPACE برای توقف موقت/ادامه، . برای رفتن به جلو (در حالت توقف)، و CTRL\-c برای خروج. .PP مثال‌ها: .IP .EX $ hledger demo # فهرست دموهای موجود $ hledger demo 1 # پخش اولین دمو با سرعت پیش‌فرض (2x) $ hledger demo install \-s4 # پخش دموی \(dqinstall\(dq با سرعت 4x .EE .PP این دستور آزمایشی است: هنوز دموهای کاربردی زیادی وجود ندارد. .SS help نمایش دفترچه راهنمای کاربر hledger با \f[CR]info\f[R]، \f[CR]man\f[R]، یا یک صفحه‌بند (pager). با یک آرگومان TOPIC (غیرحساس به بزرگی و کوچکی حروف)، تلاش می‌کند تا آن را در عنوان آن بخش باز کند. .IP .EX گزینه‌ها: \-i نمایش دفترچه راهنما با info \-m نمایش دفترچه راهنما با man \-p نمایش دفترچه راهنما با $PAGER یا less (در صورت تعیین TOPIC، همیشه less استفاده می‌شود) .EE .PP این دستور، دفترچه راهنمای hledger تعبیه‌شده در فایل اجرایی hledger شما را نمایش می‌دهد. این قابلیت زمانی که آفلاین هستید، یا وقتی که ترمینال را به یک مرورگر وب ترجیح می‌دهید، یا زمانی که دفترچه راهنما یا نمایش‌دهنده‌های مناسب hledger به‌درستی روی سیستم شما نصب نشده‌اند، می‌تواند مفید باشد. .PP به‌طور پیش‌فرض، بهترین نمایش‌دهنده یافت‌شده در $PATH را انتخاب می‌کند و به این ترتیب بررسی می‌کند: \f[CR]info\f[R]، \f[CR]man\f[R]، \f[CR]$PAGER\f[R]، \f[CR]less\f[R]، \f[CR]more\f[R] و stdout. (اگر TOPIC مشخص شده باشد، \f[CR]$PAGER\f[R] و \f[CR]more\f[R] بررسی نمی‌شوند.) می‌توانید با گزینه‌های \f[CR]\-i\f[R]، \f[CR]\-m\f[R] یا \f[CR]\-p\f[R] استفاده از info، man یا یک صفحه‌بند را اجباری کنید. اگر هیچ نمایش‌دهنده‌ای پیدا نشود، یا در صورت اجرا به‌صورت غیرتعاملی، راهنما را تنها در stdout چاپ می‌کند. .PP هنگام استفاده از \f[CR]info\f[R]، آرگومان TOPIC می‌تواند با عنوان کامل یا یک پیشوند مطابقت داشته باشد. اگر نسخه \f[CR]info \-\-version\f[R] شما کمتر از 6 است، باید آن را ارتقا دهید، مثلاً در مک با \(aq\f[CR]brew install texinfo\f[R]\(aq. .PP هنگام استفاده از \f[CR]man\f[R] یا \f[CR]less\f[R]، آرگومان TOPIC باید با عنوان کامل مطابقت داشته باشد. برای تطبیق پیشوند، می‌توانید بنویسید: \(aq\f[CR]TOPIC.*\f[R]\(aq. .PP مثال‌ها .IP .EX $ hledger help \-h # نمایش نحوه استفاده از دستور help $ hledger help # نمایش راهنما با info، man یا $PAGER $ hledger help \(aqtime periods\(aq # نمایش مبحث \(dqTime periods\(dq در راهنما $ hledger help \(aqtime periods\(aq \-m # استفاده از man، حتی اگر info نصب باشد .EE.SH "دستورهای رابط کاربری (USER INTERFACE COMMANDS)" .SS repl یک اعلان (prompt) تعاملی را آغاز می‌کند که در آن می‌توانید هر یک از دستورهای hledger را اجرا کنید. فایل‌های داده تنها یک‌بار تجزیه می‌شوند، از این رو دستورها سریع‌تر اجرا می‌شوند. .IP .EX Flags: no command\-specific flags .EE .PP این دستور آزمایشی است و ممکن است در آینده تغییر کند. .PP دستور \f[CR]hledger repl\f[R] یک حلقهٔ خواندن\-ارزیابی\-چاپ (REPL) را آغاز می‌کند که در آن می‌توانید دستورها را به‌صورت تعاملی وارد نمایید. همانند دستور \f[CR]run\f[R]، هر فایل ورودی (یا هر ترکیب فایل ورودی/گزینه‌های ورودی) تنها یک‌بار تجزیه می‌شود، بنابراین دستورها سریع‌تر از زمانی که آن‌ها را به‌صورت جداگانه در خط فرمان اجرا کنید، اجرا خواهند شد. .PP همچنین مانند \f[CR]run\f[R]، فایل(های) ورودی مشخص‌شده برای دستور \f[CR]repl\f[R] ورودی پیش‌فرض تمام دستورهای تعاملی خواهد بود. می‌توانید با مشخص کردن گزینهٔ \f[CR]\-f\f[R] در دستورهایی خاص، این مورد را موقتاً نادیده بگیرید (override کنید). اما توجه داشته باشید تا زمانی که از REPL خارج نشوید و آن را دوباره اجرا نکنید، دستورها تغییرات اعمال‌شده در فایل‌های ورودی را (برای نمونه توسط \f[CR]add\f[R]) نخواهند دید. .PP نحو دستور همانند \f[CR]run\f[R] است: .IP \(bu 2 در هر نوبت یک دستور hledger وارد کنید، بدون کلمهٔ نخست معمول یعنی \f[CR]hledger\f[R] .IP \(bu 2 خط‌های خالی و متن‌های توضیحی از \f[CR]#\f[R] تا انتهای خط نادیده گرفته می‌شوند .IP \(bu 2 در صورت نیاز، برای نقل‌قول کردن آرگومان‌ها از علامت نقل‌قول تکی یا دوتایی استفاده کنید .IP \(bu 2 برای خروج از REPL عبارت \f[CR]exit\f[R] یا \f[CR]quit\f[R] را تایپ کنید یا control\-D را بفشارید. .PP در زمان اجرا، REPL تاریخچهٔ دستورهای شما را به خاطر می‌سپارد و می‌توانید به روش‌های معمول در آن پیمایش کنید: .IP \(bu 2 کلیدهای جهت‌نما یا کلیدهای پیمایش Emacs برای ویرایش خط فرمان جاری .IP \(bu 2 کلیدهای بالا/پایین یا control\-P/control\-N برای حرکت به عقب/جلو در تاریخچه .IP \(bu 2 کلیدهای control\-R برای جستجو به دنبال دستوری در گذشته .IP \(bu 2 کلید TAB برای تکمیل خودکار مسیر فایل‌ها. .PP به‌طور کلی خط فرمان‌های \f[CR]repl\f[R] بسیار شبیه به رابط خط فرمان معمول hledger هستند، اما ممکن است متوجه تفاوت‌هایی شوید. دستور \f[CR]repl\f[R] کمی سخت‌گیرتر است؛ مثلاً به نام‌های کامل دستورها یا مخفف‌های رسمی (همان‌طور که در فهرست دستورها دیده می‌شود) نیاز دارد. .PP دستورهای \f[CR]commands\f[R] و \f[CR]help\f[R]، و پرچم‌های راهنمای دستورها (\f[CR]CMD \-\-tldr\f[R]، \f[CR]CMD \-h/\-\-help\f[R]، \f[CR]CMD \-\-info\f[R]، \f[CR]CMD \-\-man\f[R]) می‌توانند مفید باشند. .PP می‌توانید control\-C را برای لغو دستوری با اجرای طولانی بفشارید (اما فقط یک‌بار؛ فشردن مجدد آن سبب خروج از REPL خواهد شد). .PP و در بیشتر پوسته‌ها می‌توانید control\-Z را برای خروج موقت به پوسته بفشارید (و سپس با \f[CR]fg\f[R] به REPL بازگردید). .SS "مثال‌ها (EXAMPLES)" اجرای REPL و وارد کردن چند دستور: .IP .EX $ hledger repl Enter hledger commands. To exit, enter \(aqquit\(aq or \(aqexit\(aq, or send EOF. % stats Main file : .../2025.journal \&... % stats \-f 2024/2024.journal Main file : .../2024.journal \&... % stats Main file : .../2025.journal \&... .EE .PP یا: .IP .EX $ hledger repl \-f some.journal Enter hledger commands. To exit, enter \(aqquit\(aq or \(aqexit\(aq, or send EOF. % bs \&... % print \-b \(aqlast week\(aq \&... % bs \-f other.journal \&... .EE.SS run اجرای توالی‌ای از دستورهای hledger که در قالب فایل یا آرگومان‌های خط فرمان ارائه می‌شوند. فایل‌های داده تنها یک‌بار تجزیه می‌شوند، بنابراین دستورها سریع‌تر اجرا خواهند شد. .IP .EX پرچم‌ها: هیچ پرچم خاصی برای این دستور وجود ندارد .EE .PP این دستور آزمایشی است و ممکن است در آینده تغییر کند. .PP می‌توانید از \f[CR]run\f[R] به سه روش استفاده کنید: .IP \(bu 2 \f[CR]hledger run \-\- CMD1 \-\- CMD2 \-\- CMD3\f[R] \- خواندن دستورها از خط فرمان، تفکیک‌شده با \f[CR]\-\-\f[R] .IP \(bu 2 \f[CR]hledger run SCRIPTFILE1 SCRIPTFILE2\f[R] \- خواندن دستورها از یک یا چند فایل .IP \(bu 2 \f[CR]cat SCRIPTFILE1 | hledger run\f[R] \- خواندن دستورها از ورودی استاندارد. .PP دستور \f[CR]run\f[R] ابتدا فایل(های) ورودی مشخص‌شده توسط \f[CR]LEDGER_FILE\f[R] یا گزینه‌های \f[CR]\-f\f[R] را به شیوهٔ معمول بارگذاری می‌کند. سپس هر دستور را به نوبت اجرا می‌نماید، که هر یک از همان داده‌های ورودی یکسان استفاده می‌کنند. اما اگر می‌خواهید یک دستور خاص از ورودی متفاوتی استفاده کند، می‌توانید گزینهٔ \f[CR]\-f\f[R] را درون آن دستور مشخص کنید. این کار ورودی پیش‌فرض را صرفاً برای همان دستور بازنویسی می‌کند (نه اینکه به آن بیفزاید). .PP هر فایل ورودی (به‌طور دقیق‌تر، هر ترکیب از فایل ورودی و گزینه‌های ورودی) تنها یک‌بار تجزیه می‌شود. این بدان معناست که دستورها تا اجرای بعدی، متوجه هیچ‌گونه تغییری که در این فایل‌ها ایجاد شده باشد نخواهند شد. اما دستورها نسبت به زمانی که به صورت جداگانه اجرا شوند سریع‌تر اجرا خواهند شد (معمولاً حدود دو برابر سریع‌تر). .PP اسکریپت‌های دستوری، چه در یک فایل و چه در خط فرمان نوشته شده باشند، نحو ساده‌ای دارند: .IP \(bu 2 هر خط می‌تواند شامل یک دستور منفرد hledger و آرگومان‌های آن باشد، بدون واژهٔ نخستین معمول \f[CR]hledger\f[R] .IP \(bu 2 خطوط خالی نادیده گرفته می‌شوند .IP \(bu 2 متن از \f[CR]#\f[R] تا انتهای خط، توضیح (کامنت) محسوب شده و نادیده گرفته می‌شود .IP \(bu 2 در صورت نیاز می‌توانید مانند خط فرمان، از نقل‌قول تکی یا دوتایی برای محصور کردن آرگومان‌ها استفاده کنید .IP \(bu 2 این دستورهای اضافی نیز در دسترس هستند: \f[CR]echo TEXT\f[R] متنی را چاپ می‌کند، و \f[CR]exit\f[R] یا \f[CR]quit\f[R] به اجرا خاتمه می‌دهد. .PP در سیستم‌های یونیکس می‌توانید از \f[CR]#!/usr/bin/env hledger run\f[R] در خط نخست یک فایل دستوری استفاده کنید تا آن را به یک اسکریپت قابل اجرا تبدیل نمایید. اگر این کار با خطا مواجه شد، از \f[CR]#!/usr/bin/env \-S hledger run\f[R] استفاده کنید. .PP استفاده از دستور \f[CR]run\f[R] به‌صورت بازگشتی در داخل یک اسکریپت دستوری بلامانع است. .PP ممکن است متوجه تفاوت‌هایی در رفتار بین خطوط فرمان \f[CR]run\f[R] و خطوط فرمان معمول hledger شوید. دستور \f[CR]run\f[R] کمی سخت‌گیرتر است؛ مثلاً به نام کامل دستورها یا مخفف‌های رسمی (همان‌طور که در فهرست دستورها آمده) نیاز دارد، و گزینه‌های دستور باید حتماً پس از نام دستور نوشته شوند. .SS "مثال‌ها (EXAMPLES)" اجرای دستورها از خط فرمان: .IP .EX hledger \-f some.journal run \-\- balance assets \-\-depth 2 \-\- balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose \-\- stats .EE .PP این دستور \f[CR]some.journal\f[R] را بارگذاری می‌کند، \f[CR]balance assets \-\-depth 2\f[R] را روی آن اجرا می‌نماید، سپس \f[CR]balance liabilities \-\-depth 3 \-\-transpose\f[R] را روی \f[CR]/some/other.journal\f[R] اجرا کرده، و در نهایت \f[CR]stats\f[R] را روی \f[CR]some.journal\f[R] به اجرا درمی‌آورد. .PP اجرای دستورها از ورودی استاندارد: .IP .EX (echo \(dqfiles\(dq; echo \(dqstats\(dq) | hledger \-f some.journal run .EE .PP اجرای دستورها در قالب یک اسکریپت: .IP .EX $ cat report #!/usr/bin/env \-S hledger run \-f some.journal echo \(dqList of accounts in some.journal\(dq accounts echo \(dqAssets of some.journal\(dq balance assets \-\-depth 2 echo \(dqLiabilities from /some/other.journal\(dq balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose echo \(dqCommands from another.script, applied to another.journal\(dq run \-f another.journal another.script .EE .IP .EX $ chmod +x report $ ./report List of accounts in some.journal \&... .EE.SS ui برنامه hledger\-ui را (در صورت نصب بودن) اجرا می‌کند. .SS web برنامه hledger\-web را (در صورت نصب بودن) اجرا می‌کند. .SH "دستورهای ورود داده (DATA ENTRY COMMANDS)" .SS add افزودن تراکنش‌های جدید به یک فایل دفتر روزنامه (journal)، با اعلان‌های تعاملی. .IP .EX Flags: \-\-no\-new\-accounts عدم اجازه برای ایجاد حساب‌های جدید .EE .PP بسیاری از کاربران hledger دفترهای روزنامه خود را مستقیماً با یک ویرایشگر متن ویرایش می‌کنند یا آن‌ها را از CSV تولید می‌نمایند. برای ورود تعاملی‌تر داده‌ها، دستور \f[CR]add\f[R] وجود دارد که در کنسول به صورت تعاملی اعلان‌هایی را برای تراکنش‌های جدید نمایش می‌دهد و آن‌ها را به انتهای فایل اصلی دفتر روزنامه (که باید در قالب journal باشد) الحاق می‌کند. تراکنش‌های موجود تغییر داده نمی‌شوند. این یکی از معدود دستورهای hledger است که در فایل دفتر روزنامه می‌نویسد (همچنین \f[CR]import\f[R] را ببینید). .PP برای استفاده از آن، کافی است \f[CR]hledger add\f[R] را اجرا کرده و اعلان‌ها را دنبال کنید. می‌توانید هر تعداد تراکنش که مایلید اضافه کنید؛ هنگامی که کارتان تمام شد، برای خروج \f[CR].\f[R] را وارد کرده یا کلیدهای control\-d یا control\-c را فشار دهید. .PP ویژگی‌ها: .IP \(bu 2 دستور add تلاش می‌کند با استفاده از مشابه‌ترین تراکنش اخیر (بر اساس شرح) به عنوان الگو (که در صورت وجود، با پرسمان فیلتر شده است)، مقادیر پیش‌فرض مفیدی را ارائه دهد. .IP \(bu 2 همچنین می‌توانید مقادیر پیش‌فرض اولیه را با آرگومان‌های خط فرمان تعیین کنید. .IP \(bu 2 هنگام ورود داده‌ها می‌توان از کلیدهای ویرایشی به سبک Readline استفاده کرد. .IP \(bu 2 کلید tab تا جای ممکن موارد را به طور خودکار تکمیل می‌کند \- حساب‌ها، دریافت‌کنندگان/شرح‌ها، تاریخ‌ها (\f[CR]yesterday\f[R]، \f[CR]today\f[R]، \f[CR]tomorrow\f[R]). اگر بخش ورودی خالی باشد، مقدار پیش‌فرض را درج می‌کند. .IP \(bu 2 می‌توان پس از تاریخ، یک کد تراکنش داخل پرانتز وارد کرد. .IP \(bu 2 می‌توان به دنبال شرح یا مبلغ، کامنت‌ها و برچسب‌ها را وارد نمود. .IP \(bu 2 اگر مرتکب اشتباه شدید، در هر اعلانی \f[CR]<\f[R] را وارد کنید تا یک مرحله به عقب بازگردید. .IP \(bu 2 در صورت پشتیبانی ترمینال، اعلان‌های ورودی با رنگ متفاوتی نمایش داده می‌شوند. .PP نکات: .IP \(bu 2 اگر عددی را بدون نماد کالا (commodity) وارد کنید، و با یک دستورالعمل \f[CR]D\f[R] کالای پیش‌فرضی را تعریف کرده باشید، ممکن است انتظار داشته باشید \f[CR]add\f[R] این نماد را برای شما اضافه کند. این دستور چنین کاری انجام نمی‌دهد؛ فرض ما بر این است که اگر از یک دستورالعمل \f[CR]D\f[R] استفاده می‌کنید، ترجیح می‌دهید نماد کالا روی مقادیر در دفتر روزنامه تکرار نشود. .IP \(bu 2 دستور \f[CR]add\f[R] مدخل‌ها را در قالب journal ایجاد می‌کند؛ و با فایل‌های timeclock یا timedot کار نخواهد کرد. .IP \(bu 2 در صورتی که این نسخه hledger از stackage ساخته شده باشد، یک مشکل شناخته‌شده در Windows وجود دارد: اعلان‌ها به جای رنگ‌ها، کاراکترهای زائد ANSI را نشان می‌دهند (#2410). می‌توانید با استفاده از باینری‌های رسمی منتشرشده hledger یا ساخت آن با haskeline >=0.8.4 از این مشکل دوری کنید؛ یا اینکه \f[CR]add\f[R] را با \f[CR]\-\-color=no\f[R] اجرا نمایید، که احتمالاً در فایل پیکربندی شما نیز قابل تنظیم است. .PP مثال‌ها: .IP \(bu 2 ثبت تراکنش‌های جدید و ذخیره در فایل پیش‌فرض دفتر روزنامه: .RS 2 .PP \f[CR]hledger add\f[R] .RE .IP \(bu 2 افزودن تراکنش‌ها به 2024.journal، اما بارگذاری 2023.journal برای تکمیل خودکار: .RS 2 .PP \f[CR]hledger add \-\-file 2024.journal \-\-file 2023.journal\f[R] .RE .IP \(bu 2 ارائه پاسخ‌ها برای چهار اعلان نخست: .RS 2 .PP \f[CR]hledger add today \(aqbest buy\(aq expenses:supplies \(aq$20\(aq\f[R] .RE .PP یک راهنمای جامع در https://hledger.org/add.html وجود دارد..SS add و اعلان‌های تراز از hledger نسخهٔ 1.43 به بعد، می‌توانید هنگام درخواست مبلغ، با نوشتن \f[CR]AMOUNT = BALANCE\f[R] یک اعلان تراز اضافه کنید. به‌عنوان مثال \f[CR]100 = 500\f[R]. .PP همچنین، هر بار که مبلغ جدیدی را وارد می‌کنید، hledger تمام اعلان‌های تراز موجود در دفتر روزنامه را دوباره بررسی می‌کند و اگر مقدار جدید باعث رد شدن هر یک از آن‌ها شود، آن را رد می‌کند. می‌توانید \f[CR]add\f[R] را با \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] اجرا کنید تا بررسی اعلان تراز غیرفعال شود. .SS add و تخصیص‌های تراز از hledger نسخهٔ 1.51 به بعد، می‌توانید هنگام درخواست مبلغ، با نوشتن \f[CR]= BALANCE\f[R] (یا \f[CR]==\f[R]، \f[CR]=*\f[R] و غیره) یک تخصیص تراز اضافه کنید. مبلغ ناموجود به‌طور خودکار محاسبه خواهد شد. .PP دستور \f[CR]add\f[R] در حالت عادی به شما اجازه نخواهد داد ثبت (posting) جدیدی اضافه کنید که تاریخ آن قبل از یک تخصیص ترازِ موجود باشد. (زیرا هنگام اجرای \f[CR]add\f[R]، تخصیص‌های ترازِ موجود قبلاً محاسبه شده و به مبالغ و اعلان‌های تراز تبدیل شده‌اند.) می‌توانید با غیرفعال کردن بررسی اعلان تراز با استفاده از \f[CR]\-I\f[R] این کار را مجاز کنید. .SS import وارد کردن تراکنش‌های جدید از یک یا چند فایل داده به دفتر روزنامهٔ اصلی. .IP .EX Flags: \-\-catchup just mark all transactions as already imported \-\-dry\-run just show the transactions to be imported .EE .PP این دستور تراکنش‌های جدید را در یک یا چند فایل دادهٔ مشخص‌شده به‌عنوان آرگومان شناسایی کرده و آن‌ها را به دفتر روزنامهٔ اصلی اضافه می‌کند. .PP شما می‌توانید از هر قالب فایل ورودی که hledger پشتیبانی می‌کند داده وارد کنید، اما فایل‌های CSV/SSV/TSV دانلودشده از مؤسسات مالی، رایج‌ترین منبع وارد کردن هستند. .PP مقصد وارد کردن، فایل پیش‌فرض دفتر روزنامه است، یا فایل دیگری که به روش معمول با \f[CR]$LEDGER_FILE\f[R] یا \f[CR]\-f/\-\-file\f[R] مشخص شده باشد. این فایل باید در قالب journal باشد. .PP مثال‌ها: .IP .EX $ hledger import bank1\-checking.csv bank1\-savings.csv .EE .IP .EX $ hledger import *.csv .EE .SS اجرای آزمایشی وارد کردن (dry run) پیش‌نمایش وارد کردن با اجرای اولیه به همراه \f[CR]\-\-dry\-run\f[R] بسیار مفید است؛ تا بررسی صحت روی محدودهٔ تاریخ‌های در حال وارد شدن انجام گیرد و در صورت تبدیل از CSV، تأثیر قواعد تبدیل شما بررسی شود. به‌عنوان مثال: .IP .EX $ hledger import bank.csv \-\-dry\-run .EE .PP خروجی اجرای آزمایشی دارای قالب معتبر journal است، بنابراین hledger می‌تواند آن را دوباره تجزیه کند. اگر خروجی حجیم است، می‌توانید فقط تراکنش‌های دسته‌بندی‌نشده را به‌این صورت نمایش دهید: .IP .EX $ hledger import \-\-dry\-run bank.csv | hledger \-f\- \-I print unknown .EE .PP همچنین می‌توانید این دستور را به‌طور مکرر اجرا کنید تا تأثیر ویرایش‌های اعمال‌شده بر قواعد تبدیل خود را مشاهده کنید: .IP .EX $ watchexec \-\- \(dqhledger import \-\-dry\-run bank.csv | hledger \-f\- \-I print unknown\(dq .EE .PP هنگامی که تبدیل و تاریخ‌ها برای وارد شدن به دفتر روزنامهٔ شما به اندازهٔ کافی مناسب به نظر رسیدند (شاید همراه با اصلاحات دستی در ادامه)، می‌توانید وارد کردن واقعی را انجام دهید: .IP .EX $ hledger import bank.csv .EE.SS "تشخیص هم‌پوشانی (Overlap detection)" خواندن فایل‌های CSV به صورت توکار در hledger وجود دارد و منحصر به \f[CR]import\f[R] نیست؛ بنابراین می‌توانید درون‌ریزی را با انجام \f[CR]hledger \-f bank.csv print >>$LEDGER_FILE\f[R] نیز انجام دهید. .PP اما \f[CR]import\f[R] ساده‌تر است و مزایایی به همراه دارد. مهم‌ترین مزیت این است که از درون‌ریزی مجدد تراکنش‌هایی که در اجراهای قبلی دیده است جلوگیری می‌کند. این بدان معناست که نیازی نیست نگران هم‌پوشانی داده‌ها در دریافت‌های متوالی فایل CSV بانک خود باشید؛ تنها هر زمان که مایل بودید فایل را دریافت و \f[CR]import\f[R] کنید، و هر بار تنها تراکنش‌های جدید درون‌ریزی خواهند شد. .PP ما این کار را \(dqحذف موارد تکراری\(dq نمی‌نامیم، چرا که به طور کلی تشخیص مطمئن موارد تکراری در فایل‌های CSV بانکی امکان‌پذیر نیست. در عوض، \f[CR]import\f[R] آخرین تاریخ پردازش‌شده از هر فایل CSV در دفعات قبل را به خاطر می‌سپارد (با ذخیره کردن آن در یک فایل مخفی)، و از تمام رکوردهای پیش از آن تاریخ صرف‌نظر می‌کند. این سازوکار برای بیشتر فایل‌های CSV در دنیای واقعی که شرایط زیر را دارند به‌خوبی کار می‌کند: .IP "1." 3 نام فایل داده بین درون‌ریزی‌های مختلف ثابت باشد (تغییر نکند) .IP "2." 3 تاریخ اقلام بین درون‌ریزی‌های مختلف ثابت باشد .IP "3." 3 ترتیب اقلامِ دارای تاریخ یکسان بین درون‌ریزی‌های مختلف ثابت بماند .IP "4." 3 جدیدترین اقلام، جدیدترین تاریخ‌ها را داشته باشند .PP (نقض گاه‌به‌گاه موارد ۲ تا ۴ اغلب بی‌ضرر است؛ می‌توانید با دریافت و درون‌ریزی در فواصل کوتاه‌تر، احتمال اختلال را کاهش دهید.) .PP تشخیص هم‌پوشانی خودکار است و نباید نیاز به توجه چندانی از سوی شما داشته باشد، مگر شاید در نخستین درون‌ریزی (به بخش زیر مراجعه کنید). اما شیوه کارکرد آن بدین صورت است: .IP \(bu 2 به ازای هر \f[CR]FILE\f[R] که از آن درون‌ریزی انجام می‌شود: .RS 2 .IP "1." 3 برنامه hledger فایلی به نام \f[CR].latest.FILE\f[R] را در صورت وجود در همان دایرکتوری می‌خواند. این فایل شامل آخرین تاریخ رکورد درون‌ریزی‌شده از FILE در گذشته، در قالب YYYY\-MM\-DD است. اگر چندین رکورد با آن تاریخ درون‌ریزی شده باشند، آن تاریخ در N خط تکرار می‌شود. .IP "2." 3 برنامه hledger رکوردها را از FILE می‌خواند. اگر آخرین تاریخی در مرحله ۱ یافت شود، تمام رکوردهای پیش از آن تاریخ، و N رکورد نخست در آن تاریخ نادیده گرفته می‌شوند. .RE .IP \(bu 2 پس از یک درون‌ریزی موفق از تمام FILEها، بدون خطا و بدون گزینه \f[CR]\-\-dry\-run\f[R]، برنامه hledger فایل \f[CR].latest.FILE\f[R] مربوط به هر FILE را برای دفعات بعدی به‌روزرسانی می‌کند. .PP اگر این فرآیند دچار مشکل شود، اصلاح آن نسبتاً آسان است: .IP \(bu 2 پیش از درون‌ریزی، هنگامی که با \f[CR]import \-\-dry\-run\f[R] پیش‌نمایش را بررسی می‌کنید متوجه آن خواهید شد. .IP \(bu 2 یا پس از درون‌ریزی، هنگامی که تلاش می‌کنید تراز حساب‌های hledger خود را با بانک تطبیق دهید. .IP \(bu 2 دستور \f[CR]hledger print \-f FILE.csv\f[R] تمام تراکنش‌های اخیراً دریافت‌شده را نمایش می‌دهد. این موارد را با دفتر روزنامه (journal) خود مقایسه کنید. در صورت نیاز رونوشت/جای‌گذاری (Copy/paste) کنید. .IP \(bu 2 قوانین تبدیل خود را به‌روزرسانی کرده و در صورت نیاز دوباره خروجی را چاپ کنید. .IP \(bu 2 می‌توانید فایل .latest را به صورت دستی به‌روزرسانی یا حذف کنید، یا از \f[CR]import \-\-catchup FILE\f[R] استفاده نمایید. .IP \(bu 2 دریافت و درون‌ریزی را در فواصل کوتاه‌تر، مثلاً دو بار در هفته انجام دهید، حداقل تا زمانی که در حال یادگیری هستید. وقتی تراکنش‌ها کمتر باشند، بررسی و عیب‌یابی آسان‌تر خواهد بود. .SS "نخستین درون‌ریزی (First import)" نخستین باری که از یک فایل درون‌ریزی می‌کنید، زمانی که هنوز فایل .latest متناظری ایجاد نشده است، تمام رکوردها درون‌ریزی خواهند شد. .PP اما شاید داده‌ها را پیش‌تر به صورت دستی وارد کرده باشید، بنابراین می‌دانید که تمام این تراکنش‌ها از قبل در دفتر روزنامه ثبت شده‌اند. در این صورت می‌توانید دستور \f[CR]hledger import \-\-catchup\f[R] را یک‌بار اجرا کنید. این کار یک فایل .latest حاوی آخرین تاریخ رکورد فایل CSV ایجاد می‌کند، به‌طوری‌که هیچ‌یک از آن رکوردها مجدداً درون‌ریزی نخواهند شد. .PP یا اگر می‌دانید که برخی از تراکنش‌ها (نه همه آن‌ها) در دفتر روزنامه وجود دارند، می‌توانید خودتان فایل .latest را بسازید. برای مثال، فرض کنید قبلاً تراکنش‌های foobank را تا تاریخ 2024\-10\-31 در دفتر روزنامه ثبت کرده‌اید. آنگاه در دایرکتوری‌ای که \f[CR]foobank.csv\f[R] را در آن ذخیره می‌کنید، فایلی به نام \f[CR].latest.foobank.csv\f[R] شامل محتوای زیر می‌سازید: .IP .EX 2024\-10\-31 .EE .PP یا اگر سه تراکنش foobank ثبت‌شده با آن تاریخ داشته باشید، آن تاریخ را به همان تعداد تکرار می‌کنید: .IP .EX 2024\-10\-31 2024\-10\-31 2024\-10\-31 .EE .PP سپس دستور \f[CR]hledger import foobank.csv [\-\-dry\-run]\f[R] تنها رکوردهای جدیدتر را درون‌ریزی خواهد کرد..SS وارد کردن انتساب‌های موجودی ورودی‌های دفتر روزنامه که با import اضافه می‌شوند، تمام مقادیر ثبت را به‌صورت صریح خواهند داشت (مانند \f[CR]print \-x\f[R]). .PP این بدان معناست که هرگونه انتساب موجودی در ورودی‌های واردشده باید ارزیابی شود. اما این کار عموماً امکان‌پذیر نیست، زیرا موجودی حساب‌های فایل اصلی در طول import قابل مشاهده نیستند. بنابراین سعی کنید از ایجاد انتساب‌های موجودی با قواعد CSV خود یا وارد کردن از دفتر روزنامه‌ای که حاوی انتساب‌های موجودی است، خودداری کنید. (در هر صورت بهتر است از انتساب‌های موجودی اجتناب شود.) .PP اما اگر مجبور به استفاده از آن‌ها هستید، مثلاً به این دلیل که CSV شما فقط شامل موجودی‌ها است: می‌توانید با \f[CR]print\f[R] وارد کنید، که مقادیر ضمنی را به‌صورت ضمنی باقی می‌گذارد. (\f[CR]print\f[R] همچنین می‌تواند با پرچم \f[CR]\-\-new\f[R] مانند import تشخیص هم‌پوشانی را انجام دهد): .IP .EX $ hledger print \-\-new \-f bank.csv >> $LEDGER_FILE .EE .PP (اگر فکر می‌کنید \f[CR]import\f[R] باید موجودی‌های ضمنی را حفظ کند، لطفاً آن را آزمایش کرده و یک درخواست pull ارسال کنید.) .SS وارد کردن و سبک‌های کالا مبالغ در ورودی‌های اضافه‌شده توسط import بر اساس سبک‌های استاندارد کالای دفتر روزنامه، طبق آنچه در دستورالعمل‌های \f[CR]commodity\f[R] تعیین شده یا از مبالغ دفتر روزنامه استنتاج شده است، قالب‌بندی خواهند شد. .PP مرتبط: CSV > Amount decimal places. .SS بایگانی در import هنگام وارد کردن از یک فایل قواعد CSV (\f[CR]hledger import bank.rules\f[R])، می‌توانید از قاعده archive برای فعال کردن بایگانی خودکار فایل داده استفاده کنید. پس از یک import موفق، فایل داده (مشخص‌شده توسط \f[CR]source\f[R]) به یک پوشه بایگانی (\f[CR]data/\f[R]، در کنار فایل قواعد، با ایجاد خودکار) منتقل شده و مشابه با نام فایل قواعد، به همراه یک تاریخ تغییر نام می‌یابد. این قابلیت می‌تواند برای عیب‌یابی، تشخیص تغییرات در داده‌های CSV بانک‌ها، تولید مجدد ورودی‌ها با قواعد بهبودیافته و غیره مفید باشد. .PP قاعده \f[CR]archive\f[R] همچنین باعث می‌شود \f[CR]import\f[R] با الگوهای glob در \f[CR]source\f[R] رفتار متفاوتی داشته باشد: هنگامی که چندین فایل مطابقت داشته باشند، قدیمی‌ترین را انتخاب می‌کند، نه جدیدترین را. .SS موارد خاص import .SS حذف موارد تکراری در اینجا دو نوع از \(dqحذف موارد تکراری\(dq آورده شده است که \f[CR]import\f[R] به آن‌ها رسیدگی نمی‌کند (و نباید هم بکند، زیرا این موارد می‌توانند به‌طور مشروع در داده‌های مالی رخ دهند): .IP \(bu 2 دو یا چند رکورد از رکوردهای جدید CSV یکسان هستند و ورودی‌های یکسانی در دفتر روزنامه ایجاد می‌کنند. .IP \(bu 2 یک رکورد جدید CSV ورودی دفتر روزنامه‌ای ایجاد می‌کند که با ورودی(های) موجود در دفتر روزنامه یکسان است. .SS نام فایل متغیر اگر فایلی بارگیری‌شده دارید که نام فایل آن تغییر می‌کند، می‌توانید پس از هر بار بارگیری، نام آن را به یک نام ثابت تغییر دهید. یا می‌توانید از قاعده \f[CR]source\f[R] در CSV با یک الگوی glob مناسب استفاده کرده و از فایل rules. وارد کنید. .SS نسخه‌های چندگانه فرض کنید \f[CR]bank.csv\f[R] را بارگیری و آن را وارد می‌کنید، اما فراموش می‌کنید آن را از پوشه بارگیری‌های خود حذف کنید. دفعه بعد که آن را بارگیری می‌کنید، مرورگر وب شما آن را به‌صورت (مثلاً) \f[CR]bank (2).csv\f[R] ذخیره خواهد کرد. الگوهای glob در قاعده source دقیقاً برای چنین موقعیتی هستند: به جای مشخص کردن \f[CR]source bank.csv\f[R]، مقدار \f[CR]source bank*.csv\f[R] را مشخص کنید. سپس \f[CR]hledger \-f bank.rules CMD\f[R] یا \f[CR]hledger import bank.rules\f[R] به‌طور خودکار جدیدترین فایل مطابقت‌یافته (\f[CR]bank (2).csv\f[R]) را انتخاب خواهد کرد. .PP از طرف دیگر، چه می‌شود اگر فایلی را بارگیری کنید، اما وارد کردن یا حذف آن را فراموش کرده و سپس دوباره بارگیری کنید؟ اکنون ممکن است هر یک از فایل‌های \f[CR]bank.csv\f[R] و \f[CR]bank (2).csv\f[R] حاوی داده‌هایی باشند که در دیگری و همچنین در دفتر روزنامه شما وجود ندارند. در این حالت، بهتر است هر کدام را به نوبت، از قدیمی‌ترین به جدیدترین وارد کنید (در غیر این صورت، تشخیص هم‌پوشانی ممکن است باعث نادیده گرفته شدن رکوردهای جدید شود). فعال کردن بایگانی در import این موضوع را تضمین می‌کند. سپس دستور \f[CR]hledger import bank.rules; hledger import bank.rules\f[R] ابتدا \f[CR]bank.csv\f[R] و سپس \f[CR]bank (2).csv\f[R] را وارد و بایگانی خواهد کرد..SH "دستورهای پایه گزارش (Basic report commands)" .SS accounts نام‌های حساب استفاده‌شده یا اعلان‌شده در ژورنال را فهرست می‌کند. .IP .EX پرچم‌ها: \-u \-\-used فهرست کردن حساب‌های استفاده‌شده \-d \-\-declared فهرست کردن حساب‌های اعلان‌شده \-\-undeclared فهرست کردن حساب‌های استفاده‌شده اما اعلان‌نشده \-\-unused فهرست کردن حساب‌های اعلان‌شده اما استفاده‌نشده \-\-find فهرست کردن نخستین حساب منطبق با اولین آرگومان (یک عبارت باقاعده میانی ناوابسته به بزرگی و کوچکی حروف) \-\-directives نمایش به‌صورت دستورالعمل‌های حساب، برای استفاده در ژورنال‌ها \-\-locations همچنین نمایش محل اعلان حساب‌ها \-\-types همچنین نمایش نوع حساب‌ها در صورت مشخص بودن \-l \-\-flat حالت فهرست/درخت: نمایش حساب‌ها به‌صورت یک فهرست مسطح (پیش‌فرض) \-t \-\-tree حالت فهرست/درخت: نمایش حساب‌ها به‌صورت یک درخت \-\-drop=N حالت مسطح: صرف‌نظر کردن از N بخش ابتدایی نام حساب .EE .PP این دستور نام‌های حساب را فهرست می‌کند \- به‌طور پیش‌فرض همه‌ی آن‌ها را، یا فقط مواردی که در تراکنش‌ها استفاده شده‌اند (\f[CR]\-u/\-\-used\f[R])، یا با دستورالعمل‌های \f[CR]account\f[R] اعلان شده‌اند (\f[CR]\-d/\-\-declared\f[R])، یا استفاده شده اما اعلان نشده‌اند (\f[CR]\-\-undeclared\f[R])، یا اعلان شده اما استفاده نشده‌اند (\f[CR]\-\-unused\f[R])، یا تنها نخستین موردی که با یک الگو منطبق شود (\f[CR]\-\-find\f[R]، که در صورت عدم موفقیت یک کد خروج غیرصفر بازمی‌گرداند). .PP می‌توانید برای انتخاب زیرمجموعه‌ای از تراکنش‌ها یا حساب‌ها، آرگومان‌های پرس‌وجو اضافه کنید. .PP با \f[CR]\-\-directives\f[R]، دستورالعمل‌های معتبر حساب را نمایش می‌دهد که می‌توان آن‌ها را در یک فایل ژورنال جای‌گذاری کرد. این گزینه همراه با \f[CR]\-\-undeclared\f[R] هنگام به‌روزرسانی اعلان‌های حساب خود برای برآورده کردن شرایط \f[CR]hledger check accounts\f[R] مفید است. .PP با \f[CR]\-\-locations\f[R]، همچنین فایل و شماره خط اعلان هر حساب (در صورت وجود) و ترتیب کلی اعلان حساب را نمایش می‌دهد؛ این اطلاعات ممکن است هنگام عیب‌یابی ترتیب نمایش حساب‌ها مفید باشد. .PP با \f[CR]\-\-types\f[R]، همچنین نوع هر حساب را در صورت مشخص بودن نمایش می‌دهد. (ببینید: Declaring accounts > Account types.) .PP این دستور به‌طور پیش‌فرض یک فهرست مسطح نمایش می‌دهد. با \f[CR]\-\-tree\f[R]، از تورفتگی برای نمایش سلسله‌مراتب حساب استفاده می‌کند. در حالت مسطح می‌توانید \f[CR]\-\-drop N\f[R] را برای حذف چند بخش ابتدایی نام حساب اضافه کنید. نام حساب‌ها را می‌توان با \f[CR]depth:N\f[R]، \f[CR]\-\-depth N\f[R] یا \f[CR]\-N\f[R] از نظر عمق محدود کرد. .PP مثال‌ها: .IP .EX $ hledger accounts assets:bank:checking assets:bank:saving assets:cash expenses:food expenses:supplies income:gifts income:salary liabilities:debts .EE .IP .EX $ hledger accounts \-\-undeclared \-\-directives >> $LEDGER_FILE $ hledger check accounts .EE .SS codes کدهای دیده‌شده در تراکنش‌ها را به ترتیبی که تجزیه شده‌اند، فهرست می‌کند. .IP .EX پرچم‌ها: بدون پرچم خاص برای این دستور .EE .PP این دستور مقدار فیلد کد هر تراکنش را به ترتیبی که تراکنش‌ها تجزیه شده‌اند، چاپ می‌کند. کد تراکنش یک مقدار اختیاری است که در پرانتز بین تاریخ و شرح نوشته می‌شود، و اغلب برای ذخیره شماره چک، شماره سفارش یا موارد مشابه استفاده می‌شود. .PP تراکنش‌ها الزامی به داشتن کد ندارند و کدهای موجود‌نبوده یا خالی به‌طور پیش‌فرض نمایش داده نمی‌شوند. با پرچم \f[CR]\-E\f[R]/\f[CR]\-\-empty\f[R]، آن‌ها به‌صورت خطوط خالی چاپ خواهند شد. .PP می‌توانید برای انتخاب زیرمجموعه‌ای از تراکنش‌ها، یک پرس‌وجو اضافه کنید. .PP مثال‌ها: .IP .EX 2022/1/1 (123) Supermarket Food $5.00 Checking 2022/1/2 (124) Post Office Postage $8.32 Checking 2022/1/3 Supermarket Food $11.23 Checking 2022/1/4 (126) Post Office Postage $3.21 Checking .EE .IP .EX $ hledger codes 123 124 126 .EE .IP .EX $ hledger codes \-E 123 124 126 .EE.SS commodities فهرست کردن نمادهای کالای استفاده‌شده یا اعلان‌شده در دفتر روزنامه. .IP .EX پرچم‌ها: \-\-used فهرست کردن کالاهای استفاده‌شده \-\-declared فهرست کردن کالاهای اعلان‌شده \-\-undeclared فهرست کردن کالاهای استفاده‌شده اما اعلان‌نشده \-\-unused فهرست کردن کالاهای اعلان‌شده اما استفاده‌نشده \-\-find فهرست کردن نخستین کالای منطبق با اولین آرگومان (یک regexp میانی غیرحساس به بزرگی و کوچکی حروف) .EE .PP این دستور نمادها/نام‌های کالا را فهرست می‌کند \- به‌طور پیش‌فرض همه‌ی آن‌ها، یا فقط مواردی که در تراکنش‌ها یا دستورالعمل‌های \f[CR]P\f[R] استفاده شده‌اند، یا با دستورالعمل‌های \f[CR]commodity\f[R] اعلان شده‌اند، یا استفاده شده اما اعلان نشده‌اند، یا اعلان شده اما استفاده نشده‌اند، یا فقط نخستین موردی که با یک الگو مطابقت دارد (با \f[CR]\-\-find\f[R]، که در صورت شکست یک کد خروج غیرصفر بازمی‌گرداند). .PP می‌توانید آرگومان‌های پرس‌وجوی \f[CR]cur:\f[R] را برای محدود کردن بیشتر کالاها اضافه کنید. .SS descriptions فهرست کردن شرح‌های یکتای استفاده‌شده در تراکنش‌ها. .IP .EX پرچم‌ها: بدون پرچم اختصاصی برای دستور .EE .PP این دستور شرح‌های یکتایی را که در تراکنش‌ها آمده است، به ترتیب الفبایی فهرست می‌کند. می‌توانید یک پرس‌وجو برای انتخاب زیرمجموعه‌ای از تراکنش‌ها اضافه کنید. .PP مثال: .IP .EX $ hledger descriptions Store Name Gas Station | Petrol Person A .EE .SS files فهرست کردن تمام فایل‌های گنجانده‌شده در دفتر روزنامه. با یک آرگومان REGEX، تنها نام فایل‌های منطبق با عبارت منظم (حساس به بزرگ و کوچکی حروف) نشان داده می‌شوند. .IP .EX پرچم‌ها: بدون پرچم اختصاصی برای دستور .EE .SS notes فهرست کردن یادداشت‌های یکتایی که در تراکنش‌ها آمده است. .IP .EX پرچم‌ها: بدون پرچم اختصاصی برای دستور .EE .PP این دستور یادداشت‌های یکتایی را که در تراکنش‌ها آمده است، به ترتیب الفبایی فهرست می‌کند. می‌توانید یک پرس‌وجو برای انتخاب زیرمجموعه‌ای از تراکنش‌ها اضافه کنید. یادداشت، بخشی از شرح تراکنش پس از نویسه‌ی | است (یا در صورت نبود |، کل شرح). .PP مثال: .IP .EX $ hledger notes Petrol Snacks .EE .SS payees فهرست کردن نام‌های دریافت‌کننده/پرداخت‌کننده استفاده‌شده یا اعلان‌شده در دفتر روزنامه. .IP .EX پرچم‌ها: \-\-used فهرست کردن دریافت‌کنندگان استفاده‌شده \-\-declared فهرست کردن دریافت‌کنندگان اعلان‌شده \-\-undeclared فهرست کردن دریافت‌کنندگان استفاده‌شده اما اعلان‌نشده \-\-unused فهرست کردن دریافت‌کنندگان اعلان‌شده اما استفاده‌نشده \-\-find فهرست کردن نخستین دریافت‌کننده منطبق با نخستین آرگومان (یک regexp میانی غیرحساس به بزرگی و کوچکی حروف) .EE .PP این دستور نام‌های یکتای دریافت‌کننده/پرداخت‌کننده را فهرست می‌کند \- به‌طور پیش‌فرض همه‌ی آن‌ها، یا فقط مواردی که در شرح تراکنش‌ها استفاده شده‌اند، یا با دستورالعمل‌های \f[CR]payee\f[R] اعلان شده‌اند، یا استفاده شده اما اعلان نشده‌اند، یا اعلان شده اما استفاده نشده‌اند، یا فقط نخستین موردی که با یک الگو مطابقت دارد (با \f[CR]\-\-find\f[R]، که در صورت شکست یک کد خروج غیرصفر بازمی‌گرداند). .PP نام دریافت‌کننده/پرداخت‌کننده، بخشی از شرح تراکنش قبل از نویسه‌ی | است (یا در صورت نبود |، کل شرح). .PP می‌توانید آرگومان‌های پرس‌وجو را برای انتخاب زیرمجموعه‌ای از تراکنش‌ها یا دریافت‌کنندگان اضافه کنید. .PP مثال: .IP .EX $ hledger payees Store Name Gas Station Person A .EE.SS prices چاپ قیمت‌های بازار اعلان‌شده با دستورالعمل‌های P. با \-\-infer\-market\-prices، هرگونه قیمت اضافی استنتاج‌شده از هزینه‌ها نیز نمایش داده می‌شود. با \-\-show\-reverse، قیمت‌های اضافی استنتاج‌شده از معکوس‌کردن قیمت‌های شناخته‌شده نیز نمایش داده می‌شوند. .IP .EX گزینه‌ها: \-\-show\-reverse همچنین نمایش قیمت‌های استنتاج‌شده با معکوس‌کردن قیمت‌های شناخته‌شده .EE .PP مقادیر قیمت همیشه با دقت کامل نمایش داده می‌شوند، به استثنای قیمت‌های معکوس که به ۸ رقم اعشار محدود شده‌اند. .PP قیمت‌ها را می‌توان با یک پرس‌وجوی date:، cur: یا amt: فیلتر کرد. .PP به‌طور کلی اگر این دستور را با \-\-infer\-market\-prices و \-\-show\-reverse اجرا کنید، همان قیمت‌هایی را نشان می‌دهد که به‌طور داخلی برای محاسبهٔ گزارش‌های ارزش استفاده می‌شوند. اما اگر تردید دارید، می‌توانید با اجرای گزارش ارزش همراه با \-\-debug=2 مستقیماً آن‌ها را بررسی کنید. .SS stats نمایش آمار دفتر روزنامه و عملکرد. .IP .EX گزینه‌ها: \-1 نمایش خروجی در یک سطر \-v \-\-verbose نمایش خروجی با جزئیات بیشتر \-o \-\-output\-file=FILE نوشتن خروجی در FILE. .EE .PP دستور stats اطلاعات خلاصه‌ای را برای کل دفتر روزنامه یا بخشی از آن که تطبیق یافته است، نمایش می‌دهد. با تعیین یک بازهٔ گزارش‌گیری، گزارشی را برای هر دورهٔ گزارش نشان می‌دهد. .PP این دستور همچنین برخی از آمارهای عملکرد را نمایش می‌دهد: .IP \(bu 2 مدت زمانی که برنامه اجرا شده است .IP \(bu 2 تعداد تراکنش‌های پردازش‌شده در هر ثانیه .IP \(bu 2 اوج حافظهٔ زندهٔ در حال استفاده توسط برنامه برای انجام کار خود .IP \(bu 2 اوج حافظهٔ تخصیص‌یافته از دید برنامه .PP به‌طور پیش‌فرض، خروجی تا حد مناسبی گزیده و محتاطانه است؛ این خروجی نام فایل اصلی، سطح فعالیت شما و سرعت سیستم شما را آشکار می‌سازد. .PP با \f[CR]\-v/\-\-verbose\f[R]، جزئیات بیشتری نشان داده می‌شود: مسیرهای کامل همهٔ فایل‌ها، و نام کالاهایی که با آن‌ها کار می‌کنید. .PP با \f[CR]\-1\f[R]، تنها یک خط خروجی در قالبی جداشده با تب و مناسب برای ماشین نمایش داده می‌شود: نسخهٔ برنامه، نام فایل اصلی دفتر روزنامه، و آمارهای عملکرد. .PP زمان اجرای \f[CR]stats\f[R] مشابه با یک گزارش تراز است. .PP مثال: .IP .EX $ hledger stats \-f examples/1ktxns\-1kaccts.journal Main file : .../1ktxns\-1kaccts.journal Included files : 0 Txns span : 2000\-01\-01 to 2002\-09\-27 (1000 days) Last txn : 2002\-09\-26 (7827 days ago) Txns : 1000 (1.0 per day) Txns last 30 days : 0 (0.0 per day) Txns last 7 days : 0 (0.0 per day) Payees/descriptions : 1000 Accounts : 1000 (depth 10) Commodities : 26 Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc .EE .IP .EX $ hledger stats \-1 \-f examples/10ktxns\-1kaccts.journal 1.50.99\-g0835a2485\-20251119, mac\-aarch64 10ktxns\-1kaccts.journal 0.66 s elapsed 15244 txns/s 28 MB live 86 MB alloc .EE .PP این دستور از گزینهٔ \-o/\-\-output\-file پشتیبانی می‌کند (اما از \-O/\-\-output\-format پشتیبانی نمی‌کند)..SS tags فهرست کردن نام برچسب‌های استفاده‌شده یا اعلان‌شده در دفتر روزنامه، یا مقادیر آن‌ها. .IP .EX Flags: \-\-used فهرست کردن برچسب‌های استفاده‌شده \-\-declared فهرست کردن برچسب‌های اعلان‌شده \-\-undeclared فهرست کردن برچسب‌های استفاده‌شده اما اعلان‌نشده \-\-unused فهرست کردن برچسب‌های اعلان‌شده اما استفاده‌نشده \-\-find فهرست نخستین برچسبی که نام آن با آرگومان نخست مطابقت دارد (یک عبارت باقاعده میانیِ غیرحساس به بزرگی‌کوچکی حروف) \-\-values فهرست کردن مقادیر برچسب به‌جای نام برچسب‌ها \-\-parsed نمایش آن‌ها به ترتیبی که تجزیه شده‌اند (غالباً)، شامل موارد تکراری .EE .PP این دستور نام برچسب‌ها را فهرست می‌کند \- به‌طور پیش‌فرض همه آن‌ها را، یا فقط آن‌هایی را که در تراکنش‌ها/ثبت‌ها/حساب‌ها استفاده شده‌اند، یا با دستورالعمل‌های \f[CR]tag\f[R] اعلان شده‌اند، یا استفاده شده اما اعلان نشده‌اند، یا اعلان شده اما استفاده نشده‌اند، یا فقط نخستین موردی را که با یک الگو مطابقت دارد (با \f[CR]\-\-find\f[R]، که در صورت عدم موفقیت یک کد خروج غیرصفر بازمی‌گرداند). .PP به آرگومان نخست غیراستاندارد این دستور توجه کنید: این آرگومان یک عبارت باقاعده میانیِ غیرحساس به بزرگی و کوچکی حروف برای تطبیق نام برچسب‌ها است، که برچسب‌های نمایش‌داده‌شده را محدود می‌کند. هر آرگومان اضافی، یک آرگومان پرس‌وجوی استاندارد است که تراکنش‌ها، ثبت‌ها یا حساب‌های ارائه‌دهنده برچسب‌ها را محدود می‌سازد. .PP با \f[CR]\-\-values\f[R]، به‌جای نام‌ها، مقادیر یکتا و غیرخالیِ برچسب‌ها فهرست می‌شوند. .PP با \f[CR]\-E\f[R]/\f[CR]\-\-empty\f[R]، مقادیر سفید/خالی نیز نشان داده می‌شوند. .PP با \f[CR]\-\-parsed\f[R]، برچسب‌ها یا مقادیر به همان ترتیبی که تجزیه شده‌اند نشان داده می‌شوند، همراه با موارد تکراری. (به استثنای برچسب‌های حاصل از اعلان حساب‌ها که همیشه اول نشان داده می‌شوند.) .PP به یاد داشته باشید که حساب‌ها برچسب‌ها را از والد خود نیز به ارث می‌برند؛ ثبت‌ها نیز برچسب‌ها را از حساب و تراکنشِ مربوطه کسب می‌کنند؛ و تراکنش‌ها نیز برچسب‌ها را از ثبت‌های خود می‌گیرند. .SH "دستورهای استاندارد گزارش‌گیری (Standard report commands)" .SS print نمایش مدخل‌های کامل دفتر روزنامه، که نشان‌دهنده تراکنش‌ها هستند. .IP .EX Flags: \-x \-\-explicit نمایش صریح تمامی مبالغ \-\-invert نمایش تمام مبالغ با علامت معکوس (قرینه) \-\-locations افزودن برچسب‌هایی که مسیر فایل‌ها و شماره خط‌ها را نشان می‌دهند \-m \-\-match=DESC جست‌وجوی فازی برای یک تراکنش اخیر با توضیحاتی که بیشترین شباهت را به DESC دارد \-\-new تنها نمایش تراکنش‌های با تاریخ جدیدتر اضافه‌شده در هر فایل از زمان آخرین اجرا \-\-round=TYPE هنگام نمایش مبالغ چه میزان گرد کردن یا فاصله‌گذاری انجام شود؟ none \- نمایش ارقام اعشاری اصلی، همان‌طور که در دفتر روزنامه آمده است (پیش‌فرض) soft \- صرفاً افزودن یا حذف صفرهای اعشاری برای تطابق با دقت hard \- گرد کردن مبالغ ثبت‌ها تا حد دقت (می‌تواند تراکنش‌ها را ناتراز کند) all \- گرد کردن مبالغ بهای تمام‌شده تا حد دقت (می‌تواند تراکنش‌ها را ناتراز کند) \-\-base\-url=URLPREFIX در خروجی html، تولید پیوندها به hledger\-web با این پیشوند. (معمولاً URL پایه‌ای که توسط hledger\-web نشان داده می‌شود؛ می‌تواند نسبی نیز باشد.) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt, beancount, csv, tsv, html, fods, json, sql. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. پسوند فایلی که با یکی از قالب‌های بالا مطابقت داشته باشد، آن قالب را برمی‌گزیند. .EE .PP دستور print مدخل‌های کامل دفتر روزنامه (تراکنش‌ها) را از فایل دفتر روزنامه، مرتب‌شده بر پایه تاریخ (یا با \f[CR]\-\-date2\f[R]، بر پایه تاریخ ثانویه) نمایش می‌دهد. .PP در حال حاضر دستورالعمل‌ها و یادداشت‌های میان تراکنش‌ها نمایش داده نمی‌شوند. این بدان معناست که دستور print تا حدی با اتلاف اطلاعات همراه است، و چنانچه از آن برای قالب‌بندی مجدد یا بازتولید دفتر روزنامه خود استفاده می‌کنید، باید دقت داشته باشید که دستورالعمل‌ها و یادداشت‌های میان تراکنش‌ها را نیز کپی کنید. .PP برای مثال: .IP .EX $ hledger print \-f examples/sample.journal date:200806 2008/06/01 gift assets:bank:checking $1 income:gifts $\-1 2008/06/02 save assets:bank:saving $1 assets:bank:checking $\-1 2008/06/03 * eat & shop expenses:food $1 expenses:supplies $1 assets:cash $\-2 .EE.SS صراحت مبالغ در print به‌طور معمول، ضمنی یا صریح بودن مبالغ ثبت‌ها حفظ می‌شود. برای مثال، هنگامی که مبلغی در دفتر روزنامه حذف شده باشد، در خروجی نیز ظاهر نخواهد شد. به‌همین ترتیب، اگر هزینه تبدیل به‌صورت ضمنی در نظر گرفته شده اما نوشته نشده باشد، در خروجی نمایش داده نمی‌شود. .PP می‌توانید از پرچم \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] برای اجبار به نمایش صریح تمام مبالغ و هزینه‌ها استفاده کنید. این گزینه می‌تواند برای عیب‌یابی یا خواناتر کردن دفتر روزنامه و مقاوم‌سازی آن در برابر خطاهای ورود داده مفید باشد. استفاده از هر یک از گزینه‌های \f[CR]\-B\f[R]، \f[CR]\-V\f[R]، \f[CR]\-X\f[R] یا \f[CR]\-\-value\f[R] نیز به‌طور خودکار \f[CR]\-x\f[R] را فعال می‌کند. .PP پرچم \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] باعث می‌شود هر ثبتی با مبلغ چندکالایی (که می‌تواند ناشی از داشتن مبلغ ضمنی در یک تراکنش چندکالایی باشد) به چندین ثبت تک‌کالایی تقسیم شود تا خروجی همچنان قابل تجزیه باقی بماند. .SS ترازبندی در print مبالغ در هر تراکنش به‌صورت راست‌چین نمایش داده می‌شوند (اما در سراسر تمام تراکنش‌ها هم‌تراز نمی‌شوند؛ برای رسیدن به این هدف می‌توانید از ledger\-mode در Emacs استفاده کنید). .SS سبک نمایش مبالغ در print مبالغ اغلب بر اساس سبک نمایش کالای (واحد ارزی) خود، با جای‌گذاری استاندارد نماد، علامت اعشار و نشانگرهای گروه‌بندی ارقام نمایش داده می‌شوند. این موضوع شامل ارقام اعشاری آن‌ها نمی‌شود؛ \f[CR]print\f[R] به‌طور معمول همان ارقام اعشاری را که در هر ورودی دفتر روزنامه ثبت شده است نشان می‌دهد. .PP می‌توانید با گزینه ویژه \f[CR]\-\-round\f[R] در \f[CR]print\f[R] (\f[I]از نسخه 1.32\f[R]) دقت اعشار را بازنویسی کنید. گزینه \f[CR]\-\-round\f[R] تلاش می‌کند مبالغ را با دقت اعشار استاندارد کالاها، با سطوح سخت‌گیری فزاینده نشان دهد: .IP \(bu 2 \f[CR]\-\-round=none\f[R] نمایش مبالغ با دقت اصلی (پیش‌فرض) .IP \(bu 2 \f[CR]\-\-round=soft\f[R] افزودن/حذف صفرهای اعشاری در مبالغ (به‌جز هزینه‌ها) .IP \(bu 2 \f[CR]\-\-round=hard\f[R] گرد کردن مبالغ (به‌جز هزینه‌ها)، با احتمال پنهان‌سازی ارقام بااهمیت .IP \(bu 2 \f[CR]\-\-round=all\f[R] گرد کردن تمام مبالغ و هزینه‌ها .PP حالت \f[CR]soft\f[R] برای مرتب‌سازی بدون اتلاف داده، نمایش اعشارهای یکدست‌تر در صورت امکان، و بدون برهم زدن تراز ورودی‌ها مناسب است. .PP حالت‌های \f[CR]hard\f[R] یا \f[CR]all\f[R] برای مرتب‌سازی‌های قوی‌تر، در مواقعی که گرد کردن اعشار مورد نیاز است، کاربرد دارند. توجه داشته باشید که گرد کردن می‌تواند ورودی‌های نامتراز در دفتر روزنامه ایجاد کند که ممکن است نیازمند اصلاح دستی باشد. .SS قابلیت تجزیه خروجی print به‌طور معمول، خروجی print یک دفتر روزنامه معتبر hledger است که می‌توانید آن را برای پردازش‌های بعدی به یک دستور دیگر hledger پایپ (\(dqpipe\(dq) کنید. این کار گاهی برای اجرای انواع خاصی از پرس‌وجوها مناسب است (اگرچه اکنون که پرس‌وجوها قدرتمندتر شده‌اند کمتر مورد نیاز است): .IP .EX # نمایش جمع جاری هزینه‌های خوراک پرداخت‌شده از وجه نقد. # \-f\- از stdin می‌خواند. \-I/\-\-ignore\-assertions گاهی لازم است. $ hledger print assets:cash | hledger \-f\- \-I reg expenses:food .EE .PP اما در اینجا مواردی آورده شده است که می‌توانند موجب غیرقابل تجزیه شدن خروجی print شوند: .IP \(bu 2 \f[CR]\-\-round\f[R] (توضیحات بالا را ببینید) می‌تواند تراز تراکنش را مختل کند. .IP \(bu 2 نام‌های مستعار حساب (Account aliases) یا چرخش (pivoting) می‌توانند نام حساب‌ها، بررسی‌های تراز (balance assertions) یا انتساب‌های تراز (balance assignments) را برهم بزنند. .IP \(bu 2 گزارش‌گیری ارزش (Value reporting) نیز می‌تواند بررسی‌های تراز یا انتساب‌های تراز را مختل کند. .IP \(bu 2 ثبت‌های خودکار (Auto postings) می‌توانند تعداد بیش از حدی ثبتِ بدون مبلغ ایجاد کنند. .IP \(bu 2 \f[CR]\-\-infer\-costs یا \-\-infer\-equity\f[R] می‌توانند هزینه‌های مازاد و بیش از حد پیچیده تولید کنند. .IP \(bu 2 از آنجا که print همیشه تراکنش‌ها را بر اساس تاریخ مرتب می‌کند، بررسی‌های تراز شامل تراکنش‌های نامرتب از نظر تاریخی (و ثبت‌های مربوط به یک روز) ممکن است مختل شوند..SS "سایر قابلیت‌های print (print, other features)" با \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R]، مبالغ دارای بهای تمام‌شده، به‌صورت تبدیل‌شده به بهای تمام‌شده نمایش داده می‌شوند. .PP با \f[CR]\-\-invert\f[R]، مبالغ ثبت (posting) با علامت معکوس نمایش داده می‌شوند. این گزینه در صورتی که به‌طور تصادفی برخی تراکنش‌ها را با علامت‌های نادرست ثبت کرده باشید، می‌تواند مفید باشد. .PP با \f[CR]\-\-new\f[R]، دستور print تنها تراکنش‌هایی را نمایش می‌دهد که در اجرای قبلی ندیده باشد. این قابلیت از همان سامانه یکتا‌سازی و حذف موارد تکراری (deduplication) مشابه دستور \f[CR]import\f[R] استفاده می‌کند. (برای جزئیات، مستندات \f[CR]import\f[R] را ببینید.) .PP با \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R]، دستور print یک تراکنش اخیر را که شرح آن بیشترین شباهت را به DESC دارد نمایش می‌دهد. آرگومان DESC باید دست‌کم شامل دو نویسه باشد. اگر تطابق به اندازه کافی مشابهی وجود نداشته باشد، هیچ تراکنشی نمایش داده نخواهد شد و کد خروج برنامه غیرصفر خواهد بود. .PP با \f[CR]\-\-locations\f[R]، دستور print نام فایل منبع و شماره سطر را به‌صورت یک برچسب (tag) به هر تراکنش اضافه می‌کند. .SS "قالب خروجی print (print output format)" این دستور همچنین از گزینه‌های مقصد خروجی و قالب خروجی پشتیبانی می‌کند. قالب‌های خروجی پشتیبانی‌شده عبارتند از \f[CR]txt\f[R]، \f[CR]beancount\f[R] (\f[I]افزوده‌شده در 1.32\f[R])، \f[CR]csv\f[R]، \f[CR]tsv\f[R] (\f[I]افزوده‌شده در 1.32\f[R])، \f[CR]json\f[R] و \f[CR]sql\f[R]. .PP قالب \f[CR]beancount\f[R] تلاش می‌کند خروجی سازگار با Beancount تولید کند، به شرح زیر: .IP \(bu 2 تراکنش‌ها و ثبت‌های با وضعیت بدون علامت (unmarked) به وضعیت تسویه‌شده (\f[CR]*\f[R]) تبدیل می‌شوند. .IP \(bu 2 دریافت‌کننده وجه (payee) و یادداشت (note) تراکنش‌ها با بک‌اسلش و نقل‌قول دوتایی گریز داده شده (escaped) و درون نقل‌قول‌های دوتایی قرار می‌گیرند. .IP \(bu 2 برچسب‌های تراکنش به قالب #tag در Beancount کپی می‌شوند. .IP \(bu 2 نمادهای کالا/ارز (commodity) به حروف بزرگ تبدیل می‌شوند، و تعداد اندکی از نمادهای ارزی مانند \f[CR]$\f[R] به نام‌های ارز متناظر تبدیل می‌گردند. .IP \(bu 2 بخش‌های نام حساب با حروف بزرگ آغاز می‌شوند و نویسه‌های پشتیبانی‌نشده با \f[CR]\-\f[R] جایگزین می‌شوند. اگر بخشی از نام حساب با یک حرف آغاز نشود، یا اگر بخش نخست یکی از موارد Assets، Liabilities، Equity، Income یا Expenses نباشد، خطایی صادر می‌شود. (برای سازگار کردن حساب‌های خود، از گزینه‌های \f[CR]\-\-alias\f[R] استفاده کنید.) .IP \(bu 2 یک دستورالعمل (directive) \f[CR]open\f[R] برای هر حساب استفاده‌شده، در نخستین تاریخ تراکنش تولید می‌شود. .PP برخی محدودیت‌ها: .IP \(bu 2 تأییدیه‌های تراز (balance assertions) حذف می‌شوند. .IP \(bu 2 تخصیص‌های تراز (balance assignments) به مبالغ نامشخص تبدیل می‌شوند. .IP \(bu 2 ثبت‌های مجازی (virtual) و مجازی تراز‌شده به ثبت‌های عادی تبدیل می‌شوند. .IP \(bu 2 دستورالعمل‌ها (directives) تبدیل نمی‌شوند. .PP در اینجا نمونه‌ای از خروجی CSV دستور print آمده است: .IP .EX $ hledger print \-Ocsv \(dqtxnidx\(dq,\(dqdate\(dq,\(dqdate2\(dq,\(dqstatus\(dq,\(dqcode\(dq,\(dqdescription\(dq,\(dqcomment\(dq,\(dqaccount\(dq,\(dqamount\(dq,\(dqcommodity\(dq,\(dqcredit\(dq,\(dqdebit\(dq,\(dqposting\-status\(dq,\(dqposting\-comment\(dq \(dq1\(dq,\(dq2008/01/01\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq,\(dqincome\(dq,\(dq\(dq,\(dqassets:bank:checking\(dq,\(dq1\(dq,\(dq$\(dq,\(dq\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq \(dq1\(dq,\(dq2008/01/01\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq,\(dqincome\(dq,\(dq\(dq,\(dqincome:salary\(dq,\(dq\-1\(dq,\(dq$\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq \(dq2\(dq,\(dq2008/06/01\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq,\(dqgift\(dq,\(dq\(dq,\(dqassets:bank:checking\(dq,\(dq1\(dq,\(dq$\(dq,\(dq\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq \(dq2\(dq,\(dq2008/06/01\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq,\(dqgift\(dq,\(dq\(dq,\(dqincome:gifts\(dq,\(dq\-1\(dq,\(dq$\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq \(dq3\(dq,\(dq2008/06/02\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq,\(dqsave\(dq,\(dq\(dq,\(dqassets:bank:saving\(dq,\(dq1\(dq,\(dq$\(dq,\(dq\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq \(dq3\(dq,\(dq2008/06/02\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq,\(dqsave\(dq,\(dq\(dq,\(dqassets:bank:checking\(dq,\(dq\-1\(dq,\(dq$\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq \(dq4\(dq,\(dq2008/06/03\(dq,\(dq\(dq,\(dq*\(dq,\(dq\(dq,\(dqeat & shop\(dq,\(dq\(dq,\(dqexpenses:food\(dq,\(dq1\(dq,\(dq$\(dq,\(dq\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq \(dq4\(dq,\(dq2008/06/03\(dq,\(dq\(dq,\(dq*\(dq,\(dq\(dq,\(dqeat & shop\(dq,\(dq\(dq,\(dqexpenses:supplies\(dq,\(dq1\(dq,\(dq$\(dq,\(dq\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq \(dq4\(dq,\(dq2008/06/03\(dq,\(dq\(dq,\(dq*\(dq,\(dq\(dq,\(dqeat & shop\(dq,\(dq\(dq,\(dqassets:cash\(dq,\(dq\-2\(dq,\(dq$\(dq,\(dq2\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq \(dq5\(dq,\(dq2008/12/31\(dq,\(dq\(dq,\(dq*\(dq,\(dq\(dq,\(dqpay off\(dq,\(dq\(dq,\(dqliabilities:debts\(dq,\(dq1\(dq,\(dq$\(dq,\(dq\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq \(dq5\(dq,\(dq2008/12/31\(dq,\(dq\(dq,\(dq*\(dq,\(dq\(dq,\(dqpay off\(dq,\(dq\(dq,\(dqassets:bank:checking\(dq,\(dq\-1\(dq,\(dq$\(dq,\(dq1\(dq,\(dq\(dq,\(dq\(dq,\(dq\(dq .EE .IP \(bu 2 به ازای هر ثبت (posting)، یک رکورد CSV وجود دارد که در آن فیلدهای تراکنش والد تکرار می‌شوند. .IP \(bu 2 فیلد \(dqtxnidx\(dq (شناسهٔ تراکنش) نشان می‌دهد که کدام ثبت‌ها متعلق به یک تراکنش یکسان هستند. (این شماره ممکن است در صورت تغییر ترتیب تراکنش‌ها در فایل، پردازش یا گنجاندن فایل‌ها با ترتیبی دیگر، و غیره تغییر کند.) .IP \(bu 2 مبلغ به دو فیلد \(dqcommodity\(dq (نماد) و \(dqamount\(dq (مقدار عددی) تفکیک می‌شود. .IP \(bu 2 مقدار عددی برای راحتی در یکی از ستون‌های \(dqcredit\(dq یا \(dqdebit\(dq تکرار می‌شود. (این نام‌ها از نظر حسابداری دقیق نیستند؛ برنامه صرفاً مبالغ منفی را زیر credit و مبالغ صفر یا مثبت را زیر debit قرار می‌دهد.).SS aregister (areg) .PP نمایش تراکنش‌ها و مانده‌های جاری در یک حساب، با قرار گرفتن هر تراکنش در یک خط. .IP .EX پرچم‌ها: \-\-txn\-dates فیلتر دقیق بر اساس تاریخ تراکنش، نه تاریخ ثبت (posting date). هشدار: این کار می‌تواند مانده جاری نادرستی را نشان دهد. \-\-no\-elide عدم محدودسازی به نمایش تنها ۲ کالا به ازای هر مقدار \-\-cumulative حالت تجمیعی: نمایش مجموع جاری از تاریخ شروع گزارش \-H \-\-historical حالت تجمیعی: نمایش مجموع/مانده جاری تاریخی (شامل ثبت‌های پیش از تاریخ شروع گزارش) (پیش‌فرض) \-\-invert نمایش تمام مقادیر با علامت معکوس \-\-drop=N حذف N بخش ابتدایی نام حساب \-\-heading=YN نمایش سطر سربرگ بالای جدول: yes (پیش‌فرض) یا no \-w \-\-width=N تنظیم عرض خروجی (پیش‌فرض: عرض ترمینال). \-wN,M عرض توضیحات را نیز تعیین می‌کند. \-\-align\-all تضمین تراز بودن در تمام خطوط (کندتر) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt، html، csv، tsv، json. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. پسوند فایلی که با یکی از قالب‌های بالا مطابقت داشته باشد، آن قالب را انتخاب می‌کند. .EE .PP دستور \f[CR]aregister\f[R] تراکنش‌های کلی تأثیرگذار بر یک حساب خاص (و هرگونه زیرحساب آن) را نمایش می‌دهد. هر خط گزارش نشان‌دهنده یک تراکنش در این حساب است. تراکنش‌های پیش از تاریخ آغاز گزارش در مانده جاری گنجانده می‌شوند (حالت \f[CR]\-\-historical\f[R] پیش‌فرض است). می‌توانید با استفاده از گزینهٔ \f[CR]\-\-cumulative\f[R] این رفتار را لغو کنید. .PP این دستور در مقایسه با دستور \f[CR]register\f[R] (که ثبت‌های جداگانه را، احتمالاً از چندین حساب و نه لزوماً در حالت تاریخی نشان می‌دهد)، نمایی «واقعی‌تر» و شبیه به صورت‌حساب‌های بانکی ارائه می‌دهد. به عنوان یک قاعده کلی: .IP \(bu 2 دستور \f[CR]aregister\f[R] بهترین گزینه برای تطبیق و مغایرت‌گیری حساب‌های واقعی دارایی/بدهی است .IP \(bu 2 دستور \f[CR]register\f[R] بهترین گزینه برای بازبینی تک‌تک درآمدها/هزینه‌ها است. .PP به نخستین آرگومان غیر استاندارد و الزامی این دستور توجه داشته باشید؛ این آرگومان حسابی را که دفتر روزنامهٔ آن باید نمایش داده شود مشخص می‌کند. می‌توانید نام حساب را وارد کنید، یا (برای کاهش تایپ) از یک عبارت منظم میانی غیرحساس به بزرگ و کوچکی حروف مطابق با نام آن استفاده کنید، که حسابی را که از نظر الفبایی اولین تطابق را داشته باشد انتخاب می‌کند. (برای نمونه، اگر حساب‌های \f[CR]assets:personal checking\f[R] و \f[CR]assets:business checking\f[R] را داشته باشید، دستور \f[CR]hledger areg checking\f[R] حساب \f[CR]assets:business checking\f[R] را انتخاب خواهد کرد.) .PP تراکنش‌های شامل زیرحساب‌های این حساب نیز نمایش داده خواهند شد. دستور \f[CR]aregister\f[R] محدودیت‌های عمق را نادیده می‌گیرد، بنابراین مجموع نهایی آن همواره با یک گزارش مانده تاریخی با آرگومان‌های مشابه مطابقت خواهد داشت. .PP هرگونه آرگومان اضافی، یک آرگومان پرسمان استاندارد محسوب می‌شود که تراکنش‌های نمایش‌داده‌شده را محدود می‌کند. توجه داشته باشید که برخی از پرسمان‌ها مانده جاری را تغییر می‌دهند و باعث می‌شوند با مانده جاری واقعی حساب متفاوت باشد. .PP یک مثال: این دستور تراکنش‌ها و مانده جاری تاریخی را در طول ماه ژوئیه در نخستین حسابی که نام آن شامل \(dqchecking\(dq است نمایش می‌دهد: .IP .EX $ hledger areg checking date:jul .EE .PP هر سطر در خروجی \f[CR]aregister\f[R] موارد زیر را نمایش می‌دهد: .IP \(bu 2 تاریخ تراکنش (یا تاریخ ثبت مربوطه در صورت متفاوت بودن، پایین‌تر را ببینید) .IP \(bu 2 نام تمام حساب‌های دیگری که در این تراکنش دخیل هستند (احتمالاً به صورت مخفف) .IP \(bu 2 تغییر کلی در مانده این حساب بر اثر این تراکنش .IP \(bu 2 مانده جاری تاریخی حساب پس از انجام این تراکنش. .PP تراکنش‌هایی که تغییر خالص آن‌ها صفر است به‌طور پیش‌فرض نمایش داده نمی‌شوند؛ برای نمایش آن‌ها پرچم \f[CR]\-E/\-\-empty\f[R] را اضافه کنید. .PP به دلایل کارایی، عرض ستون‌ها بر اساس ۱۰۰۰ خط اول تعیین می‌شود؛ این بدان معناست که مقادیر بیش از حد عریض در خطوط بعدی ممکن است هنگام تنظیم مجدد عرض ستون‌ها باعث ناهماهنگی دیداری شوند. اگر می‌خواهید از تراز بودن کامل ستون‌ها اطمینان حاصل کنید (به بهای صرف زمان و حافظه بیشتر)، از پرچم \f[CR]\-\-align\-all\f[R] استفاده کنید. .PP به‌طور پیش‌فرض، \f[CR]aregister\f[R] یک سربرگ در بالای داده‌ها نمایش می‌دهد. با این حال، هنگام گزارش‌گیری به زبانی غیر از انگلیسی، آسان‌تر است که این سربرگ را حذف کرده و سربرگ مورد نظر خود را درج کنید. برای این منظور، از گزینهٔ \f[CR]\-\-heading=no\f[R] استفاده کنید. .PP این دستور همچنین از گزینه‌های تعیین مقصد خروجی و قالب خروجی پشتیبانی می‌کند. قالب‌های خروجی پشتیبانی‌شده عبارتند از \f[CR]txt\f[R]، \f[CR]csv\f[R]، \f[CR]tsv\f[R] (\f[I]افزوده‌شده در 1.32\f[R])، \f[CR]html\f[R]، \f[CR]fods\f[R] (\f[I]افزوده‌شده در 1.41\f[R]) و \f[CR]json\f[R]..SS aregister و تاریخ‌های ثبت (posting dates) دستور aregister همواره به‌ازای هر تراکنش یک خط (و یک تاریخ و مبلغ) را نمایش می‌دهد. اما گاهی تراکنش‌ها دارای ثبت‌هایی (postings) با تاریخ‌های متفاوت هستند. همچنین، ممکن است تمام ثبت‌های یک تراکنش در بازه زمانی گزارش قرار نگیرند. برای حل این مسئله، aregister کهن‌ترین تاریخ میان تاریخ تراکنش و تاریخ‌های ثبت را که در دوره گزارش قرار دارند، به‌همراه مجموع ثبت‌های درون دوره نمایش می‌دهد. به عبارت دیگر، یک ردیف ادغام‌شده را تنها با کهن‌ترین تاریخ نشان خواهد داد، و تراز جاری (موقتاً، تا آخرین ثبت تراکنش) نادقیق خواهد بود. اگر نیاز به مشاهده تک‌تک ثبت‌ها دارید، از \f[CR]register \-H\f[R] استفاده کنید. .PP همچنین پرچم \f[CR]\-\-txn\-dates\f[R] نیز وجود دارد که صرفاً بر اساس تاریخ تراکنش پالایش می‌کند و تاریخ‌های ثبت را نادیده می‌گیرد. این مورد نیز می‌تواند باعث نادقیق شدن تراز جاری شود. .SS register (reg) .PP نمایش ثبت‌ها و مجموع جاری آن‌ها. .IP .EX Flags: \-\-cumulative حالت انباشتگی: نمایش مجموع جاری از تاریخ شروع گزارش (پیش‌فرض) \-H \-\-historical حالت انباشتگی: نمایش مجموع/تراز جاری تاریخی (شامل ثبتی‌های پیش از تاریخ شروع گزارش) \-A \-\-average نمایش میانگین جاری مقادیر ثبتی به‌جای مجموع (به‌معنای \-\-empty نیز هست) \-m \-\-match=DESC جست‌وجوی فازی برای یک ثبتی اخیر با شرحی که نزدیک‌ترین به DESC باشد \-r \-\-related نمایش موارد همزاد (siblings) ثبتی‌ها به‌جای خود آن‌ها \-\-invert نمایش همه مقادیر با علامت معکوس \-\-drop=N حذف N بخش ابتدایی نام حساب \-\-sort=FIELDS مرتب‌سازی بر اساس: date، desc، account، amount، absamount یا ترکیبی از آن‌ها با کاما. برای مرتب‌سازی نزولی، پیشوند \- بگذارید. (پیش‌فرض: date) \-w \-\-width=N تنظیم عرض خروجی (پیش‌فرض: عرض ترمینال). \-wN,M عرض شرح را نیز تنظیم می‌کند. \-\-align\-all تضمین تراز بودن در تمام خطوط (کندتر) \-\-base\-url=URLPREFIX در خروجی html، تولید پیوندها به hledger\-web با این پیشوند. (معمولاً base url ارائه‌شده توسط hledger\-web؛ می‌تواند نسبی نیز باشد.) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt، csv، tsv، html، fods، json. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. پسوند فایلی که با یکی از قالب‌های بالا مطابقت داشته باشد آن قالب را انتخاب می‌کند. .EE .PP دستور register ثبت‌های منطبق را در تمام حساب‌ها، به ترتیب تاریخ، همراه با مجموع جاری یا تراز تاریخی جاری آن‌ها نمایش می‌دهد. (همچنین دستور \f[CR]aregister\f[R] را ببینید که تراکنش‌های منطبق را در یک حساب خاص نشان می‌دهد.) .PP دستور register به‌طور معمول برای هر ثبت یک خط را نمایش می‌دهد، اما توجه داشته باشید که مبالغ چندکالایی (multi\-commodity) چند خط را اشغال خواهند کرد (یک خط به‌ازای هر کالا). .PP این دستور معمولاً با یک پرس‌وجو برای انتخاب حسابی خاص استفاده می‌شود تا فعالیت‌های آن حساب مشاهده شود: .IP .EX $ hledger register checking 2008/01/01 income assets:bank:checking $1 $1 2008/06/01 gift assets:bank:checking $1 $2 2008/06/02 save assets:bank:checking $\-1 $1 2008/12/31 pay off assets:bank:checking $\-1 0 .EE .PP با گزینهٔ \f[CR]\-\-date2\f[R]، به‌جای آن بر اساس تاریخ ثانویه نمایش داده و مرتب می‌کند. .PP به دلایل کارایی، عرض ستون‌ها بر اساس ۱۰۰۰ خط اول تعیین می‌شود؛ این بدان معناست که مقادیر با عرض نامتعارف در خطوط بعدی می‌توانند با تنظیم مجدد عرض ستون‌ها، ناهماهنگی‌های بصری ایجاد کنند. اگر می‌خواهید تراز بودن کامل خطوط را تضمین کنید (به بهای صرف زمان و حافظهٔ بیشتر)، از پرچم \f[CR]\-\-align\-all\f[R] استفاده کنید. .PP پرچم \f[CR]\-\-historical\f[R]/\f[CR]\-H\f[R]، تراز ثبت‌های پیشین نمایش‌داده‌نشده را به مجموع جاری اضافه می‌کند. این قابلیت زمانی مفید است که می‌خواهید تنها فعالیت‌های اخیر را با یک تراز جاری دقیق از نظر تاریخی مشاهده کنید: .IP .EX $ hledger register checking \-b 2008/6 \-\-historical 2008/06/01 gift assets:bank:checking $1 $2 2008/06/02 save assets:bank:checking $\-1 $1 2008/12/31 pay off assets:bank:checking $\-1 0 .EE .PP گزینهٔ \f[CR]\-\-depth\f[R] میزان جزئیات نمایش‌داده‌شده از زیرحساب‌ها را محدود می‌کند. .PP گزینهٔ \f[CR]\-\-drop\f[R] بخش‌های ابتدایی از نام حساب‌ها را حذف می‌کند. .PP پرچم \f[CR]\-\-average\f[R]/\f[CR]\-A\f[R] میانگین جاری مقادیر ثبت را به‌جای مجموع جاری نمایش می‌دهد (بنابراین، آخرین عدد نمایش‌داده‌شده میانگین کل دوره گزارش است). این پرچم مستلزم \f[CR]\-\-empty\f[R] است (به بخش زیر مراجعه کنید). این گزینه تحت تأثیر \f[CR]\-\-historical\f[R] قرار می‌گیرد. این ویژگی زمانی بهترین عملکرد را دارد که تنها یک حساب و یک کالا نمایش داده شود. .PP پرچم \f[CR]\-\-related\f[R]/\f[CR]\-r\f[R] ثبت‌های \f[I]دیگر\f[R] تراکنش‌هایی را نمایش می‌دهد که ثبت‌های آن‌ها در حالت عادی نمایش داده می‌شدند. .PP پرچم \f[CR]\-\-invert\f[R] علامت تمام مبالغ را معکوس می‌کند. به‌عنوان مثال، می‌توان از آن در یک حساب درآمد استفاده کرد که مبالغ آن معمولاً به‌صورت اعداد منفی نمایش داده می‌شوند. همچنین برای نمایش ثبت‌های حساب checking به همراه حساب مرتبط با آن مفید است: .PP پرچم \f[CR]\-\-sort=FIELDS\f[R] بر اساس فیلدهای ارائه‌شده مرتب‌سازی می‌کند که می‌توانند هر یک از موارد \f[CR]account\f[R]، \f[CR]amount\f[R]، \f[CR]absamount\f[R]، \f[CR]date\f[R]، یا \f[CR]desc\f[R]/\f[CR]description\f[R] باشند که با کاما از هم جدا شده‌اند. برای نمونه، \f[CR]\-\-sort account,amount\f[R] تمام تراکنش‌ها را در هر حساب گروه‌بندی کرده و بر اساس مبلغ تراکنش مرتب می‌کند. هر فیلد می‌تواند با یک پیشوند \f[CR]\-\f[R] معکوس شود، بنابراین \f[CR]\-\-sort \-amount\f[R] تراکنش‌ها را از کوچک‌ترین مبلغ به بزرگ‌ترین مبلغ نمایش خواهد داد. .IP .EX $ hledger register \-\-related \-\-invert assets:checking .EE .PP با تعیین بازهٔ گزارش‌گیری، register ثبت‌های خلاصه‌شده را نمایش می‌دهد؛ یک ثبت به‌ازای هر بازه، که ثبت‌های هر حساب را تجمیع می‌کند: .IP .EX $ hledger register \-\-monthly income 2008/01 income:salary $\-1 $\-1 2008/06 income:gifts $\-1 $\-2 .EE .PP دوره‌های بدون فعالیت، و ثبت‌های خلاصه با مبلغ صفر، به‌طور پیش‌فرض نمایش داده نمی‌شوند؛ برای دیدن آن‌ها از پرچم \f[CR]\-\-empty\f[R]/\f[CR]\-E\f[R] استفاده کنید: .IP .EX $ hledger register \-\-monthly income \-E 2008/01 income:salary $\-1 $\-1 2008/02 0 $\-1 2008/03 0 $\-1 2008/04 0 $\-1 2008/05 0 $\-1 2008/06 income:gifts $\-1 $\-2 2008/07 0 $\-2 2008/08 0 $\-2 2008/09 0 $\-2 2008/10 0 $\-2 2008/11 0 $\-2 2008/12 0 $\-2 .EE .PP اغلب مایل خواهید بود که فقط یک خط به‌ازای هر بازه مشاهده کنید. گزینهٔ \f[CR]\-\-depth\f[R] در این زمینه کمک می‌کند و باعث تجمیع زیرحساب‌ها می‌شود: .IP .EX $ hledger register \-\-monthly assets \-\-depth 1 2008/01 assets $1 $1 2008/06 assets $\-1 0 2008/12 assets $\-1 $\-1 .EE .PP توجه داشته باشید هنگام استفاده از بازه‌های زمانی گزارش‌گیری، اگر تاریخ‌های شروع/پایان را مشخص کنید، در صورت لزوم به سمت بیرون تنظیم می‌شوند تا تعداد کاملی از بازه‌ها را در بر گیرند. این امر تضمین می‌کند که بازه‌های اول و آخر دارای طول کامل بوده و با سایر بازه‌های موجود در گزارش قابل مقایسه باشند. .PP اگر درخت حساب‌های شما دارای سطوح تودرتوی عمیقی است، ممکن است برخی گزارش‌ها با حذف بخش‌های ابتدایی از نام حساب‌ها با استفاده از \f[CR]\-\-drop\f[R] سودمندتر شوند. .IP .EX $ hledger register \-\-monthly income \-\-drop 1 2008/01 salary $\-1 $\-1 2008/06 gifts $\-1 $\-2 .EE.PP با \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R]، دستور register یک جست‌وجوی فازی (fuzzy search) برای یک ثبت (posting) اخیر که شرح آن بیشترین شباهت را به DESC دارد انجام می‌دهد. DESC باید دست‌کم شامل دو نویسه باشد. اگر تطابق به‌اندازه کافی مشابهی وجود نداشته باشد، هیچ ثبتی نمایش داده نخواهد شد و کد خروج برنامه غیرصفر خواهد بود. .SS خروجی سفارشی register دستور register به‌طور معمول از تمام عرض ترمینال (یا ۸۰ ستون اگر نتواند آن را تشخیص دهد) استفاده می‌کند. می‌توانید با گزینهٔ \f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] این مقدار را تغییر دهید. .PP ستون‌های شرح (description) و حساب (account) به‌طور معمول فضا را به‌طور مساوی تقسیم می‌کنند (هر کدام حدود نیمی از (width \- 40)). می‌توانید این مقدار را با افزودن عرض شرح به‌عنوان بخشی از آرگومان \-\-width، با کاما جدا شده، تنظیم کنید: \f[CR]\-\-width W,D\f[R] . در اینجا نموداری آورده شده است (در \-\-help به‌درستی نمایش داده نخواهد شد): .IP .EX <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- width (W) \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-> date (10) description (D) account (W\-41\-D) amount (12) balance (12) DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA .EE .PP و چند مثال: .IP .EX $ hledger reg # استفاده از عرض ترمینال (یا ۸۰ در ویندوز) $ hledger reg \-w 100 # استفاده از عرض ۱۰۰ $ hledger reg \-w 100,40 # تنظیم عرض کلی ۱۰۰، عرض شرح ۴۰ .EE .PP این دستور همچنین از گزینه‌های مقصد خروجی و قالب خروجی پشتیبانی می‌کند. قالب‌های خروجی پشتیبانی‌شده عبارتند از \f[CR]txt\f[R]، \f[CR]csv\f[R]، \f[CR]tsv\f[R] (\f[I]افزوده‌شده در 1.32\f[R]) و \f[CR]json\f[R]. .SS balancesheet (bs) .PP نمایش موجودی‌های پایانی در حساب‌های دارایی (asset) و بدهی (liability). مبالغ با علامت مثبت عادی نمایش داده می‌شوند، همانند صورت‌های مالی متداول. .IP .EX گزینه‌ها (Flags): \-\-sum حالت محاسبه: نمایش مجموع مبالغ ثبت‌ها (پیش‌فرض) \-\-valuechange حالت محاسبه: نمایش کل تغییر ارزش موجودی‌های تاریخی پایان دوره (ناشی از واریزها، برداشت‌ها، نوسانات قیمت بازار) \-\-gain حالت محاسبه: نمایش سود/زیان سرمایه‌ای تحقق‌نیافته (ارزش موجودی تاریخی منهای بهای تمام‌شده) \-\-count حالت محاسبه: نمایش تعداد ثبت‌ها \-\-change حالت تجمیع: تجمیع مبالغ از ابتدای ستون تا انتهای ستون (در گزارش‌های چندستونی) \-\-cumulative حالت تجمیع: تجمیع مبالغ از ابتدای گزارش (مشخص‌شده مثلاً با \-b/\-\-begin) تا انتهای ستون \-H \-\-historical حالت تجمیع: تجمیع مبالغ از ابتدای دفتر روزنامه تا انتهای ستون (شامل ثبت‌های پیش از تاریخ آغاز گزارش) (پیش‌فرض) \-l \-\-flat حالت فهرست/درخت: نمایش حساب‌ها به‌صورت یک فهرست مسطح (پیش‌فرض). مبالغ شامل مبالغ زیرحساب‌ها نمی‌شوند، مگر در مواردی که عمق حساب محدود شده باشد. \-t \-\-tree حالت فهرست/درخت: نمایش حساب‌ها به‌صورت درختی. مبالغ شامل مبالغ زیرحساب‌ها می‌شوند. \-\-drop=N در حالت فهرست، حذف N بخش ابتدایی نام حساب \-\-declared شامل حساب‌های تعریف‌شده غیر والد (بهترین حالت استفاده همراه با \-E) \-A \-\-average نمایش یک ستون میانگین ردیف (در گزارش‌های چندستونی) \-T \-\-row\-total نمایش یک ستون مجموع ردیف (در گزارش‌های چندستونی) \-\-summary\-only تنها نمایش خلاصه‌های ردیف (مانند مجموع ردیف، میانگین) (در گزارش‌های چندستونی) \-N \-\-no\-total حذف ردیف مجموع نهایی \-\-no\-elide در حالت درختی، عدم ادغام حساب‌های والد بدون تغییر \-\-format=FORMATSTR استفاده از این قالب خط سفارشی (در گزارش‌های ساده) \-S \-\-sort\-amount مرتب‌سازی بر اساس مبلغ به‌جای کد/نام حساب \-% \-\-percent بیان مقادیر به‌صورت درصدی از مجموع هر ستون \-\-layout=ARG نحوه نمایش مبالغ چندکالایی: \(aqwide[,WIDTH]\(aq: تمام کالاها در یک خط \(aqtall\(aq : هر کالا در یک خط جدید \(aqbare\(aq : تنها اعداد، نمادها در یک ستون \-\-base\-url=URLPREFIX در خروجی html، تولید ابرپیوندها به hledger\-web با این پیشوند. (معمولاً URL پایه‌ای که توسط hledger\-web نشان داده می‌شود؛ می‌تواند نسبی نیز باشد.) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt، html، csv، tsv، json. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. یک پسوند فایل که با یکی از قالب‌های بالا مطابقت داشته باشد آن قالب را انتخاب می‌کند. .EE .PP این دستور یک ترازنامه را نمایش می‌دهد که موجودی‌های پایانی تاریخی حساب‌های دارایی و بدهی را نشان می‌دهد. (برای دیدن حقوق صاحبان سهام نیز، از دستور balancesheetequity استفاده کنید.) .PP حساب‌های تعریف‌شده با نوع \f[CR]Asset\f[R]، \f[CR]Cash\f[R] یا \f[CR]Liability\f[R] نمایش داده می‌شوند (انواع حساب را ببینید). یا اگر چنین حساب‌هایی تعریف نشده باشند، حساب‌های سطح بالایی با نام \f[CR]asset\f[R] یا \f[CR]liability\f[R] (غیرحساس به حروف بزرگ و کوچک، حالت‌های جمع مجاز است) و زیرحساب‌های آن‌ها را نشان می‌دهد. .PP مثال: .IP .EX $ hledger balancesheet Balance Sheet 2008\-12\-31 || 2008\-12\-31 ====================++============ Assets || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- assets:bank:saving || $1 assets:cash || $\-2 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- || $\-1 ====================++============ Liabilities || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- liabilities:debts || $\-1 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- || $\-1 ====================++============ Net: || 0 .EE .PP این دستور نوعی سطح‌بالاتر از دستور \f[CR]balance\f[R] است و از بسیاری از ویژگی‌های آن دستور، مانند گزارش‌های چنددوره‌ای پشتیبانی می‌کند. مشابه \f[CR]hledger balance \-H assets liabilities\f[R] است، اما با تشخیص هوشمندانه‌تر حساب‌ها و نمایش بدهی‌ها با علامت معکوس‌شده. .PP این دستور همچنین از گزینه‌های مقصد خروجی و قالب خروجی پشتیبانی می‌کند. قالب‌های خروجی پشتیبانی‌شده عبارتند از \f[CR]txt\f[R]، \f[CR]csv\f[R]، \f[CR]tsv\f[R] (\f[I]افزوده‌شده در 1.32\f[R])، \f[CR]html\f[R] و \f[CR]json\f[R]..SS balancesheetequity (bse) .PP این دستور یک ترازنامه را نمایش می‌دهد و مانده‌های پایانی تاریخی حساب‌های دارایی، بدهی و سرمایه را نشان می‌دهد. مبالغ با علامت مثبت عادی نمایش داده می‌شوند، همانند صورت‌های مالی متداول. .IP .EX پرچم‌ها: \-\-sum حالت محاسبه: نمایش مجموع مبالغ ثبت‌ها (پیش‌فرض) \-\-valuechange حالت محاسبه: نمایش کل تغییر ارزش مانده‌های تاریخی پایان دوره (ناشی از واریزها، برداشت‌ها، نوسانات قیمت بازار) \-\-gain حالت محاسبه: نمایش سود/زیان سرمایه‌ای تحقق‌نیافته (ارزش مانده تاریخی منهای بهای تمام‌شده) \-\-count حالت محاسبه: نمایش تعداد ثبت‌ها \-\-change حالت انباشت: انباشت مبالغ از آغاز ستون تا پایان ستون (در گزارش‌های چندستونی) \-\-cumulative حالت انباشت: انباشت مبالغ از آغاز گزارش (تعیین‌شده مثلاً با \-b/\-\-begin) تا پایان ستون \-H \-\-historical حالت انباشت: انباشت مبالغ از آغاز دفتر روزنامه تا پایان ستون (شامل ثبت‌های پیش از تاریخ آغاز گزارش) (پیش‌فرض) \-l \-\-flat حالت فهرست/درخت: نمایش حساب‌ها به صورت فهرست هم‌سطح (پیش‌فرض). مبالغ شامل مبالغ زیرحساب‌ها نمی‌شوند، مگر در جایی که عمق حساب محدود شده باشد. \-t \-\-tree حالت فهرست/درخت: نمایش حساب‌ها به صورت درختی. مبالغ شامل مبالغ زیرحساب‌ها می‌شوند. \-\-drop=N در حالت فهرست، حذف N بخش ابتدایی نام حساب \-\-declared شامل کردن حساب‌های تعریف‌شدهٔ غیروالد (بهترین کاربرد با \-E) \-A \-\-average نمایش یک ستون میانگین سطر (در گزارش‌های چندستونی) \-T \-\-row\-total نمایش یک ستون مجموع سطر (در گزارش‌های چندستونی) \-\-summary\-only تنها نمایش خلاصه‌های سطر (مثلاً مجموع سطر، میانگین) (در گزارش‌های چندستونی) \-N \-\-no\-total حذف سطر مجموع نهایی \-\-no\-elide در حالت درختی، فشرده نکردن حساب‌های والد میانی \-\-format=FORMATSTR استفاده از این قالب خط سفارشی (در گزارش‌های ساده) \-S \-\-sort\-amount مرتب‌سازی بر اساس مبلغ به جای کد/نام حساب \-% \-\-percent بیان مقادیر به صورت درصدی از مجموع هر ستون \-\-layout=ARG چگونگی نمایش مبالغ چندکالایی: \(aqwide[,WIDTH]\(aq: همه کالاها در یک خط \(aqtall\(aq : هر کالا در یک خط جدید \(aqbare\(aq : فقط اعداد، نمادها در یک ستون \-\-base\-url=URLPREFIX در خروجی html، ایجاد ابرپیوندها به hledger\-web با این پیشوند. (معمولاً URL پایهٔ نمایش‌داده‌شده با hledger\-web؛ می‌تواند نسبی نیز باشد.) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt, html, csv, tsv, json. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. پسوند فایلی که با یکی از قالب‌های بالا همخوانی داشته باشد، آن قالب را انتخاب می‌کند. .EE .PP این گزارش حساب‌هایی را نشان می‌دهد که با نوع \f[CR]Asset\f[R]، \f[CR]Cash\f[R]، \f[CR]Liability\f[R] یا \f[CR]Equity\f[R] تعریف شده‌اند (انواع حساب را ببینید). یا اگر چنین حساب‌هایی تعریف نشده باشند، حساب‌های سطح بالایی با نام‌های \f[CR]asset\f[R]، \f[CR]liability\f[R] یا \f[CR]equity\f[R] (بدون حساسیت به حروف کوچک و بزرگ، جمع مجاز است) و زیرحساب‌های آن‌ها را نشان می‌دهد. .PP مثال: .IP .EX $ hledger balancesheetequity Balance Sheet With Equity 2008\-12\-31 || 2008\-12\-31 ====================++============ Assets || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- assets:bank:saving || $1 assets:cash || $\-2 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- || $\-1 ====================++============ Liabilities || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- liabilities:debts || $\-1 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- || $\-1 ====================++============ Equity || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- || 0 ====================++============ Net: || 0 .EE .PP این دستور گونه‌ای سطح‌بالاتر از دستور \f[CR]balance\f[R] است، و از بسیاری از قابلیت‌های آن دستور، مانند گزارش‌های چنددوره‌ای پشتیبانی می‌کند. این دستور مشابه \f[CR]hledger balance \-H assets liabilities equity\f[R] است، اما با تشخیص هوشمندانه‌تر حساب‌ها، و با معکوس کردن علامت بدهی‌ها و سرمایه (liabilities/equity) برای نمایش. .PP این گزارش ساده‌ترین روش برای بررسی برقراری معادله حسابداری (A+L+E = 0) است (پس از آنکه یک \f[CR]close \-\-retain\f[R] برای ادغام درآمدها و هزینه‌ها در سرمایه اجرا کردید، و احتمالاً \f[CR]\-\-infer\-equity\f[R] را برای تراز کردن تبدیل ارزها/کالاهای خود افزودید). .PP این دستور همچنین از گزینه‌های مقصد خروجی و قالب خروجی پشتیبانی می‌کند. قالب‌های خروجی پشتیبانی‌شده عبارت‌اند از: \f[CR]txt\f[R]، \f[CR]csv\f[R]، \f[CR]tsv\f[R]، \f[CR]html\f[R] و \f[CR]json\f[R]..SS cashflow (cf) .PP این دستور یک صورت جریان وجوه نقد (ساده) را نمایش می‌دهد که ورودی‌ها و خروجی‌های مؤثر بر دارایی‌های \(dqنقد\(dq (یعنی دارایی‌های نقدشونده با قابلیت تبدیل آسان) را نشان می‌دهد. مبالغ با علامت مثبت معمول، همانند صورت‌های مالی متداول، نشان داده می‌شوند. .IP .EX گزینه‌ها: \-\-sum حالت محاسبه: نمایش مجموع مبالغ ثبتی (پیش‌فرض) \-\-valuechange حالت محاسبه: نمایش کل تغییر ارزش مانده‌های تاریخی پایان دوره (ناشی از واریزها، برداشت‌ها، نوسانات قیمت بازار) \-\-gain حالت محاسبه: نمایش سود/زیان سرمایه‌ای تحقق‌نیافته (ارزش مانده تاریخی منهای بهای تمام‌شده) \-\-count حالت محاسبه: نمایش تعداد ثبت‌ها \-\-change حالت انباشت: انباشت مبالغ از ابتدای ستون تا انتهای ستون (در گزارش‌های چندستونی) (پیش‌فرض) \-\-cumulative حالت انباشت: انباشت مبالغ از ابتدای گزارش (مشخص‌شده مثلاً توسط \-b/\-\-begin) تا انتهای ستون \-H \-\-historical حالت انباشت: انباشت مبالغ از ابتدای دفتر روزنامه تا انتهای ستون (شامل ثبت‌های پیش از تاریخ شروع گزارش) \-l \-\-flat حالت فهرست/درخت: نمایش حساب‌ها به صورت فهرست مسطح (پیش‌فرض). مبالغ شامل مبالغ زیرحساب‌ها نمی‌شود، مگر در جایی که عمق حساب محدود شده باشد. \-t \-\-tree حالت فهرست/درخت: نمایش حساب‌ها به صورت درختی. مبالغ شامل مبالغ زیرحساب‌ها می‌شود. \-\-drop=N در حالت فهرست، حذف N بخش ابتدایی نام حساب \-\-declared شامل کردن حساب‌های اعلام‌شده غیروالد (بهترین کاربرد همراه با \-E) \-A \-\-average نمایش ستون میانگین ردیف (در گزارش‌های چندستونی) \-T \-\-row\-total نمایش ستون مجموع ردیف (در گزارش‌های چندستونی) \-\-summary\-only تنها نمایش خلاصه ردیف‌ها (مانند مجموع ردیف، میانگین) (در گزارش‌های چندستونی) \-N \-\-no\-total صرف‌نظر از ردیف نهایی مجموع \-\-no\-elide در حالت درختی، عدم ادغام حساب‌های والد بدون تراکنش \-\-format=FORMATSTR استفاده از این قالب سفارشی سطر (در گزارش‌های ساده) \-S \-\-sort\-amount مرتب‌سازی بر اساس مبلغ به جای کد/نام حساب \-% \-\-percent بیان مقادیر به صورت درصدی از مجموع هر ستون \-\-layout=ARG نحوه نمایش مبالغ چندکالایی: \(aqwide[,WIDTH]\(aq: همه کالاها در یک سطر \(aqtall\(aq : هر کالا در یک سطر جدید \(aqbare\(aq : اعداد خام، نمادها در یک ستون \-\-base\-url=URLPREFIX در خروجی html، ایجاد ابرپیوندها به hledger\-web با این پیشوند. (معمولاً نشانی پایه نمایش‌یافته توسط hledger\-web؛ می‌تواند نسبی نیز باشد.) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt, html, csv, tsv, json. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. پسوند فایلی که با یکی از قالب‌های بالا مطابقت داشته باشد آن قالب را انتخاب می‌کند. .EE .PP این گزارش حساب‌های اعلام‌شده با نوع \f[CR]Cash\f[R] را نمایش می‌دهد (انواع حساب را ببینید). یا اگر چنین حساب‌هایی اعلام نشده باشند، حساب‌هایی را نشان می‌دهد که .IP \(bu 2 زیر یک حساب سطح‌بالا به نام \f[CR]asset\f[R] قرار دارند (غیرحساس به حروف بزرگ و کوچک، جمع مجاز است) .IP \(bu 2 نام آن‌ها شامل گونه‌ای از \f[CR]cash\f[R]، \f[CR]bank\f[R]، \f[CR]checking\f[R] یا \f[CR]saving\f[R] باشد. .PP به‌طور دقیق‌تر: تمامی حساب‌هایی که با این عبارت باقاعده غیرحساس به حروف بزرگ و کوچک مطابقت دارند: .PP \f[CR]\(haassets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)\f[R] .PP و زیرحساب‌های آن‌ها. .PP یک نمونه گزارش cashflow: .IP .EX $ hledger cashflow Cashflow Statement 2008 || 2008 ====================++====== Cash flows || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\- assets:bank:saving || $1 assets:cash || $\-2 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\- || $\-1 .EE .PP این دستور گونه‌ای سطح‌بالاتر از دستور \f[CR]balance\f[R] است و از بسیاری از ویژگی‌های آن دستور، مانند گزارش‌های چنددوره‌ای پشتیبانی می‌کند. مشابه با \f[CR]hledger balance assets not:fixed not:investment not:receivable\f[R] است، اما با تشخیص هوشمندانه‌تر حساب‌ها. .PP این دستور همچنین از گزینه‌های مقصد خروجی و قالب خروجی پشتیبانی می‌کند. قالب‌های خروجی پشتیبانی‌شده عبارتند از \f[CR]txt\f[R]، \f[CR]csv\f[R]، \f[CR]tsv\f[R] (\f[I]اضافه‌شده در 1.32\f[R])، \f[CR]html\f[R] و \f[CR]json\f[R]..SS incomestatement (is) .PP نمایش جریان‌های ورودی درآمد و خروجی‌های هزینه در طول دورهٔ گزارش. مبالغ همانند صورت‌های مالی متداول، با علامت مثبتِ عادی نمایش داده می‌شوند. .IP .EX گزینه‌ها: \-\-sum حالت محاسبه: نمایش مجموع مبالغ ثبت‌ها (پیش‌فرض) \-\-valuechange حالت محاسبه: نمایش تغییر کل ارزش موجودی‌های تاریخی پایان دوره (ناشی از واریزها، برداشت‌ها، نوسانات قیمت بازار) \-\-gain حالت محاسبه: نمایش سود/زیان سرمایه‌ای محقق‌نشده (ارزش موجودی تاریخی منهای بهای تمام‌شده) \-\-count حالت محاسبه: نمایش تعداد ثبت‌ها \-\-change حالت انباشت: انباشت مبالغ از ابتدای ستون تا انتهای ستون (در گزارش‌های چندستونی) (پیش‌فرض) \-\-cumulative حالت انباشت: انباشت مبالغ از شروع گزارش (مشخص‌شده مثلاً با \-b/\-\-begin) تا انتهای ستون \-H \-\-historical حالت انباشت: انباشت مبالغ از ابتدای دفتر روزنامه تا انتهای ستون (شامل ثبت‌های پیش از تاریخ شروع گزارش) \-l \-\-flat حالت فهرست/درخت: نمایش حساب‌ها به‌صورت یک فهرست تخت (پیش‌فرض). مبالغ شامل مبالغ زیرحساب‌ها نمی‌شوند، مگر در مواردی که عمق حساب محدود شده باشد. \-t \-\-tree حالت فهرست/درخت: نمایش حساب‌ها به‌صورت یک درخت. مبالغ شامل مبالغ زیرحساب‌ها می‌شوند. \-\-drop=N در حالت فهرست، حذف N بخش ابتدایی از نام حساب \-\-declared شامل حساب‌های تعریف‌شدهٔ غیر والد (بهترین کاربرد همراه با \-E) \-A \-\-average نمایش ستون میانگین سطر (در گزارش‌های چندستونی) \-T \-\-row\-total نمایش ستون مجموع سطر (در گزارش‌های چندستونی) \-\-summary\-only صرفاً نمایش خلاصه‌های سطر (مانند مجموع سطر، میانگین) (در گزارش‌های چندستونی) \-N \-\-no\-total حذف سطر مجموع نهایی \-\-no\-elide در حالت درختی، حساب‌های والد غیرضروری فشرده نشوند \-\-format=FORMATSTR استفاده از این قالب خط سفارشی (در گزارش‌های ساده) \-S \-\-sort\-amount مرتب‌سازی بر اساس مبلغ به‌جای کد/نام حساب \-% \-\-percent بیان مقادیر به‌صورت درصدی از مجموع هر ستون \-\-layout=ARG نحوهٔ نمایش مبالغ چندکالایی: \(aqwide[,WIDTH]\(aq: تمام کالاها در یک خط \(aqtall\(aq : هر کالا در یک خط جدید \(aqbare\(aq : اعداد خالص، نمادها در یک ستون \-\-base\-url=URLPREFIX در خروجی html، تولید ابرپیوندها به hledger\-web با این پیشوند. (معمولاً نشانی وب پایهٔ نمایش‌داده‌شده توسط hledger\-web؛ همچنین می‌تواند نسبی باشد.) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt, html, csv, tsv, json. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. پسوند فایلی که با یکی از قالب‌های بالا همخوانی داشته باشد، آن قالب را انتخاب می‌کند. .EE .PP این دستور صورت سود و زیان را نمایش می‌دهد که درآمدها و هزینه‌ها را در طول یک یا چند دوره نشان می‌دهد. .PP این دستور حساب‌های تعریف‌شده با نوع \f[CR]Revenue\f[R] یا \f[CR]Expense\f[R] را نشان می‌دهد (انواع حساب را ببینید). یا اگر چنین حساب‌هایی تعریف نشده باشند، حساب‌های سطح بالا با نام \f[CR]revenue\f[R]، \f[CR]income\f[R] یا \f[CR]expense\f[R] (غیرحساس به بزرگی و کوچکی حروف، با امکان استفاده از حالت جمع) و زیرحساب‌های آن‌ها را نمایش می‌دهد. .PP مثال: .IP .EX $ hledger incomestatement Income Statement 2008 || 2008 ===================++====== Revenues || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\- income:gifts || $1 income:salary || $1 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\- || $2 ===================++====== Expenses || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\- expenses:food || $1 expenses:supplies || $1 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\- || $2 ===================++====== Net: || 0 .EE .PP این دستور یک نگارش سطح‌بالاتر از دستور \f[CR]balance\f[R] است و از بسیاری از قابلیت‌های آن دستور، مانند گزارش‌های چنددوره‌ای پشتیبانی می‌کند. این دستور شبیه به \f[CR]hledger balance \(aq(revenues|income)\(aq expenses\f[R] است، اما با تشخیص هوشمندانه‌تر حساب‌ها، و نمایش درآمدها با علامت معکوس‌شده. .PP این دستور همچنین از گزینه‌های مقصد خروجی و قالب خروجی پشتیبانی می‌کند. قالب‌های خروجی پشتیبانی‌شده عبارتند از \f[CR]txt\f[R]، \f[CR]csv\f[R]، \f[CR]tsv\f[R] (\f[I]افزوده‌شده در 1.32\f[R])، \f[CR]html\f[R] و \f[CR]json\f[R]..SH "دستورهای گزارش‌گیری پیشرفته (Advanced report commands)" .SS balance (bal) .PP یک گزارش انعطاف‌پذیر و چندمنظوره برای «جمع‌بندی» که حساب‌ها را به همراه نوعی از داده‌های عددی نمایش می‌دهد. این داده‌ها می‌توانند تغییرات تراز در هر دوره، ترازهای پایانی، عملکرد بودجه، سود/زیان محقق‌نشدهٔ سرمایه و غیره باشند. .IP .EX گزینه‌ها: \-\-sum حالت محاسبه: نمایش مجموع مقادیر ثبت‌ها (پیش‌فرض) \-\-valuechange حالت محاسبه: نمایش کل تغییر ارزش ترازهای تاریخی پایان دوره (ناشی از واریزها، برداشت‌ها، نوسانات قیمت بازار) \-\-gain حالت محاسبه: نمایش سود/زیان محقق‌نشدهٔ سرمایه (ارزش تراز تاریخی منهای بهای تمام‌شده) \-\-budget[=DESCPAT] حالت محاسبه: نمایش مجموع مقادیر ثبت‌ها همراه با اهداف بودجه تعیین‌شده با تراکنش‌های دوره‌ای. با آرگومان DESCPAT (باید با = جدا شود نه با فاصله)، تنها از تراکنش‌های دوره‌ای با شرح مطابق استفاده شود (تطابق زیررشته بدون حساسیت به بزرگی و کوچکی حروف). \-\-count حالت محاسبه: نمایش تعداد ثبت‌ها \-\-change حالت تجمیع: انباشت مقادیر از ابتدای ستون تا انتهای ستون (در گزارش‌های چندستونه، پیش‌فرض) \-\-cumulative حالت تجمیع: انباشت مقادیر از آغاز گزارش (تعیین‌شده مثلاً با \-b/\-\-begin) تا انتهای ستون \-H \-\-historical حالت تجمیع: انباشت مقادیر از ابتدای دفتر روزنامه تا انتهای ستون (شامل ثبت‌های پیش از تاریخ آغاز گزارش) \-l \-\-flat حالت فهرست/درخت: نمایش حساب‌ها به صورت فهرستی هم‌سطح (پیش‌فرض). مبالغ شامل مقادیر زیرحساب‌ها نمی‌شوند، مگر در جایی که عمق حساب محدود شده باشد. \-t \-\-tree حالت فهرست/درخت: نمایش حساب‌ها به صورت درختی. مبالغ شامل مقادیر زیرحساب‌ها می‌شوند. \-\-drop=N در حالت فهرست، حذف N بخش ابتدایی نام حساب \-\-declared شامل کردن حساب‌های اظهارشدهٔ غیر والد (بهترین حالت استفاده همراه با \-E) \-A \-\-average نمایش ستون میانگین سطر (در گزارش‌های چندستونه) \-T \-\-row\-total نمایش ستون مجموع سطر (در گزارش‌های چندستونه) \-\-summary\-only تنها نمایش خلاصه‌های سطر (مانند مجموع سطر، میانگین) (در گزارش‌های چندستونه) \-N \-\-no\-total حذف سطر مجموع پایانی \-\-no\-elide در حالت درختی، عدم ادغام حساب‌های والد بدون تغییر \-\-format=FORMATSTR استفاده از این قالب خط سفارشی (در گزارش‌های ساده) \-S \-\-sort\-amount مرتب‌سازی بر اساس مبلغ به جای کد/نام حساب (در حالت هم‌سطح). در صورت چندستونه بودن، بر اساس مجموع سطر یا میانگین سطر (در صورت نمایش) مرتب می‌شود. \-% \-\-percent بیان مقادیر به صورت درصد از کل هر ستون \-r \-\-related نمایش حساب‌های طرف معامله به جای حساب اصلی \-\-invert نمایش تمامی مبالغ با علامت معکوس \-\-transpose جابه‌جایی سطرها و ستون‌ها (استفاده از محور زمان عمودی) \-\-layout=ARG نحوه چیدمان مبالغ چندکالایی و جدول کلی: \(aqwide[,W]\(aq: کالاها در همان خط، حداکثر تا عرض W \(aqtall\(aq : کالاها در خطوط جداگانه \(aqbare\(aq : نمادهای کالا در ستونی جداگانه \(aqtidy\(aq : هر فیلد داده در ستون جداگانهٔ خود \-\-base\-url=URLPREFIX در خروجی html، ایجاد پیوندها به hledger\-web با این پیشوند. (معمولاً نشانی پایهٔ نمایش‌یافته توسط hledger\-web؛ می‌تواند نسبی نیز باشد.) \-O \-\-output\-format=FMT انتخاب قالب خروجی. قالب‌های پشتیبانی‌شده: txt, html, csv, tsv, json, fods. \-o \-\-output\-file=FILE نوشتن خروجی در FILE. پسوند فایلی که با یکی از قالب‌های بالا مطابقت داشته باشد، آن قالب را انتخاب می‌کند. .EE .PP دستور \f[CR]balance\f[R] یکی از قدیمی‌ترین و همه‌کاره‌ترین دستورهای hledger برای فهرست کردن تراز حساب‌ها، تغییرات تراز، ارزش‌ها، تغییرات ارزش و موارد دیگر در طول یک یا چند دورهٔ زمانی است. به طور کلی این دستور جدولی را نشان می‌دهد که سطرهای آن بیانگر حساب‌ها و ستون‌های آن بیانگر دوره‌ها هستند. .PP توجه داشته باشید که چند گونه از دستور \f[CR]balance\f[R] با پیش‌فرض‌های مناسب وجود دارند که استفاده از آن‌ها ساده‌تر است: \f[CR]balancesheet\f[R]، \f[CR]balancesheetequity\f[R]، \f[CR]cashflow\f[R] و \f[CR]incomestatement\f[R]. هنگامی که به کنترل بیشتری نیاز دارید، از \f[CR]balance\f[R] استفاده کنید..SS ویژگی‌های balance در اینجا مروری گذرا بر قابلیت‌های دستور \f[CR]balance\f[R] آمده است و به‌دنبال آن توضیحات و مثال‌های دقیق‌تر ارائه می‌شود. بسیاری از این قابلیت‌ها با سایر دستورهای مشابه balance نیز کار می‌کنند (\f[CR]bs\f[R]، \f[CR]cf\f[R]، \f[CR]is\f[R]..). .PP دستور \f[CR]balance\f[R] می‌تواند نمایش دهد.. .IP \(bu 2 حساب‌ها را به‌صورت فهرست (\f[CR]\-l\f[R]) یا درخت (\f[CR]\-t\f[R]) .IP \(bu 2 اختیاراً با محدودیت عمق (\f[CR]\-[1\-9]\f[R]) .IP \(bu 2 مرتب‌شده بر اساس ترتیب اعلان و نام، یا بر اساس مقدار .PP \&..و.. .IP \(bu 2 تغییرات موجودی آن‌ها را (پیش‌فرض) .IP \(bu 2 یا تغییرات موجودی واقعی و برنامه‌ریزی‌شده (\f[CR]\-\-budget\f[R]) .IP \(bu 2 یا ارزش تغییرات موجودی (\f[CR]\-V\f[R]) .IP \(bu 2 یا تغییر در ارزش موجودی‌ها (\f[CR]\-\-valuechange\f[R]) .IP \(bu 2 یا سود/زیان سرمایه‌ای تحقق‌نیافته (\f[CR]\-\-gain\f[R]) .IP \(bu 2 یا تغییرات موجودی ناشی از ثبت‌های همتا (\f[CR]\-\-related\f[R]/\f[CR]\-r\f[R]) .IP \(bu 2 یا تعداد ثبت‌ها (\f[CR]\-\-count\f[R]) .PP \&..در.. .IP \(bu 2 یک دوره زمانی (به‌طور پیش‌فرض کل دوره دفتر روزنامه) .IP \(bu 2 یا دوره‌های چندگانه (\f[CR]\-D\f[R]، \f[CR]\-W\f[R]، \f[CR]\-M\f[R]، \f[CR]\-Q\f[R]، \f[CR]\-Y\f[R]، \f[CR]\-p INTERVAL\f[R]) .PP \&..خواه.. .IP \(bu 2 به‌ازای هر دوره (پیش‌فرض) .IP \(bu 2 یا انباشته‌شده از تاریخ شروع گزارش (\f[CR]\-\-cumulative\f[R]) .IP \(bu 2 یا انباشته‌شده از زمان ایجاد حساب (\f[CR]\-\-historical/\-H\f[R]) .PP \&..احتمالاً تبدیل‌شده به.. .IP \(bu 2 بهای تمام‌شده (\f[CR]\-\-value=cost[,COMM]\f[R]/\f[CR]\-\-cost\f[R]/\f[CR]\-B\f[R]) .IP \(bu 2 یا ارزش بازار، در تاریخ تراکنش‌ها (\f[CR]\-\-value=then[,COMM]\f[R]) .IP \(bu 2 یا در پایان دوره‌ها (\f[CR]\-\-value=end[,COMM]\f[R]) .IP \(bu 2 یا در زمان حال (\f[CR]\-\-value=now\f[R]) .IP \(bu 2 یا در تاریخی دیگر (\f[CR]\-\-value=YYYY\-MM\-DD\f[R]) .PP \&..همراه با.. .IP \(bu 2 مجموع‌ها (\f[CR]\-T\f[R])، میانگین‌ها (\f[CR]\-A\f[R])، درصدها (\f[CR]\-%\f[R])، علامت معکوس (\f[CR]\-\-invert\f[R]) .IP \(bu 2 سطرها و ستون‌های جابه‌جاشده (\f[CR]\-\-transpose\f[R]) .IP \(bu 2 استفاده از فیلدی دیگر به‌عنوان نام حساب (\f[CR]\-\-pivot\f[R]) .IP \(bu 2 ردیف‌های قالب‌بندی‌شده به‌صورت سفارشی (تنها در گزارش‌های تک‌دوره‌ای) (\f[CR]\-\-format\f[R]) .IP \(bu 2 کالاهای نمایش‌یافته در یک سطر یا چندین سطر (\f[CR]\-\-layout\f[R]) .PP این دستور از گزینه‌های مقصد خروجی و قالب خروجی پشتیبانی می‌کند، با قالب‌های خروجی \f[CR]txt\f[R]، \f[CR]csv\f[R]، \f[CR]tsv\f[R] (\f[I]اضافه‌شده در 1.32\f[R])، \f[CR]json\f[R]، و (تنها در گزارش‌های چنددوره‌ای:) \f[CR]html\f[R]، \f[CR]fods\f[R] (\f[I]اضافه‌شده در 1.40\f[R]). در خروجی \f[CR]txt\f[R] در پایانه‌های با قابلیت پشتیبانی از رنگ، مقادیر منفی با رنگ قرمز نمایش داده می‌شوند..SS "گزارش تراز ساده (Simple balance report)" بدون هیچ آرگومانی، \f[CR]balance\f[R] فهرستی از همهٔ حساب‌ها و تغییرات تراز آن‌ها را نشان می‌دهد \- یعنی مجموع مبالغ ثبت‌شده، هم ورودی‌ها و هم خروجی‌ها \- در تمام طول دورهٔ دفتر روزنامه. (منظور از \(dqساده\(dq در اینجا تنها یک ستون از اعداد است که یک دورهٔ منفرد را پوشش می‌دهد. همچنین می‌توانید گزارش‌های چنددوره‌ای داشته باشید که جلوتر شرح داده شده‌اند.) .PP برای حساب‌های دنیای واقعی، این اعداد معمولاً تراز پایانی آن‌ها در پایان دورهٔ دفتر روزنامه خواهند بود؛ در این باره در ادامه بیشتر توضیح داده می‌شود. .PP حساب‌ها بر اساس ترتیب تعریف (در صورت وجود) و سپس بر اساس الفبا طبق نام حساب مرتب می‌شوند. به عنوان نمونه (با استفاده از examples/sample.journal): .IP .EX $ hledger \-f examples/sample.journal bal $1 assets:bank:saving $\-2 assets:cash $1 expenses:food $1 expenses:supplies $\-1 income:gifts $\-1 income:salary $1 liabilities:debts \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP حساب‌های با تراز صفر (و بدون زیرحساب‌های غیرصفر، در حالت درختی \- زیر را ببینید) به‌طور پیش‌فرض پنهان هستند. برای نمایش آن‌ها از \f[CR]\-E/\-\-empty\f[R] استفاده کنید (که در اینجا \f[CR]assets:bank:checking\f[R] را آشکار می‌کند): .IP .EX $ hledger \-f examples/sample.journal bal \-E 0 assets:bank:checking $1 assets:bank:saving $\-2 assets:cash $1 expenses:food $1 expenses:supplies $\-1 income:gifts $\-1 income:salary $1 liabilities:debts \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP مجموع مقادیر نشان‌داده‌شده در آخرین خط نمایش داده می‌شود، مگر آنکه از \f[CR]\-N\f[R]/\f[CR]\-\-no\-total\f[R] استفاده شده باشد. .SS "قالب خط گزارش تراز (Balance report line format)" برای گزارش‌های تراز تک‌دوره‌ای که در ترمینال نمایش داده می‌شوند (فقط)، می‌توانید از \f[CR]\-\-format FMT\f[R] برای سفارشی‌سازی قالب و محتوای هر خط استفاده کنید. برای نمونه: .IP .EX $ hledger \-f examples/sample.journal balance \-\-format \(dq%20(account) %12(total)\(dq assets $\-1 bank:saving $1 cash $\-2 expenses $2 food $1 supplies $1 income $\-2 gifts $\-1 salary $\-1 liabilities:debts $1 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP رشتهٔ قالب FMT قالب‌بندی اعمال‌شده روی هر جفت حساب/تراز را مشخص می‌کند. این رشته می‌تواند شامل هر متن مناسبی باشد، به‌طوری که فیلدهای داده به این صورت درون آن جای‌گذاری می‌شوند: .PP \f[CR]%[MIN][.MAX](FIELDNAME)\f[R] .IP \(bu 2 مقدار MIN حداقل تا این پهنا با فاصله پر می‌کند (اختیاری) .IP \(bu 2 مقدار MAX در این پهنا برش می‌زند (اختیاری) .IP \(bu 2 مقدار FIELDNAME باید در پرانتز قرار گیرد و می‌تواند یکی از موارد زیر باشد: .RS 2 .IP \(bu 2 \f[CR]depth_spacer\f[R] \- تعدادی فاصله برابر با عمق حساب، یا در صورت تعیین شدن MIN، برابر با MIN * عمق، فاصله قرار می‌دهد. .IP \(bu 2 \f[CR]account\f[R] \- نام حساب .IP \(bu 2 \f[CR]total\f[R] \- تراز/مجموع ثبت‌شدهٔ حساب، راست‌چین‌شده .RE .PP همچنین، FMT می‌تواند با یک پیشوند اختیاری برای کنترل نحوهٔ رندر مبالغ چندکالایی (multi\-commodity) شروع شود: .IP \(bu 2 \f[CR]%_\f[R] \- رندر در چندین خط، تراز از پایین (پیش‌فرض) .IP \(bu 2 \f[CR]%\(ha\f[R] \- رندر در چندین خط، تراز از بالا .IP \(bu 2 \f[CR]%,\f[R] \- رندر در یک خط، با جداکنندهٔ ویرگول .PP برخی رفتارهای خاص وجود دارد. برای نمونه در حالت تک‌خطی، \f[CR]%(depth_spacer)\f[R] هیچ تأثیری ندارد، در عوض \f[CR]%(account)\f[R] دارای تورفتگی توکار است. \ ممکن است برای رسیدن به نتایج مطلوب به آزمون و خطا نیاز باشد. .PP چند قالب نمونه: .IP \(bu 2 \f[CR]%(total)\f[R] \- مجموع حساب .IP \(bu 2 \f[CR]%\-20.20(account)\f[R] \- نام حساب، چپ‌چین‌شده، پرشده با فاصله تا ۲۰ نویسه و برش‌خورده در ۲۰ نویسه .IP \(bu 2 \f[CR]%,%\-50(account) %25(total)\f[R] \- نام حساب پرشده با فاصله تا ۵۰ نویسه، مجموع پرشده تا ۲۰ نویسه، همراه با رندر چندکالایی در یک خط .IP \(bu 2 \f[CR]%20(total) %2(depth_spacer)%\-(account)\f[R] \- قالب پیش‌فرض برای گزارش تراز تک‌ستونی.SS گزارش تراز فیلترشده می‌توانید با استفاده از آرگومان‌های پرس‌وجو (query) یا گزینه‌ها برای محدود کردن ثبت‌های (postings) مورد تطبیق، حساب‌های کمتری را نمایش دهید، بازه زمانی متفاوتی را بررسی کنید، مجموع‌ها را فقط از تراکنش‌های تسویه‌شده (cleared) نمایش دهید و غیره. برای مثال: .IP .EX $ hledger \-f examples/sample.journal bal \-\-cleared assets date:200806 $\-2 assets:cash \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- $\-2 .EE .SS حالت فهرستی یا درختی به‌طور پیش‌فرض، یا با استفاده از \f[CR]\-l/\-\-flat\f[R]، حساب‌ها همانند مثال‌های بالا به صورت یک فهرست تخت و با نمایش نام کاملشان ارائه می‌شوند. .PP با گزینهٔ \f[CR]\-t/\-\-tree\f[R]، سلسله‌مراتب حساب‌ها نمایش داده می‌شود، به طوری که نام‌های \(dqبرگ\(dq (انتهایی) زیرحساب‌ها با تورفتگی در زیر حساب والد خود قرار می‌گیرند: .IP .EX $ hledger \-f examples/sample.journal balance $\-1 assets $1 bank:saving $\-2 cash $2 expenses $1 food $1 supplies $\-2 income $\-1 gifts $\-1 salary $1 liabilities:debts \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP نکات: .IP \(bu 2 حساب‌های \(dqکسل‌کننده\(dq (boring) برای خروجی فشرده‌تر با زیرحساب خود ادغام می‌شوند، مگر اینکه از \f[CR]\-\-no\-elide\f[R] استفاده شود. حساب‌های کسل‌کننده خودشان ترازی ندارند و تنها دارای یک زیرحساب هستند (مانند \f[CR]assets:bank\f[R] و \f[CR]liabilities\f[R] در بالا). .IP \(bu 2 تمامی ترازهای نمایش داده‌شده \(dqجامع\(dq (inclusive) هستند، یعنی شامل ترازهای همهٔ زیرحساب‌ها نیز می‌شوند. توجه داشته باشید که این امر موجب مقداری تکرار در خروجی می‌شود، که هنگام به‌اشتراک‌گذاری گزارش‌ها با کاربرانی که با سیستم حسابداری متن‌ساده (plaintext accounting) آشنایی ندارند نیازمند توضیح است. مجموع نهایی گزارش در حالت درختی، حاصل‌جمع ترازهای سطح بالا است، نه جمع تمامی ترازهای نشان‌داده‌شده. .IP \(bu 2 هر گروه از حساب‌های هم‌سطح (هم‌نیا، یعنی تحت یک والد مشترک) به‌طور جداگانه مرتب می‌شوند. .SS محدود کردن عمق با پرس‌وجوی \f[CR]depth:NUM\f[R]، گزینهٔ \f[CR]\-\-depth NUM\f[R]، یا صرفاً \f[CR]\-NUM\f[R] (مانند: \f[CR]\-3\f[R])، گزارش‌های تراز حساب‌ها را فقط تا عمق تعیین‌شده نمایش می‌دهند و زیرحساب‌های عمیق‌تر را پنهان می‌کنند. این قابلیت برای دریافت یک دید کلی بدون جزئیات بیش‌ازحد مفید است. .PP تراز حساب‌ها در حد عمق تعیین‌شده، همواره شامل ترازهای زیرحساب‌های عمیق‌تر است (حتی در حالت فهرستی). برای مثال، محدود کردن به عمق ۱: .IP .EX $ hledger \-f examples/sample.journal balance \-1 $\-1 assets $2 expenses $\-2 income $1 liabilities \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .SS حذف سطوح بالایی حساب‌ها همچنین می‌توانید با استفاده از \f[CR]\-\-drop NUM\f[R]، یک یا چند بخش از نام حساب‌های سطح بالا را پنهان کنید. این قابلیت می‌تواند برای پنهان کردن نام‌های تکراری حساب‌های سطح بالا مفید باشد: .IP .EX $ hledger \-f examples/sample.journal bal expenses \-\-drop 1 $1 food $1 supplies \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- $2 .EE .PP.SS نمایش حساب‌های اعلان‌شده با \f[CR]\-\-declared\f[R]، حساب‌هایی که با دستورالعمل account اعلان شده‌اند، حتی در صورت نداشتن تراکنش، در گزارش تراز گنجانده می‌شوند. (از آنجا که این حساب‌ها تراز صفر خواهند داشت، برای مشاهدهٔ آن‌ها به \f[CR]\-E/\-\-empty\f[R] نیز نیاز خواهید داشت.) .PP به‌طور دقیق‌تر، حساب‌های اعلان‌شدهٔ \f[I]برگ\f[R] (leaf \- بدون زیرحساب) گنجانده خواهند شد، چرا که این حساب‌ها معمولاً در گزارش‌ها کاربردی‌تر هستند. .PP هدف از این قابلیت، امکان مشاهدهٔ یک گزارش تراز \(dqکامل\(dq و مفید است، حتی زمانی که هنوز در تمام حساب‌های اعلان‌شدهٔ خود تراکنشی ثبت نکرده‌اید. .SS مرتب‌سازی بر اساس مقدار با \f[CR]\-S/\-\-sort\-amount\f[R]، حساب‌های دارای بیشترین (مثبت‌ترین) تراز در ابتدا نمایش داده می‌شوند. برای مثال: \f[CR]hledger bal expenses \-MAS\f[R] بیشترین میانگین هزینه‌های ماهانهٔ شما را اول نشان می‌دهد. هنگامی که بیش از یک کالا (commodity) وجود داشته باشد، ابتدا بر اساس کالایی که از نظر الفبایی زودتر می‌آید مرتب می‌شوند، و سپس بر اساس کالاهای بعدی (اگر مقداری فاقد کالا باشد، به عنوان 0 در نظر گرفته می‌شود). .PP با این حال، ترازهای درآمد و بدهی معمولاً منفی هستند، بنابراین \f[CR]\-S\f[R] این موارد را به ترتیب معکوس نشان می‌دهد. برای رفع این مشکل، می‌توانید \f[CR]\-\-invert\f[R] را برای معکوس کردن علامت‌ها اضافه کنید. یا می‌توانید از یکی از گزارش‌های تراز سطح بالاتر (\f[CR]bs\f[R]، \f[CR]is\f[R]..) استفاده کنید که علامت را به‌طور خودکار معکوس می‌کنند (مانند: \f[CR]hledger is \-MAS\f[R]). .PP .SS درصدها با \f[CR]\-%/\-\-percent\f[R]، گزارش‌های تراز ارزش هر حساب را به صورت درصدی از مجموع (ستون) نشان می‌دهند. .PP توجه داشته باشید که اگر مقادیر موجود در یک ستون دارای علامت‌های مختلف باشند، محاسبهٔ درصدها مفید نخواهد بود. در این حالت، برای هر علامت یک گزارش جداگانه تهیه کنید؛ به عنوان مثال: .IP .EX $ hledger bal \-% amt:\(ga>0\(ga $ hledger bal \-% amt:\(ga<0\(ga .EE .PP به‌طور مشابه، اگر مقادیر موجود در یک ستون شامل کالاهای متعددی باشند، آن‌ها را با \f[CR]\-B\f[R]، \f[CR]\-V\f[R]، \f[CR]\-X\f[R] یا \f[CR]\-\-value\f[R] به یک کالا تبدیل کنید، یا برای هر کالا یک گزارش جداگانه تهیه نمایید: .IP .EX $ hledger bal \-% cur:\(rs\(rs$ $ hledger bal \-% cur:€ .EE .SS گزارش تراز چنددوره‌ای با تعیین یک بازهٔ گزارش (توسط پرچم‌های \f[CR]\-D/\-\-daily\f[R]، \f[CR]\-W/\-\-weekly\f[R]، \f[CR]\-M/\-\-monthly\f[R]، \f[CR]\-Q/\-\-quarterly\f[R]، \f[CR]\-Y/\-\-yearly\f[R]، یا \f[CR]\-p/\-\-period\f[R])، دستور \f[CR]balance\f[R] گزارشی جدول‌بندی‌شده نمایش می‌دهد که ستون‌های آن نشان‌دهندهٔ دوره‌های زمانی پیاپی هستند (به همراه عنوان): .IP .EX $ hledger \-f examples/sample.journal bal \-\-quarterly income expenses \-E Balance changes in 2008: || 2008q1 2008q2 2008q3 2008q4 ===================++================================= expenses:food || 0 $1 0 0 expenses:supplies || 0 $1 0 0 income:gifts || 0 $\-1 0 0 income:salary || $\-1 0 0 0 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || $\-1 $1 0 0 .EE .PP نکات: .IP \(bu 2 تاریخ‌های شروع/پایان گزارش در صورت لزوم گسترش می‌یابند تا زیردوره‌های نمایش‌داده‌شده را به‌طور کامل در بر بگیرند (تا اولین و آخرین زیردوره مدت زمانی برابر با سایر دوره‌ها داشته باشند). .IP \(bu 2 دوره‌های (ستون‌های) ابتدایی و انتهایی که تماماً حاوی مقادیر صفر هستند، نمایش داده نمی‌شوند مگر اینکه از \f[CR]\-E/\-\-empty\f[R] استفاده شود. .IP \(bu 2 حساب‌های (سطرهای) تماماً حاوی صفر نمایش داده نمی‌شوند مگر اینکه از \f[CR]\-E/\-\-empty\f[R] استفاده شود. .IP \(bu 2 مقادیر دارای کالاهای گوناگون به‌شکل کوتاه و خلاصه نمایش داده می‌شوند، مگر اینکه از \f[CR]\-\-no\-elide\f[R] استفاده شود. .IP \(bu 2 ستون‌های میانگین و/یا مجموع را می‌توان با پرچم‌های \f[CR]\-A/\-\-average\f[R] و \f[CR]\-T/\-\-row\-total\f[R] اضافه کرد. .IP \(bu 2 از پرچم \f[CR]\-\-transpose\f[R] می‌توان برای جابه‌جایی سطرها و ستون‌ها استفاده کرد. .IP \(bu 2 گزینهٔ \f[CR]\-\-pivot FIELD\f[R] باعث می‌شود یک فیلد تراکنش دیگر به عنوان \(dqنام حساب\(dq استفاده شود. بخش PIVOTING را ببینید. .IP \(bu 2 پرچم \f[CR]\-\-summary\-only\f[R] (\f[CR]\-\-summary\f[R] نیز کار می‌کند) تمام ستون‌ها را به‌جز ستون‌های Total و Average پنهان می‌کند (این ستون‌ها باید با \f[CR]\-\-row\-total\f[R] و \f[CR]\-A/\-\-average\f[R] فعال شوند). .PP گزارش‌های چنددوره‌ای با دوره‌های زیاد ممکن است بیش از حد عریض باشند و به راحتی در ترمینال دیده نشوند. در ادامه روش‌هایی برای رفع این مشکل آمده است: .IP \(bu 2 پنهان کردن سطر مجموع با \f[CR]\-N/\-\-no\-total\f[R] .IP \(bu 2 فیلتر کردن روی یک ارز خاص با \f[CR]cur:\f[R] .IP \(bu 2 تبدیل به یک ارز واحد با \f[CR]\-V [\-\-infer\-market\-price]\f[R] .IP \(bu 2 استفاده از طرح‌بندی فشرده‌تر مانند \f[CR]\-\-layout=bare\f[R] .IP \(bu 2 بزرگ‌نمایی پنجرهٔ ترمینال (Maximize) .IP \(bu 2 کاهش اندازهٔ قلم ترمینال .IP \(bu 2 مشاهده از طریق یک صفحه‌بند مانند less؛ برای نمونه: \f[CR]hledger bal \-D \-\-color=yes | less \-RS\f[R] .IP \(bu 2 خروجی گرفتن به صورت CSV و استفاده از یک نمایش‌دهندهٔ CSV مانند visidata (\f[CR]hledger bal \-D \-O csv | vd \-f csv\f[R])، حالت csv\-mode ایمکس (\f[CR]M\-x csv\-mode, C\-c C\-a\f[R])، یا یک نرم‌افزار صفحه‌گسترده (\f[CR]hledger bal \-D \-o a.csv && open a.csv\f[R]) .IP \(bu 2 خروجی گرفتن به فرمت HTML و مشاهده با مرورگر: \f[CR]hledger bal \-D \-o a.html && open a.html\f[R].SS تغییر مانده، مانده پایانی (Balance change, end balance) درک دقیق مفهوم اعداد نمایش‌داده‌شده در گزارش‌های balance بسیار مهم است. در اینجا اصطلاحاتی که استفاده می‌کنیم آورده شده است: .PP یک \f[B]\f[BI]تغییر مانده (balance change)\f[B]\f[R] عبارت است از مقدار خالصی که در طول یک دوره مشخص به یک حساب اضافه یا از آن کسر شده است. .PP یک \f[B]\f[BI]مانده پایانی (end balance)\f[B]\f[R] مقدار انباشته‌شده در یک حساب تا یک تاریخ مشخص است (و زمانی معین، اما hledger آن را ذخیره نمی‌کند؛ پایان روز را در منطقه زمانی خود فرض کنید). این مقدار مجموع تغییرات قبلی مانده است. .PP اگر این مقدار شامل تمام تغییرات مانده از زمان ایجاد حساب باشد، آن را \f[B]\f[BI]مانده پایانی تاریخی (historical end balance)\f[B]\f[R] می‌نامیم. برای یک حساب در دنیای واقعی، این بدان معناست که با «سوابق تاریخی» مطابقت خواهد داشت، مانند مانده‌های گزارش‌شده در صورت‌حساب‌های بانکی یا رابط وب بانک شما. (اگر درست باشند!) .PP به‌طور کلی، تغییرات مانده همان چیزی است که هنگام بررسی درآمدها و هزینه‌ها می‌خواهید ببینید، و مانده‌های پایانی تاریخی مواردی هستند که می‌خواهید هنگام بررسی یا تطبیق حساب‌های دارایی، بدهی و سرمایه مشاهده کنید. .PP دستور \f[CR]balance\f[R] به‌طور پیش‌فرض تغییرات مانده را نشان می‌دهد. برای مشاهده مانده‌های پایانی تاریخی دقیق: .IP "1." 3 مانده‌های اولیه حساب را با یک تراکنش «مانده‌های افتتاحیه» (opening balances) مقداردهی اولیه کنید (انتقال از سرمایه به حساب)، مگر اینکه دفتر روزنامه کل طول عمر حساب را پوشش دهد. .IP "2." 3 با مشخص نکردن تاریخ شروع گزارش، یا با استفاده از پرچم \f[CR]\-H/\-\-historical\f[R]، تمام ثبت‌های پیشین حساب را در گزارش بگنجانید. (\f[CR]\-H\f[R] باعث می‌شود هنگام جمع بستن ثبت‌ها، تاریخ شروع گزارش نادیده گرفته شود.) .SS حالت‌های گزارش تراز (Balance report modes) دستور balance کاملاً انعطاف‌پذیر است؛ در اینجا جزئیات کامل نحوه کنترل آنچه گزارش می‌دهد آورده شده است. اگر موارد زیر پیچیده به نظر می‌رسند، نگران نباشید \- این بخش برای گزارش‌گیری پیشرفته است، و آشنایی با تمام حالت‌های گزارش نیازمند زمان و آزمایش است. .PP سه گروه گزینه مهم وجود دارد: .PP \f[CR]hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ...\f[R] .SS حالت محاسبه (Calculation mode) محاسبه پایه‌ای که باید برای هر سلول جدول انجام شود. یکی از موارد زیر است: .IP \(bu 2 \f[CR]\-\-sum\f[R] : جمع بستن مقادیر ثبت‌ها (\f[B]پیش‌فرض\f[R]) .IP \(bu 2 \f[CR]\-\-budget\f[R] : جمع بستن مقادیر، و همچنین نمایش مقدار هدف بودجه (برای هر حساب/دوره) .IP \(bu 2 \f[CR]\-\-valuechange\f[R] : نمایش تغییر در ارزش مانده‌های تاریخی پایان دوره (ناشی از واریزها، برداشت‌ها و/یا نوسانات قیمت بازار) .IP \(bu 2 \f[CR]\-\-gain\f[R] : نمایش سود/زیان سرمایه‌ای تحقق‌نیافته، (مانده ارزش‌گذاری‌شده فعلی منهای بهای تمام‌شده اولیه هر مقدار) .IP \(bu 2 \f[CR]\-\-count\f[R] : نمایش تعداد ثبت‌ها .SS حالت انباشت (Accumulation mode) نحوه انباشته شدن مقادیر در زیردوره‌ها/ستون‌های یک گزارش. به بیان دیگر: ثبت‌های کدام دوره زمانی باید در محاسبه هر سلول مشارکت داشته باشند. یکی از موارد زیر است: .IP \(bu 2 \f[CR]\-\-change\f[R] : محاسبه با ثبت‌ها از شروع ستون تا پایان ستون، یعنی «فقط همین ستون». معمولاً برای مشاهده درآمدها/هزینه‌ها استفاده می‌شود. (\f[B]پیش‌فرض برای balance،‏ cashflow،‏ incomestatement\f[R]) .IP \(bu 2 \f[CR]\-\-cumulative\f[R] : محاسبه با ثبت‌ها از شروع گزارش تا پایان ستون، یعنی «ستون‌های قبلی به علاوه این ستون». معمولاً برای نشان دادن تغییرات انباشته‌شده از تاریخ شروع گزارش استفاده می‌شود. چندان پرکاربرد نیست. .IP \(bu 2 \f[CR]\-\-historical/\-H\f[R] : محاسبه با ثبت‌ها از شروع دفتر روزنامه تا پایان ستون، یعنی «تمام ثبت‌ها از قبل از تاریخ شروع گزارش تا پایان این ستون». معمولاً برای مشاهده مانده‌های پایانی تاریخیِ دارایی‌ها/بدهی‌ها/سرمایه استفاده می‌شود. (\f[B]پیش‌فرض برای balancesheet،‏ balancesheetequity\f[R]).SS حالت ارزش‌گذاری (Valuation mode) مشخص می‌کند که در صورت نیاز، چه نوع تبدیل ارزش یا بهایی باید پیش از نمایش گزارش اعمال شود. برای اطلاعات بیشتر دربارهٔ تبدیل‌ها، بخش‌های «Cost reporting» و «Value reporting» را ببینید. .PP حالت ارزش‌گذاری (یا بها) را می‌توان با گزینهٔ \f[CR]\-\-value\f[R] انتخاب کرد: .IP \(bu 2 بدون تبدیل : به بها یا ارزش تبدیل نمی‌شود (\f[B]پیش‌فرض\f[R]) .IP \(bu 2 \f[CR]\-\-value=cost[,COMM]\f[R] : تبدیل مقادیر به بها (سپس در صورت تمایل به کالایی دیگر) .IP \(bu 2 \f[CR]\-\-value=then[,COMM]\f[R] : تبدیل مقادیر به ارزش بازار در تاریخ‌های تراکنش .IP \(bu 2 \f[CR]\-\-value=end[,COMM]\f[R] : تبدیل مقادیر به ارزش بازار در تاریخ(های) پایان دوره .PD 0 .P .PD (\f[B]پیش‌فرض همراه با \f[CB]\-\-valuechange\f[B]، \f[CB]\-\-gain\f[B]\f[R]) .IP \(bu 2 \f[CR]\-\-value=now[,COMM]\f[R] : تبدیل مقادیر به ارزش بازار در تاریخ امروز .IP \(bu 2 \f[CR]\-\-value=YYYY\-MM\-DD[,COMM]\f[R] : تبدیل مقادیر به ارزش بازار در تاریخی دیگر .PP یا با گزینه‌های موروثی \-B/\-V/\-X که معادل بوده و تایپ کردن آن‌ها آسان‌تر است: .IP \(bu 2 \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R] : مانند \-\-value=cost .IP \(bu 2 \f[CR]\-V\f[R]/\f[CR]\-\-market\f[R] : مانند \-\-value=end .IP \(bu 2 \f[CR]\-X COMM\f[R]/\f[CR]\-\-exchange COMM\f[R] : مانند \-\-value=end,COMM .PP توجه داشته باشید که گزینهٔ \-\-value برای راحتی کار می‌تواند به بها نیز تبدیل کند؛ اما در واقع \-\-cost و \-\-value گزینه‌های مستقلی هستند و می‌توانند با یکدیگر استفاده شوند. .SS ترکیب حالت‌های گزارش تراز (Combining balance report modes) بیشتر ترکیب‌های این حالت‌ها باید گزارش‌های معقولی تولید کنند، اما اگر موردی یافتید که نادرست یا گمراه‌کننده به نظر می‌رسد، به ما اطلاع دهید. محدودیت‌های زیر اعمال می‌شوند: .IP \(bu 2 \f[CR]\-\-valuechange\f[R] مستلزم \f[CR]\-\-value=end\f[R] است .IP \(bu 2 \f[CR]\-\-valuechange\f[R] هنگام استفاده با دستورهای \f[CR]balancesheet\f[R]/\f[CR]balancesheetequity\f[R]، گزینهٔ \f[CR]\-\-change\f[R] را پیش‌فرض قرار می‌دهد .IP \(bu 2 \f[CR]\-\-cumulative\f[R] یا \f[CR]\-\-historical\f[R] گزینهٔ \f[CR]\-\-row\-total/\-T\f[R] را غیرفعال می‌کنند .PP جهت اطلاع، آنچه ترکیب‌های انباشت و ارزش‌گذاری نشان می‌دهند در اینجا آمده است: .PP .TS tab(@); lw(7.9n) lw(16.4n) lw(16.9n) lw(15.1n) lw(13.7n). T{ ارزش‌گذاری:> انباشت:v T}@T{ بدون ارزش‌گذاری T}@T{ \f[CR]\-\-value= then\f[R] T}@T{ \f[CR]\-\-value= end\f[R] T}@T{ \f[CR]\-\-value= YYYY\-MM\-DD /now\f[R] T} _ T{ \f[CR]\-\-change\f[R] T}@T{ تغییرات در دوره T}@T{ مجموع ارزش بازار در تاریخ‌های ثبت در دوره T}@T{ ارزش تغییرات دوره در پایان دوره T}@T{ ارزش تغییرات دوره در DATE T} T{ \f[CR]\-\-cumulative\f[R] T}@T{ تغییرات از آغاز گزارش تا پایان دوره T}@T{ مجموع ارزش بازار در تاریخ‌های ثبت از آغاز گزارش تا پایان دوره T}@T{ ارزش تغییرات از آغاز گزارش تا پایان دوره در پایان دوره T}@T{ ارزش تغییرات از آغاز گزارش تا پایان دوره در DATE T} T{ \f[CR]\-\-historical /\-H\f[R] T}@T{ تغییرات از آغاز دفتر روزنامه تا پایان دوره (ماندهٔ نهایی تاریخی) T}@T{ مجموع ارزش بازار در تاریخ‌های ثبت از آغاز دفتر روزنامه تا پایان دوره T}@T{ ارزش تغییرات از آغاز دفتر روزنامه تا پایان دوره در پایان دوره T}@T{ ارزش تغییرات از آغاز دفتر روزنامه تا پایان دوره در DATE T} .TE.SS گزارش بودجه (Budget report) گزارش \f[CR]\-\-budget\f[R] شبیه به یک گزارش تراز معمولی است، اما با دو تفاوت اصلی: .IP \(bu 2 اهداف بودجه و درصدهای عملکرد نیز درون کروشه نمایش داده می‌شوند .IP \(bu 2 حساب‌هایی که هدف بودجه ندارند، به‌طور پیش‌فرض پنهان می‌شوند. .PP این ویژگی برای مقایسهٔ درآمدها، هزینه‌ها، میزان مصرف زمان و موارد دیگر، بین مقادیر برنامه‌ریزی‌شده و واقعی مفید است. .PP از قوانین تراکنش‌های دوره‌ای برای تعریف اهداف بودجه استفاده می‌شود. به‌عنوان مثال، در اینجا یک قانون دوره‌ای آورده شده است که اهداف ماهانه را برای هزینه‌های اتوبوس و غذا تعیین می‌کند: .IP .EX ;; Budget \(ti monthly (expenses:bus) $30 (expenses:food) $400 .EE .PP پس از ثبت چند هزینهٔ واقعی، .IP .EX ;; Two months worth of expenses 2017\-11\-01 income $\-1950 expenses:bus $35 expenses:food:groceries $310 expenses:food:dining $42 expenses:movies $38 assets:bank:checking 2017\-12\-01 income $\-2100 expenses:bus $53 expenses:food:groceries $380 expenses:food:dining $32 expenses:gifts $100 assets:bank:checking .EE .PP می‌توانیم گزارش بودجه‌ای مانند این را ببینیم: .IP .EX $ hledger bal \-M \-\-budget Budget performance in 2017\-11\-01..2017\-12\-31: || Nov Dec ===============++============================================ || $\-425 $\-565 expenses || $425 [ 99% of $430] $565 [131% of $430] expenses:bus || $35 [117% of $30] $53 [177% of $30] expenses:food || $352 [ 88% of $400] $412 [103% of $400] \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || 0 [ 0% of $430] 0 [ 0% of $430] .EE .PP این روش «بودجه‌بندی مبتنی بر هدف» (\(dqgoal\-based budgeting\(dq) نامیده می‌شود؛ شما اهدافی را برای حساب‌ها و دوره‌ها، اغلب به‌صورت تکرارشونده، تعیین می‌کنید و hledger عملکرد را نسبت به این اهداف نشان می‌دهد. این در مقایسه با «بودجه‌بندی پاکتی» (\(dqenvelope budgeting\(dq) است که جزئی‌تر و سخت‌گیرانه‌تر بوده و در زمان محدود بودن نقدینگی کارآمد است، اما زحمت بسیار بیشتری دارد. در https://plaintextaccounting.org/Budgeting اطلاعات بیشتری پیرامون این موضوع وجود دارد. .SS استفاده از گزارش بودجه (Using the budget report) از گذشته این گزارش گیج‌کننده و ناپایدار بوده است. نسخهٔ hledger باید نسبتاً پایدار و قابل درک باشد، اما ممکن است همچنان با موارد پیش‌بینی‌نشده‌ای مواجه شوید. در ادامه نکات بیشتری برای کمک به یادگیری و عیب‌یابی آورده شده است. .IP \(bu 2 در مثال بالا، \f[CR]expenses:bus\f[R] و \f[CR]expenses:food\f[R] نشان داده شده‌اند زیرا در طول دورهٔ گزارش دارای اهداف بودجه هستند. .IP \(bu 2 حساب والد آن‌ها یعنی \f[CR]expenses\f[R] نیز نشان داده شده است، همراه با اهداف بودجه‌ای که از حساب‌های فرزند تجمیع شده‌اند. .IP \(bu 2 زیرحساب‌های \f[CR]expenses:food:groceries\f[R] و \f[CR]expenses:food:dining\f[R] نمایش داده نمی‌شوند چرا که هدف بودجهٔ اختصاصی ندارند، اما در مقدار واقعی \f[CR]expenses:food\f[R] سهیم هستند. .IP \(bu 2 حساب‌های بدون بودجهٔ \f[CR]expenses:movies\f[R] و \f[CR]expenses:gifts\f[R] نیز نشان داده نمی‌شوند، اما در مقدار واقعی \f[CR]expenses\f[R] مشارکت دارند. .IP \(bu 2 سایر حساب‌های بدون بودجه یعنی \f[CR]income\f[R] و \f[CR]assets:bank:checking\f[R] تحت عنوان \f[CR]\f[R] دسته‌بندی می‌شوند. .IP \(bu 2 می‌توان از \f[CR]\-\-depth\f[R] یا \f[CR]depth:\f[R] برای محدود کردن عمق گزارش به شیوهٔ معمول استفاده کرد (اما زیرحساب‌های بدون بودجه را آشکار نخواهد کرد). .IP \(bu 2 مبالغ همواره شامل زیرحساب‌ها هستند (حتی در حالت \f[CR]\-l/\-\-list\f[R]). .IP \(bu 2 اعدادی که در یک گزارش \-\-budget نمایش داده می‌شوند، به دلیل حساب‌های بدون بودجهٔ پنهان‌شده، همیشه با جمع کل همخوانی نخواهند داشت؛ این موضوع طبیعی است. می‌توان از \f[CR]\-E/\-\-empty\f[R] برای آشکار کردن حساب‌های پنهان استفاده کرد. .IP \(bu 2 در قوانین دوره‌ای که برای تنظیم اهداف بودجه به کار می‌روند، استفاده از ثبت‌های نامتوازن (unbalanced postings) کار را راحت‌تر می‌کند. .IP \(bu 2 می‌توانید گزارش‌های بودجه را با پرس‌وجوهای معمول فیلتر کنید، به عنوان مثال برای تمرکز بر روی حساب‌های خاص. محدود کردن آن‌ها صرفاً به هزینه‌ها (expenses) رایج است. (مستثنی کردن حساب \f[CR]\f[R] گاهی دشوار است؛ این موضوع به دلیل رفتارهای پیش‌بینی‌نشده در تاریخ‌ها رخ می‌دهد که در ادامه شرح داده شده است.) .IP \(bu 2 هنگامی که چندین ارز دارید، ممکن است بخواهید آن‌ها را به یک ارز تبدیل کنید (\f[CR]\-X COMM \-\-infer\-market\-prices\f[R]) و/یا در هر زمان فقط یکی را نشان دهید (\f[CR]cur:COMM\f[R]). اگر نیاز دارید چند ارز را هم‌زمان نمایش دهید، \f[CR]\-\-layout bare\f[R] می‌تواند مفید باشد. .IP \(bu 2 می‌توانید با استفاده از \f[CR]\-\-cumulative\f[R] مقادیر (واقعی و بودجه‌بندی‌شده) را به دورهٔ بعدی انتقال دهید (اصطلاحاً \(dqroll over\(dq کنید). .PP همچنین ببینید: https://hledger.org/budgeting.html.SS موارد غیرمنتظره در تاریخ بودجه با داده‌های اندک، یا در زمان شروع کار، ممکن است برخی از تاریخ‌های تراکنش‌های هدف بودجه تولیدشده خارج از دوره‌های گزارش قرار گیرند. به‌عنوان مثال، با دفتر روزنامه (journal) و گزارش زیر، به نظر می‌رسد دوره اول هیچ بودجه‌ای برای \f[CR]expenses:food\f[R] ندارد. (همچنین حساب \f[CR]\f[R] باید توسط پرسمان \f[CR]expenses\f[R] مستثنی می‌شد، اما نشده است): .IP .EX \(ti monthly in 2020 (expenses:food) $500 2020\-01\-15 expenses:food $400 assets:checking .EE .IP .EX $ hledger bal \-\-budget expenses Budget performance in 2020\-01\-15: || 2020\-01\-15 ===============++==================== || $400 expenses:food || 0 [ 0% of $500] \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || $400 [80% of $500] .EE .PP در این حالت، تراکنش‌های هدف بودجه در روزهای اول ماه تولید می‌شوند (این موضوع با دستور \f[CR]hledger print \-\-forecast tag:generated expenses\f[R] قابل مشاهده است). در حالی که دوره گزارش به‌طور پیش‌فرض تنها به روز ۱۵ام ژانویه محدود می‌شود (این نکته از سرستون‌های جدول گزارش مشخص است). .PP برای رفع این‌گونه موارد، بازه زمانی گزارش (و/یا تاریخ‌های قواعد دوره‌ای) را صریح‌تر مشخص کنید. در این مورد، افزودن \f[CR]\-b 2020\f[R] مشکل را حل می‌کند. .SS انتخاب اهداف بودجه به‌طور پیش‌فرض، گزارش بودجه از تمام قواعد تراکنش دوره‌ایِ موجود برای تولید اهداف استفاده می‌کند. این شامل قواعدی با بازه زمانی متفاوت از گزارش شما نیز می‌شود. برای مثال، اگر قواعد دوره‌ای روزانه، هفتگی و ماهانه داشته باشید، همه آن‌ها در تعیین اهداف یک گزارش بودجه ماهانه سهیم خواهند بود. .PP می‌توانید با ارائه یک آرگومان به پرچم \f[CR]\-\-budget\f[R]، زیرمجموعه‌ای از قواعد دوره‌ای را انتخاب کنید. گزینه \f[CR]\-\-budget=DESCPAT\f[R] با تمام قواعد دوره‌ای که توضیحات آن‌ها شامل DESCPAT باشد، به‌صورت زیررشته‌ای و بدون حساسیت به حروف بزرگ و کوچک (نه یک عبارت باقاعده یا پرسمان) مطابقت داده می‌شود. این بدان معناست که می‌توانید به قواعد دوره‌ای خود توضیحاتی اختصاص دهید (به خاطر داشته باشید که بین عبارت دوره و توضیحات دو فاصله لازم است)، و سپس از میان چندین بودجه تعریف‌شده در دفتر روزنامه خود، مورد دلخواه را انتخاب کنید. .SS بودجه‌بندی در برابر پیش‌بینی هر دو گزینه \f[CR]\-\-forecast\f[R] و \f[CR]\-\-budget\f[R] از قواعد تراکنش‌های دوره‌ای در دفتر روزنامه برای تولید تراکنش‌های موقت جهت مقاصد گزارش‌گیری استفاده می‌کنند. با این حال، این دو قابلیت‌هایی مجزا هستند \- هرچند در صورت تمایل می‌توانید از هر دو به‌طور هم‌زمان استفاده کنید. در اینجا برخی از تفاوت‌های میان آن‌ها آمده است: .PP .TS tab(@); lw(38.2n) lw(31.8n). T{ \-\-forecast T}@T{ \-\-budget T} _ T{ یک گزینه عمومی است؛ پیش‌بینی را در تمام گزارش‌ها فعال می‌کند T}@T{ یک گزینه برای دستور balance است؛ حالت بودجه گزارش balance را انتخاب می‌کند T} T{ تراکنش‌های مرئی تولید می‌کند که در گزارش‌ها ظاهر می‌شوند T}@T{ تراکنش‌های نامرئی تولید می‌کند که مقادیر هدف را می‌سازند T} T{ تراکنش‌های پیش‌بینی را از پس از آخرین تراکنش عادی تا پایان دوره گزارش تولید می‌کند؛ یا با آرگومان \f[CR]\-\-forecast=PERIODEXPR\f[R] آن‌ها را در سراسر دوره مشخص‌شده تولید می‌کند (در هر دو حالت، به‌طور اختیاری توسط دوره‌های مشخص‌شده در قواعد تراکنش دوره‌ای محدود می‌شود) T}@T{ تراکنش‌های هدف بودجه را در سراسر دوره گزارش تولید می‌کند (به‌طور اختیاری توسط دوره‌های مشخص‌شده در قواعد تراکنش دوره‌ای محدود می‌شود) T} T{ از تمام قواعد دوره‌ای استفاده می‌کند T}@T{ از تمام قواعد دوره‌ای استفاده می‌کند؛ یا با آرگومان \f[CR]\-\-budget=DESCPAT\f[R] تنها از قواعدی که با DESCPAT مطابقت دارند استفاده می‌کند T} .TE.SS چیدمان گزارش تراز (Balance report layout) گزینهٔ \f[CR]\-\-layout\f[R] بر نحوهٔ نمایش مقادیر چندکالایی و نمادهای کالا توسط \f[CR]balance\f[R] و سایر دستورهای مشابه تراز تأثیر می‌گذارد. این گزینه می‌تواند خوانایی را برای انسان‌ها و/یا ماشین‌ها (سایر نرم‌افزارها) بهبود بخشد. چهار مقدار ممکن برای آن وجود دارد: .IP \(bu 2 \f[CR]\-\-layout=wide[,WIDTH]\f[R]: کالاها در یک سطر واحد نمایش داده می‌شوند، و به‌صورت اختیاری تا WIDTH کوتاه (خلاصه) می‌شوند .IP \(bu 2 \f[CR]\-\-layout=tall\f[R]: هر کالا در یک سطر جداگانه نمایش داده می‌شود .IP \(bu 2 \f[CR]\-\-layout=bare\f[R]: نمادهای کالا در ستون اختصاصی خود قرار می‌گیرند و مقادیر به‌صورت اعداد خالص هستند .IP \(bu 2 \f[CR]\-\-layout=tidy\f[R]: داده‌ها به شکل \(dqtidy\(dq (مرتب) با استفادهٔ آسان، با یک سطر به ازای هر مقدار داده، نرمال‌سازی می‌شوند. (این حالت در حال حاضر تنها توسط دستور \f[CR]balance\f[R] پشتیبانی می‌شود.) .PP حالت‌های \f[CR]\-\-layout\f[R] پشتیبانی‌شده توسط هر قالب خروجی در ادامه آورده شده است. تنها خروجی CSV از همهٔ آن‌ها پشتیبانی می‌کند: .PP .TS tab(@); l l l l l l. T{ \- T}@T{ txt T}@T{ csv T}@T{ html T}@T{ json T}@T{ sql T} _ T{ wide T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T} T{ tall T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T} T{ bare T}@T{ Y T}@T{ Y T}@T{ Y T}@T{ T}@T{ T} T{ tidy T}@T{ T}@T{ Y T}@T{ T}@T{ T}@T{ T} .TE .PP مثال‌ها:.SS "چیدمان عریض (Wide layout)" در صورت وجود کالاهای متعدد، گزارش‌ها می‌توانند بسیار عریض شوند: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=wide Balance changes in 2012\-01\-01..2014\-12\-31: || 2012 2013 2014 Total ==================++==================================================================================================================================================================================================================== Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, \-98.12 USD, 10.00 VEA, 18.00 VHT \-11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, \-98.12 USD, 10.00 VEA, 18.00 VHT \-11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT .EE .PP تعیین محدودیت عرض، پهنا را کاهش می‌دهد، اما برخی از کالاها پنهان خواهند شد: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=wide,32 Balance changes in 2012\-01\-01..2014\-12\-31: || 2012 2013 2014 Total ==================++=========================================================================================================================== Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. \-11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. \-11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. .EE .SS "چیدمان طولی (Tall layout)" هر کالا در یک سطر جدید قرار می‌گیرد (که ممکن است در هر ستون متفاوت باشد) و نام‌های حساب تکرار می‌شوند: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=tall Balance changes in 2012\-01\-01..2014\-12\-31: || 2012 2013 2014 Total ==================++================================================== Assets:US:ETrade || 10.00 ITOT 70.00 GLD \-11.00 ITOT 70.00 GLD Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT Assets:US:ETrade || 12.00 VEA \-98.12 USD 14.00 VEA 5120.50 USD Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA Assets:US:ETrade || 18.00 VHT 294.00 VHT \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || 10.00 ITOT 70.00 GLD \-11.00 ITOT 70.00 GLD || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT || 12.00 VEA \-98.12 USD 14.00 VEA 5120.50 USD || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA || 18.00 VHT 294.00 VHT .EE .SS "چیدمان ساده (Bare layout)" نمادهای کالا در یک ستون نگه داشته می‌شوند، هر کالا ردیف مخصوص به خود را دارد، مبالغ صرفاً عدد خام هستند و نام‌های حساب تکرار می‌شوند: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=bare Balance changes in 2012\-01\-01..2014\-12\-31: || Commodity 2012 2013 2014 Total ==================++============================================= Assets:US:ETrade || GLD 0 70.00 0 70.00 Assets:US:ETrade || ITOT 10.00 18.00 \-11.00 17.00 Assets:US:ETrade || USD 337.18 \-98.12 4881.44 5120.50 Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || GLD 0 70.00 0 70.00 || ITOT 10.00 18.00 \-11.00 17.00 || USD 337.18 \-98.12 4881.44 5120.50 || VEA 12.00 10.00 14.00 36.00 || VHT 106.00 18.00 170.00 294.00 .EE .PP چیدمان bare خروجی CSV را نیز تحت تأثیر قرار می‌دهد، که برای تولید داده‌هایی با پردازش و استفادهٔ آسان‌تر (مثلاً برای رسم نمودارها) سودمند است: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-layout=bare \(dqaccount\(dq,\(dqcommodity\(dq,\(dqbalance\(dq \(dqAssets:US:ETrade\(dq,\(dqGLD\(dq,\(dq70.00\(dq \(dqAssets:US:ETrade\(dq,\(dqITOT\(dq,\(dq17.00\(dq \(dqAssets:US:ETrade\(dq,\(dqUSD\(dq,\(dq5120.50\(dq \(dqAssets:US:ETrade\(dq,\(dqVEA\(dq,\(dq36.00\(dq \(dqAssets:US:ETrade\(dq,\(dqVHT\(dq,\(dq294.00\(dq \(dqTotal:\(dq,\(dqGLD\(dq,\(dq70.00\(dq \(dqTotal:\(dq,\(dqITOT\(dq,\(dq17.00\(dq \(dqTotal:\(dq,\(dqUSD\(dq,\(dq5120.50\(dq \(dqTotal:\(dq,\(dqVEA\(dq,\(dq36.00\(dq \(dqTotal:\(dq,\(dqVHT\(dq,\(dq294.00\(dq .EE .PP چیدمان bare گاهی اوقات به دلیل مقادیر صفر، یک سطر اضافی برای کالاهای بدون نماد (no\-symbol) نمایش می‌دهد (معمولاً hledger مقادیر صفر را بدون کالا در نظر می‌گیرد). این موضوع می‌تواند باعث ایجاد خطای گیج‌کننده در \f[CR]hledger\-bar\f[R] شود (راهکار: اضافه کردن یک پرس‌وجوی \f[CR]cur:\f[R] برای حذف سطر بدون نماد)..SS چیدمان مرتب (Tidy layout) این مورد \(dqtidy data\(dq نرمال‌سازی‌شده تولید می‌کند (ببینید: https://cran.r\-project.org/web/packages/tidyr/vignettes/tidy\-data.html) که در آن هر متغیر ستون مخصوص به خود را دارد و هر سطر نمایانگر یک نقطه داده تکی است. این ساده‌ترین نوع داده برای پردازش توسط سایر نرم‌افزارها است: .IP .EX $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-Y \-O csv \-\-layout=tidy \(dqaccount\(dq,\(dqperiod\(dq,\(dqstart_date\(dq,\(dqend_date\(dq,\(dqcommodity\(dq,\(dqvalue\(dq \(dqAssets:US:ETrade\(dq,\(dq2012\(dq,\(dq2012\-01\-01\(dq,\(dq2012\-12\-31\(dq,\(dqGLD\(dq,\(dq0\(dq \(dqAssets:US:ETrade\(dq,\(dq2012\(dq,\(dq2012\-01\-01\(dq,\(dq2012\-12\-31\(dq,\(dqITOT\(dq,\(dq10.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2012\(dq,\(dq2012\-01\-01\(dq,\(dq2012\-12\-31\(dq,\(dqUSD\(dq,\(dq337.18\(dq \(dqAssets:US:ETrade\(dq,\(dq2012\(dq,\(dq2012\-01\-01\(dq,\(dq2012\-12\-31\(dq,\(dqVEA\(dq,\(dq12.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2012\(dq,\(dq2012\-01\-01\(dq,\(dq2012\-12\-31\(dq,\(dqVHT\(dq,\(dq106.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2013\(dq,\(dq2013\-01\-01\(dq,\(dq2013\-12\-31\(dq,\(dqGLD\(dq,\(dq70.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2013\(dq,\(dq2013\-01\-01\(dq,\(dq2013\-12\-31\(dq,\(dqITOT\(dq,\(dq18.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2013\(dq,\(dq2013\-01\-01\(dq,\(dq2013\-12\-31\(dq,\(dqUSD\(dq,\(dq\-98.12\(dq \(dqAssets:US:ETrade\(dq,\(dq2013\(dq,\(dq2013\-01\-01\(dq,\(dq2013\-12\-31\(dq,\(dqVEA\(dq,\(dq10.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2013\(dq,\(dq2013\-01\-01\(dq,\(dq2013\-12\-31\(dq,\(dqVHT\(dq,\(dq18.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2014\(dq,\(dq2014\-01\-01\(dq,\(dq2014\-12\-31\(dq,\(dqGLD\(dq,\(dq0\(dq \(dqAssets:US:ETrade\(dq,\(dq2014\(dq,\(dq2014\-01\-01\(dq,\(dq2014\-12\-31\(dq,\(dqITOT\(dq,\(dq\-11.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2014\(dq,\(dq2014\-01\-01\(dq,\(dq2014\-12\-31\(dq,\(dqUSD\(dq,\(dq4881.44\(dq \(dqAssets:US:ETrade\(dq,\(dq2014\(dq,\(dq2014\-01\-01\(dq,\(dq2014\-12\-31\(dq,\(dqVEA\(dq,\(dq14.00\(dq \(dqAssets:US:ETrade\(dq,\(dq2014\(dq,\(dq2014\-01\-01\(dq,\(dq2014\-12\-31\(dq,\(dqVHT\(dq,\(dq170.00\(dq .EE .SS خروجی گزارش تراز (Balance report output) همان‌طور که در «قالب خروجی» (Output format) اشاره شد، اگر خروجی HTML را انتخاب کنید (با استفاده از \f[CR]\-O html\f[R] یا \f[CR]\-o somefile.html\f[R])، می‌توانید یک فایل \f[CR]hledger.css\f[R] در همان دایرکتوری ایجاد کنید تا ظاهر گزارش را شخصی‌سازی نمایید. .PP قالب‌های خروجی HTML و FODS می‌توانند برای هر حساب و دوره، ابرپیوندهایی به نمای دفترکل در \f[CR]hledger\-web\f[R] ایجاد کنند. برای مثال، اگر سرور \f[CR]hledger\-web\f[R] شما در \f[CR]http://localhost:5000\f[R] در دسترس باشد، می‌توانید دستور \f[CR]balance\f[R] را با گزینه اضافی \f[CR]\-\-base\-url=http://localhost:5000\f[R] اجرا کنید. (همچنین می‌توانید پیوندهای نسبی ایجاد کنید، مانند \f[CR]\-\-base\-url=\(dqsome/path\(dq\f[R] یا \f[CR]\-\-base\-url=\(dq\(dq\f[R].) .SS برخی گزارش‌های مفید balance (Some useful balance reports) برخی از گزینه‌ها/گزارش‌های پرکاربرد \f[CR]balance\f[R] عبارتند از: .IP \(bu 2 \f[CR]bal \-M revenues expenses\f[R] .PD 0 .P .PD نمایش درآمدها/هزینه‌ها در هر ماه. همچنین از طریق دستور \f[CR]incomestatement\f[R] در دسترس است. .IP \(bu 2 \f[CR]bal \-M \-H assets liabilities\f[R] .PD 0 .P .PD نمایش تراز تاریخی دارایی‌ها/بدهی‌ها در پایان هر ماه. همچنین از طریق دستور \f[CR]balancesheet\f[R] در دسترس است. .IP \(bu 2 \f[CR]bal \-M \-H assets liabilities equity\f[R] .PD 0 .P .PD نمایش تراز تاریخی دارایی‌ها/بدهی‌ها/سرمایه در پایان هر ماه. همچنین از طریق دستور \f[CR]balancesheetequity\f[R] در دسترس است. .IP \(bu 2 \f[CR]bal \-M assets not:receivable\f[R] .PD 0 .P .PD نمایش تغییرات دارایی‌های نقدی در هر ماه. همچنین از طریق دستور \f[CR]cashflow\f[R] در دسترس است. .PP همچنین: .IP \(bu 2 \f[CR]bal \-M expenses \-2 \-SA\f[R] .PD 0 .P .PD نمایش هزینه‌های ماهانه خلاصه‌شده تا عمق ۲ و مرتب‌شده بر اساس میانگین مقدار. .IP \(bu 2 \f[CR]bal \-M \-\-budget expenses\f[R] .PD 0 .P .PD نمایش هزینه‌های ماهانه و اهداف بودجه. .IP \(bu 2 \f[CR]bal \-M \-\-valuechange investments\f[R] .PD 0 .P .PD نمایش تغییرات ماهانه در ارزش بازار دارایی‌های سرمایه‌گذاری. .IP \(bu 2 \f[CR]bal investments \-\-valuechange \-D date:lastweek amt:\(aq>1000\(aq \-STA [\-\-invert]\f[R] .PD 0 .P .PD نمایش بیشترین سودها [یا زیان‌ها] در هفته گذشته.SS roi نرخ بازده وزنی\-زمانی (TWR) و وزنی\-پولی (IRR) را برای سرمایه‌گذاری‌های شما نمایش می‌دهد. .IP .EX Flags: \-\-cashflow show all amounts that were used to compute returns \-\-investment=QUERY query to select your investment transactions \-\-profit\-loss=QUERY \-\-pnl query to select profit\-and\-loss or appreciation/valuation transactions .EE .PP در کمترین حالت، باید یک پرس‌وجو (که می‌تواند صرفاً یک نام حساب باشد) با \f[CR]\-\-inv\f[R] برای انتخاب سرمایه‌گذاری(ها) و پرس‌وجویی دیگر با \f[CR]\-\-pnl\f[R] برای مشخص کردن تراکنش‌های سود و زیان خود ارائه دهید. .PP اگر تغییرات در ارزش سرمایه‌گذاری خود را به صورت دستی ثبت نمی‌کنید، یا نیازی به محاسبهٔ بازده وزنی\-زمانی (TWR) ندارید، \f[CR]\-\-pnl\f[R] می‌تواند یک پرس‌وجوی خالی باشد (\f[CR]\-\-pnl \(dq\(dq\f[R] یا \f[CR]\-\-pnl STR\f[R] که در آن \f[CR]STR\f[R] با هیچ‌یک از حساب‌های شما مطابقت ندارد). .PP این دستور نرخ بازده داخلی (IRR، همچنین شناخته‌شده با عنوان نرخ بازده وزنی\-پولی) و نرخ بازده وزنی\-زمانی (TWR) را برای سرمایه‌گذاری‌های شما در بازهٔ زمانی درخواستی محاسبه و نمایش می‌دهد. به دلیل نحوهٔ محاسبه، IRR همواره سالانه می‌شود، اما TWR هم به صورت یک نرخ در طول دورهٔ گزارش‌گیری انتخاب‌شده و هم به عنوان یک نرخ سالانه گزارش می‌شود. .PP در صورت ارائهٔ پرچم‌های مناسب \f[CR]\-\-cost\f[R] یا \f[CR]\-\-value\f[R]، دستورالعمل‌های قیمت لحاظ خواهند شد (بخش VALUATION را ببینید). .PP توجه داشته باشید که در برخی موارد این گزارش ممکن است به دلایل زیر ناموفق باشد: .IP \(bu 2 خطای Error (NotBracketed): راه‌حلی برای نرخ بازده داخلی (IRR) یافت نشد. علل احتمالی: مقدار IRR بسیار بزرگ است (>1000000%)، موجودی سرمایه‌گذاری در مقطعی از زمان منفی می‌شود. .IP \(bu 2 خطای Error (SearchFailed): یافتن راه‌حل برای نرخ بازده داخلی (IRR) با شکست مواجه شد. یا جست‌وجو به یک راه‌حل همگرا نمی‌شود، یا بسیار کند همگرا می‌شود. .PP مثال‌ها: .IP \(bu 2 استفاده از roi برای محاسبهٔ بازده کل سرمایه‌گذاری در سهام: https://github.com/simonmichael/hledger/blob/master/examples/investing/roi\-unrealised.ledger .IP \(bu 2 Cookbook > Return on Investment: https://hledger.org/roi.html .SS فاصله‌ها و نویسه‌های خاص در \f[CR]\-\-inv\f[R] و \f[CR]\-\-pnl\f[R] توجه داشته باشید که آرگومان \f[CR]\-\-inv\f[R] و \f[CR]\-\-pnl\f[R] یک پرس‌وجو است، و پرس‌وجوها می‌توانند شامل چندین عبارت جداشده با فاصله باشند (بخش QUERIES را ببینید). .PP برای مشخص کردن اینکه همهٔ عبارت‌های جست‌وجو یک آرگومان واحد خط فرمان را تشکیل می‌دهند، باید آن‌ها را داخل نقل‌قول قرار دهید (بخش Special characters را ببینید): .IP .EX $ hledger roi \-\-inv \(aqterm1 term2 term3 ...\(aq .EE .PP اگر هر یک از عبارت‌های پرس‌وجو خود حاوی فاصله باشند، به یک سطح اضافی از نقل‌قول تو‌در‌تو نیاز خواهید داشت، برای مثال: .IP .EX $ hledger roi \-\-inv=\(dq\(aqAssets:Test 1\(aq\(dq \-\-pnl=\(dq\(aqEquity:Unrealized Profit and Loss\(aq\(dq .EE .SS معناشناسی \f[CR]\-\-inv\f[R] و \f[CR]\-\-pnl\f[R] پرس‌وجوی ارائه‌شده به \f[CR]\-\-inv\f[R] باید با تمام تراکنش‌های مرتبط با سرمایه‌گذاری شما مطابقت داشته باشد. تراکنش‌هایی که با \f[CR]\-\-inv\f[R] تطابق ندارند نادیده گرفته خواهند شد. .PP در این تراکنش‌ها، ROI ثبت‌هایی (postings) را که با \f[CR]\-\-inv\f[R] مطابقت دارند به‌عنوان \(dqثبت‌های سرمایه‌گذاری\(dq در نظر می‌گیرد و سایر ثبت‌ها (که با \f[CR]\-\-inv\f[R] مطابقت ندارند) به دو دسته تفکیک می‌شوند: \(dqجریان وجوه نقد\(dq و \(dqسود و زیان\(dq؛ چرا که ROI باید بداند کدام بخش از ارزش سرمایه‌گذاری مربوط به آورده‌های شماست و کدام بخش ناشی از بازده سرمایه‌گذاری است. .IP \(bu 2 \(dqجریان وجوه نقد\(dq عبارت است از واریز یا برداشت پول، خرید یا فروش دارایی‌ها، یا هرگونه تبدیل دیگر بین کالای سرمایه‌گذاری شما و هر کالای دیگر. مثال: .RS 2 .IP .EX 2019\-01\-01 Investing in Snake Oil assets:cash \-$100 investment:snake oil 2020\-01\-01 Selling my Snake Oil assets:cash $10 investment:snake oil = 0 .EE .RE .IP \(bu 2 \(dqسود و زیان\(dq تغییر در ارزش سرمایه‌گذاری شما است: .RS 2 .IP .EX 2019\-06\-01 Snake Oil falls in value investment:snake oil = $57 equity:unrealized profit or loss .EE .RE .PP تمام ثبت‌های غیرسرمایه‌گذاری \(dqجریان وجوه نقد\(dq فرض می‌شوند، مگر اینکه با پرس‌وجوی \f[CR]\-\-pnl\f[R] مطابقت داشته باشند. تغییرات در ارزش سرمایه‌گذاری شما ناشی از ثبت‌های \(dqسود و زیان\(dq به‌عنوان بخشی از بازده سرمایه‌گذاری شما لحاظ خواهد شد. .PP مثال: اگر از \f[CR]\-\-inv snake \-\-pnl equity:unrealized\f[R] استفاده کنید، آنگاه ثبت‌ها در مثال زیر به این صورت طبقه‌بندی می‌شوند: .IP .EX 2019\-01\-01 Snake Oil #1 assets:cash \-$100 ; cash flow posting investment:snake oil ; investment posting 2019\-03\-01 Snake Oil #2 equity:unrealized pnl \-$100 ; profit and loss posting snake oil ; investment posting 2019\-07\-01 Snake Oil #3 equity:unrealized pnl ; profit and loss posting cash \-$100 ; cash flow posting snake oil $50 ; investment posting .EE.SS توضیح IRR و TWR \(dqROI\(dq مخفف \(dqبازگشت سرمایه\(dq (return on investment) است. به‌طور سنتی، این مقدار به صورت تفاوت میان ارزش فعلی سرمایه‌گذاری و ارزش اولیه آن محاسبه می‌شد و به صورت درصدی از ارزش اولیه بیان می‌گردید. .PP با این حال، این رویکرد تنها در موارد ساده کاربرد دارد، جایی که سرمایه‌گذاری هیچ‌گونه جریان ورودی یا خروجی پول دریافت نمی‌کند و نرخ رشد در طول زمان ثابت است. برای سناریوهای پیچیده‌تر، به روش‌های متفاوتی برای محاسبه نرخ بازده نیاز دارید، و این دستور دو مورد از آن‌ها را پیاده‌سازی می‌کند: IRR و TWR. .PP نرخ بازده داخلی، یا \(dqIRR\(dq (که \(dqنرخ بازده وزنی\-پولی\(dq نیز نامیده می‌شود) اثرات جریان‌های ورودی و خروجی و زمان بین آن‌ها را در نظر می‌گیرد. سرمایه‌گذاری با یک نرخ بهره ثابت مشخص، بهره بیشتری نسبت به همان مقدار سرمایه‌گذاری‌شده با همان نرخ بهره ولی در زمانی دیرتر، برای شما به همراه خواهد داشت. اگر از سرمایه‌گذاری خود برداشت کنید، سودهای آتی شما (در ارقام مطلق) کمتر خواهد بود و درصد کمتری از سرمایه‌گذاری اولیه شما را تشکیل می‌دهد، بنابراین IRR شما کمتر خواهد شد. و اگر به سرمایه‌گذاری خود بیفزایید، سودهای مطلق بزرگ‌تری دریافت خواهید کرد که درصد بیشتری از سرمایه‌گذاری اولیه شما خواهد بود، بنابراین IRR شما بزرگ‌تر خواهد شد. .PP همان‌طور که پیش‌تر ذکر شد، جریان‌های ورودی و خروجی شامل هرگونه وجه نقدی است که شخصاً وارد یا برداشت می‌کنید، و برای دستور \(dqroi\(dq، این‌ها ثبت‌هایی (postings) هستند که با پرس‌وجوی آرگومان \f[CR]\-\-inv\f[R] مطابقت داشته و با پرس‌وجوی آرگومان \f[CR]\-\-pnl\f[R] مطابقت ندارند. .PP اگر تغییرات ارزش سرمایه‌گذاری خود را به صورت دستی و در قالب تراکنش‌هایی ثبت می‌کنید که آن‌ها را در برابر حساب \(dqسود و زیان\(dq (یا \(dqسودهای تحقق‌نیافته\(dq) تراز می‌کند یا از دستورالعمل‌های قیمت (price directives) استفاده می‌کنید، برای اینکه IRR اثر دقیق جریان‌های ورودی و خروجی شما را بر نرخ بازده محاسبه کند، باید ارزش سرمایه‌گذاری خود را در همان روزها یا نزدیک به روزهایی که ورود یا خروج پول رخ می‌دهد ثبت نمایید. .PP از نظر فنی، IRR از همان رویکرد محاسبه ارزش خالص فعلی استفاده می‌کند و تلاش می‌کند تا نرخ تنزیلی را بیابد که مجموع ارزش خالص فعلی تمام جریان‌های نقدی سرمایه‌گذاری شما را برابر با صفر کند. درک این موضوع ممکن است دشوار باشد، به‌ویژه اگر قبلاً تحلیل جریان نقدی تنزیل‌شده را انجام نداده باشید. پیاده‌سازی IRR در hledger باید نتایجی مطابق با فرمول \f[CR]=XIRR\f[R] در Excel تولید کند. .PP دومین روش برای محاسبه نرخ بازده که دستور \f[CR]roi\f[R] پیاده‌سازی می‌کند، \(dqنرخ بازده وزنی\-زمانی\(dq یا \(dqTWR\(dq نامیده می‌شود. مانند IRR، این روش اثر جریان‌های ورودی و خروجی شما را در نظر می‌گیرد، اما بر خلاف IRR تلاش می‌کند تا نرخ بازده واقعی دارایی مبنا را با خنثی کردن اثری که واریزها و برداشت‌ها بر نرخ رشد ظاهری سرمایه‌گذاری شما می‌گذارند، محاسبه نماید. .PP روش TWR سرمایه‌گذاری شما را مانند یک \(dqصندوق سرمایه‌گذاری واحدی\(dq فرضی نشان می‌دهد که در آن جریان‌های ورودی/خروجی منجر به خرید یا فروش \(dqواحدها\(dqی سرمایه‌گذاری شما شده و تغییرات ارزش آن، ارزش \(dqواحد سرمایه‌گذاری\(dq را تغییر می‌دهد. تغییر در \(dqقیمت هر واحد\(dq در طول دوره گزارش، نرخ بازده سرمایه‌گذاری‌تان را به شما می‌دهد و حساسیت TWR را نسبت به اثرات جریان‌های نقدی ورودی و خروجی در مقایسه با IRR کمتر می‌کند. .PP منابع: .IP \(bu 2 توضیح نرخ بازده .IP \(bu 2 توضیح IRR .IP \(bu 2 توضیح TWR .IP \(bu 2 مقایسه IRR و TWR .IP \(bu 2 مثال‌هایی از محاسبه IRR و TWR و بحث درباره محدودیت‌های هر دو معیار .SH "دستورهای نمودار (CHART COMMANDS)" .SS activity نمایش یک نمودار میله‌ای اسکی از تعداد ثبت‌ها (postings) در هر بازه زمانی. .IP .EX Flags: no command\-specific flags .EE .PP دستور activity یک هیستوگرام اسکی را نمایش می‌دهد که تعداد تراکنش‌ها را بر اساس روز، هفته، ماه یا سایر بازه‌های گزارش‌دهی نشان می‌دهد (پیش‌فرض روزانه است). با آرگومان‌های پرس‌وجو، این دستور تنها تراکنش‌های مطابقت‌یافته را می‌شمارد. .PP مثال‌ها: .IP .EX $ hledger activity \-\-quarterly 2008\-01\-01 ** 2008\-04\-01 ******* 2008\-07\-01 2008\-10\-01 ** .EE.SH "دستورهای تولید داده (Data generation commands)" .SS close (equity) .PP دستور \f[CR]close\f[R] چندین نوع از تراکنش‌های «بستن» و/یا «باز کردن» را چاپ می‌کند که در موقعیت‌های گوناگونی کاربرد دارند: انتقال ترازها به یک فایل دفتر روزنامه جدید، انتقال سود انباشته به حقوق صاحبان سهام (equity)، تجمیع ترازها، مشاهده بهای تمام‌شده دسته‌ها (lot costs)... مانند \f[CR]print\f[R]، این دستور ثبت‌های معتبر دفتر روزنامه را چاپ می‌کند. می‌توانید پس از اطمینان و رضایت از نحوه نمایش آن‌ها، آن‌ها را در فایل(های) دفتر روزنامه خود کپی کنید. .IP .EX Flags: \-\-clopen[=TAGVAL] نمایش تراکنش‌های ترازهای بستن و باز کردن، به‌طور پیش‌فرض برای حساب‌های AL \-\-close[=TAGVAL] تنها نمایش یک تراکنش ترازهای بستن \-\-open[=TAGVAL] تنها نمایش یک تراکنش ترازهای باز کردن \-\-assert[=TAGVAL] نمایش یک تراکنش اعلان‌های تراز (balance assertions) \-\-assign[=TAGVAL] نمایش یک تراکنش تخصیص‌های تراز (balance assignments) \-\-retain[=TAGVAL] نمایش یک تراکنش سود انباشته، به‌طور پیش‌فرض برای حساب‌های RX \-x \-\-explicit نمایش صریح تمام مبالغ \-\-show\-costs نمایش جداگانه مبالغ با هزینه‌های متفاوت \-\-interleaved نمایش هم‌زمان ثبت‌های مبدأ و مقصد در کنار یکدیگر \-\-assertion\-type=TYPE =* یا ==* ،== ،= \-\-close\-desc=DESC تنظیم شرح تراکنش بستن \-\-close\-acct=ACCT تنظیم حساب مقصد تراکنش بستن \-\-open\-desc=DESC تنظیم شرح تراکنش باز کردن \-\-open\-acct=ACCT تنظیم حساب مبدأ تراکنش باز کردن \-\-round=TYPE چه میزان گرد کردن یا فاصله‌گذاری هنگام نمایش مبالغ باید انجام شود؟ none \- نمایش ارقام اعشاری اصلی، همان‌طور که در دفتر روزنامه است (پیش‌فرض) soft \- فقط افزودن یا حذف صفرهای اعشاری جهت تطابق با دقت (precision) hard \- گرد کردن مبالغ ثبت به میزان دقت (می‌تواند تراز تراکنش را برهم زند) all \- همچنین گرد کردن مبالغ هزینه به میزان دقت (می‌تواند تراز تراکنش را برهم زند) .EE .PP دستور \f[CR]close\f[R] دارای شش حالت است که با انتخاب یکی از پرچم‌های حالت تعیین می‌شوند: \f[CR]\-\-clopen\f[R]، \f[CR]\-\-close\f[R] (پیش‌فرض)، \f[CR]\-\-open\f[R]، \f[CR]\-\-assert\f[R]، \f[CR]\-\-assign\f[R]، یا \f[CR]\-\-retain\f[R]. همه آن‌ها نوع یکسانی از عملیات را انجام می‌دهند، اما با مقادیر پیش‌فرض متفاوت برای موقعیت‌های گوناگون. .PP ثبت‌های دفتر روزنامه تولیدشده توسط \f[CR]close\f[R] دارای یک برچسب \f[CR]clopen:\f[R] خواهند بود که هنگام تمایل به مستثنی کردن آن‌ها از گزارش‌ها مفید است. اگر نام فایل اصلی دفتر روزنامه شامل یک عدد باشد، مقدار برچسب همان نام پایه فایل با یک واحد افزایش عدد خواهد بود. به‌عنوان مثال، اگر فایل دفتر روزنامه 2025.journal باشد، برچسب \f[CR]clopen:2026\f[R] خواهد بود. یا می‌توانید مقدار برچسب را با ارائه یک آرگومان به پرچم حالت تنظیم کنید؛ مانند \f[CR]\-\-close=foo\f[R] یا \f[CR]\-\-clopen=2025\-main\f[R]. .SS close \-\-clopen این حالت زمانی مفید است که بخواهید در آغاز یک سال جدید، ترازها را به یک فایل دفتر روزنامه جدید انتقال دهید. این دستور یک تراکنش «ترازهای بستن» چاپ می‌کند که تراز حساب‌ها را صفر می‌کند (به‌طور پیش‌فرض حساب‌های دارایی [Asset] و بدهی [Liability])، و یک تراکنش متضاد «ترازهای باز کردن» که دوباره آن‌ها را بازیابی می‌کند. به‌طور معمول، چنین دستوری را اجرا می‌کنید: .IP .EX hledger close \-\-clopen \-e NEWYEAR >> $LEDGER_FILE .EE .PP و سپس تراکنش باز کردن را از فایل قدیمی به فایل جدید منتقل می‌کنید (و احتمالاً متغیر محیطی LEDGER_FILE خود را نیز به‌روزرسانی خواهید کرد). .PP چرا ممکن است این کار را انجام دهید؟ اگر گزارش‌های شما با سرعت بالا تولید می‌شوند، ممکن است نیازی به این کار نداشته باشید. اما در نقطه‌ای احتمالاً مایل خواهید بود داده‌های خود را به دلایل کارایی، حفظ یکپارچگی داده‌ها یا الزامات قانونی، بر اساس زمان بخش‌بندی کنید. ایجاد یک فایل یا مجموعه‌ای از فایل‌های جدید برای هر سال امری متداول است. سپس، احاطه شدن هر فایل/مجموعه‌فایل با تراکنش‌های تراز باز کردن در ابتدا و بستن در انتها به شما امکان می‌دهد آزادانه انتخاب کنید کدام فایل‌ها خوانده شوند \- فقط سال جاری، هر سالی در گذشته، هر توالی از سال‌ها، یا تمام آن‌ها \- در حالی که در هر حالت، ترازهای صحیح حساب‌ها نمایش داده می‌شوند. نخستین تراکنش ترازهای باز کردن، ترازهای آغازین صحیح را تعیین می‌کند و هر جفت بستن/باز کردن بعدی بدون ایجاد مشکل اثر یکدیگر را خنثی خواهند کرد. .PP ترازها به‌طور پیش‌فرض به حساب \f[CR]equity:opening/closing balances\f[R] و از آن منتقل خواهند شد. می‌توانید با استفاده از \f[CR]\-\-close\-acct\f[R] و/یا \f[CR]\-\-open\-acct\f[R] این رفتار را لغو و حساب دیگری را تعیین کنید. .PP می‌توانید با ارائه یک پرس‌وجوی حساب، مجموعه متفاوتی از حساب‌ها را برای بستن/باز کردن انتخاب کنید. برای مثال، جهت افزودن حساب‌های سرمایه (Equity)، آرگومان‌هایی مانند \f[CR]assets liabilities equity\f[R] یا \f[CR]type:ALE\f[R] ارائه دهید. هنگام انتقال به یک فایل جدید، معمولاً می‌خواهید حساب‌های AL یا ALE را منتقل کنید، نه حساب‌های RX (درآمد [Revenue]، هزینه [Expense]). .PP اعلان‌هایی (assertions) اضافه خواهند شد که ترازهای جدید حساب‌های بسته‌شده/بازشده را نشان داده و صحت آن‌ها را بررسی می‌کنند..SS close \-\-close این دستور صرفاً تراکنش ترازهای پایانی مربوط به \f[CR]\-\-clopen\f[R] را چاپ می‌کند. اگر حالتی را مشخص نکنید، این حالت پیش‌فرض است. .PP گزینه‌های سفارشی‌سازی بیشتر در زیر توضیح داده شده‌اند. افزون بر موارد دیگر، می‌توانید از \f[CR]close \-\-close\f[R] برای ایجاد تراکنشی استفاده کنید که ترازها را از هر مجموعه‌ای از حساب‌ها به یک حساب متفاوت منتقل می‌کند. (اگر نیاز دارید فقط بخشی از تراز را منتقل کنید، \f[CR]hledger\-move\f[R] را ببینید.) .SS close \-\-open این دستور صرفاً تراکنش ترازهای آغازین مربوط به \f[CR]\-\-clopen\f[R] را چاپ می‌کند. (مشابه دستور equity در Ledger است.) .SS close \-\-assert این دستور تراکنشی را چاپ می‌کند که ترازهای حساب را همان‌گونه که در تاریخ پایانی هستند اثبات (assert) می‌کند (و یک برچسب \f[CR]assert:\f[R] می‌افزاید). این کار می‌تواند به عنوان مستندسازی و محافظت در برابر تغییرات مفید باشد. .SS close \-\-assign این دستور تراکنشی را چاپ می‌کند که ترازهای حساب را همان‌گونه که در تاریخ پایانی هستند تخصیص می‌دهد (و یک برچسب \(dqassign:\(dq می‌افزاید). برخلاف اثبات ترازها، تخصیص‌ها برای رسیدن به مقادیر مشخص‌شده، در صورت نیاز تغییراتی را در ترازها ثبت خواهند کرد. .PP این روش دیگری برای تنظیم ترازهای آغازین هنگام مهاجرت به یک فایل جدید است و آن‌ها را حتی در صورت وجود فایل‌های قبلی که فاقد تراکنش ترازهای پایانی هستند به‌درستی تنظیم می‌کند. با این حال، این روش می‌تواند خطاها را پنهان کرده و معادله حسابداری را بر هم بزند؛ بنابراین معمولاً استفاده از \f[CR]\-\-clopen\f[R] توصیه می‌شود. .SS close \-\-retain این گزینه مشابه \f[CR]\-\-close\f[R] است، اما به‌طور پیش‌فرض ترازهای حساب‌های درآمد (Revenue) و هزینه (Expense) را می‌بندد. این مقادیر به \f[CR]equity:retained earnings\f[R] یا حساب دیگری که با \f[CR]\-\-close\-acct\f[R] مشخص شده است منتقل خواهند شد. .PP درآمدها و هزینه‌ها متناظر با تغییرات در حقوق صاحبان سهام و سرمایه (equity) هستند. آن‌ها برای مقاصد گزارش‌دهی به‌طور جداگانه دسته‌بندی می‌شوند، اما طبق سنت در پایان هر دوره حسابداری، کسب‌وکارها آن‌ها را در سرمایه تجمیع می‌کنند. این کار «سود انباشته» (\(dqretaining earnings\(dq) یا «بستن حساب‌ها» (\(dqclosing the books\(dq) نامیده می‌شود. .PP در حسابداری شخصی دلیل چندانی برای انجام این کار وجود ندارد و بیشتر افراد آن را انجام نمی‌دهند. (یک دلیل برای انجام این کار، کمک به گزارش \f[CR]balancesheetequity\f[R] است تا مجموع صفر را نشان دهد و اثبات کند که معادله حسابداری (A\-L=E) برقرار است.) .SS سفارشی‌سازی close (close customisation) در تمام حالت‌ها، موارد زیر را می‌توان بازنویسی (override) کرد: .IP \(bu 2 حساب‌هایی که باید بسته/باز شوند، با آرگومان‌های پرس‌وجوی حساب .IP \(bu 2 تاریخ‌های بستن/باز کردن، با \f[CR]\-e OPENDATE\f[R] .IP \(bu 2 حساب ترازکننده، با \f[CR]\-\-close\-acct=ACCT\f[R] و/یا \f[CR]\-\-open\-acct=ACCT\f[R] .IP \(bu 2 توضیحات تراکنش، با \f[CR]\-\-close\-desc=DESC\f[R] و \f[CR]\-\-open\-desc=DESC\f[R] .IP \(bu 2 مقدار برچسب \f[CR]clopen\f[R] تراکنش‌ها، با یک آرگومان \f[CR]TAGVAL\f[R] برای پرچم حالت (به بالا مراجعه کنید). .PP به‌طور پیش‌فرض، تاریخ بستن روز گذشته است، یا تاریخ پایان دفتر روزنامه (journal)، هر کدام که دیرتر باشد؛ و تاریخ باز کردن همواره یک روز پس از تاریخ بستن است. می‌توانید با تعیین یک تاریخ پایان گزارش، این موارد را تغییر دهید؛ تاریخ بستن آخرین روز دوره گزارش خواهد بود. برای نمونه \f[CR]\-e 2024\f[R] به معنی \(dqبستن در 2023\-12\-31، باز کردن در 2024\-01\-01\(dq است. .PP با \f[CR]\-\-x/\-\-explicit\f[R]، مقدار ترازکننده به‌صورت صریح نمایش داده می‌شود، و اگر شامل چندین کالا/ارز (commodity) باشد، برای هر کدام از آن‌ها یک ثبتی (posting) جداگانه ایجاد خواهد شد (مشابه \f[CR]print \-x\f[R]). .PP با \f[CR]\-\-interleaved\f[R]، هر انتقالِ جداگانه همراه با ثبت‌های مبدأ و مقصد در کنار یکدیگر نمایش داده می‌شود (که ممکن است برای عیب‌یابی مفید باشد). .PP با \f[CR]\-\-show\-costs\f[R]، بهای تمام‌شده ترازها نیز نمایش داده می‌شود و هزینه‌ها/بهاهای متفاوت جدا از هم نگهداری می‌شوند. این امر در صورت وجود تراکنش‌های متعدد تبدیل ارز یا سرمایه‌گذاری، ممکن است مدخل‌های بسیار بزرگی در دفتر روزنامه ایجاد کند. در حال حاضر \f[CR]close \-\-show\-costs\f[R] بهترین راه برای مشاهده بسته‌های سرمایه‌گذاری (lots) با hledger است. (برای جابجایی یا بستن lotها، اسکریپت توانمندتر \f[CR]hledger\-move\f[R] را ببینید.).SS دستور close و ادعاهای تراز دستور \f[CR]close\f[R] ادعاهای ترازی را اضافه می‌کند که بررسی می‌کنند آیا حساب‌ها در یک تراکنش بستن، صفر شده‌اند یا در یک تراکنش افتتاحیه، به ترازهای پیشین خود بازگردانده شده‌اند. این ادعاها بررسی خطای مفیدی را فراهم می‌کنند، اما می‌توانید با \f[CR]\-I\f[R] موقتاً آن‌ها را نادیده بگیرید، یا در صورت تمایل آن‌ها را حذف کنید. .PP به‌طور پیش‌فرض، ادعاهای تراز تک‌کالایی و بدون احتساب زیرحساب‌ها (\f[CR]=\f[R]) تولید می‌شوند. این مورد را می‌توان تغییر داد، برای نمونه با \f[CR]\-\-assertion\-type=\(aq==*\(aq\f[R]. .PP هنگام اجرای \f[CR]close\f[R] احتمالاً باید از به‌کارگیری \f[CR]\-C\f[R]، \f[CR]\-R\f[R]، \f[CR]status:\f[R] (فیلتر کردن بر اساس وضعیت یا واقعی بودن) یا \f[CR]\-\-auto\f[R] (تولید ثبت‌ها) خودداری کنید، چرا که ادعاهای تراز تولیدشده پس از آن به این موارد نیاز خواهند داشت. .PP تراکنش‌هایی با چندین تاریخ (مانند تاریخ‌های ثبت) که از مرز فایل فراتر می‌روند نیز می‌توانند ادعاهای تراز را با اختلال مواجه کنند: .IP .EX 2023\-12\-30 a purchase made in december, cleared in january expenses:food 5 assets:bank:checking \-5 ; date: 2023\-01\-02 .EE .PP برای حل این مشکل می‌توانید پول را به و از یک حساب موقت منتقل کنید، و تراکنش چندروزه را به دو تراکنش یک‌روزه تقسیم نمایید: .IP .EX ; in 2022.journal: 2022\-12\-30 a purchase made in december, cleared in january expenses:food 5 equity:pending \-5 ; in 2023.journal: 2023\-01\-02 last year\(aqs transaction cleared equity:pending 5 = 0 assets:bank:checking \-5 .EE .SS مثال‌های close .SS سود انباشته (Retain earnings) ثبت درآمدها/هزینه‌های سال 2022 به عنوان سود انباشته در تاریخ 2022\-12\-31، با الحاق تراکنش تولیدشده به انتهای فایل journal: .IP .EX $ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal .EE .PP پس از این کار، برای مشاهده درآمدها و هزینه‌های سال 2022 باید تراکنش سود انباشته (retain earnings) را مستثنی کنید: .IP .EX $ hledger \-f 2022.journal is not:desc:\(aqretain earnings\(aq .EE .SS انتقال ترازها به یک فایل جدید بستن دارایی‌ها/بدهی‌ها در تاریخ 2022\-12\-31 و بازگشایی مجدد آن‌ها در تاریخ 2023\-01\-01: .IP .EX $ hledger close \-\-clopen \-f 2022.journal \-p 2022 # copy/paste the closing transaction to the end of 2022.journal # copy/paste the opening transaction to the start of 2023.journal .EE .PP پس از این کار، برای مشاهده ترازهای پایان سال 2022 باید تراکنش ترازهای پایانی (closing balances) را مستثنی کنید: .IP .EX $ hledger \-f 2022.journal bs not:desc:\(aqclosing balances\(aq .EE .PP برای انعطاف‌پذیری بیشتر، برچسب‌گذاری تراکنش‌های بستن و بازگشایی با مواردی نظیر \f[CR]clopen:NEWYEAR\f[R] کمک‌کننده است؛ سپس می‌توانید با مستثنی کردن تمام تراکنش‌های بازگشایی/بستن به جز مورد اول، از درستی ترازها اطمینان حاصل کنید، مانند زیر: .IP .EX $ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\(aqtag:clopen=2021 or not tag:clopen\(aq $ hledger bs \-Y \-f 2021.j \-f 2022.j expr:\(aqtag:clopen=2021 or not tag:clopen\(aq $ hledger bs \-Y \-f 2022.j \-f 2023.j expr:\(aqtag:clopen=2022 or not tag:clopen\(aq $ hledger bs \-Y \-f 2021.j expr:\(aqtag:clopen=2021 or not tag:clopen\(aq $ hledger bs \-Y \-f 2022.j expr:\(aqtag:clopen=2022 or not tag:clopen\(aq $ hledger bs \-Y \-f 2023.j # unclosed file, no query needed .EE.SS مثال‌های با جزئیات بیشتر برای بستن حساب‌ها به examples/multi\-year مراجعه کنید. .SS rewrite تمام تراکنش‌ها را با بازنویسی ثبت‌های تراکنش‌های منطبق چاپ می‌کند. در حال حاضر تنها بازنویسی موجود، افزودن ثبت‌های جدید است، مانند print \-\-auto. .IP .EX Flags: \-\-add\-posting=\(aqACCT AMTEXPR\(aq add a posting to ACCT, which may be parenthesised. AMTEXPR is either a literal amount, or *N which means the transaction\(aqs first matched amount multiplied by N (a decimal number). Two spaces separate ACCT and AMTEXPR. \-\-diff generate diff suitable as an input for patch tool .EE .PP این ابزار، آغازی برای یک بازنویس عمومی ورودی‌های تراکنش است. دفتر روزنامه پیش‌فرض را می‌خواند و همانند print تراکنش‌ها را چاپ می‌کند، اما یک یا چند ثبت مشخص‌شده را به هر تراکنش منطبق با QUERY اضافه می‌کند. مبالغ ثبت‌ها می‌تواند ثابت باشد، یا ضریبی از مبلغ اولین ثبت تراکنش موجود. .PP مثال‌ها: .IP .EX $ hledger\-rewrite.hs \(haincome \-\-add\-posting \(aq(liabilities:tax) *.33 ; income tax\(aq \-\-add\-posting \(aq(reserve:gifts) $100\(aq $ hledger\-rewrite.hs expenses:gifts \-\-add\-posting \(aq(reserve:gifts) *\-1\(dq\(aq $ hledger\-rewrite.hs \-f rewrites.hledger .EE .PP فایل rewrites.hledger می‌تواند شامل ورودی‌هایی مانند این باشد: .IP .EX = \(haincome amt:<0 date:2017 (liabilities:tax) *0.33 ; tax on income (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery .EE .PP به علامت‌های نقل‌قول تکی (single quotes) برای محافظت از علامت دلار در برابر bash، و دو فاصله میان حساب و مبلغ دقت کنید. .PP موارد بیشتر: .IP .EX $ hledger rewrite [QUERY] \-\-add\-posting \(dqACCT AMTEXPR\(dq ... $ hledger rewrite \(haincome \-\-add\-posting \(aq(liabilities:tax) *.33\(aq $ hledger rewrite expenses:gifts \-\-add\-posting \(aq(budget:gifts) *\-1\(dq\(aq $ hledger rewrite \(haincome \-\-add\-posting \(aq(budget:foreign currency) *0.25 JPY; diversify\(aq .EE .PP آرگومان گزینه \f[CR]\-\-add\-posting\f[R] یک ثبت معمولی تراکنش است با این استثنا که در مشخص کردن مبلغ تفاوت دارد. به‌طور دقیق‌تر، می‌توانید از نماد ستاره (\f[CR]\(aq*\(aq\f[R]) پیش از مبلغ استفاده کنید تا نشان دهید که این مقدار، ضریبی برای مبلغِ ثبت منطبق‌شده اولیه است. اگر مبلغ شامل نام یک کالا (commodity) باشد، مبلغ ثبت جدید برحسب کالای جدید خواهد بود؛ در غیر این صورت، برحسب کالای مبلغ ثبت منطبق‌شده خواهد بود. .SS قواعد بازنویسی در یک فایل این ابزار هنگام اجرا، به‌اصطلاح «تراکنش‌های خودکار» (\(dqAutomated Transactions\(dq) موجود در هر دفتر روزنامه‌ای را که پردازش می‌کند اجرا خواهد کرد. به این معنی که به جای مشخص کردن این عملیات‌ها در خط فرمان، می‌توانید آن‌ها را در یک فایل دفتر روزنامه قرار دهید. .IP .EX $ rewrite\-rules.journal .EE .PP محتویات را به این شکل تنظیم کنید: .IP .EX = \(haincome (liabilities:tax) *.33 = expenses:gifts budget:gifts *\-1 assets:budget *1 .EE .PP به نماد مساوی (\f[CR]\(aq=\(aq\f[R]) دقت کنید که به جای تاریخ، در تراکنش‌هایی که معمولاً می‌نویسید استفاده شده است. این نماد، پرسمانی (query) را مشخص می‌کند که می‌خواهید ثبت‌ها را با آن تطبیق دهید تا ثبت‌های جدید اضافه شوند. .IP .EX $ hledger rewrite \-f input.journal \-f rewrite\-rules.journal > rewritten\-tidy\-output.journal .EE .PP این عملکرد مشابه خط لوله (pipeline) دستورهای زیر است: .IP .EX $ hledger rewrite \-f input.journal \(aq\(haincome\(aq \-\-add\-posting \(aq(liabilities:tax) *.33\(aq \(rs | hledger rewrite \-f \- expenses:gifts \-\-add\-posting \(aqbudget:gifts *\-1\(aq \(rs \-\-add\-posting \(aqassets:budget *1\(aq \(rs > rewritten\-tidy\-output.journal .EE .PP درک این نکته ضروری است که ترتیب نسبی این ورودی‌ها در دفتر روزنامه اهمیت دارد. شما می‌توانید از نتیجه ثبت‌هایی که پیش‌تر اضافه شده‌اند مجدداً استفاده کنید..SS قالب خروجی Diff برای استفاده از این ابزار جهت تغییرات دسته‌ای (batch) فایل‌های journal خود، خروجی در قالب تفاوت یکپارچه (unified diff) می‌تواند برای شما مفید باشد. .IP .EX $ hledger rewrite \-\-diff \-f examples/sample.journal \(aq\(haincome\(aq \-\-add\-posting \(aq(liabilities:tax) *.33\(aq .EE .PP خروجی ممکن است به این صورت باشد: .IP .EX \-\-\- /tmp/examples/sample.journal +++ /tmp/examples/sample.journal \(at\(at \-18,3 +18,4 \(at\(at 2008/01/01 income \- assets:bank:checking $1 + assets:bank:checking $1 income:salary + (liabilities:tax) 0 \(at\(at \-22,3 +23,4 \(at\(at 2008/06/01 gift \- assets:bank:checking $1 + assets:bank:checking $1 income:gifts + (liabilities:tax) 0 .EE .PP اگر این خروجی را به ابزار \f[CR]patch\f[R] منتقل کنید، تراکنش‌های شامل ثبت‌هایی (posting) که با پرس‌وجوی شما مطابقت دارند به‌روزرسانی خواهند شد. توجه داشته باشید که بر اساس فهرست فایل‌های ورودی مشخص‌شده از طریق گزینه‌های \f[CR]\-\-file\f[R] و دستورالعمل‌های \f[CR]include\f[R] درون این فایل‌ها، ممکن است چندین فایل به‌روزرسانی شوند. .PP مراقب باشید. کل تراکنش به سبک خروجی دستور \f[CR]hledger print\f[R] بازقالب‌بندی می‌شود. .PP همچنین ببینید: .PP https://github.com/simonmichael/hledger/issues/99 .SS مقایسه rewrite با print \-\-auto این دستور پیش از print \-\-auto ارائه شده است و در حال حاضر تا حد زیادی عملکرد مشابهی دارد، اما با این تفاوت‌ها: .IP \(bu 2 در حالت چندفایلی، rewrite اجازه می‌دهد تا قوانین موجود در هر فایل بر تمام فایل‌های دیگر تأثیر بگذارند. print \-\-auto از محدوده‌بندی استاندارد دستورالعمل‌ها استفاده می‌کند؛ بدین ترتیب قوانین تنها بر فایل‌های فرزند اثر می‌گذارند. .IP \(bu 2 پرس‌وجوی rewrite تعیین می‌کند کدام تراکنش‌ها می‌توانند بازنویسی شوند؛ در حالی که همه تراکنش‌ها چاپ می‌شوند. پرس‌وجوی print \-\-auto مشخص می‌کند که کدام تراکنش‌ها چاپ شوند. .IP \(bu 2 دستور rewrite قواعد مشخص‌شده در خط فرمان یا در journal را اعمال می‌کند. دستور print \-\-auto قواعد مشخص‌شده در journal را اعمال می‌کند. .SH "دستورهای نگهداری (MAINTENANCE COMMANDS)" .SS check بررسی انواع مختلف خطاها در داده‌های شما. .IP .EX Flags: no command\-specific flags .EE .PP ابزار hledger تعدادی بررسی توکار برای سنجش درستی ارائه می‌دهد تا به اعتبارسنجی داده‌های شما و جلوگیری از خطاها کمک کند. برخی از آن‌ها به‌صورت خودکار اجرا می‌شوند و برخی هنگام فعال کردن حالت \f[CR]\-\-strict\f[R]؛ یا می‌توانید هر کدام را برحسب نیاز با ارائه به‌عنوان آرگومان به دستور \f[CR]check\f[R] اجرا کنید. اگر همه‌چیز درست باشد، \f[CR]check\f[R] هیچ خروجی تولید نمی‌کند و با کد وضعیت صفر خارج می‌شود. برای مثال: .IP .EX hledger check # run basic checks hledger check \-s # run basic and strict checks hledger check ordereddates payees # run basic checks and two others .EE .PP اگر از کاربران Emacs هستید، می‌توانید flycheck\-hledger را نیز برای اجرای این بررسی‌ها پیکربندی کنید تا هنگام ویرایش journal، بازخورد آنی دریافت نمایید. .PP بررسی‌های موجود در حال حاضر در اینجا آمده است. این موارد معمولاً به همان ترتیبی که در اینجا نشان داده شده بررسی می‌شوند و فقط اولین خطا گزارش خواهد شد..SS "بررسی‌های پایه (Basic checks)" این بررسی‌های مهم به‌طور پیش‌فرض توسط تقریباً تمامی دستورهای hledger انجام می‌شوند: .IP \(bu 2 \f[B]parseable\f[R] \- فایل‌های داده در قالبی پشتیبانی‌شده هستند و هیچ خطای نحوی یا دستورالعمل include نامعتبری ندارند. این بررسی تضمین می‌کند که همهٔ فایل‌ها وجود دارند و قابل خواندن هستند. .IP \(bu 2 \f[B]autobalanced\f[R] \- همهٔ تراکنش‌ها پس از استنتاج خودکار مقادیر ناموجود و نرخ‌های تبدیل و سپس تبدیل مبالغ به بهای تمام‌شده، تراز هستند. این بررسی تضمین می‌کند که مدخل دفتر روزنامهٔ هر تراکنش ساختار درستی دارد. .IP \(bu 2 \f[B]assertions\f[R] \- همهٔ ادعاهای تراز (balance assertions) در دفتر روزنامه برقرار هستند. ادعاهای تراز دفاعی محکم در برابر خطاها هستند و مشکلات زیادی را شناسایی می‌کنند. این بررسی به‌طور پیش‌فرض فعال است، اما اگر برایتان مانعی ایجاد می‌کند، می‌توانید آن را موقتاً با \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] یا به‌طور پیش‌فرض با افزودن این پرچم به فایل پیکربندی خود غیرفعال کنید. (سپس هر زمان که مایل به فعال‌سازی مجدد آن بودید از \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] یا \f[CR]hledger check assertions\f[R] استفاده کنید). .SS "بررسی‌های سخت‌گیرانه (Strict checks)" هنگامی که پرچم \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] استفاده شود (معروف به حالت سخت‌گیرانه یا strict mode)، تمامی دستورها بررسی‌های تکمیلی زیر (و همچنین \f[CR]assertions\f[R] در بالا) را انجام خواهند داد. این بررسی‌ها قدرت خطایابی بیشتری را فراهم می‌کنند تا به شما در تمیز و صحیح نگه‌داشتن داده‌هایتان کمک کنند: .IP \(bu 2 \f[B]balanced\f[R] \- مانند \f[CR]autobalanced\f[R] است، اما تبدیل‌های ضمنی میان کالاها مجاز نیستند؛ تمامی تراکنش‌های تبدیل باید از نمادگذاری بهای تمام‌شده یا ثبت‌های ارزش ویژه (equity postings) استفاده کنند. این بررسی از تبدیل‌های نادرست ناشی از خطاهای تایپی جلوگیری می‌کند. .IP \(bu 2 \f[B]commodities\f[R] \- تمامی نمادهای کالای (commodity) استفاده‌شده باید تعریف شده باشند. این بررسی در برابر خطای تایپی یا جا انداختن نمادهای کالا محافظت می‌کند. .IP \(bu 2 \f[B]accounts\f[R] \- تمامی نام‌های حساب استفاده‌شده باید تعریف شده باشند. این بررسی از به‌کارگیری نام‌های حساب دارای غلط املایی یا منسوخ‌شده جلوگیری می‌کند. .SS "سایر بررسی‌ها (Other checks)" این بررسی‌ها مورد نیاز همگان نیستند، اما می‌توان آن‌ها را با استفاده از دستور \f[CR]check\f[R] اجرا کرد: .IP \(bu 2 \f[B]tags\f[R] \- تمامی برچسب‌های استفاده‌شده باید تعریف شده باشند. این کار از نام‌های برچسب دارای غلط املایی جلوگیری می‌کند. توجه داشته باشید که hledger اغلب اوقات برچسب‌های ناخواسته‌ای را در توضیحات پیدا می‌کند. .IP \(bu 2 \f[B]payees\f[R] \- تمامی دریافت‌کنندگان وجه (payees) استفاده‌شده در تراکنش‌ها باید تعریف شده باشند. این بررسی شما را وادار می‌کند تا پیش از استفاده از هر نام طرف حساب جدید، آن را تعریف کنید. احتمالاً بیشتر افراد این مورد را کمی بیش از حد سخت‌گیرانه می‌دانند. .IP \(bu 2 \f[B]ordereddates\f[R] \- درون هر فایل، تراکنش‌ها باید بر اساس تاریخ مرتب شده باشند. این یک خطایاب ساده و مؤثر است. این مورد در حالت سخت‌گیرانه گنجانده نشده است، اما می‌توانید با اجرای \f[CR]hledger check \-s ordereddates\f[R] آن را اضافه کنید. در صورت فعال بودن، این بررسی پیش از ادعاهای تراز انجام می‌شود. .IP \(bu 2 \f[B]recentassertions\f[R] \- تمامی حساب‌های دارای ادعای تراز باید دست‌کم یک ادعا داشته باشند که در بازهٔ ۷ روز پیش از آخرین ثبت (posting) آن‌ها باشد. این کار شما را به افزودن ادعاهای تراز برای حساب‌های فعال دارایی/بدهی تشویق می‌کند، که به نوبهٔ خود شما را به تطبیق و مغایرت‌گیری منظم با مانده‌های دنیای واقعی ترغیب خواهد کرد \- که دفاع محکم دیگری در برابر خطاهاست. (\f[CR]hledger close \-\-assert >>$LEDGER_FILE\f[R] روشی مناسب برای افزودن ادعاهای تراز جدید است. بعداً این موارد کاملاً زاید می‌شوند و ممکن است برای کاهش شلوغی، حذف آن‌ها را انتخاب کنید). .IP \(bu 2 \f[B]uniqueleafnames\f[R] \- هیچ دو حسابی نباید بخش انتهایی نام حسابِ یکسانی داشته باشند (برای نمونه \f[CR]checking\f[R] در \f[CR]assets:bank:checking\f[R]). این امر تضمین می‌کند که هر حساب با یک نام کوتاه یکتا قابل تطبیق باشد، که به خاطر سپردن و تایپ آن آسان‌تر است. .SS "بررسی‌های سفارشی (Custom checks)" می‌توانید بررسی‌های سفارشی خود را با اسکریپت‌های دستوری الحاقی (add\-on) بسازید. همچنین بخش Cookbook > Scripting را ببینید. در اینجا چند نمونه از hledger/bin/ آورده شده است: .IP \(bu 2 \f[B]hledger\-check\-tagfiles\f[R] \- تمامی مقادیر برچسب حاوی \f[CR]/\f[R] به‌عنوان مسیر فایل وجود داشته باشند .IP \(bu 2 \f[B]hledger\-check\-fancyassertions\f[R] \- ادعاهای تراز پیچیده‌تر با موفقیت برقرار شوند.SS diff تراکنش‌های یک حساب مشخص را در دو فایل ورودی با یکدیگر مقایسه می‌کند. تراکنش‌های مربوط به این حساب را که در یکی از فایل‌ها وجود دارند ولی در دیگری نیستند، نمایش می‌دهد. .IP .EX Flags: no command\-specific flags .EE .PP به‌طور دقیق‌تر: برای هر ثبت (posting) مؤثر بر این حساب در هر یک از دو فایل، این دستور به‌دنبال ثبتی متناظر در فایل دیگر می‌گردد که همان مبلغ را به همان حساب منتقل کرده باشد (با نادیده گرفتن تاریخ، شرح و غیره). .PP از آنجا که این دستور ثبت‌ها (postings) را مقایسه می‌کند و نه تراکنش‌ها را، در مواردی که چند تراکنش بانکی در قالب یک مدخل دفتر روزنامه (journal entry) ترکیب شده باشند نیز کار می‌کند. .PP این دستور به‌عنوان مثال زمانی مفید است که تراکنش‌های یک حساب را از بانک خود دریافت کرده باشید (مثلاً در قالب داده‌های CSV): هنگامی که hledger و بانک شما بر سر موجودی حساب اختلاف دارند، می‌توانید داده‌های بانک را با دفتر روزنامهٔ خود مقایسه کنید تا علت را بیابید. .PP مثال‌ها: .IP .EX $ hledger diff \-f $LEDGER_FILE \-f bank.csv assets:bank:giro These transactions are in the first file only: 2014/01/01 Opening Balances assets:bank:giro EUR ... ... equity:opening balances EUR \-... These transactions are in the second file only: .EE .SS setup بررسی وضعیت نصب hledger. .IP .EX Flags: no command\-specific flags .EE .PP دستور \f[CR]setup\f[R] وضعیت نصب hledger شما را آزمایش کرده و فهرستی از نتایج را، گاهی همراه با راهنمایی‌های مفید، چاپ می‌کند. این دستور، نخستین دستور مناسب برای اجرا پس از نصب hledger است؛ همچنین پس از ارتقا، یا هنگامی که چیزی درست کار نمی‌کند، یا صرفاً زمانی که می‌خواهید یادآوری شود که اجزای مختلف در کجا قرار دارند. .PP این دستور یک درخواست شبکه برای شناسایی آخرین نسخهٔ منتشرشدهٔ hledger ارسال می‌کند. در صورتی که این درخواست با خطا مواجه شود یا مهلت زمانی آن پایان یابد (timeout)، مشکلی ایجاد نمی‌شود. به‌طور پیش‌فرض از رنگ‌های ANSI استفاده خواهد شد، مگر اینکه توسط NO_COLOR یا \-\-color=n غیرفعال شده باشد. از صفحه‌بند (pager) یا فایل پیکربندی استفاده نمی‌کند. .PP این دستور انتظار دارد نسخهٔ hledger در حال اجرا، در PATH شما نصب شده باشد. اگر چنین نباشد، تا زمانی که این کار را انجام ندهید متوقف خواهد شد (برای ساده نگه‌داشتن امور). .PP مثال: .IP .EX $ hledger setup Checking your hledger setup.. Legend: good, neutral, unknown, warning hledger * is a released version ? no hledger 1.42.99\-gbca4b39c5\-20250425, mac\-aarch64 * is up to date ? yes 1.42.99 installed, latest is 1.42.1 * is a native binary for this machine ? yes aarch64 * is installed in PATH ? yes /Users/simon/.local/bin/hledger * has a system text encoding configured ? yes UTF\-8, data files should use this encoding * has a user config file ? (optional) no * current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf * the config file is readable ? yes /Users/simon/src/hledger/hledger.conf terminal * the NO_COLOR variable is defined ? no * \-\-color is configured by config file ? no * hledger will use color by default ? yes * the PAGER variable is defined ? yes less * \-\-pager is configured by config file ? no * hledger will use a pager when needed ? yes /opt/homebrew/bin/less * the LESS variable is defined ? yes * the HLEDGER_LESS variable is defined ? no * adjusting LESS variable for color etc. ? yes * \-\-pretty is enabled by config file ? no tables will use ASCII characters * bash shell completions are installed ? ? * zsh shell completions are installed ? ? journal * the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal * a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal * it includes additional files ? yes 15 * all commodities are declared ? yes 10 * all accounts are declared ? yes 160 * all accounts have types ? no 14 untyped * accounts of each type were detected ? yes ALERXCV * commodities/accounts are checked ? no use \-s to check commodities/accounts * balance assertions are checked ? yes use \-I to ignore assertions .EE.SS test اجرای آزمون‌های واحد توکار. .IP .EX Flags: no command\-specific flags .EE .PP این دستور آزمون‌های واحد توکار در hledger و hledger\-lib را اجرا کرده و نتایج را در stdout چاپ می‌کند. اگر آزمونی شکست بخورد، وضعیت خروج غیرصفر خواهد بود. .PP این دستور عمدتاً توسط توسعه‌دهندگان hledger استفاده می‌شود، اما شما نیز می‌توانید برای بررسی سلامت (sanity\-check) فایل اجرایی hledger نصب‌شده روی پلتفرم خود از آن استفاده کنید. انتظار می‌رود همهٔ آزمون‌ها با موفقیت سپری شوند \- اگر با شکستی مواجه شدید، لطفاً آن را به‌عنوان باگ گزارش دهید! .PP هر آرگومانی قبل از یک آرگومان \f[CR]\-\-\f[R] به‌عنوان الگوهای \-p انتخاب آزمون به اجراکنندهٔ آزمون \f[CR]tasty\f[R] ارسال خواهد شد، و هر آرگومانی بعد از \f[CR]\-\-\f[R] بدون تغییر به tasty تحویل داده می‌شود. .PP مثال‌ها: .IP .EX $ hledger test # run all unit tests $ hledger test balance # run tests with \(dqbalance\(dq in their name $ hledger test \-\- \-h # show tasty\(aqs options .EE .PP .SH "بخش ۵: کارهای متداول (PART 5: COMMON TASKS)" در اینجا چند مثال سریع از نحوهٔ انجام برخی کارهای پایه‌ای با hledger آورده شده است. .SS دریافت راهنمایی (Getting help) روش فهرست کردن دستورها و مشاهدهٔ گزینه‌ها و مستندات دستورها به این صورت است: .IP .EX $ hledger # show available commands $ hledger \-\-help # show common options $ hledger CMD \-\-help # show CMD\(aqs options, common options and CMD\(aqs documentation .EE .PP شما همچنین می‌توانید با استفاده از دستور help، کتابچهٔ راهنمای نسخهٔ hledger خود را در چندین قالب مختلف مشاهده کنید. به‌عنوان مثال: .IP .EX $ hledger help # show the hledger manual with info, man or $PAGER (best available) $ hledger help journal # show the journal topic in the hledger manual $ hledger help \-\-help # find out more about the help command .EE .PP برای مشاهدهٔ کتابچه‌های راهنما و مستندات مقدماتی در وب، به https://hledger.org مراجعه کنید. پشتیبانی گفتگو و فهرست پستی و بایگانی بحث‌ها را می‌توانید در https://hledger.org/support بیابید. .SS ساخت خطوط فرمان (Constructing command lines) دستور hledger دارای یک رابط خط فرمان انعطاف‌پذیر است. ما تلاش می‌کنیم آن را ساده و ارگونومیک نگه داریم، اما اگر به یکی از نکات دشوار توصیف‌شده در گزینه‌ها (OPTIONS) برخوردید، این نکات ممکن است کمک‌کننده باشند: .IP \(bu 2 گزینه‌های ویژهٔ دستور باید پس از دستور قرار گیرند (قرار دادن گزینه‌های عمومی در آنجا نیز مانعی ندارد: \f[CR]hledger CMD OPTS ARGS\f[R]) .IP \(bu 2 می‌توانید دستورهای افزونه را از طریق hledger (\f[CR]hledger ui [ARGS]\f[R]) یا مستقیماً (\f[CR]hledger\-ui [ARGS]\f[R]) اجرا کنید .IP \(bu 2 آرگومان‌های \(dqمشکل‌ساز\(dq را در علامت نقل‌قول تکی (single quotes) قرار دهید .IP \(bu 2 در صورت نیاز، یک بک‌اسلش اضافه کنید تا نویسه‌های خاص عبارت باقاعده از دید پوسته پنهان بمانند .IP \(bu 2 برای مشاهدهٔ نحوهٔ تجزیه شدن خط فرمانی که رفتار نادرستی دارد، \f[CR]\-\-debug=2\f[R] را اضافه کنید. .SS شروع یک فایل journal دستور hledger به‌طور پیش‌فرض داده‌های حسابداری شما را در یک فایل journal به نشانی \f[CR]$HOME/.hledger.journal\f[R] جستجو می‌کند: .IP .EX $ hledger stats The hledger journal file \(dq/Users/simon/.hledger.journal\(dq was not found. Please create it first, eg with \(dqhledger add\(dq or a text editor. Or, specify an existing journal file with \-f or LEDGER_FILE. .EE .PP می‌توانید با تنظیم متغیر محیطی \f[CR]LEDGER_FILE\f[R] این مقدار را بازنویسی کنید (به پایین مراجعه کنید). نگهداری این فایل مهم تحت کنترل نسخه (version control) و شروع یک فایل جدید در هر سال، روش کاری بسیار مناسبی است. بنابراین می‌توانید کاری شبیه به این انجام دهید: .IP .EX $ mkdir \(ti/finance $ cd \(ti/finance $ git init Initialized empty Git repository in /Users/simon/finance/.git/ $ touch 2023.journal $ echo \(dqexport LEDGER_FILE=$HOME/finance/2023.journal\(dq >> \(ti/.profile $ source \(ti/.profile $ hledger stats Main file : /Users/simon/finance/2023.journal Included files : Transactions span : to (0 days) Last transaction : none Transactions : 0 (0.0 per day) Transactions last 30 days: 0 (0.0 per day) Transactions last 7 days : 0 (0.0 per day) Payees/descriptions : 0 Accounts : 0 (depth 0) Commodities : 0 () Market prices : 0 () .EE.SS تنظیم LEDGER_FILE .SS تنظیم LEDGER_FILE در یونیکس این موضوع به شل (shell) شما بستگی دارد، اما اجرای این دستورها در ترمینال برای بیشتر افراد کارساز خواهد بود؛ در صورت نیاز آن را تطبیق دهید: .IP .EX $ echo \(aqexport LEDGER_FILE=\(ti/finance/main.journal\(aq >> \(ti/.profile $ source \(ti/.profile .EE .PP هنگامی که به درستی پیکربندی شود: .IP \(bu 2 دستور \f[CR]env | grep LEDGER_FILE\f[R] تنظیمات جدید شما را نمایش خواهد داد .IP \(bu 2 و \f[CR]hledger setup\f[R] و \f[CR]hledger files\f[R] نیز باید همین کار را انجام دهند. .SS تنظیم LEDGER_FILE در مک در یک پنجرهٔ ترمینال، مراحل یونیکس ذکرشده در بالا را دنبال کنید. .PP همچنین، این مرحلهٔ اختیاری ممکن است برای برنامه‌های دارای رابط گرافیکی (GUI) مفید باشد: .IP "1." 3 یک مدخل به \f[CR]\(ti/.MacOSX/environment.plist\f[R] اضافه کنید، مانند: .RS 4 .IP .EX { \(dqLEDGER_FILE\(dq : \(dq\(ti/finance/main.journal\(dq } .EE .RE .IP "2." 3 دستور \f[CR]killall Dock\f[R] را در یک پنجرهٔ ترمینال اجرا کنید (یا رایانه را مجدداً راه‌اندازی کنید) تا تغییرات اعمال شوند. .PP هنگامی که به درستی برای برنامه‌های گرافیکی پیکربندی شود: .IP \(bu 2 برنامه‌هایی که از dock یا جستجوی spotlight اجرا می‌شوند، مانند Emacs گرافیکی، از تنظیم جدید LEDGER_FILE مطلع خواهند شد. .SS تنظیم LEDGER_FILE در ویندوز ایجاد یک فایل پیش‌فرض در مسیر \f[CR]C:\(rsUsers\(rsUSER\(rs.hledger.journal\f[R] و درج فایل‌های دیگر درون آن می‌تواند ساده‌تر باشد. به بخش \(dqI\(aqm on Windows, how do I keep my files in AppData?\(dq رجوع کنید. .PP در غیر این صورت، استفاده از رابط گرافیکی آسان‌ترین راه است: .IP "1." 3 در نوار وظیفه (task bar)، عبارت \f[CR]environment variables\f[R] را جستجو کرده و گزینهٔ \(dqEdit environment variables for your account\(dq را انتخاب کنید. .IP "2." 3 در بخش متغیرهای کاربر (User variables)، تنظیم \f[CR]LEDGER_FILE\f[R] را ایجاد کرده یا تغییر دهید. یک مقدار معمول بدین شکل است: \f[CR]C:\(rsUsers\(rsUSER\(rsfinance\(rsmain.journal\f[R]. .IP "3." 3 برای نهایی‌سازی تغییرات روی OK کلیک کنید. .IP "4." 3 و یک پنجرهٔ powershell جدید باز کنید. (پنجره‌های موجود این تغییر را مشاهده نخواهند کرد.) .PP یا در خط فرمان، می‌توانید این کار را بدین صورت انجام دهید: .IP "1." 3 در یک پنجرهٔ powershell، دستور زیر را اجرا کنید: \f[CR][Environment]::SetEnvironmentVariable(\(dqLEDGER_FILE\(dq, \(dqC:\(rsUser\(rsUSER\(rsfinance\(rsmain.journal\(dq, [System.EnvironmentVariableTarget]::User)\f[R] .IP "2." 3 و یک پنجرهٔ powershell جدید باز کنید. (پنجره‌های موجود این تغییر را مشاهده نخواهند کرد.) .PP هشدار: انجام این کار از خط فرمان ویندوز می‌تواند پیچیده باشد؛ روش‌های دیگری که ممکن است در اینترنت بیابید: .IP \(bu 2 ممکن است بر پنجرهٔ فعلی تأثیر نگذارند .IP \(bu 2 ممکن است دائمی نباشند .IP \(bu 2 ممکن است کار نکنند مگر اینکه مدیر سیستم (administrator) باشید .IP \(bu 2 ممکن است مقدارها را به ۱۰۲۴ نویسه محدود کنند .IP \(bu 2 ممکن است ارجاعات پویا به متغیرهای دیگر را با خطا مواجه کنند .IP \(bu 2 ممکن است به نگارش به‌اندازهٔ کافی جدیدی از powershell نیاز داشته باشند .IP \(bu 2 یا ممکن است برای پنجرهٔ خط فرمان قدیمی‌تر (command window) طراحی شده باشند. .IP \(bu 2 اگر همچنان با مشکل مواجه هستید، برای نمونه به \(dqSetting Windows PowerShell environment variables\(dq یا \(dqAdding path permanently to windows using powershell doesn\(aqt appear to work\(dq رجوع کنید. .PP هنگامی که به درستی پیکربندی شود: .IP \(bu 2 در یک پنجرهٔ powershell جدید، دستور \f[CR]$env:LEDGER_FILE\f[R] تنظیمات جدید شما را نمایش خواهد داد .IP \(bu 2 و \f[CR]hledger setup\f[R] و (پس از ایجاد فایل) \f[CR]hledger files\f[R] نیز باید همین کار را انجام دهند..SS تنظیم مانده‌های آغازین یک تاریخ آغازین انتخاب کنید که در آن بتوانید مانده‌های برخی از دارایی‌های واقعی (حساب‌های بانکی، کیف پول و...) و بدهی‌ها (کارت‌های اعتباری و...) را بررسی کنید. .PP برای جلوگیری از ورود حجم زیادی از داده‌ها، ممکن است بخواهید تنها با یک یا دو حساب شروع کنید، مانند حساب جاری یا کیف پول نقد؛ و یک تاریخ آغازین نزدیک را انتخاب نمایید، مانند امروز یا ابتدای هفته. همیشه می‌توانید بعداً بازگردید و حساب‌های بیشتر و تراکنش‌های قدیمی‌تری را اضافه کنید، به عنوان مثال تا اول ژانویه به عقب برگردید. .PP یک تراکنش مانده‌های آغازین به دفتر روزنامه (journal) اضافه کنید و مانده‌ها را در این تاریخ اعلام نمایید. در اینجا دو روش برای انجام این کار آورده شده است: .IP \(bu 2 روش اول: دفتر روزنامه را در هر ویرایشگر متنی باز کرده و مدخلی مانند این را ذخیره کنید: .RS 2 .IP .EX 2023\-01\-01 * opening balances assets:bank:checking $1000 = $1000 assets:bank:savings $2000 = $2000 assets:cash $100 = $100 liabilities:creditcard $\-50 = $\-50 equity:opening/closing balances .EE .PP این‌ها مانده‌های ابتدای روز هستند، یعنی هر آنچه که در پایان روز قبل در حساب موجود بوده است. .PP علامت * پس از تاریخ یک پرچم وضعیت اختیاری است. در اینجا این علامت به معنای \(dqتسویه‌شده و تأییدشده\(dq است. .PP نمادهای ارز اختیاری هستند، اما معمولاً ایدهٔ خوبی است زیرا دیر یا زود با چندین ارز سر و کار خواهید داشت. .PP مبالغ دارای = تصدیق‌های اختیاری مانده (balance assertions) هستند که امکان خطایابی مضاعف را فراهم می‌کنند. .RE .IP \(bu 2 روش دوم: دستور \f[CR]hledger add\f[R] را اجرا کرده و اعلان‌ها را برای ثبت یک تراکنش مشابه دنبال کنید: .RS 2 .IP .EX $ hledger add Adding transactions to journal file /Users/simon/finance/2023.journal Any command line arguments will be used as defaults. Use tab key to complete, readline keys to edit, enter to accept defaults. An optional (CODE) may follow transaction dates. An optional ; COMMENT may follow descriptions or amounts. If you make a mistake, enter < at any prompt to go one step backward. To end a transaction, enter . when prompted. To quit, enter . at a date prompt or press control\-d or control\-c. Date [2023\-02\-07]: 2023\-01\-01 Description: * opening balances Account 1: assets:bank:checking Amount 1: $1000 Account 2: assets:bank:savings Amount 2 [$\-1000]: $2000 Account 3: assets:cash Amount 3 [$\-3000]: $100 Account 4: liabilities:creditcard Amount 4 [$\-3100]: $\-50 Account 5: equity:opening/closing balances Amount 5 [$\-3050]: Account 6 (or . or enter to finish this transaction): . 2023\-01\-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 liabilities:creditcard $\-50 equity:opening/closing balances $\-3050 Save this transaction to the journal ? [y]: Saved. Starting the next transaction (. or ctrl\-D/ctrl\-C to quit) Date [2023\-01\-01]: . .EE .RE .PP اگر از سیستم کنترل نسخه استفاده می‌کنید، اکنون می‌تواند زمان مناسبی برای commit کردن دفتر روزنامه باشد. به عنوان مثال: .IP .EX $ git commit \-m \(aqinitial balances\(aq 2023.journal .EE.SS ثبت تراکنش‌ها (Recording transactions) هنگامی که پولی خرج کرده یا دریافت می‌کنید، می‌توانید این تراکنش‌ها را با استفاده از یکی از روش‌های بالا (ویرایشگر متن، \f[CR]hledger add\f[R])، با استفاده از افزونه‌های \f[CR]hledger\-iadd\f[R] یا \f[CR]hledger\-web\f[R]، یا با استفاده از دستور \f[CR]import\f[R] برای تبدیل داده‌های CSV بارگیری‌شده از بانک خود ثبت کنید. .PP در اینجا چند نمونه تراکنش ساده آورده شده است؛ برای ایده‌های بیشتر دفترچه راهنمای \f[CR]hledger_journal(5)\f[R] و hledger.org را ببینید: .IP .EX 2023/1/10 * gift received assets:cash $20 income:gifts 2023.1.12 * farmers market expenses:food $13 assets:cash 2023\-01\-15 paycheck income:salary assets:bank:checking $1000 .EE .SS تطبیق و مغایرت‌گیری (Reconciling) به‌طور دوره‌ای باید حساب‌ها را تطبیق دهید \- یعنی موجودی‌های گزارش‌شده توسط hledger را با منابع خارجی موثق، مانند صورت‌حساب‌های بانکی یا وبگاه بانک خود مقایسه کنید \- تا مطمئن شوید که دفتر شما به‌درستی موجودی‌های دنیای واقعی را نشان می‌دهد (و همچنین اینکه مؤسسات مالی دنیای واقعی اشتباهی نکرده باشند!). این کار با (۱) تمرین و (۲) تکرار مداوم، آسان و سریع می‌شود. اگر آن را روزانه انجام دهید، ممکن است بین ۲ تا ۱۰ دقیقه زمان ببرد. اگر بگذارید روی هم انباشته شود، با صرف وقت برای یافتن خطاها و مغایرت‌ها، انتظار داشته باشید که زمان بیشتری طول بکشد. .PP یک گردش کار معمول: .IP "1." 3 تطبیق وجه نقد. آنچه را که در کیف پولتان هست بشمارید. آن را با آنچه hledger گزارش می‌دهد مقایسه کنید (\f[CR]hledger bal cash\f[R]). اگر متفاوت هستند، سعی کنید تراکنش فراموش‌شده را به خاطر بیاورید، یا به دنبال خطا در تراکنش‌های ثبت‌شده بگردید. یک گزارش دفتر روزنامه می‌تواند مفید باشد (\f[CR]hledger reg cash\f[R]). اگر نمی‌توانید خطا را پیدا کنید، یک تراکنش تعدیل اضافه کنید. به عنوان مثال اگر پس از موارد بالا ۱۰۵ دلار دارید، و نمی‌توانید ۲ دلار گم‌شده را توجیه کنید، می‌تواند به این شکل باشد: .RS 4 .IP .EX 2023\-01\-16 * adjust cash assets:cash $\-2 = $105 expenses:misc .EE .RE .IP "2." 3 تطبیق حساب جاری (checking). وارد وبگاه بانک خود شوید. موجودی امروز (تسویه‌شده یا cleared) را با موجودی تسویه‌شده در hledger مقایسه کنید (\f[CR]hledger bal checking \-C\f[R]). اگر متفاوت هستند، خطا را ردیابی کنید یا تراکنش(های) فراموش‌شده را ثبت کنید یا مشابه بالا، یک تراکنش تعدیل اضافه نمایید. برخلاف حالت وجه نقد، معمولاً می‌توانید تاریخچه تراکنش‌ها و مانده لحظه‌ای بانک خود را با آنچه توسط \f[CR]hledger reg checking \-C\f[R] گزارش شده است مقایسه کنید. اگر عموماً تاریخ تراکنش‌ها را کاملاً نزدیک به تاریخ‌های تسویه بانک خود ثبت کنید، این کار ساده‌تر خواهد بود. .IP "3." 3 این روند را برای سایر حساب‌های دارایی/بدهی تکرار کنید. .PP نکته: به جای دستور register، از \f[CR]hledger\-ui\f[R] استفاده کنید تا هنگام ویرایش دفتر، ثبتی با به‌روزرسانی زنده را مشاهده کنید: \f[CR]hledger\-ui \-\-watch \-\-register checking \-C\f[R] .PP پس از مغایرت‌گیری، در صورتی که مایل به ردیابی آن هستید، زمان مناسبی است تا وضعیت تراکنش‌های تطبیق‌یافته را با افزودن نشانگر \f[CR]*\f[R] به صورت \(dqتسویه‌شده و تأییدشده\(dq علامت‌گذاری کنید. به عنوان مثال در تراکنش حقوق (paycheck) در بالا، علامت \f[CR]*\f[R] را بین \f[CR]2023\-01\-15\f[R] و \f[CR]paycheck\f[R] درج کنید. .PP اگر از ابزارهای کنترل نسخه استفاده می‌کنید، اکنون زمان مناسب دیگری برای ثبت تغییرات (commit) است: .IP .EX $ git commit \-m \(aqtxns\(aq 2023.journal .EE.SS گزارش‌گیری (Reporting) در اینجا چند گزارش پایه‌ای آورده شده است. .PP نمایش تمام تراکنش‌ها: .IP .EX $ hledger print 2023\-01\-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 liabilities:creditcard $\-50 equity:opening/closing balances $\-3050 2023\-01\-10 * gift received assets:cash $20 income:gifts 2023\-01\-12 * farmers market expenses:food $13 assets:cash 2023\-01\-15 * paycheck income:salary assets:bank:checking $1000 2023\-01\-16 * adjust cash assets:cash $\-2 = $105 expenses:misc .EE .PP نمایش نام حساب‌ها و سلسله‌مراتب آن‌ها: .IP .EX $ hledger accounts \-\-tree assets bank checking savings cash equity opening/closing balances expenses food misc income gifts salary liabilities creditcard .EE .PP نمایش مجموع کل حساب‌ها: .IP .EX $ hledger balance $4105 assets $4000 bank $2000 checking $2000 savings $105 cash $\-3050 equity:opening/closing balances $15 expenses $13 food $2 misc $\-1020 income $\-20 gifts $\-1000 salary $\-50 liabilities:creditcard \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 0 .EE .PP نمایش تنها مانده‌های دارایی و بدهی، به‌صورت یک فهرست مسطح، محدود به عمق ۲: .IP .EX $ hledger bal assets liabilities \-2 $4000 assets:bank $105 assets:cash $\-50 liabilities:creditcard \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- $4055 .EE .PP نمایش همان موارد بدون اعداد منفی، قالب‌بندی‌شده به‌صورت یک ترازنامه ساده: .IP .EX $ hledger bs \-2 Balance Sheet 2023\-01\-16 || 2023\-01\-16 ========================++============ Assets || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- assets:bank || $4000 assets:cash || $105 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- || $4105 ========================++============ Liabilities || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- liabilities:creditcard || $50 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\- || $50 ========================++============ Net: || $4055 .EE .PP مجموع نهایی، \(dqارزش خالص\(dq شما در تاریخ پایانی است. (یا از \f[CR]bse\f[R] برای یک ترازنامه کامل به همراه حقوق صاحبان سهام استفاده کنید.) .PP نمایش مجموع درآمدها و هزینه‌ها، قالب‌بندی‌شده به‌صورت صورت سود و زیان: .IP .EX hledger is Income Statement 2023\-01\-01\-2023\-01\-16 || 2023\-01\-01\-2023\-01\-16 ===============++======================= Revenues || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- income:gifts || $20 income:salary || $1000 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || $1020 ===============++======================= Expenses || \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- expenses:food || $13 expenses:misc || $2 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- || $15 ===============++======================= Net: || $1005 .EE .PP مجموع نهایی، درآمد خالص شما در این بازه زمانی است. .PP نمایش تراکنش‌های اثرگذار بر وجه نقد، به همراه مانده تجمعی: .IP .EX $ hledger register cash 2023\-01\-01 opening balances assets:cash $100 $100 2023\-01\-10 gift received assets:cash $20 $120 2023\-01\-12 farmers market assets:cash $\-13 $107 2023\-01\-16 adjust cash assets:cash $\-2 $105 .EE .PP نمایش تعداد ثبت‌ها در هفته به‌صورت یک نمودار میله‌ای: .IP .EX $ hledger activity \-W 2019\-12\-30 ***** 2023\-01\-06 **** 2023\-01\-13 **** .EE.SS مهاجرت به یک فایل جدید در پایان سال، ممکن است بخواهید دفتر روزنامه خود را در یک فایل جدید ادامه دهید، تا تراکنش‌های قدیمی سرعت گزارش‌های شما را کاهش ندهند یا آن‌ها را شلوغ نکنند، و همچنین به تضمین یکپارچگی تاریخچه حسابداری شما کمک شود. دستور close را ببینید. .PP در صورت استفاده از سامانه کنترل نسخه، فراموش نکنید فایل جدید را \f[CR]git add\f[R] کنید. .SH "گزارش باگ‌ها (BUGS)" ما از گزارش‌های باگ در سامانه پیگیری اشکالات hledger (https://bugs.hledger.org) یا در گفت‌وگو یا فهرست پستی hledger (https://hledger.org/support) استقبال می‌کنیم. .PP برخی از مشکلات و محدودیت‌های شناخته‌شده: .PP برنامه hledger هنگام خواندن متن‌های غیر ascii از کدگذاری متن سیستم استفاده می‌کند. اگر هیچ کدگذاری سیستمی پیکربندی نشده باشد، یا اگر کدگذاری داده‌ها متفاوت باشد، hledger خطا خواهد داد. (بخش‌های Text encoding و عیب‌یابی را ببینید.) .PP در Microsoft Windows، بسته به نوع پنجره ترمینالی که استفاده می‌کنید، ممکن است نویسه‌های غیر ascii، قالب‌بندی متن ANSI، و/یا کلید TAB در دستور add به‌طور کامل پشتیبانی نشوند. (برای دستیابی به بهترین نتیجه، یک پنجره powershell را امتحان کنید.) .PP هنگام پردازش فایل‌های داده بزرگ، hledger نسبت به Ledger حافظه بیشتری مصرف می‌کند. .SS عیب‌یابی در اینجا برخی از مشکلات رایجی که ممکن است هنگام اجرای hledger با آن‌ها مواجه شوید و نحوه رفع آن‌ها آورده شده است (همچنین به یاد داشته باشید که معمولاً می‌توانید پشتیبانی سریعی دریافت کنید): .PP \f[B]مشکلات PATH: خطایی مانند \(dqNo command \(aqhledger\(aq found\(dq دریافت می‌کنم\f[R] .PD 0 .P .PD بسته به نحوه نصب hledger، ممکن است فایل‌های اجرایی در PATH پوسته شما قرار نداشته باشند. به عنوان مثال در سیستم‌های unix، ابزار stack برنامه hledger را در \f[CR]\(ti/.local/bin\f[R] و cabal آن را در \f[CR]\(ti/.cabal/bin\f[R] نصب می‌کند. ممکن است لازم باشد یکی از این دایرکتوری‌ها را به PATH پوسته خود اضافه کنید، و/یا یک پنجره ترمینال جدید باز کنید. .PP \f[B]مشکلات LEDGER_FILE: متغیر LEDGER_FILE را پیکربندی کرده‌ام اما hledger از آن استفاده نمی‌کند\f[R] .PD 0 .P .PD .IP \(bu 2 متغیر \f[CR]LEDGER_FILE\f[R] باید یک متغیر محیطی واقعی باشد، نه صرفاً یک متغیر پوسته. به عنوان مثال در unix، دستور \f[CR]env | grep LEDGER_FILE\f[R] باید آن را نمایش دهد. ممکن است نیاز به استفاده از دستور \f[CR]export\f[R] داشته باشید (ببینید: https://stackoverflow.com/a/7411509). در Windows، دستور \f[CR]$env:LEDGER_FILE\f[R] باید آن را نمایش دهد. .IP \(bu 2 ممکن است لازم باشد پوسته خود را مجبور کنید تا پیکربندی جدید را ببیند. یک راه ساده این است که پنجره ترمینال خود را ببندید و یک پنجره جدید باز کنید. .PP \f[B]مشکلات رمزگشایی متن: خطاهایی مانند \(dqIllegal byte sequence\(dq یا \(dqInvalid or incomplete multibyte or wide character\(dq یا \(dqcommitAndReleaseBuffer: invalid argument (invalid character)\(dq دریافت می‌کنم\f[R] .PD 0 .P .PD برنامه hledger معمولاً نیاز دارد که ورودی آن با کدگذاری متن محلی (locale) سیستم قابل رمزگشایی باشد. بخش‌های Text encoding و Install: Text encoding را ببینید. .PP \f[B]مشکلات سازگاری: hledger در پردازش فایل Ledger من خطا می‌دهد\f[R] .PD 0 .P .PD تمامی نحو فایل دفتر روزنامه یا مجموعه قابلیت‌های Ledger پشتیبانی نمی‌شود. برای جزئیات کامل بخش‌های hledger و Ledger را ببینید..SH "نویسندگان (AUTHORS)" Simon Michael و مشارکت‌کنندگان. .br http://hledger.org/CREDITS.html را ببینید. .SH "کپی‌رایت و تکثیر (COPYRIGHT)" کپی‌رایت 2007\-2023 متعلق به Simon Michael و مشارکت‌کنندگان. .SH "مجوز (LICENSE)" تحت مجوز GNU GPL v3 یا بالاتر منتشر شده است. .SH "همچنین ببینید (SEE ALSO)" hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)