کدگذاری متن (Text encoding)

برنامه hledger انتظار دارد ورودی‌های غیر ascii با کدگذاری متنی locale سیستم قابل رمزگشایی باشند. (برای فایل‌های CSV/SSV/TSV، این مورد می‌تواند با قاعده CSV encoding لغو شود.)

بنابراین، تلاش برای خواندن فایل‌های غیر ascii که دارای کدگذاری متنی نادرست هستند، یا زمانی که هیچ locale سیستمی پیکربندی نشده است، با شکست مواجه خواهد شد. برای رفع این مشکل، locale سیستم خود را به درستی پیکربندی کنید و/یا فایل‌ها را به کدگذاری متنی سیستم خود تبدیل کنید (با استفاده از iconv در unix، یا powershell یا notepad در ویندوز). برای نکات بیشتر به Install: Text encoding مراجعه کنید.

خروجی hledger از کدگذاری locale سیستم استفاده خواهد کرد.

مستندات و فایل‌های نمونه hledger اغلب از کدگذاری UTF-8 استفاده می‌کنند.

قالب‌های داده (Data formats)

معمولاً فایل داده در قالب journal متعلق به hledger است، اما می‌تواند در هر یک از قالب‌های فایل پشتیبانی‌شده باشد که در حال حاضر عبارتند از:

این قالب‌ها در ادامه با جزئیات بیشتری توضیح داده شده‌اند.

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

همچنین می‌توانید با قرار دادن نام قالب و یک دونقطه در ابتدای مسیر فایل، استفاده از یک خواننده/قالب خاص را اجبار کنید. به عنوان مثال، برای خواندن یک فایل ‎.dat حاوی مقادیر جداشده با تب:

$ hledger -f tsv:/some/file.dat stats
نام فایل - به معنی ورودی استاندارد است:

$ cat FILE | hledger -f- print

در صورت خواندن داده‌های غیر از journal به این روش، باید قالب را به عنوان یک پیشوند مشخص کنید، مانند timeclock: در اینجا:

$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-

چندین فایل (Multiple files)

می‌توانید چند گزینهٔ -f را مشخص کنید تا چندین فایل به عنوان یک journal بزرگ خوانده شوند. هنگام انجام این کار، توجه داشته باشید که برخی ویژگی‌ها (توضیح داده شده در زیر) تحت تأثیر قرار خواهند گرفت:

• بررسی‌های تراز (balance assertions) تأثیر تراکنش‌های فایل‌های قبلی را نخواهند دید. (معمولاً این موضوع مشکلی ایجاد نمی‌کند زیرا هر فایل مانده‌های ابتدای دورهٔ متناظر خود را تنظیم می‌کند.)
• برخی دستورالعمل‌ها (directives) روی فایل‌های قبلی یا بعدی تأثیر نخواهند گذاشت.

در صورت نیاز، می‌توانید این مشکل را با استفاده از یک فایل والد (parent file) که سایر فایل‌ها را در بر می‌گیرد، یا با چسباندن فایل‌ها به یکدیگر دور بزنید؛ به عنوان مثال: cat a.journal b.journal | hledger -f- CMD.

حالت سخت‌گیرانه (Strict mode)

نرم‌افزار hledger فایل‌های ورودی را برای اطمینان از معتبر بودن داده‌ها بررسی می‌کند. به‌طور پیش‌فرض، مهم‌ترین خطاها شناسایی می‌شوند، در حالی که همچنان فایل‌های journal ساده را بدون نیاز به اعلان‌های فراوان می‌پذیرد:

• آیا فایل‌های ورودی با نحو (syntax) معتبر، قابل تجزیه هستند؟
• آیا همهٔ تراکنش‌ها تراز هستند؟
• آیا تمام بررسی‌های تراز با موفقیت تأیید می‌شوند؟

با پرچم -s/--strict، بررسی‌های بیشتری انجام می‌شود:

• آیا همهٔ حساب‌هایی که در آن‌ها تراکنشی ثبت شده، با یک دستورالعمل account اعلان شده‌اند؟ (بررسی خطای حساب)
• آیا همهٔ کالاها با یک دستورالعمل commodity اعلان شده‌اند؟ (بررسی خطای کالا)
• آیا همهٔ تبدیل‌های کالا به صراحت اعلان شده‌اند؟

می‌توانید از دستور check برای اجرای بررسی‌های جداگانه استفاده کنید - مواردی که در بالا ذکر شد و چند مورد بیشتر.

گریزاندن نویسه‌های خاص پوسته

این‌ها برخی از نویسه‌هایی هستند که ممکن است برای پوستهٔ شما (برنامه‌ای که خطوط فرمان را تفسیر می‌کند) معنای ویژه‌ای داشته باشند:

• فاصله (SPACE)، <، >، (، )، |، \، %
• $ اگر بعد از آن یک نویسهٔ کلمه‌ای (word character) بیاید

بنابراین برای مثال، برای تطبیق یک نام حساب حاوی فاصله، مانند "credit card"، این را ننویسید:

$ hledger register credit card

در عوض، نام را درون تک‌نقل‌قول قرار دهید:

$ hledger register 'credit card'

در یونیکس یا PowerShell ویندوز، اگر از نقل‌قول دوگانه استفاده کنید، پوستهٔ شما بی‌سر و صدا $ را به عنوان جایگزینی متغیر در نظر می‌گیرد. بنابراین احتمالاً باید از نقل‌قول دوگانه پرهیز کنید، مگر اینکه خواهان این رفتار باشید، مثلاً در یک اسکریپت:

$ hledger register "assets:$SOMEACCT"

اما در پنجره‌های قدیمی‌تر CMD.EXE ویندوز، باید از نقل‌قول دوگانه استفاده کنید:

C:\Users\Me> hledger register "credit card"

در یونیکس یا PowerShell ویندوز، به عنوان جایگزینی برای نقل‌قول‌ها می‌توانید قبل از هر نویسهٔ خاص یک بک‌اسلش بنویسید:

$ hledger register credit\ card

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

$ hledger register credit.card

گریزاندن نویسه‌های خاص در عبارت‌های باقاعده

برخی نویسه‌ها همچنین در عبارت‌های باقاعده (که آرگومان‌های hledger معمولاً چنین هستند) معنای ویژه‌ای دارند. این نویسه‌ها عبارتند از:

•

.، ^، $، [، ]، (، )، |، \

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

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

$ hledger balance cur:\\$

توضیح:

1.

افزودن یک بک‌اسلش \ قبل از علامت دلار $ برای محافظت از آن در برابر عبارت‌های باقاعده (تا به صورت تحت‌اللفظی و بدون معنای ویژه مطابقت داده شود).

2.

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

3.

در این مورد نیازی به محافظت از $ در برابر پوسته نیست، زیرا پس از آن نویسهٔ کلمه‌ای نیامده است؛ اما انجام این کار هم بی‌ضرر است.

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

$ hledger balance cur:'\$'
گزینه‌ها و آرگومان‌های hledger گاهی در جاهایی به جز خط فرمان به کار می‌روند که قوانین گریز دادن/نقل‌قول (escaping/quoting) در آن‌ها متفاوت است.
برای نمونه، نقل‌قول با بک‌اسلش ممکن است در دسترس نباشد.
در اینجا یک راهنمای مرجع سریع آورده شده است:

کاراکترهای یونیکد

انتظار می‌رود hledger کاراکترهای غیر ascii را به درستی پردازش کند:

• آن‌ها باید در فایل‌های ورودی و در خط فرمان توسط تمامی ابزارهای hledger (مانند add،‏ iadd، فرم‌های جستجو/افزودن/ویرایش hledger-web و غیره) به درستی تجزیه شوند
• آن‌ها باید توسط تمامی ابزارهای hledger به درستی نمایش داده شوند و چینش متن روی صفحه حفظ شود.

این امر نیازمند یک محیط به خوبی پیکربندی‌شده است. در اینجا چند نکته آورده شده است:

• یک locale برای سیستم باید پیکربندی شود تا بتواند کاراکترهای مورد استفاده را رمزگشایی کند. این مورد حیاتی است - بخش Text encoding و Install: Text encoding را ببینید.
• نرم‌افزار ترمینال شما (مانند Terminal.app،‏ iTerm،‏ CMD.exe،‏ xterm و...) باید از یونیکد پشتیبانی کند. در ویندوز ممکن است نیاز به استفاده از Windows Terminal داشته باشید.
• ترمینال باید از قلمی استفاده کند که حاوی گلیف‌های یونیکد مورد نیاز باشد.
• ترمینال باید طوری پیکربندی شود که کاراکترهای عریض (wide characters) را با عرض دوگانه نمایش دهد (جهت حفظ چینش گزارش‌ها).
• در ویندوز، برای دستیابی به بهترین نتیجه باید hledger را در همان محیطی اجرا کنید که در آن ساخته شده است. به عنوان نمونه، hledger ساخته‌شده در محیط استاندارد CMD.EXE (مانند باینری‌های موجود در صفحه دانلود ما) ممکن است در هنگام اجرا در ترمینال cygwin یا msys با مشکلات نمایشی مواجه شود و بالعکس. (به عنوان نمونه #961 را ببینید)..SS "عبارات باقاعده (Regular expressions)" یک عبارت باقاعده (regexp) قطعه‌متن کوچکی است که در آن نویسه‌های خاصی (مانند .، ^، $، +، *، ()، |، []، \) معانی ویژه‌ای دارند و زبان کوچکی را برای تطبیق دقیق متن تشکیل می‌دهند - که در hledger و جاهای دیگر بسیار کاربردی است. برای یادگیری کامل دربارهٔ آن‌ها، از regular-expressions.info بازدید کنید.

ابزار hledger هر زمان که الگویی را برای تطبیق چیزی وارد کنید، از عبارات باقاعده پشتیبانی می‌کند؛ برای مثال در آرگومان‌های جستار (query)، نام‌های مستعار حساب، قواعد if در CSV، فرم جستجوی hledger-web، جستجوی / در hledger-ui و غیره. ممکن است لازم باشد آن‌ها را داخل نقل‌قول (کوتیشن) قرار دهید، به‌ویژه در خط فرمان (به بخش نویسه‌های خاص در بالا مراجعه کنید). چند مثال در ادامه آمده است:

جستارهای نام حساب (برای استفاده در خط فرمان داخل نقل‌قول قرار گرفته‌اند):

عبارت باقاعده:       تطابق‌ها:
-------------------  ------------------------------------------------------------
bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...
:bank                assets:bank:savings, expenses:art:banksy
:bank:               assets:bank:savings
'^bank'              هیچ‌کدام ( ^ با ابتدای متن مطابقت می‌یابد )
'bank$'              assets:bank   ( $ با انتهای متن مطابقت می‌یابد )
'big \$ bank'        big $ bank    ( \ معنای ویژهٔ نویسه بعدی را غیرفعال می‌کند )
'\bbank\b'           assets:bank, assets:bank:savings  ( \b با مرزهای کلمه تطابق دارد )
'(sav|check)ing'     saving یا checking  ( (|) با هر یک از دو حالت تطابق می‌یابد )
'saving|checking'    saving یا checking  ( پرانتزهای بیرونی لازم نیستند )
'savings?'           saving یا savings   ( ? با ۰ یا ۱ مورد از مورد پیشین تطابق می‌یابد )
'my +bank'           my bank, my  bank, ... ( + با ۱ یا چند مورد از مورد پیشین تطابق می‌یابد )
'my *bank'           mybank, my bank, my  bank, ... ( * با ۰ یا چند مورد از مورد پیشین تطابق می‌یابد )
'b.nk'               bank, bonk, b nk, ... ( . با هر نویسه‌ای مطابقت دارد )

برخی جستارهای دیگر:

desc:'amazon|amzn|audible'  تراکنش‌های Amazon
cur:EUR              مبالغی با نماد کالای حاوی EUR
cur:'\$'             مبالغی با نماد کالای حاوی $
cur:'^\$$'           فقط مبالغ $، نه مثلاً AU$ یا CA$
cur:....?            مبالغی با نمادهای ۴ نویسه‌ای یا بیشتر
tag:.=202[1-3]       مواردی با هر برچسبی که مقدار آن شامل 2021، 2022 یا 2023 باشد

نام‌های مستعار حساب: پذیرش . به‌جای : به‌عنوان جداکنندهٔ حساب:

alias /\./=:         تمام نقطه‌ها در نام‌های حساب را با دونقطه جایگزین می‌کند

نمایش چندین حساب سطح اول به‌صورت ترکیب‌شده در یک حساب:

--alias='/^[^:]+/=combined'  ( [^:] با هر نویسه‌ای غیر از : تطابق دارد )

نمایش حساب‌ها با حذف بخش سطح دوم:

--alias '/^([^:]+):[^:]+/ = \1'
                     یک حساب سطح اول و یک حساب سطح دوم را تطبیق می‌دهد
                     و آن‌ها را فقط با حساب سطح اول جایگزین می‌کند
                     ( \1 در متن جایگزینی به‌معنای "هر آن‌چه با
                     نخستین بخش پرانتزدار عبارت باقاعده تطابق یافته" است )

قواعد CSV: تطبیق رکوردهای CSV حاوی کدهای MCC مرتبط با غذاخوری:

if \?MCC581[124]

تطبیق رکوردهای CSV با مبلغی مشخص در حوالی پایان یا آغاز ماه:

if %amount \b3\.99
&  %date   (29|30|31|01|02|03)$
عبارت‌های باقاعده hledger از کتابخانه regex-tdfa می‌آیند.
اگر آن‌طور که انتظار دارید عمل نمی‌کنند، دانستن دقیق مواردی که پشتیبانی می‌کنند مهم است:

1.

آن‌ها به بزرگی و کوچکی حروف حساس نیستند (case insensitive).

2.

آن‌ها تطبیق درونی هستند (نیازی نیست کل رشته مورد تطبیق را پوشش دهند).

3.

آن‌ها از نوع POSIX ERE (عبارت‌های باقاعده توسعه‌یافته) هستند.

4.

آن‌ها همچنین از مرزهای کلمه گنو پشتیبانی می‌کنند (\b،
\B، \<، \>).

5.

ارجاع‌های به عقب (backreferences) هنگام جایگزینی متن در نام‌های مستعار حساب یا قوانین CSV پشتیبانی می‌شوند؛ در این بخش‌ها می‌توان از ارجاع‌های به عقب در رشته جایگزین برای ارجاع به گروه‌های گیرنده (capturing groups) در عبارت باقاعده جستجو استفاده کرد.
در غیر این صورت، اگر \1 را بنویسید، با رقم
1 تطبیق می‌یابد.

6.

آن‌ها از کمّیت‌سنج‌های تنبل (*?)، تغییردهنده‌های حالت
((?s))، کلاس‌های نویسه (\w،
\d) یا هر چیز دیگری که در بالا ذکر نشده است پشتیبانی نمی‌کنند.

7.

آن‌ها ممکن است (احتمالاً نه) به‌درستی از متن‌های راست‌به‌چپ یا دوجهته پشتیبانی نکنند.

چند نکته قابل توجه:

• در دستورالعمل alias و گزینه --alias،
  عبارت‌های باقاعده باید درون اسلش‌های رو به جلو قرار گیرند
  (/REGEX/).
  در جاهای دیگر در hledger، این کار الزامی نیست.

• در پرس‌وجوها، برای تطبیق یک فرانویسه عبارت باقاعده مانند
  $ به عنوان یک نویسه لفظی، یک بک‌اسلش در ابتدا قرار دهید.
  به عنوان مثال برای جستجوی مبالغ دارای علامت دلار در hledger-web، بنویسید
  cur:\$.

• در خط فرمان، برخی از فرانویسه‌ها مانند $ معنای خاصی برای شل دارند و بنابراین باید حداقل یک بار دیگر گریز داده شوند.
  بخش نویسه‌های خاص (Special characters) را ببینید.

فایل‌های آرگومان (Argument files)

شما می‌توانید مجموعه‌ای از گزینه‌ها و آرگومان‌های خط فرمان را در یک فایل ذخیره کرده و سپس با نوشتن @FILE.args به عنوان یک آرگومان دستور hledger از آن‌ها استفاده کنید. پسوند فایل .args مرسوم است، اما الزامی نیست. در یک فایل آرگومان:

• هر خط می‌تواند شامل یک آرگومان، پرچم یا گزینه باشد.
• خطوط خالی یا خطوطی که با # شروع می‌شوند نادیده گرفته می‌شوند.
• پرچم و مقدار یک گزینه باید با = به یکدیگر متصل شوند.
• مقدار یک گزینه یا یک آرگومان می‌تواند حاوی فاصله باشد. از نقل‌قول‌های تکی یا جفتی استفاده نکنید.
• و به‌طور کلی، از یک سطح نقل‌قول/گریز کمتر نسبت به خط فرمان استفاده کنید. به عنوان مثال cur:\$، نه cur:\\$ مانند آنچه در خط فرمان است.

برای مثال:

# cash.args
assets:cash
assets:charles schwab:sweep
cur:\$
-c=$1.

$ hledger bal @cash.args

فایل‌های پیکربندی (Config files)

با hledger نسخه 1.40 به بالا، می‌توانید گزینه‌ها و آرگومان‌های اضافی خط فرمان را در یک فایل پیکربندی کامل‌تر hledger ذخیره کنید. در اینجا یک مثال کوچک آمده است:

# General options are listed first, and used with hledger commands that support them.
--pretty
# Options following a `[COMMAND]` heading are used with that hledger command only.
[print]
--explicit --infer-costs

برای استفاده از یک فایل پیکربندی، آن را با گزینه --conf مشخص کنید. گزینه‌های آن در نزدیکی ابتدای خط فرمان شما درج می‌شوند، بنابراین در صورت نیاز می‌توانید آن‌ها را با گزینه‌های خط فرمان بازنویسی کنید.

یا می‌توانید با ایجاد hledger.conf در دایرکتوری جاری یا دایرکتوری‌های بالاتر، یا .hledger.conf در دایرکتوری خانگی خود (~/.hledger.conf)، یا hledger.conf در دایرکتوری پیکربندی XDG خود (~/.config/hledger/hledger.conf)، یک فایل پیکربندی خودکار تنظیم کنید که هر زمان hledger را اجرا می‌کنید مورد استفاده قرار گیرد.

در اینجا یک نمونه پیکربندی دیگر وجود دارد که می‌توانید از آن شروع کنید: https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample

شما می‌توانید نه تنها گزینه‌ها، بلکه آرگومان‌ها را نیز در فایل پیکربندی قرار دهید. اگر اولین کلمه در بخش بالایی (عمومی) یک فایل پیکربندی با خط تیره شروع نشود (مانند: print)، به عنوان آرگومان دستور در نظر گرفته می‌شود (و هر آرگومانی را در خط فرمان لغو می‌کند).

در رایانه‌های یونیکس، می‌توانید یک خط shebang در بالای فایل پیکربندی اضافه کنید، مجوز اجرا را روی فایل تنظیم کرده و مانند یک اسکریپت از آن استفاده کنید. برای مثال (-S در برخی سیستم‌عامل‌ها مورد نیاز است):

#!/usr/bin/env -S hledger --conf

شما می‌توانید با افزودن پرچم -n/--no-conf به خط فرمان، فایل‌های پیکربندی را نادیده بگیرید. این قابلیت هنگام استفاده از hledger در اسکریپت‌ها یا هنگام عیب‌یابی مفید است. هنگامی که هر دو گزینه --conf و --no-conf استفاده شوند، گزینه سمت راستی اولویت دارد.

برای بررسی نحوه پردازش فایل‌های پیکربندی، از --debug یا --debug=8 استفاده کنید. یا دستور setup را اجرا کنید که هرگونه فایل پیکربندی فعال را نمایش می‌دهد. (برخلاف سایر دستورات، خود setup تحت تأثیر فایل‌های پیکربندی قرار نمی‌گیرد.)

هشدار!

قابلیت‌های زیادی در hledger وجود ندارند که نیازمند هشدار باشند، اما این یکی هست!

فایل‌های پیکربندی خودکار در عین راحتی، hledger را کمتر قابل پیش‌بینی و اتکا می‌کنند. ساختن یک فایل پیکربندی که رفتار یک گزارش را تغییر دهد یا اسکریپت‌ها/برنامه‌های متکی بر hledger شما را به روش‌هایی خراب کند که بعداً شما را شگفت‌زده کند، آسان است.

اگر این را نمی‌خواهید:

1.

فقط فایل hledger.conf را روی سیستم خود ایجاد نکنید.

2.

همچنین مراقب دایرکتوری‌های دانلودشده که ممکن است حاوی یک فایل hledger.conf باشند باشید.

3.

همچنین اگر در حال اشتراک‌گذاری اسکریپت‌ها، مثال‌ها یا پشتیبانی هستید، توجه داشته باشید که دیگران ممکن است یک فایل hledger.conf داشته باشند.

برعکس، هنگامی که تصمیم به استفاده از این قابلیت گرفتید، سعی کنید به یاد داشته باشید:

1.

هر زمان که یک دستور hledger طبق انتظار کار نکرد، دوباره آن را با -n (--no-conf) اجرا کنید تا ببینید آیا فایل پیکربندی مقصر بوده است یا خیر.

2.

هر زمان که hledger را از یک اسکریپت فراخوانی می‌کنید، در نظر بگیرید که آیا آن فراخوانی باید از -n استفاده کند یا خیر.

3.

در مورد آنچه در فایل پیکربندی خود قرار می‌دهید محتاط باشید؛ سعی کنید تأثیر آن را بر تمام گزارش‌های خود در نظر بگیرید.

4.

برای عیب‌یابی تأثیر فایل‌های پیکربندی، با --debug یا --debug 8 اجرا کنید.

قابلیت فایل پیکربندی در hledger 1.40 اضافه شد..SS "تکمیل خودکار در پوسته (Shell completions)" اگر از پوسته‌های bash یا zsh استفاده می‌کنید، می‌توانید در صورت تمایل تکمیل خودکار حساس به متن را برای خطوط فرمان hledger تنظیم کنید. فشردن hledger<SPACE><TAB><TAB> (که باید تمام دستورات hledger را فهرست کند) یا hledger reg acct:<TAB><TAB> (که باید نام حساب‌های سطح بالای شما را فهرست کند) را امتحان کنید. اگر تکمیل خودکار کار نمی‌کند، یا برای جزئیات بیشتر، به Install > Shell completions مراجعه کنید.

مقصد خروجی (Output destination)

دستورات hledger خروجی خود را به‌طور پیش‌فرض به ترمینال ارسال می‌کنند. البته می‌توانید با استفاده از نحو استاندارد پوسته، آن را تغییر مسیر دهید، مثلاً به درون یک فایل:

$ hledger print > foo.txt

برخی از دستورات (print، register، stats و دستورات balance) گزینهٔ -o/--output-file را نیز ارائه می‌دهند که همین کار را بدون نیاز به پوسته انجام می‌دهد. به عنوان مثال:

$ hledger print -o foo.txt
$ hledger print -o -        # write to stdout (the default)

قالب خروجی (Output format)

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

همچنین می‌توانید با اجرای hledger CMD -h و بررسی گزینهٔ -O/--output-format=FMT ببینید که یک دستور از چه قالب‌های خروجی پشتیبانی می‌کند،.PP می‌توانید قالب خروجی را با استفاده از آن گزینه تعیین کنید:

$ hledger print -O csv    # print CSV to standard output

یا با انتخاب یک پسوند نام فایل مناسب به کمک گزینهٔ -o/--output-file=FILE.FMT:

$ hledger balancesheet -o foo.csv    # write CSV to foo.csv

در صورت نیاز، گزینهٔ -O می‌تواند با -o ترکیب شود تا پسوند فایل را لغو و جایگزین کند:

$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt

در ادامه نکاتی پیرامون قالب‌های مختلف خروجی آمده است.

خروجی متنی (Text output)

این حالت پیش‌فرض است: خروجی گزارش به صورت متن ساده و خوانا برای انسان، مناسب برای مشاهده با قلمی با عرض یکسان (monospace) در یک ترمینال. اگر داده‌های شما حاوی نویسه‌های یونیکد یا عریض هستند، به ترمینال و قلمی نیاز خواهید داشت که آن‌ها را به درستی نمایش دهند. (این امر ممکن است در MS Windows چالش‌برانگیز باشد.)

برخی از گزارش‌ها (register، aregister) به طور معمول از تمام عرض پنجره استفاده می‌کنند. اگر این حالت به درستی کار نمی‌کند یا مایل به تغییر آن هستید، می‌توانید از گزینهٔ -w/--width استفاده کنید.

گزارش‌های ترازنامه و موجودی (balance، balancesheet، incomestatement...) به هر میزان عرض که نیاز داشته باشند استفاده می‌کنند. گزارش‌های چنددوره‌ای و چندارزی اغلب می‌توانند از عرض پنجره فراتر بروند. علاوه بر استفاده از یک صفحه‌بند (pager)، فنون کاربردی برای این وضعیت عبارتند از: --layout=bare، -X COMM، cur:، --transpose، --tree، --depth، --drop، تغییر وضعیت به خروجی html و غیره.

نویسه‌های رسم کادر (Box-drawing characters)

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

اما ترمینال و قلم شما احتمالاً از آن‌ها پشتیبانی می‌کنند؛ بنابراین توصیه می‌کنیم از پرچم --pretty برای نمایش جدول‌های زیباتر در ترمینال استفاده کنید. این پرچم گزینهٔ مناسبی برای افزودن به فایل پیکربندی hledger شما است.

رنگ (Colour)

ابزار hledger تلاش می‌کند پشتیبانی از رنگ‌های ANSI و استایل‌های متنی را به صورت خودکار شناسایی کند و در مواقع مناسب آن را به کار گیرد. (در حال حاضر، این قابلیت به صورت حداقلی استفاده می‌شود: برخی گزارش‌ها اعداد منفی را با رنگ قرمز نمایش می‌دهند و خروجی راهنما از متن برجسته (bold) برای تأکید بهره می‌برد.)

شما می‌توانید با تنظیم متغیر محیطی NO_COLOR برای غیرفعال کردن آن، یا با استفاده از گزینهٔ --color/--colour (احتمالاً در فایل پیکربندی‌تان) همراه با مقدار y/yes یا n/no جهت اجبار به فعال یا غیرفعال بودن، این رفتار را تغییر دهید.

صفحه‌بندی (Paging)

در محیط‌های شبه‌یونیکس (unix-like)، هنگام نمایش خروجی‌های حجیم (در هر قالبی) در ترمینال، hledger تلاش می‌کند در صورت لزوم از یک صفحه‌بند استفاده کند. (می‌توانید این قابلیت را با گزینهٔ --pager=no، مثلاً در فایل پیکربندی خود، غیرفعال کنید.)

صفحه‌بند هر بار یک صفحه از متن را نشان می‌دهد و به شما امکان می‌دهد برای دیدن متن بیشتر به بخش‌های مختلف پیمایش کنید. هنگام فعال بودن آن، معمولاً کلید SPACE صفحهٔ بعدی را نشان می‌دهد، کلید h راهنما را باز می‌کند و q خارج می‌شود. کلیدهای پیمایش ماوس، کلیدهای جهت‌نما، و کلیدهای home/end/page up/page down نیز ممکن است کار کنند.

برنامهٔ hledger از صفحه‌بند مشخص‌شده در متغیر محیطی PAGER استفاده خواهد کرد؛ در غیر این صورت، در صورت وجود از less، و سپس در صورت دردسترس بودن از more استفاده خواهد کرد. (با یک استثنا: دستور hledger help -p TOPIC همواره از less استفاده می‌کند تا بتواند به بخش مربوط به آن مبحث پیمایش کند.)

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

اگر از صفحه‌بند less استفاده می‌کنید، hledger سعی می‌کند با اجرای آن به همراه گزینه‌های اضافی اضافه‌شده به متغیر محیطی LESS شما، تجربه‌ای همواره روان و بی‌نقص ارائه دهد:

--chop-long-lines --hilite-unread --ignore-case --no-init --quit-if-one-screen --shift=8 --squeeze-blank-lines --use-backslash

و هنگامی که خروجی رنگی فعال باشد:

--RAW-CONTROL-CHARS

می‌توانید با تعریف گزینه‌های مورد نظر خود در متغیر HLEDGER_LESS که به جای LESS استفاده خواهد شد، از این سازوکار جلوگیری کنید..SS خروجی HTML خروجی HTML می‌تواند با یک فایل اختیاری hledger.css در همان دایرکتوری استایل‌بندی شود.

خروجی HTML یک قطعه‌کد HTML خواهد بود، نه یک سند کامل HTML. مانند سایر خروجی‌های hledger، برای نویسه‌های غیر-ASCII از کدگذاری متن locale سیستم استفاده خواهد کرد (بخش Text encoding را ببینید).

خروجی CSV / TSV

در خروجی CSV یا TSV، نشانه‌های گروه‌بندی ارقام (مانند جداکننده‌های هزارگان) به‌طور خودکار غیرفعال می‌شوند.

خروجی FODS

فرمت FODS همان قالب OpenDocument Spreadsheet به‌صورت XML ساده است، آن‌گونه که توسط LibreOffice و OpenOffice پذیرفته می‌شود. اگر از برنامه‌های صفحه‌گسترده آن‌ها استفاده می‌کنید، این قالب بهتر از CSV است زیرا در localeهای گوناگون کار می‌کند (نقطه اعشار در برابر کامای اعشار، ذخیره کدگذاری نویسه‌ها در سرآیند XML و در نتیجه عدم بروز مشکل با اوملاوت‌ها)، از ردیف‌ها و ستون‌های ثابت سرآیند، نوع سلول‌ها (رشته در برابر عدد در برابر تاریخ)، تفکیک عدد و واحد پول (واحد پول نمایش داده می‌شود اما نوع سلول همچنان عددی و برای محاسبات در دسترس است)، سبک‌ها (حالت برجسته/bold) و حاشیه‌ها پشتیبانی می‌کند. ضمناً همچنان می‌توانید با استفاده از ابزارهای مختلفی مانند libreoffice --headless یا ods2csv از FODS/ODS داده‌های CSV را استخراج کنید.

خروجی Beancount

این قالب دفتر روزنامه Beancount است. می‌توانید از این برای برون‌بری داده‌های hledger خود به Beancount، مثلاً برای استفاده از برنامه تحت وب Fava بهره ببرید.

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

• استفاده از نام‌های حساب سازگار با Beancount
• استفاده از کدهای ارز به‌جای نمادهای ارز
• استفاده از نشانه‌گذاری بهای تمام‌شده (cost notation) به‌جای ثبت‌های تبدیل حقوق صاحبان سهام (equity conversion postings)
• اجتناب از ثبت‌های مجازی، تخصیص‌های تراز (balance assignments) و تاریخ‌های ثانویه.

یک تنظیم اساسی وجود دارد که باید خودتان آن را مدیریت کنید: برای Beancount، نام حساب‌های سطح بالا باید Assets، Liabilities، Equity، Income و/یا Expenses باشند. در صورت نیاز می‌توانید از نام‌های مستعار حساب برای بازنویسی موقت نام‌های حساب خود استفاده کنید، مانند آنچه در فایل پیکربندی hledger2beancount.conf آمده است.

2024-12-20: چند مورد دیگر که هنوز برای شما به‌طور خودکار انجام نمی‌شوند:

• دستورالعمل‌های P به‌طور خودکار تبدیل نمی‌شوند - آن‌ها را خودتان تبدیل کنید.
• تخصیص‌های تراز (Balance assignments) تبدیل نمی‌شوند (Beancount از آن‌ها پشتیبانی نمی‌کند) - آن‌ها را با مقادیر صریح جایگزین کنید.

نام‌های حساب Beancount

جدا از نام‌های سطح بالا، hledger با بزرگ نوشتن حرف اول هر بخش، جایگزینی فاصله‌ها با -، جایگزینی سایر نویسه‌های پشتیبانی‌نشده با C<HEXBYTES>، افزودن A به ابتدای بخش‌هایی از نام حساب که با یک حرف یا رقم آغاز نمی‌شوند، و افزودن :A به نام‌های حسابی که فقط از یک بخش تشکیل شده‌اند، نام‌های حساب شما را به نام‌های حساب معتبر در Beancount تبدیل می‌کند.

نام‌های کالای Beancount

ابزار hledger نام‌های کالای (commodity) شما را جهت تبدیل به نام‌های معتبر کالا/ارز در Beancount تنظیم خواهد کرد؛ این نام‌ها باید بین ۲ تا ۲۴ نویسه از حروف بزرگ، ارقام، یا '، .، _، - باشند که با یک حرف شروع شده و با یک حرف یا رقم پایان می‌یابند. ابزار hledger نمادهای ارزی شناخته‌شده را به کدهای ارزی ISO 4217 تبدیل می‌کند، حروف را بزرگ می‌سازد، فاصله‌ها را با - جایگزین می‌کند، سایر نویسه‌های پشتیبانی‌نشده را با C<HEXBYTES> جایگزین می‌نماید، و در صورت نیاز C را به ابتدا یا انتهای آن می‌افزاید.

ثبت‌های مجازی Beancount

ابزار Beancount اجازه استفاده از ثبت‌های مجازی را نمی‌دهد؛ اگر مواردی از آن‌ها را داشته باشید، از خروجی Beancount حذف خواهند شد.

متاداده Beancount

برچسب‌های hledger به متاداده‌های Beancount تبدیل خواهند شد (به‌جز برچسب‌هایی که نام آن‌ها با _ آغاز می‌شود). نام‌های متاداده طوری تنظیم می‌شوند که با Beancount سازگار باشند: با یک حرف کوچک آغاز شوند، حداقل دو نویسه طول داشته باشند، و نویسه‌های پشتیبانی‌نشده کدگذاری شوند. مقادیر متاداده از نوع رشته‌ای (string) Beancount استفاده خواهند کرد.

در hledger، اشیاء می‌توانند یک برچسب یکسان را با مقادیر متعدد تکرار کنند. برای نمونه یک حساب assets:cash ممکن است هر دو برچسب type:Asset و type:Cash را داشته باشد. برای Beancount این برچسب‌ها با یکدیگر ترکیب شده و مقادیر آن‌ها با کاما از هم جدا می‌شوند. مانند: type: "Asset, Cash"..SS "هزینه‌های Beancount (Beancount costs)" Beancount برخلاف hledger، هزینه‌ها و ثبت‌های تبدیل (conversion postings) اضافی را مجاز نمی‌داند. اگر هر یک از این موارد را داشته باشید، ثبت‌های تبدیل حذف خواهند شد. در حال حاضر حداکثر از یک گروه «هزینه + ثبت‌های تبدیل» در هر تراکنش پشتیبانی می‌کنیم.

ارز عملیاتی Beancount (Beancount operating currency)

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

option "operating_currency" "USD"

خروجی SQL (SQL output)

انتظار می‌رود خروجی SQL دست‌کم با SQLite، MySQL و Postgres کار کند.

انتظار می‌رود دستورات SQL در یک پایگاه داده خالی اجرا شوند. اگر از قبل جدول‌هایی دارید که از طریق خروجی SQL در hledger ایجاد شده‌اند، احتمالاً بهتر است پیش از درون‌ریزی، یا داده‌های آن‌ها را پاک کنید (از طریق دستورات SQL مانند delete یا truncate) یا جدول‌ها را به‌طور کامل drop کنید؛ در غیر این صورت ثبت‌های شما تکراری خواهند شد.

برای SQLite، مفیدتر است که فیلد id تولیدشده را به یک PRIMARY KEY تغییر دهید. به عنوان مثال:

$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...

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

خروجی JSON (JSON output)

خروجی JSON ما نسبتاً بزرگ و پرحجم (verbose) است، چرا که بازنمایی دقیقی از انواع داده‌های داخلی hledger است. برای درک ساختار آن، تعاریف نوع Haskell را که بیشتر در نشانی زیر قرار دارند مطالعه کنید: https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs مشخصات OpenAPI مربوط به hledger-web نیز ممکن است مرتبط باشد.

hledger اعداد را گاهی تا ۲۵۵ رقم بااهمیت ذخیره می‌کند. این تعداد رقم برای بیشتر مصرف‌کنندگان JSON بیش از حد زیاد است، بنابراین در خروجی JSON اعداد را حداکثر تا ۱۰ رقم اعشار گرد می‌کنیم. (ما تعداد ارقام صحیح را محدود نمی‌کنیم.) اگر متوجه شدید که این مسئله مشکلی ایجاد می‌کند، لطفاً به ما اطلاع دهید. مرتبط: #1195

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

شیوه‌های کالا (Commodity styles)

هنگام نمایش مقادیر، hledger یک شیوه نمایش استاندارد را برای هر کالا/ارز استنتاج می‌کند، همان‌طور که در ادامه در «شیوه نمایش کالا» توضیح داده شده است.

در صورت نیاز، می‌توان این شیوه را با گزینه -c/--commodity-style بازنویسی کرد (به‌جز برای مقادیر هزینه و مقادیر نمایش‌داده‌شده توسط دستور print، که همیشه با تمام ارقام اعشار نمایش داده می‌شوند). برای مثال، دستور زیر مقادیر دلاری را مجبور می‌کند تا به صورت نشان‌داده‌شده نمایش داده شوند:

$ hledger print -c '$1.000,0'

این گزینه می‌تواند برای تعیین شیوه نمایش برای چندین کالا/ارز تکرار شود. آرگومان آن همان‌طور است که در دستورالعمل commodity شرح داده شده است. توجه داشته باشید که حذف نماد کالا، شیوه نمایش را تنها برای کالای بدون نماد تعیین می‌کند، نه تمام کالاها.

در برخی موارد hledger قالب‌بندی اعداد را برای بهبود قابلیت تجزیه (parseability) آن‌ها تنظیم می‌کند (مانند افزودن ممیزهای اعشاری انتهایی در صورت نیاز).

خروجی اشکال‌زدایی (Debug output)

هدف ما این است که عیب‌یابی، بررسی درونی و توسعه hledger نسبتاً آسان باشد. می‌توانید --debug[=N] را به هر خط فرمان hledger اضافه کنید تا خروجی اشکال‌زدایی اضافی را مشاهده کنید. مقدار N از ۱ (کمترین خروجی، پیش‌فرض) تا ۹ (بیشترین خروجی) متغیر است. معمولاً از ۱ شروع می‌کنید و تا زمانی که خروجی کافی ببینید، آن را افزایش می‌دهید. خروجی اشکال‌زدایی به stderr ارسال می‌شود و تحت تأثیر -o/--output-file قرار نمی‌گیرد (مگر اینکه stderr را به stdout تغییر مسیر دهید، مانند: 2>&1). این خروجی با خروجی عادی درهم‌آمیخته می‌شود، که می‌تواند به آشکار شدن زمان ارزیابی بخش‌هایی از کد کمک کند. برای ثبت خروجی اشکال‌زدایی در یک فایل گزارش به جای آن، معمولاً می‌توانید stderr را تغییر مسیر دهید، مانند:

hledger bal --debug=3 2>hledger.log

(این گزینه هنوز در فایل پیکربندی کار نمی‌کند.).SH "محیط (ENVIRONMENT)" این متغیرهای محیطی بر hledger تأثیر می‌گذارند:

HLEDGER_LESS اگر less صفحه‌بند (pager) شما باشد، این متغیر گزینه‌های less را که hledger باید استفاده کند، مشخص می‌نماید. (در غیر این صورت، LESS + گزینه‌های سفارشی استفاده می‌شوند.)

LEDGER_FILE فایل ژورنال پیش‌فرض، برای زمانی که هیچ گزینهٔ -f/--file ارائه نشده باشد. برای مثال، می‌تواند ~/finance/main.journal باشد. این مقدار همچنین می‌تواند یک الگوی glob باشد، مانند ./2???.journal. (اگر الگو با چندین فایل تطبیق یابد، تنها نخستین فایل بر اساس ترتیب الفبایی-عددی استفاده می‌شود.) اگر LEDGER_FILE به فایلی اشاره کند که وجود ندارد، خطایی رخ خواهد داد. اگر مقدار آن یک رشتهٔ خالی باشد، نادیده گرفته می‌شود.

اگر LEDGER_FILE تنظیم نشده باشد و -f نیز ارائه نشود، فایل ژورنال پیش‌فرض $HOME/.hledger.journal خواهد بود (یا چنانچه دایرکتوری خانگی شناسایی نشود، ./.hledger.journal).

همچنین بخش کارهای متداول > تنظیم LEDGER_FILE (Common tasks > Setting LEDGER_FILE) را ببینید.

NO_COLOR اگر این متغیر محیطی وجود داشته باشد (با هر مقداری، از جمله خالی)، hledger از کدهای رنگ ANSI در خروجی ترمینال استفاده نخواهد کرد، مگر اینکه با یک گزینهٔ صریح --color=y یا --colour=y لغو شود.

برگهٔ تقلب ژورنال (Journal cheatsheet)

# ساختار دستوری اصلی قالب ژورنال hledger در اینجا آمده است
# (بدون در نظر گرفتن دستور زبان اضافی برای سازگاری با Ledger).
###############################################################################
# ۱. این‌ها خطوط توضیح هستند، برای یادداشت‌ها یا غیرفعال‌سازی موقت موارد.
; آن‌ها با # یا ; آغاز می‌شوند
comment
یا این‌که خطوط می‌توانند درون "comment" / "end comment" قرار گیرند.
این یک بلوک از 
خطوط توضیح است.
end comment
# برخی ورودی‌های ژورنال می‌توانند در انتهای خط توضیح با نقطه‌ویرگول داشته باشند  ; مانند این
# برخی از آن‌ها به ۲ یا چند فاصله قبل از نقطه‌ویرگول نیاز دارند.
###############################################################################
# ۲. دستورالعمل‌ها پردازش یا خروجی را به نوعی سفارشی می‌کنند.
# برای شروع به هیچ دستورالعملی نیاز ندارید.
# اما آن‌ها می‌توانند بررسی خطای بیشتری اضافه کنند، یا نحوهٔ نمایش موارد را تغییر دهند.
# آن‌ها با یک کلمه، حرف یا نماد آغاز می‌شوند.
# آن‌ها اغلب در بالا، پیش از تراکنش‌ها قرار می‌گیرند.
account assets             ; اعلان نام‌های حساب معتبر و ترتیب نمایش.
account assets:savings     ; یک زیرحساب. این یکی نشان‌دهندهٔ یک حساب بانکی است.
account assets:checking    ; دیگری. توجه: ۲+ فاصله پس از نام حساب.
account assets:receivable  ; نوع حسابداری از نام‌های انگلیسی استنباط می‌شود،
account passifs            ; یا با یک برچسب "type" اعلام می‌گردد، 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   ; درج یک فایل ژورنال دیگر در اینجا.
# اعلان یک «تراکنش دوره‌ای» ("periodic transaction")، برای گزارش‌های بودجه/پیش‌بینی
~ 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
    ; خطوط توضیح اضافی تراکنش، با تورفتگی.
    ; می‌تواند یک ! یا * پس از تاریخ باشد به معنای «در انتظار» ("pending") یا «تسویه‌شده» ("cleared").
    ; می‌تواند یک (code) داخل پرانتز پس از تاریخ/وضعیت وجود داشته باشد.
                                    ; علامت مبالغ جهت گردش را نشان می‌دهد.
    assets:checking          $-500  ; منفی یعنی برداشت از این حساب (بستانکار/credit).
    expenses:rent             $500  ; مثبت یعنی واریز به این حساب (بدهکار/debit).
; نگه‌داشتن تراکنش‌ها به ترتیب تاریخ اختیاری است (اما به بررسی خطا کمک می‌کند).
2024-01-02 Gringott's 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 "Chocolate Frogs"  ; نمادهای پیچیدهٔ کالا
    assets:pouch             3 "Chocolate Frogs"  ; باید داخل علامت نقل‌قول باشند.
2024-01-15 buy some shares, in two lots                 ; هزینه می‌تواند قید شود.
    assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  به معنای هزینهٔ هر واحد است
    assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ به معنای هزینهٔ کل است
                      ; ^ زیرحساب‌های به ازای هر بهر (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 "Chocolate Frogs" =      3 "Chocolate Frogs"
    assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50
    assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $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
خطوط دفتر روزنامه (journal) در صورتی که با یک علامت هش
(#) یا یک نقطه-ویرگول (;) آغاز شوند نادیده گرفته خواهند شد.
(همچنین بخش «سایر ساختارها» را ببینید.)
برنامه hledger همچنین بخش‌هایی را که با یک خط comment
آغاز شده و با یک خط end comment (یا انتهای فایل) پایان می‌یابند، نادیده می‌گیرد.
در اینجا پیشنهادی برای انتخاب میان آن‌ها آورده شده است:

• # برای یادداشت‌های سطح بالا

• ; برای کامنت کردن موقت موارد

• comment برای کامنت کردن سریع بخش‌های بزرگ (به خاطر
  داشته باشید که آنجاست، وگرنه ممکن است گیج شوید)

برای مثال:

# a comment line
; another commentline
comment
A multi-line comment block,
continuing until "end comment" directive
or the end of the current file.
end comment

برخی مدخل‌های hledger می‌توانند کامنت‌های درون‌خطی داشته باشند، از ; (نقطه-ویرگول) تا پایان خط. بخش‌های «کامنت‌های تراکنش» (Transaction comments)، «کامنت‌های ثبت» (Posting comments) و «کامنت‌های حساب» (Account comments) را در ادامه ببینید.

تراکنش‌ها (Transactions)

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

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

• یک نویسه وضعیت (خالی، !، یا *)
• یک کد (هر عدد یا متن کوتاه، محصور در پرانتز)
• یک شرح (هر متن باقی‌مانده تا انتهای خط یا نقطه-ویرگول)
• یک کامنت (هر متن باقی‌مانده پس از یک نقطه-ویرگول تا انتهای خط، و هر خط تورفته پس از آن که با نقطه-ویرگول آغاز شود)
• 0 یا چند خط تورفته ثبت (posting)، که توصیف‌کننده موارد منتقل‌شده و حساب‌های درگیر است (خطوط کامنت تورفته نیز مجاز هستند، اما خطوط خالی یا خطوط بدون تورفتگی مجاز نیستند).

در اینجا یک فایل دفتر روزنامه ساده شامل یک تراکنش آورده شده است:

2008/01/01 income
  assets:bank:checking   $1
  income:salary         $-1

تاریخ‌ها (Dates)

تاریخ‌های ساده (Simple dates)

تاریخ‌ها در فایل دفتر روزنامه از قالب تاریخ‌های ساده استفاده می‌کنند: YYYY-MM-DD یا YYYY/MM/DD یا YYYY.MM.DD، که صفرهای ابتدایی در آن‌ها اختیاری است. ممکن است سال حذف شود، که در این حالت از زمینه استنباط خواهد شد: تراکنش فعلی، سال پیش‌فرضی که با دستورالعمل Y تنظیم شده، یا تاریخ جاری هنگام اجرای دستور. چند مثال: 2010-01-31، 2010/01/31، 2010.1.31، 1/31.

(رابط کاربری علاوه بر تاریخ‌های ساده، تاریخ‌های هوشمندِ انعطاف‌پذیرتر را که در دفترچه راهنمای hledger مستند شده‌اند نیز می‌پذیرد.)

تاریخ‌های ثبت (Posting dates)

می‌توانید با افزودن یک کامنت ثبت شامل یک برچسب (در ادامه ببینید) مانند ; date:DATE، به هر یک از ثبت‌ها تاریخی متفاوت از تراکنش والد اختصاص دهید. (همچنین یک ساختار سازگار با Ledger وجود دارد: ; [DATE]، که می‌تواند کارآمد باشد.)

این روش احتمالاً بهترین راه برای کنترل دقیق تاریخ‌های ثبت است. برای مثال در این نمونه، هزینه باید در گزارش‌های May نمایش داده شود و کسر از حساب checking باید در 6/1 گزارش شود تا تطبیق بانکی به سادگی انجام گیرد:

2015/5/30
    expenses:food     $10  ; food purchased on saturday 5/30
    assets:checking        ; bank cleared it on monday, date:6/1

$ hledger -f t.j register food
2015-05-30                      expenses:food                  $10           $10

$ hledger -f t.j register checking
2015-06-01                      assets:checking               $-10          $-10

مقدار DATE باید یک تاریخ ساده باشد؛ اگر سال مشخص نشده باشد، از سالِ تاریخ تراکنش استفاده خواهد شد.

برچسب date: در صورت وجود باید یک مقدار معتبر از تاریخ ساده داشته باشد؛ برای مثال، برچسب date: بدون مقدار مجاز نیست..SS "وضعیت (Status)" تراکنش‌ها (یا ثبت‌های مجزا درون یک تراکنش) می‌توانند یک نشان وضعیت داشته باشند، که نویسه‌ای منفرد پیش از شرح تراکنش (یا نام حسابِ ثبت) است، با یک فاصله از آن جدا می‌شود، و نشان‌دهنده یکی از سه وضعیت زیر است:

هنگام گزارش‌گیری، می‌توانید با پرچم‌های -U/--unmarked، -P/--pending و -C/--cleared بر اساس وضعیت فیلتر کنید (و می‌توانید این پرچم‌ها را ترکیب کنید، برای مثال -UP برای تطبیق همه موارد به جز موارد تسویه‌شده). یا می‌توانید از پرس‌وجوهای status:، status:! و status:*، یا کلیدهای U، P و C در hledger-ui استفاده کنید.

(یادداشت: در Ledger وضعیت "unmarked" به نام "uncleared" خوانده می‌شود؛ در hledger ما آن را برای شفافیت معنایی به "unmarked" تغییر نام دادیم.)

نشان‌های وضعیت اختیاری هستند، اما می‌توانند به عنوان مثال برای مغایرت‌گیری با حساب‌های دنیای واقعی (real-world) مفید باشند. برخی حالت‌های ویرایشگر قابلیت برجسته‌سازی و میان‌برهایی را برای کار با وضعیت ارائه می‌دهند. برای مثال در ledger-mode ایمکس (Emacs)، می‌توانید وضعیت تراکنش را با C-c C-e، یا وضعیت ثبت را با C-c C-c تغییر وضعیت (toggle) دهید.

این‌که "uncleared"، "pending" و "cleared" در عمل واقعاً چه معنایی دارند، به شما بستگی دارد. در این‌جا یک پیشنهاد آمده است:

با این شیوه، می‌توانید از -PC برای دیدن موجودی فعلی در بانک خود، از -U برای مشاهده مواردی که احتمالاً به‌زودی در بانک شما اعمال می‌شوند (مانند چک‌های وصول‌نشده)، و بدون هیچ پرچمی برای دیدن به‌روزترین وضعیت مالی خود استفاده کنید..SS "کد (Code)" پس از نشانگر وضعیت، اما پیش از شرح، می‌توانید به‌صورت اختیاری یک "کد" (code) برای تراکنش، مانند شماره چک یا شناسهٔ تراکنش را محصور در پرانتز بنویسید.

این کار چند محدودیت دارد: کد نباید حاوی پرانتز بسته باشد (وگرنه کوتاه و بریده خواهد شد). کدها معمولاً تراز گزارش دفاتر (register report) را به هم می‌زنند و بازبینی چشمی آن را سخت‌تر می‌کنند. همچنین نمی‌توانید در هر تراکنش بیش از یک مقدار در آن ذخیره کنید. به این دلایل ممکن است ترجیح دهید از فیلد کد اجتناب کرده و در عوض از tags(#tags] استفاده کنید.

شرح (Description)

پس از فیلدهای تاریخ، نشانگر وضعیت و/یا کد، باقی‌ماندهٔ سطر (یا تا جایی که کامنت با ; آغاز شود) شرح تراکنش است. در اینجا می‌توانید تراکنش را توصیف کنید (که در حسابداری سنتی "شرح سند" نامیده می‌شود)، یا می‌توانید نام دریافت‌کننده/پرداخت‌کننده (payee/payer) را ثبت کنید، یا آن را خالی بگذارید.

شرح‌های تراکنش در خروجی دستور print و در گزارش‌های register نمایش داده می‌شوند و می‌توان آن‌ها را با دستور descriptions فهرست کرد.

می‌توانید با استفاده از desc:DESCREGEX بر اساس شرح پرس‌وجو کنید، یا با --pivot desc گزارش را بر اساس شرح محوری (pivot) کنید.

دریافت‌کننده و یادداشت (Payee and note)

گاهی افراد یک فیلد اختصاصی دریافت‌کننده/پرداخت‌کننده می‌خواهند که بتوان آن را با دقت بیشتری پرس‌وجو و بررسی کرد. اگر چنین چیزی می‌خواهید، می‌توانید یک نویسهٔ | (خط عمودی/pipe) در شرح بنویسید. این کار آن را به یک فیلد "payee" در سمت چپ و یک فیلد "note" در سمت راست تقسیم می‌کند. (هر یک از آن‌ها می‌توانند خالی باشند.)

می‌توانید این موارد را با payee:PAYEEREGEX و note:NOTEREGEX پرس‌وجو کنید، مقادیر آن‌ها را با دستورهای payees و notes فهرست نمایید، یا روی payee یا note عملیات محوربندی (pivot) انجام دهید.

نکته: در تراکنش‌های فاقد نویسهٔ |، مقادیر description، payee و note همگی یکسان هستند. به‌محض اضافه شدن یک |، آن‌ها از یکدیگر مجزا می‌شوند. (اگر مایلید این رفتار تغییر کند، لطفاً آن را در لیست پستی مطرح کنید.)

اگر خواستار بررسی دقیق‌تر خطاها هستید، می‌توانید نام‌های معتبر دریافت‌کننده را با دستورالعمل‌های payee تعریف کنید، و سپس این موارد را با hledger check payees اعمال و اعتبارسنجی نمایید. (توجه: به دلیل نکتهٔ ذکر شده در بالا، برای این کار باید مطمئن شوید شرح هر تراکنش شامل یک | و در نتیجه یک نام payee قابل‌بررسی باشد، حتی اگر خالی بماند.)

کامنت‌های تراکنش (Transaction comments)

متنی که پس از ;، بعد از شرح تراکنش، و/یا در سطرهای تورفته بلافاصله زیر آن قرار می‌گیرد، کامنت‌های آن تراکنش را تشکیل می‌دهد. این کامنت‌ها توسط print بازتولید می‌شوند اما در غیر این صورت نادیده گرفته خواهند شد، مگر اینکه حاوی برچسب‌ها (tags) باشند که در آن صورت نادیده گرفته نمی‌شوند.

2012-01-01 something  ; a transaction comment
    ; a second line of transaction comment
    expenses   1
    assets

ثبت‌ها (Postings)

یک ثبت عبارت است از افزودن مقداری به، یا کسر مقداری از یک حساب. هر سطر ثبت با حداقل یک فاصله یا تب آغاز می‌شود (معمولاً ۲ یا ۴ فاصله)، و در ادامه:

• (اختیاری) یک نویسهٔ وضعیت (خالی، ! یا *)، به همراه یک فاصله در ادامه
• (الزامی) یک نام حساب (هر متنی، اختیاری شامل فاصله‌های تکی. اگر هر چیزی بعد از نام حساب در همان سطر بیاید، نام حساب باید به دو یا چند فاصله ختم شود.)
• (اختیاری) یک مبلغ
• (اختیاری) یک کامنت ثبت در همان سطر، که با یک نقطه‌ویرگول (;) آغاز می‌شود.

اگر مبلغ مثبت باشد، به حساب افزوده می‌شود؛ اگر منفی باشد، از حساب کسر می‌گردد.

مبالغ ثبت در یک تراکنش باید مجموعاً برابر با صفر شوند، که نشان می‌دهد ورودی‌ها و خروجی‌ها برابر هستند. ما این را یک تراکنش تراز شده (balanced transaction) می‌نامیم. (می‌توانید دربارهٔ جزئیات تراز کردن تراکنش در ادامه اطلاعات بیشتری کسب کنید.)

اگر مبلغی نوشته نشود، به‌طور خودکار از سایر ثبت‌های درون تراکنش محاسبه خواهد شد تا تراکنش تراز شود. به عبارت دیگر، در هر تراکنش می‌توانید برای صرفه‌جویی در تایپ، یک ثبت را بدون مبلغ رها کنید..SS بدهکار و بستانکار (Debits and credits) مفاهیم سنتی حسابداری بدهکار و بستانکار مسلماً در hledger وجود دارند، اما ما آن‌ها را با علامت عددی نمایش می‌دهیم. مبالغ مثبت و منفی ثبتی (posting) به ترتیب نمایانگر بدهکار و بستانکار هستند.

نیازی نیست این موضوع را حفظ کنید، اما اگر تمایل دارید - مثلاً برای راهنمایی تازه‌واردها یا گفتگو با حسابدارتان - این یک عبارت یادیار مفید است:

debit / plus / left / short words

credit / minus / right / longer words

نام‌های حساب (Account names)

حساب‌ها شیوه اصلی دسته‌بندی موارد در hledger هستند. همانند دفترداری دوطرفه، آن‌ها می‌توانند نمایانگر حساب‌های دنیای واقعی (مانند یک حساب بانکی)، یا دسته‌بندی‌های انتزاعی‌تر مانند «پول خرج‌شده برای غذا» یا «پول قرض‌گرفته‌شده از فرانک» باشند.

نام‌های حساب منعطف هستند. می‌توانند با حروف بزرگ یا کوچک نوشته شوند؛ می‌توانند شامل حروف، اعداد، علائم نگارشی، نمادها، یا فاصله‌های تکی باشند؛ و می‌توانند به هر زبانی باشند.

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

assets, liabilities, equity, revenues, expenses

این موارد در ادامه در بخش انواع حساب (Account types) بیشتر مورد بحث قرار خواهند گرفت. در مستندات hledger ممکن است این موارد را به‌صورت اختصاری با A، L، E، R و X ببینید.

جداکننده دو فاصله (Two space delimiter)

به جداکننده دو یا چند فاصله که گاهی پس از نام‌های حساب لازم است، توجه داشته باشید. نام‌های حساب در hledger که از Ledger به ارث رسیده‌اند، بسیار منعطف هستند؛ آن‌ها می‌توانند تقریباً شامل هر نوع متنی، از جمله فاصله‌های تکی و نقطه‌ویرگول باشند. به همین دلیل، اگر چیزی در همان خط به دنبال آن‌ها بیاید، باید با دو یا چند فاصله خاتمه یابند. برای مثال، اگر یک مبلغ، انتساب موجودی (balance assignment)، یا توضیحی در همان خط پس از نام حساب بیاید، باید پیش از آن‌ها دو یا چند فاصله قرار گیرد، در غیر این صورت بخشی از نام حساب در نظر گرفته خواهند شد:

bad:     assets:accounts receivable $10        ; <- too close!
good:    assets:accounts receivable  $10

bad:     assets:accounts receivable =$1000     ; <- too close!
good:    assets:accounts receivable  =$1000

bad:     assets:accounts receivable ; comment.   <- too close!
good:    assets:accounts receivable  ; comment

این جداکننده دو فاصله‌ای در چند بخش از hledger دیده می‌شود؛ مانند پس از نام‌های حساب در ثبت‌ها (postings) یا دستورالعمل‌های حساب (account directives)؛ و همچنین پس از عبارت دوره زمانی در قواعد تراکنش‌های دوره‌ای. در ابتدای کار، انتظار داشته باشید که حداقل یک بار این موضوع شما را به اشتباه بیندازد. این مسئله گاهی آزاردهنده است، اما به ما اجازه می‌دهد ضمن حفظ سادگی نحو (syntax)، از نام‌های حساب رسا و واضح استفاده کنیم.

سلسله‌مراتب حساب (Account hierarchy)

برای گزارش‌گیری دقیق‌تر، معمولاً با قرار دادن دو‌نقطه (:) بین بخش‌های نام حساب، آن‌ها را به زیرحساب‌ها، زیرزیرحساب‌ها و موارد جزئی‌تر تقسیم می‌کنیم. به‌عنوان مثال، به‌جای نوشتن assets و expenses، ممکن است بنویسیم assets:bank:checking و expenses:food. از این نام‌ها، hledger این سلسله‌مراتب شامل پنج حساب را استنباط خواهد کرد:

assets
assets:bank
assets:bank:checking
expenses
expenses:food

یا به‌صورت یک ساختار درختی:

assets
 bank
  checking
expenses
 food

گزارش‌های hledger می‌توانند درخت حساب‌ها را در هر عمقی خلاصه کنند، بنابراین می‌توانید زیردسته‌های خود را تا هر اندازه که مایلید با جزئیات تعریف کنید. اما به‌ویژه در شروع کار زیاده‌روی نکنید؛ دسته‌بندی‌های ساده‌تر زحمت کمتری دارند..SS سایر ویژگی‌های نام حساب قراردادن نام حساب در پرانتز یا قلاب، مانند (expenses:food)، قابلیتی غیر‌استاندارد در حسابداری را فعال می‌کند: ثبت‌های مجازی (virtual postings).

نام‌های حساب را می‌توان با استفاده از نام‌های مستعار حساب (account aliases)، به‌طور موقت یا دائمی بازنویسی کرد و ساختارشان را تغییر داد.

مقادیر (Amounts)

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

قالب مقدار در hledger انعطاف‌پذیر است و از چندین قالب بین‌المللی پشتیبانی می‌کند. در اینجا چند مثال آورده شده است. مقادیر دارای یک عدد (همان «تعداد» یا «quantity») هستند:

1

..و معمولاً یک نماد ارز یا نام کالا (commodity) (توضیحات بیشتر در ادامه)، در سمت چپ یا راست مقدار عددی، با یا بدون فاصله جداکننده:

$1
4000 AAPL
3 "green apples"

پیش از مقادیر می‌تواند علامت منفی (یا علامت مثبت، هرچند مثبت پیش‌فرض است) بیاید. این علامت می‌تواند قبل یا بعد از نماد کالای واقع در سمت چپ نوشته شود:

-$1
$-1

یک یا چند فاصله بین علامت و عدد هنگام تجزیه (parsing) پذیرفته می‌شود (اما در خروجی نمایش داده نخواهند شد):

+ $1
$-      1

نماد علمی E مجاز است:

1E-6
EUR 1E3

نشانه‌های اعشار (Decimal marks)

یک نشانه اعشار می‌تواند به‌صورت نقطه یا کاما نوشته شود:

1.23
1,23

هر دوی این‌ها در قالب‌های بین‌المللی اعداد رایج هستند، بنابراین hledger نسبت به یکی بر دیگری تعصبی ندارد. از آنجا که hledger از نشانه‌های گروه‌بندی ارقام (مانند جداکننده‌های هزارگان) نیز پشتیبانی می‌کند، این بدان معناست که عددی مانند 1,000 یا 1.000 که تنها شامل یک نقطه یا کاما باشد، مبهم است. در چنین مواردی، hledger به‌طور پیش‌فرض آن را نشانه اعشار در نظر می‌گیرد و هر دوی آن‌ها را به عنوان 1 تجزیه خواهد کرد.

برای کمک به hledger جهت تجزیه دقیق‌تر چنین اعداد مبهمی، اگر از نشانه‌های گروه‌بندی ارقام استفاده می‌کنید، توصیه می‌کنیم نشانه اعشار را صریحاً تعریف کنید. بهترین روش افزودن یک دستورالعمل decimal-mark در ابتدای هر فایل داده است، مانند این:

decimal-mark .

یا می‌توانید آن را به ازای هر کالا با دستورالعمل‌های commodity که در ادامه شرح داده شده است، تعریف کنید.

hledger همچنین اعدادی مانند 10. را بدون هیچ رقمی پس از نشانه اعشار می‌پذیرد (و گاهی اوقات اعداد را برای رفع ابهام به همین شکل نمایش می‌دهد - بخش نشانه‌های اعشار پایانی یا Trailing decimal marks را ببینید)..SS "نشانه‌های تفکیک ارقام (Digit group marks)" در بخش صحیح مقدارِ مبلغ (سمت چپ نشانهٔ اعشار)، گروه‌های ارقام می‌توانند به صورت اختیاری با یک نشانهٔ تفکیک ارقام - یک کاما یا نقطه (هر کدام که به عنوان نشانهٔ اعشار استفاده نشده باشد)، یا فاصله (چندین نوع فاصله در یونیکد، مانند فاصلهٔ نشکستنی [no-break space] نیز پذیرفته می‌شوند) جدا شوند.  بنابراین این‌ها همگی مقادیر معتبری در یک فایل دفتر روزنامه هستند:

     $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

کالا (Commodity)

مبالغ در hledger هم دارای یک "مقدار" (quantity) هستند که یک عدد اعشاری علامت‌دار است، و هم دارای یک "کالا" (commodity) که یک نماد ارز، نماد معاملاتی سهام، یا هر کلمه یا عبارتی است که چیزی را که ردیابی می‌کنید توصیف می‌کند.

اگر نام کالا شامل نویسه‌های غیرحرفی (فاصله‌ها، اعداد، یا علائم نگارشی) باشد، باید همیشه آن را درون نقل‌قول دوتایی بنویسید ("green apples"، "ABC123").

اگر تنها یک عدد خالی بنویسید، آن نیز کالایی با نام "" خواهد داشت؛ ما آن را "کالای بدون نماد" (no-symbol commodity) می‌نامیم.

در واقع، hledger این مبالغ تک‌کالایی را در قالب مبالغ چندکالایی قدرتمندتری ترکیب می‌کند، که در اکثر مواقع با آن‌ها کار می‌کند. یک مبلغ چندکالایی می‌تواند برای مثال به این صورت باشد: 1 USD, 2 EUR, 3.456 TSLA. در عمل، شما مبالغ چندکالایی را تنها در خروجی hledger خواهید دید؛ نمی‌توانید آن‌ها را مستقیماً در فایل دفتر روزنامه بنویسید.

به‌طور پیش‌فرض، قالب مبالغ در دفتر روزنامه بر نحوهٔ نمایش آن‌ها توسط hledger در خروجی تأثیر می‌گذارد. این موضوع در بخش «شیوهٔ نمایش کالا» (Commodity display style) در ادامه توضیح داده شده است.

بها (Costs)

در دفترداری دوطرفهٔ سنتی، برای ثبت تراکنشی که در آن یک کالا با کالایی دیگر مبادله می‌شود، ثبت‌های حقوق مالکانه‌ی (equity postings) اضافی برای تراز کردن دو کالا اضافه می‌کنید. برای مثال:

2026-01-01 buy euros
  assets:dollars     $-123
  equity:conversion   $123
  equity:conversion  €-100
  assets:euros        €100

نرم‌افزار hledger شیوهٔ نشانه‌گذاری کارآمدتر @/@@ موسوم به "نشانه‌گذاری بها" (cost notation) را به عنوان یک جایگزین ارائه می‌دهد: به جای ثبت‌های حقوق مالکانه، می‌توانید "نرخ تبدیل" یا "قیمت معامله‌شده" را پس از مبلغِ یک ثبت بنویسید. مستندات hledger، چه در حالت خرید و چه در فروش، این را به‌طور کلی "بها" (cost) می‌نامند. این مقدار می‌تواند به صورت @ UNITPRICE یا @@ TOTALPRICE نوشته شود. برای مثال می‌توانید مورد بالا را این‌گونه بنویسید:

2026-01-01 buy euros
  assets:dollars     $-123
  assets:euros        €100 @ $1.23    ; unit cost (exchange rate)

یا:

2026-01-01 buy euros
  assets:dollars     $-123
  assets:euros        €100 @@ $123    ; total cost

بها معمولاً باید یک مقدار مثبت باشد. بهای منفی نیز پشتیبانی می‌شود، اما می‌تواند گیج‌کننده باشد، همان‌طور که در بخش --infer-market-prices: market prices from transactions مورد بحث قرار گرفته است.

بها در تراز کردن تراکنش مشارکت دارد. مبالغ پیش از بررسی اینکه آیا تراکنش تراز است یا خیر، به بهای خود تبدیل می‌شوند. همچنین می‌توانید مورد بالا را با افزونگی کمتر و به این صورت بنویسید:

2026-01-01 buy euros
  assets:dollars                      ; $-123 is inferred
  assets:euros        €100 @ $1.23

یا:

2026-01-01 buy euros
  assets:dollars                      ; $-123 is inferred
  assets:euros        €100 @@ $123

یا حتی:

2026-01-01 buy euros
  assets:euros        €100            ;  @@ $123 is inferred
  assets:dollars     $-123

این حالتِ آخر برای تراکنش‌هایی که دقیقاً شامل دو کالا هستند، بدون نیاز به نشانه‌گذاری بها یا ثبت‌های حقوق مالکانه کار می‌کند. توجه داشته باشید که ترتیب ثبت‌ها اهمیت دارد: بها به نخستین ثبت (بالایی) نسبت داده خواهد شد. بنابراین ما مجبور شدیم ترتیب ثبت‌ها را جابه‌جا کنیم تا همان معنای بالا حاصل شود. همچنین، در این شیوه ارتکاب خطاهای کشف‌نشده از همه آسان‌تر است؛ از این رو توسط hledger check balanced و همچنین توسط حالت سخت‌گیرانه (strict mode) رد می‌شود.

مزایای نشانه‌گذاری بها:

1.

فشرده‌تر است و خواندن و نوشتن آن آسان‌تر است.

2.

هنگامی که پرچم -B/--cost را اضافه کنید، گزارش‌های hledger می‌توانند چنین مبالغی را تبدیل‌شده به بهای آن‌ها نشان دهند (بخش Cost reporting را ببینید).

مزایای ثبت‌های حقوق مالکانه (equity postings):

1.

به برقرار ماندن تراز معادلهٔ حسابداری کمک می‌کنند (اگر این موضوع برایتان اهمیت دارد).

2.

به‌آسانی به هر سامانهٔ حسابداری دوطرفهٔ دیگری قابل انتقال هستند.

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

اما شما همواره می‌توانید با افزودن --infer-equity، نشانه‌گذاری بها را به ثبت‌های حقوق مالکانه تبدیل کنید. برای نمونه دستور hledger print -x --infer-equity را امتحان کنید.

و معمولاً می‌توانید با افزودن --infer-costs، ثبت‌های حقوق مالکانه را به نشانه‌گذاری بها تبدیل کنید (بخش Requirements for detecting equity conversion postings را ببینید). برای نمونه دستور hledger print -x --infer-costs را امتحان کنید.

در نهایت: استفادهٔ هم‌زمان از ثبت‌های حقوق مالکانه و نشانه‌گذاری بها تا زمانی که ساختار مدخل دفتر روزنامه مناسب باشد به طوری که معادل‌های ثبت‌های حقوق مالکانه / بها قابل تشخیص باشند، مجاز است. (در غیر این صورت، پیام خطایی دریافت خواهید کرد مبنی بر اینکه تراکنش ناتراز است.):

2026-01-01 buy euros
  assets:dollars     $-123
  equity:conversion   $123
  equity:conversion  €-100
  assets:euros        €100 @ $1.23

بنابراین در اصل می‌توانید هر دو گزینهٔ --infer-equity و --infer-costs را در فایل پیکربندی خود فعال کنید، و گزارش‌های شما از مزایای هر دو بهره‌مند خواهند شد..SS مبنای هزینه / نحو بهر (Cost basis / lot syntax) اگر کالایی را برای نگهداری به‌عنوان سرمایه‌گذاری خریداری می‌کنید، ممکن است رهگیری موارد زیر حائز اهمیت باشد:

1.

هزینهٔ اولیهٔ تملک آن

2.

تاریخ اولیهٔ تملک آن

3.

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

در hledger به این سه مورد "مبنای هزینه" (cost basis) می‌گوییم؛ و اگر مقداری که تملک می‌شود دارای مبنای هزینه باشد، آن را یک "بهر" (lot) می‌نامیم. مقامات مالیاتی معمولاً الزام می‌کنند که بهرها به‌دقت رهگیری شده و به ترتیب مشخصی واگذار (فروخته) شوند.

توجه داشته باشید هرچند "مبنای هزینه" مشابه "هزینه" (قیمت معامله) که در بالا بحث شد به نظر می‌رسد، اما این دو مفاهیمی متمایز هستند. در برخی تراکنش‌ها قیمت معامله و مبنای هزینه یکسان هستند، اما در برخی دیگر تفاوت دارند.

بنابراین مبنای هزینه نحو مختص به خود را دارد که "نحو بهر" (lot syntax) نیز نامیده می‌شود. نحو lot در hledger مشابه نحو Ledger است: یک یا چند مورد از یادداشت‌های زیر که پس از مقدار اصلی می‌آیند:

• {LOTUNITCOST} یا {{LOTTOTALCOST}} (مبحث lot price را ببینید)
• [LOTDATE] (مبحث lot date را ببینید)
• (LOTLABEL) (مبحث lot note را ببینید)

برنامهٔ hledger هنوز عملیاتی با این نحو lot انجام نمی‌دهد، به‌جز حفظ آن و نمایش در خروجی‌های txt، beancount و json دستور print. این بدان معناست که می‌توانید از این نحو در دفترهای روزنامهٔ hledger خود استفاده کنید (به‌همراه یک ثبت اضافیِ بدون مقدار در صورت نیاز برای کمک به تراز شدن تراکنش‌ها)، سپس از دستور print برای برون‌بری به Ledger ،Beancount یا rustledger استفاده نمایید تا گزارش‌های بهرها/سودها (lots/gains) آن‌ها را به‌کار بگیرید (گردش‌کار Export Lots را ببینید).

تصدیق‌های تراز (Balance assertions)

نرم‌افزار hledger از تصدیق‌های تراز به سبک Ledger در فایل‌های دفتر روزنامه پشتیبانی می‌کند. این تصدیق‌ها برای نمونه مانند = EXPECTEDBALANCE هستند که پس از مقدار یک ثبت (posting) قرار می‌گیرند. برای مثال در اینجا تراز دلاری مورد انتظار در حساب‌های a و b را پس از هر ثبت تصدیق می‌کنیم:

2013/1/1
  a   $1 =  $1
  b      = $-1
2013/1/2
  a   $1 =  $2
  b  $-1 = $-2

پس از خواندن یک فایل دفتر روزنامه، hledger تمام تصدیق‌های تراز را بررسی کرده و در صورت نادرست بودن هر یک از آن‌ها، خطایی گزارش می‌کند. تصدیق‌های تراز می‌توانند برای مثال از به‌هم‌ریختن سهوی ترازهای تطبیق‌داده‌شده هنگام پاک‌سازی مدخل‌های قدیمی جلوگیری کنند. می‌توانید آن‌ها را با پرچم -I/--ignore-assertions به‌طور موقت غیرفعال کنید که می‌تواند برای عیب‌یابی یا خواندن فایل‌های Ledger مفید باشد. (نکته: این پرچم در حال حاضر انتساب‌های تراز را که در زیر شرح داده شده است، غیرفعال نمی‌کند).

تصدیق‌ها و ترتیب (Assertions and ordering)

برنامهٔ hledger تصدیق‌های تراز یک حساب را به ترتیب تاریخ (و هنگامی که چندین تصدیق در یک روز وجود داشته باشد، به ترتیب تجزیه) محاسبه و بررسی می‌کند. توجه داشته باشید که این رفتار با Ledger متفاوت است؛ Ledger تصدیق‌ها را همیشه به ترتیب تجزیه و بدون در نظر گرفتن تاریخ‌ها بررسی می‌کند.

این بدان معناست که در hledger می‌توانید آزادانه تراکنش‌ها، ثبت‌ها یا فایل‌ها را بازآرایی کنید و تصدیق‌های تراز معمولاً به کار خود ادامه خواهند داد. استثنا زمانی است که چندین ثبت در یک روز و برای یک حساب را که دارای تصدیق تراز هستند بازآرایی کنید؛ در این صورت احتمالاً آن تصدیق‌ها نیازمند به‌روزرسانی خواهند بود.

تصدیق‌ها و فایل‌های چندگانه (Assertions and multiple files)

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

اگر همان فایل‌ها با دو گزینهٔ -f در خط فرمان مشخص شوند، تصدیق‌های موجود در فایل دوم ترازهای فایل اول را نخواهند دید.

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

چرا سیستم به این شیوه کار می‌کند؟ این امر احتمالاً با هدف hledger برای تولید گزارش‌های پایدار و قابل پیش‌بینی مرتبط است. سلسله‌مراتب فایل‌ها بخشی "همیشگی" و جزئی از داده‌های شما در نظر گرفته می‌شود، در حالی که ترتیب گزینه‌ها/آرگومان‌های خط فرمان این‌گونه نیست. ما نمی‌خواهیم تغییرات گذرا بتوانند معنای داده‌ها را تغییر دهند. به عنوان مثال بسیار ناامیدکننده خواهد بود اگر فردا همهٔ تصدیق‌های تراز شما نقض شوند، صرفاً به این دلیل که آرگومان‌های خط فرمان را با ترتیبی متفاوت وارد کرده‌اید. (از بحث و تبادل نظر در این زمینه استقبال می‌شود.).SS ادعاها و هزینه‌ها ادعاهای موجودی هزینه‌ها را نادیده می‌گیرند، و به‌طور معمول باید بدون هزینه نوشته شوند:

2019/1/1
  (a)     $1 @ €1 = $1

با این حال، ما اجازه می‌دهیم هزینه‌ها در مقادیر ادعای موجودی نوشته شوند، و print آن‌ها را نمایش می‌دهد، اما بر قبولی یا رد ادعا تأثیری ندارند. این امر برای سازگاری رو به عقب است (دستور close در hledger در گذشته ادعاهای موجودی را به همراه هزینه ایجاد می‌کرد)، و به این دلیل که انتساب‌های موجودی از هزینه‌ها استفاده می‌کنند (پایین‌تر را ببینید).

ادعاها و کالاها

ادعاهای موجودی توصیف‌شده تا اینجا «ادعاهای موجودی تک‌کالایی» هستند: آن‌ها موجودی را در یک کالا ادعا و بررسی می‌کنند، و هر کالای دیگری را که ممکن است وجود داشته باشد نادیده می‌گیرند. این همان روشی است که ادعاهای موجودی در Ledger نیز کار می‌کنند.

اگر یک حساب شامل چندین کالا باشد، می‌توانید موجودی آن‌ها را با نوشتن چندین ثبت (posting) به همراه ادعای موجودی، یکی برای هر کالا، ادعا و بررسی کنید:

2013/1/1
  usd   $-1
  eur   €-1
  both
2013/1/2
  both    0 = $1
  both    0 = €1

در hledger می‌توانید با نوشتن دو علامت مساوی (== EXPECTEDBALANCE)، یک «ادعای موجودی کالای یگانه» قوی‌تر ایجاد کنید. این کار همچنین ادعا می‌کند که به‌جز کالای ادعاشده هیچ کالای دیگری در حساب وجود ندارد (یا دست‌کم، موجودی فعلی آن‌ها صفر است):

2013/1/1
  usd   $-1  == $-1  ; these sole commodity assertions succeed
  eur   €-1  == €-1
  both      ;==  $1  ; this one would fail because 'both' contains $ and €

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

1.

جداسازی هر کالا در یک زیرحساب، و ادعا کردن آن‌ها

2.

و همچنین ادعا کردن این‌که هیچ کالایی در خودِ حساب والد وجود ندارد:

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

ادعاها و زیرحساب‌ها

تمام ادعاهای موجودی بالا (هم = و هم ==) «ادعاهای موجودی بدون احتساب زیرحساب» هستند؛ آن‌ها هر موجودی که در زیرحساب‌های عمیق‌تر وجود داشته باشد را نادیده می‌گیرند.

در hledger می‌توانید با افزودن یک ستاره پس از علامت مساوی (=* یا ==*)، «ادعاهای موجودی با احتساب زیرحساب» ایجاد کنید:

2019/1/1
  equity:start
  assets:checking  $10
  assets:savings   $10
  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else
ادعاهای تراز همواره ثبت‌های مربوط به تمام وضعیت‌ها (علامت‌نخورده، در انتظار، یا تسویه‌شده) را در نظر می‌گیرند؛ آن‌ها تحت تأثیر پرچم‌های
-U/--unmarked /
-P/--pending /
-C/--cleared یا پرس‌وجوی status:
قرار نمی‌گیرند.

ادعاها و ثبت‌های مجازی

ادعاهای تراز همواره هر دو نوع ثبت‌های واقعی و مجازی را در نظر می‌گیرند؛ آن‌ها تحت تأثیر پرچم --real/-R یا پرس‌وجوی real: قرار نمی‌گیرند.

ادعاها و ثبت‌های خودکار

ادعاهای تراز تحت تأثیر پرچم --auto قرار می‌گیرند که ثبت‌های خودکار (auto postings) تولید می‌کند و می‌تواند تراز حساب‌ها را تغییر دهد. از آنجا که ثبت‌های خودکار در hledger اختیاری هستند، حساب‌های تحت تأثیر آن‌ها در عمل دارای دو تراز هستند. اما ادعاهای تراز تنها می‌توانند یکی از این دو حالت را بیازمایند. بنابراین برای جلوگیری از ایجاد ادعاهای شکننده، یکی از موارد زیر را انجام دهید:

• ترازی را ادعا کنید که با --auto محاسبه شده است، و همواره برای آن فایل از --auto استفاده کنید
• یا ترازی را ادعا کنید که بدون --auto محاسبه شده است، و هرگز برای آن فایل از --auto استفاده نکنید
• یا از ادعاهای تراز روی حساب‌های متأثر از ثبت‌های خودکار اجتناب کنید (یا ثبت‌های خودکار را کاملاً کنار بگذارید).

ادعاها و دقت اعشار

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

ادعاها و add در hledger

ادعاهای تراز می‌توانند در مقادیر داده‌شده در add گنجانده شوند. تمام انواع ادعاها پشتیبانی می‌شوند، و ادعاها می‌توانند مشابه یک فایل دفتر روزنامه (journal) عادی استفاده شوند.

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

اگر این بررسی ادعاها مد نظر نیست، می‌توان آن را با -I غیرفعال کرد.

با این حال، تخصیص‌های تراز (balance assignments) در حال حاضر پشتیبانی نمی‌شوند.

کامنت‌های ثبت

متنی که پس از ;، در انتهای یک خط ثبت (posting)، و/یا در خطوط تورفته مستقیماً در زیر آن قرار می‌گیرد، کامنت‌های مربوط به آن ثبت را تشکیل می‌دهد. آن‌ها توسط دستور print بازتولید می‌شوند اما در غیر این صورت نادیده گرفته می‌شوند، مگر اینکه حاوی برچسب‌ها (tags) باشند که نادیده گرفته نمی‌شوند.

2012-01-01
    expenses   1  ; a comment for posting 1
    assets
    ; a comment for posting 2
    ; a second comment line for posting 2

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

ابزار hledger دقیقاً چگونه تصمیم می‌گیرد که یک تراکنش تراز است؟ به‌ویژه زمانی که پای هزینه‌ها (costs) در میان است، که اغلب به دلیل اعشارهای متناوب یا داده‌های غیردقیق مؤسسات مالی، دقیق نیستند؟ در هر commodity، ابزار hledger مقادیر ثبت تراکنش را پس از تبدیل موارد دارای هزینه، با یکدیگر جمع می‌زند؛ سپس بررسی می‌کند که آیا این حاصل‌جمع پس از گرد شدن به تعداد ارقام اعشار مناسب، برابر با صفر است یا خیر - که آن را دقت تراز کردن (balancing precision) می‌نامیم.

از نسخه 1.50، ابزار hledger دقت تراز کردن در هر تراکنش را از روی مقادیر موجود در مدخل دفتر روزنامه همان تراکنش استنتاج می‌کند (مشابه Ledger). یعنی هنگام بررسی تراز commodity A، از بالاترین دقت اعشاری دیده‌شده برای A در مدخل دفتر روزنامه (به‌استثنای مقادیر cost) استفاده می‌نماید. این کار تراز کردن تراکنش را پایدار و محکم می‌سازد؛ هرگونه عدم تراز باید به صورت آشکار در مدخل دفتر روزنامه لحاظ شود، دقت نمایش را می‌توان آزادانه با -c افزایش داد، و سازگاری با دفاتر روزنامه Ledger و Beancount بسیار خوب است.

توجه داشته باشید که نسخه‌های hledger پیش از 1.50 به شیوه متفاوتی عمل می‌کردند: آن‌ها اجازه می‌دادند دقت نمایش بر دقت تراز کردن اولویت پیدا کند (override شود). این مسئله باعث پنهان شدن عدم ترازهای جزئی و ایجاد شکنندگی می‌شد (به مسئله #2402 مراجعه کنید). در نتیجه، برخی مدخل‌های دفتر روزنامه (یا قوانین CSV) که با hledger <1.50 کار می‌کردند، اکنون با خطای "unbalanced transaction" (تراکنش نامتراز) رد می‌شوند. اگر به این مشکل برخوردید، رفع آن آسان است:

• می‌توانید رفتار پیشین را با افزودن --txn-balancing=old به دستور یا به فایل ~/.hledger.conf خود بازیابی کنید. این به شما امکان می‌دهد همچنان بدون تغییر از دفاتر روزنامه قدیمی استفاده کنید، هرچند مزایای فوق را نخواهید داشت.
• یا می‌توانید مدخل‌های دارای مشکل را برطرف کنید (توصیه‌شده). سه راهکار وجود دارد، از هر کدام که مناسب‌تر است استفاده نمایید:

انتشار برچسب (Tag propagation)

برچسب‌ها علاوه بر آنچه به آن متصل شده‌اند، به چند روش بر داده‌های مرتبط نیز تأثیر می‌گذارند و امکان پرس‌وجوهای قدرتمندتری را فراهم می‌سازند:

1.

حساب‌ها -> ثبت‌ها. ثبت‌ها برچسب‌ها را از حساب خود به ارث می‌برند.

2.

تراکنش‌ها -> ثبت‌ها. ثبت‌ها برچسب‌ها را از تراکنش خود به ارث می‌برند.

3.

ثبت‌ها -> تراکنش‌ها. تراکنش‌ها نیز برچسب‌های ثبت‌های خود را دریافت می‌کنند.  

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

account assets:checking
account expenses:food           ; atag:
2025-01-01 groceries            ; ttag:
    assets:checking             ; p1tag:
    expenses:food           $1  ; p2tag:

و دو نوع دیگر که تغییرات در این‌ها را نشان می‌دهند:

همچنین hledger از چند زیرنوع (subtype) استفاده می‌کند:

برای آسودگی، hledger بیشتر این نوع‌ها را به طور خودکار از روی نام‌های انگلیسی حساب‌ها تشخیص می‌دهد. اما بهتر است با افزودن برچسب type: در دستورهای account، آن‌ها را به طور صریح اعلان کنید. مقدار برچسب می‌تواند هر یک از انواع یا اختصارات تک‌حرفی بالا باشد.

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

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

این کار تولید آسان گزارش‌های balancesheet ،balancesheetequity ،cashflow و incomestatement، و همچنین پرس‌وجو بر اساس نوع را امکان‌پذیر می‌سازد:.

نکات:

•

می‌توانید برای عیب‌یابی، حساب‌ها و انواع آن‌ها را فهرست کنید:

• ایدهٔ خوبی است که دست‌کم یک حساب را برای هر نوع حساب اعلان کنید. اعلان برخی نوع‌ها و استنتاج برخی دیگر می‌تواند باعث اختلال در برخی گزارش‌ها شود.
• قواعد استنتاج نوع‌ها از نام حساب‌ها به شرح زیر است (با استفاده از عبارات باقاعده - Regular expressions).

اگر این قواعد برای شما کارآمد نیستند، کافی است آن‌ها را نادیده بگیرید و انواع خود را با برچسب‌های type: اعلان کنید.

دستورالعمل alias

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

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

نام‌های مستعار حساب همچنین نام‌های حساب را در دستورالعمل‌های account بازنویسی می‌کنند. آن‌ها بر نام‌های حسابی که از طریق hledger add یا hledger-web وارد می‌شوند تأثیری ندارند.

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

همچنین بخش «بازنویسی نام‌های حساب» (Rewrite account names) را ببینید.

نام‌های مستعار پایه

برای تنظیم یک نام مستعار حساب، از دستورالعمل alias در فایل دفتر روزنامه خود استفاده کنید. این کار بر تمام ورودی‌های بعدی دفتر روزنامه در فایل جاری یا فایل‌های ضمیمه‌شده به آن تأثیر می‌گذارد (اما توجه داشته باشید: بر فایل‌های هم‌سطح یا والد تأثیری ندارد). فاصله‌های اطراف = اختیاری هستند:

alias OLD = NEW

یا می‌توانید از گزینه --alias 'OLD=NEW' در خط فرمان استفاده کنید. این کار بر تمام ورودی‌ها تأثیر می‌گذارد. این روش برای آزمایش تعاملی نام‌های مستعار مفید است.

عبارات OLD و NEW نام‌های حساب کامل و حساس به بزرگی و کوچکی حروف هستند. ‏hledger هر رخدادی از نام حساب قدیمی را با نام جدید جایگزین خواهد کرد. زیرحساب‌ها نیز متأثر می‌شوند. برای مثال:

alias checking = assets:bank:wells fargo:checking
; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

نام‌های مستعار مبتنی بر عبارت باقاعده (Regex)

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

برای مثال:

alias /REGEX/ = REPLACEMENT

یا:

$ hledger --alias '/REGEX/=REPLACEMENT' ...

هر بخشی از نام حساب که با REGEX تطبیق داده شود، با REPLACEMENT جایگزین خواهد شد. ‏REGEX طبق معمول به بزرگی و کوچکی حروف حساس نیست (case-insensitive).

اگر نیاز دارید با یک اسلش رو به جلو تطبیق دهید، آن را با یک بک‌اسلش گریز دهید، مانند /\/=:.

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

alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"

‏REPLACEMENT تا انتهای خط (یا در خط فرمان، تا انتهای آرگومان گزینه) ادامه می‌یابد، بنابراین می‌تواند شامل نویسه‌های فاصله خالی انتهایی باشد..SS ترکیب نام‌های مستعار می‌توانید با استفاده از دستورالعمل‌های ژورنال و/یا گزینه‌های خط فرمان، به هر تعداد که مایلید نام مستعار (alias) تعریف کنید.

نام‌های مستعار بازگشتی - که در آن نام یک حساب ابتدا توسط یک نام مستعار، سپس توسط نام مستعاری دیگر و به همین ترتیب بازنویسی می‌شود - مجاز هستند. هر نام مستعار، تأثیر نام‌های مستعار اعمال‌شده پیشین را مشاهده می‌کند.

در چنین مواردی درک اینکه کدام نام‌های مستعار و با چه ترتیبی اعمال خواهند شد می‌تواند حائز اهمیت باشد. برای (هر نام حساب در) هر ورودی ژورنال، موارد زیر اعمال می‌شوند:

1.

دستورالعمل‌های alias پیش از ورودی ژورنال، به ترتیب آخرین مورد تجزیه‌شده (یعنی با خواندن رو به بالا از ورودی ژورنال، از پایین به بالا)

2.

گزینه‌های --alias، به همان ترتیبی که در خط فرمان ظاهر شده‌اند (از چپ به راست).

به عبارت دیگر، برای (یک نام حساب در) یک ورودی مشخص ژورنال:

• نزدیک‌ترین تعریف نام مستعار قبل/بالای ورودی ابتدا اعمال می‌شود
• نام مستعار بعدی قبل/بالای آن در مرحله بعد اعمال خواهد شد، و به همین ترتیب
• نام‌های مستعار تعریف‌شده بعد/پایین‌تر از ورودی روی آن تأثیری ندارند.

این کار به نام‌های مستعار نزدیک‌تر نسبت به موارد دورتر اولویت می‌دهد و به ارائه پایداری معنایی کمک می‌کند - نام‌های مستعار مستقل از اینکه چه فایل‌هایی و با چه ترتیبی خوانده می‌شوند، عملکرد یکسانی خواهند داشت.

در صورت بروز مشکل، افزودن --debug=6 به خط فرمان نشان خواهد داد که کدام نام‌های مستعار در چه زمانی اعمال می‌شوند.

نام‌های مستعار و چندین فایل

همان‌طور که در بخش «دستورالعمل‌ها و چندین فایل» توضیح داده شد، دستورالعمل‌های alias بر فایل‌های والد یا هم‌سطح تأثیری نمی‌گذارند. به عنوان مثال در این دستور،

hledger -f a.aliases -f b.journal

نام‌های مستعار حساب تعریف‌شده در a.aliases روی b.journal تأثیری نخواهند داشت. شامل کردن (include) نام‌های مستعار نیز کارساز نیست:

include a.aliases
2023-01-01  ; not affected by a.aliases
  foo  1
  bar

این بدان معناست که نام‌های مستعار حساب معمولاً باید در ابتدای بالاترین فایل شما اعلان شوند، مانند این:

alias foo=Foo
alias bar=Bar
2023-01-01  ; affected by aliases above
  foo  1
  bar
include c.journal  ; also affected

دستورالعمل end aliases

می‌توانید با این دستورالعمل، تمام نام‌های مستعار تعریف‌شده کنونی (دیده شده در ژورنال تا این لحظه، یا تعریف شده در خط فرمان) را پاک (فراموش) کنید:

end aliases

نام‌های مستعار می‌توانند نام‌های حساب نامعتبر ایجاد کنند

توجه داشته باشید که نام‌های مستعار حساب می‌توانند نام‌های حساب بدریخت و ناهنجاری تولید کنند که ممکن است به گزارش‌های گیج‌کننده یا خروجی نامعتبر print منجر شود. به عنوان مثال، می‌توانید تمام نام‌های حساب را پاک کنید:

2021-01-01
  a:aa     1
  b

$ hledger print --alias '/.*/='
2021-01-01
                   1

خروجی print بالا یک ژورنال معتبر نیست. یا می‌توانید یک فاصله دوتایی غیرمجاز درج کنید، که باعث ایجاد خروجی print می‌شود که در صورت تجزیه مجدد، ژورنال متفاوتی به دست می‌دهد:

2021-01-01
  old    1
  other

$ hledger print --alias old="new  USD" | hledger -f- print
2021-01-01
    new             USD 1
    other
اگر حسابی با اعلان نوع (بخش اعلان حساب‌ها > انواع حساب را ببینید) از طریق یک نام مستعار تغییر نام یابد، نوع حساب معمولاً به قوت خود باقی می‌ماند.

با این حال، تغییر نام به گونه‌ای که ساختار درخت حساب را دگرگون کند (برای نمونه تغییر نام حساب‌های والد بدون تغییر نام فرزندانشان، یا برعکس) می‌تواند مانع از به ارث بردن نوع حسابِ والدین توسط حساب‌های فرزند شود.

دوم اینکه، اگر نوع یک حساب از نام آن استنتاج می‌شود، تغییر نام آن توسط یک نام مستعار می‌تواند مانع از این کار شده یا آن را تغییر دهد.

اگر از نام‌های مستعار حساب استفاده می‌کنید و پرس‌وجوی type: حساب‌ها را آن‌طور که انتظار دارید تطبیق نمی‌دهد، عیب‌یابی را با دستور accounts امتحان کنید؛ برای مثال چیزی مانند:

$ hledger accounts --types -1 --alias assets=bassetts

دستورالعمل commodity

دستورالعمل commodity چندین عملکرد را انجام می‌دهد:

1.

اعلان می‌کند که چه نمادهای کالایی مجاز به استفاده در دفتر روزنامه هستند، و بررسی خطای مفیدی را با حالت سخت‌گیرانه (strict mode) یا دستور check ممکن می‌سازد. بخش «بررسی خطای کالا» را در زیر ببینید.

2.

اعلان می‌کند که تمام مقادیر این کالا چگونه باید نمایش داده شوند؛ برای نمونه چه تعداد رقم اعشار نمایش یابد. بخش «سبک نمایش کالا» را در بالا ببینید.

3.

(اگر هیچ دستورالعمل decimal-mark فعالی در کار نباشد:) نشانه اعشاری مورد انتظار (نقطه یا کاما) را هنگام تجزیه مقادیر این کالا، در این فایل و فایل‌های شامل‌شده در آن، از مکان این دستورالعمل تا انتهای فایل جاری تعیین می‌کند. بخش «نشانه‌های اعشار» را در بالا ببینید.

4.

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

اعلان کالاها چندین مشکل رایج تجزیه/نمایش را برطرف می‌کند، بنابراین استفاده از آن را توصیه می‌کنیم.

توجه داشته باشید که تأثیرات ۳ و ۴ در بالا، در انتهای فایلِ دستورالعمل خاتمه می‌یابند و روی فایل‌های همتا یا والد تأثیری نخواهند گذاشت. بنابراین اگر به آن‌ها متکی هستید (به‌ویژه مورد ۴) و از چندین فایل استفاده می‌کنید، قرار دادن دستورالعمل‌های commodity در یک فایل والد بالاترین سطح ممکن است حائز اهمیت باشد. یا اینکه، نشانه‌های اعشار خود را بدون ابهام نگه دارید و ورودی‌هایتان را دقیق و به‌خوبی تراز کنید.

حذف نماد کالا، سبک نمایش را تنها برای کالای بدون‌نماد تعیین می‌کند، نه همه کالاها.

سبک‌های کالا را می‌توان با گزینه خط فرمان -c/--commodity-style بازنویسی کرد.

(مرتبط: #793)

ساختار دستورالعمل commodity

یک دستورالعمل کالا معمولاً کلمه commodity است که در ادامه آن یک مقدار نمونه، و به صورت اختیاری یک توضیح می‌آید. تنها نماد مقدار و قالب عدد حائز اهمیت است. برای مثال:

commodity $1000.00
commodity 1.000,00 EUR
commodity 1 000 000.0000   ; the no-symbol commodity

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

commodity 1000. AAAA       ; show AAAA with no decimals

نمادهای کالایی حاوی فاصله، اعداد، یا نشانه‌های نگارشی باید طبق معمول داخل علامت‌های نقل‌قول دوتایی قرار گیرند:

commodity 1.0000 "AAAA 2023"

دستورالعمل‌های کالا معمولاً شامل یک مقدار نمونه هستند، اما می‌توانند تنها یک نماد را اعلان کنند (یعنی فقط عملکرد ۱ در بالا):

commodity $
commodity INR
commodity "AAAA 2023"
commodity ""               ; the no-symbol commodity

دستورالعمل‌های کالا ممکن است با یک زیردستورالعمل دندانه‌دار format نیز نوشته شوند، همانند Ledger. نماد تکرار می‌شود و باید در هر دو مکان یکسان باشد. سایر زیردستورالعمل‌ها در حال حاضر نادیده گرفته می‌شوند:

; 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
یادداشت یک دستور commodity می‌تواند حاوی برچسب‌ها باشد.
این برچسب‌ها به تمام ثبت‌هایی (postings) که از آن کالا در مقدار اصلی خود
استفاده می‌کنند، به‌عنوان برچسب‌های ثبت پنهان اما قابل پرس‌وجو، منتقل می‌شوند؛
مگر در مواردی که ثبت مذکور از قبل برچسبی با همان نام داشته باشد.
(برچسب‌های ثبت بر برچسب‌های حساب، و برچسب‌های حساب بر برچسب‌های کالا اولویت دارند.)

بررسی خطای کالا (Commodity error checking)

در حالت سخت‌گیرانه (-s/--strict) (یا هنگام اجرای hledger check commodities)، اگر نماد کالای تعریف‌نشده‌ای استفاده شود، hledger خطایی را گزارش خواهد کرد. (با یک استثنا: مقادیر صفر همیشه مجازند که نماد کالا نداشته باشند.) عملکرد آن مشابه بررسی خطای حساب (که در بالا توضیح داده شد) است.

دستور decimal-mark

می‌توانید از دستور decimal-mark - معمولاً یکی به ازای هر فایل، در بالای فایل - استفاده کنید تا مشخص نمایید هنگام تجزیه مقادیر در این فایل، چه نویسه‌ای نشان‌دهنده ممیز اعشاری است. می‌تواند به شکل زیر باشد:

decimal-mark .

یا

decimal-mark ,

این کار از هرگونه ابهام هنگام تجزیه اعداد در فایل جلوگیری می‌کند، بنابراین استفاده از آن توصیه می‌شود؛ به‌ویژه اگر فایل حاوی نشانه‌های گروه‌بندی ارقام (مانند جداکننده‌های هزارگان) باشد.

دستور include

می‌توانید با نوشتن یک دستور include، محتوای فایل‌های دیگر را به پرونده اضافه کنید، مانند زیر:

include SOMEFILE

این کار همان اثری را دارد که گویی محتوای SOMEFILE در همین نقطه درج شده است. (همچنین هر دستور include درون SOMEFILE نیز به همین ترتیب و به‌صورت بازگشتی پردازش می‌شود.)

فقط فایل‌های journal می‌توانند فایل‌های دیگر را ضمیمه (include) کنند. آن‌ها می‌توانند فایل‌های journal، timeclock یا timedot را دربرگیرند، اما فایل‌های CSV مجاز نیستند.

اگر مسیر فایل با علامت مدک (tilde) شروع شود، به معنی دایرکتوری خانگی شماست: include ~/main.journal.

اگر با یک اسلش شروع شود، یک مسیر مطلق است: include /home/user/main.journal. در غیر این صورت، مسیر نسبت به پوشه فایلی که آن را ضمیمه کرده، سنجیده می‌شود: include ../finances/main.journal.

همچنین، مسیر ممکن است دارای یک پیشوند نوع فایل باشد تا قالب فایلی مشخصی را تحمیل کرده و پسوند(های) فایل را نادیده بگیرد (همان‌طور که در Data formats شرح داده شده است): include timedot:notes/2023.md.

مسیر ممکن است شامل الگوهای glob برای تطبیق با چندین فایل باشد. الگوهای glob در hledger شبیه به zsh هستند: ? برای تطبیق با هر نویسه؛ [a-z] برای تطبیق با هر نویسه در یک محدوده؛ * برای تطبیق با صفر یا چند نویسه که جداکننده مسیر نیستند (مانند /)؛ ** برای تطبیق با صفر یا چند زیردایرکتوری و/یا صفر یا چند نویسه در ابتدای نام فایل؛ و غیره. برای سهولت کار، include همواره فایل فعلی را مستثنی می‌کند. بنابراین، می‌توانید از چنین مواردی استفاده کنید:

• include *.journal برای ضمیمه‌کردن تمام فایل‌های journal دیگر در دایرکتوری فعلی (به‌استثنای فایل‌های نقطه‌دار)
• include **.journal برای ضمیمه‌کردن تمام فایل‌های journal دیگر در این دایرکتوری و زیرشاخه‌های آن (به‌استثنای فایل‌های نقطه‌دار و دایرکتوری‌های نقطه‌دار سطح اول)
• include timelogs/2???.timedot برای ضمیمه‌کردن تمام فایل‌های timedot که نامی شبیه به شماره سال دارند.

توجه داشته باشید که * و ** معمولاً با فایل‌ها یا دایرکتوری‌های نقطه‌دار تطبیق داده نمی‌شوند، با یک استثنا: ** دایرکتوری‌های نقطه‌داری که در سطح اول نیستند را جستجو می‌کند. اگر این مسئله مشکلی ایجاد می‌کند، الگوی glob خود را دقیق‌تر تعیین کنید (مثلاً **.journal به‌جای **).

اگر از فایل‌های ضمیمه‌شده فراوان، یا با تو‌در‌تویی عمیق استفاده می‌کنید و به خطایی برخورد کرده‌اید که یافتن دقیق آن دشوار است، یک دستور عیب‌یابی خوب hledger files --debug=6 (یا 7) است..SS دستورالعمل P دستورالعمل P یک قیمت بازار را اعلان می‌کند، که در واقع نرخ تبدیل بین دو کالا در یک تاریخ مشخص است. این قابلیت به گزارش‌های ارزش اجازه می‌دهد مقادیر یک کالا را به ارزش آن در کالایی دیگر، در آن تاریخ یا پس از آن تبدیل کنند. این قیمت‌ها معمولاً از بورس اوراق بهادار، صرافی رمزارز، یا بازار تبادل ارزهای خارجی (فارکس) به دست می‌آیند.

قالب آن بدین صورت است:

P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT

DATE یک تاریخ ساده است، COMMODITY1SYMBOL نماد کالایی است که قیمت‌گذاری می‌شود، و COMMODITY2AMOUNT مقدار (نماد و کمیت) کالای ۲ است که یک واحد از کالای ۱ در این تاریخ ارزش دارد. مثال‌ها:

# 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

پرچم‌های -V، -X و --value از این قیمت‌های بازار برای نمایش مقادیر بر حسب کالایی دیگر استفاده می‌کنند. بخش گزارش‌دهی ارزش (Value reporting) را ببینید.

دستورالعمل payee

payee PAYEE NAME

از این دستورالعمل می‌توان برای اعلان مجموعه‌ای محدود از دریافت‌کنندگان وجه که ممکن است در توضیحات تراکنش ظاهر شوند استفاده کرد. در صورتی که هر تراکنشی به دریافت‌کننده‌ای اشاره کند که اعلان نشده باشد، بررسی "payees" خطا گزارش خواهد کرد. برای مثال:

payee Whole Foods    ; a comment

دریافت‌کنندگان وجه برچسب (tag) ندارند (برچسب‌ها در یادداشت نادیده گرفته می‌شوند).

برای اعلان نام دریافت‌کننده خالی، از "" استفاده کنید.

payee ""

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

دستورالعمل tag

tag TAGNAME

از این دستورالعمل می‌توان برای اعلان مجموعه‌ای محدود از نام‌های مجاز در برچسب‌ها استفاده کرد. TAGNAME باید یک نام برچسب معتبر باشد (بدون فاصله). برای مثال:

tag  item-id

هرگونه زیردستورالعمل دارای تورفتگی در حال حاضر نادیده گرفته می‌شود.

در صورتی که از هر نام برچسبِ اعلان‌نشده‌ای استفاده شود، بررسی "tags" خطا گزارش خواهد کرد. ایجاد تصادفی یک برچسب با استفاده معمول از دونقطه در یادداشت‌ها بسیار آسان است؛ اگر می‌خواهید از این کار جلوگیری کنید، می‌توانید برچسب‌های خود را اعلان و بررسی نمایید.

تراکنش‌های دوره‌ای (Periodic transactions)

دستورالعمل ~ یک «قاعده دوره‌ای» ("periodic rule") را اعلان می‌کند که هنگام اجرای hledger با پرچم --forecast، تراکنش‌های اضافی موقتی ایجاد می‌کند که معمولاً در بازه‌های زمانی مشخص تکرار می‌شوند. این «تراکنش‌های پیش‌بینی» ("forecast transactions") برای پیش‌بینی فعالیت‌های آینده مفید هستند. آن‌ها تنها در طول مدت تولید گزارش و تنها زمانی که --forecast استفاده شده باشد وجود دارند؛ آن‌ها توسط hledger در فایل دفتر روزنامه ذخیره نمی‌شوند.

قواعد دوره‌ای کاربرد دومی نیز دارند: با پرچم --budget، آن‌ها اهداف بودجه را برای بودجه‌بندی تعیین می‌کنند.

قواعد دوره‌ای می‌توانند کمی قلق‌دار باشند، بنابراین پیش از استفاده از آن‌ها، تمام این بخش یا دست‌کم نکات زیر را مطالعه کنید:

1.

افزودن یا حذف تصادفی دو فاصله برایتان دردسر ایجاد خواهد کرد - در این باره در ادامه بخوانید.

2.

برای عیب‌یابی، تراکنش‌های تولیدشده را با hledger print --forecast tag:generated یا hledger register --forecast tag:generated نمایش دهید.

3.

تراکنش‌های پیش‌بینی‌شده تنها پس از تاریخ آخرین تراکنش غیرپیش‌بینی‌شده آغاز خواهند شد.

4.

تراکنش‌های پیش‌بینی‌شده به‌طور پیش‌فرض ۶ ماه پس از امروز پایان می‌یابند. برای قواعد دقیق شروع/پایان به ادامه مراجعه کنید.

5.

عبارت‌های دوره زمانی (period expressions) می‌توانند قلق‌دار باشند. مستندات آن‌ها نیازمند بهبود است، اما ارزش مطالعه را دارد.

6.

برخی از عبارت‌های دوره زمانی با بازه تکرارشونده باید در مرز طبیعی آن بازه آغاز شوند. برای مثال در weekly from DATE، مقدار DATE باید یک دوشنبه باشد. عبارت ~ weekly from 2019/10/1 (که یک سه‌شنبه است) خطا خواهد داد.

7.

سایر عبارت‌های دوره زمانی با یک بازه به‌طور خودکار گسترش می‌یابند تا تعداد کاملی از آن بازه را پوشش دهند. (این کار برای بهبود گزارش‌ها انجام می‌شود، اما بر تراکنش‌های دوره‌ای نیز تأثیر می‌گذارد. بله، کمی با مورد بالا ناهماهنگ است.) برای مثال: ~ every 10th day of month from 2023/01 که معادل ~ every 10th day of month from 2023/01/01 است، به‌گونه‌ای تنظیم خواهد شد که از 2019/12/10 آغاز شود..SS ساختار قواعد دوره‌ای یک قاعده تراکنش دوره‌ای شبیه به یک مدخل عادی دفتر روزنامه است، که در آن تاریخ با یک مدک (~) جایگزین شده و پس از آن یک عبارت دوره‌ای می‌آید (یادآور: ~ شبیه یک موج سینوسی تکرارشونده است.):

# every first of month
~ monthly
    expenses:rent          $2000
    assets:bank:checking
# every 15th of month in 2023's first quarter:
~ monthly from 2023-04-15 to 2023-06-16
    expenses:utilities          $400
    assets:bank:checking

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

قواعد دوره‌ای و تاریخ‌های نسبی

تاریخ‌های ناقص یا نسبی (مانند 12/31، 25، tomorrow، last week، next quarter) معمولاً در قواعد دوره‌ای توصیه نمی‌شوند، زیرا با گذشت زمان نتایج تغییر خواهند کرد. در صورت استفاده، بر اساس اولویت نسبت به موارد زیر تفسیر می‌شوند:

1.

روز اول سال پیش‌فرض مشخص‌شده توسط یک دستور Y اخیر

2.

یا تاریخ مشخص‌شده با --today

3.

یا تاریخی که در آن گزارش را اجرا می‌کنید.

آن‌ها به هیچ وجه تحت تأثیر تاریخ‌های دوره گزارش یا دوره پیش‌بینی قرار نخواهند گرفت.

دو فاصله میان عبارت دوره و شرح تراکنش!

اگر به دنبال عبارت دوره یک شرح تراکنش بیاید، این دو باید با دو یا چند فاصله از هم جدا شوند. این کار به hledger کمک می‌کند تا پایان عبارت دوره را تشخیص دهد، به طوری که شرح‌ها نتوانند تصادفاً معنای آن را تغییر دهند، مانند این مثال:

; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"
;               ||
;               vv
~ every 2 months  in 2023, we will review
    assets:bank:checking   $1500
    income:acme inc

بنابراین،

• حتماً بین عبارت دوره و شرح تراکنش خود (در صورت وجود) دو فاصله قرار دهید.
• در میان عبارت دوره، به طور تصادفی دو فاصله نگذارید.

ثبت‌های خودکار (Auto postings)

دستور = یک «قاعده ثبت خودکار» ("auto posting rule") را اعلان می‌کند که ثبت‌های اضافی به تراکنش‌های موجود می‌افزاید. (به یاد داشته باشید، ثبت‌ها (postings) خطوط نام حساب و مبلغ در زیر تاریخ و شرح یک تراکنش هستند.)

در دفتر روزنامه، یک قاعده ثبت خودکار کاملاً شبیه یک تراکنش است، اما به جای تاریخ و شرح، دارای = (یادآور: تطابق یا "match") و یک پرس‌وجو (query) است، مانند این:

= QUERY
    ACCOUNT    AMOUNT
    ...

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

هر قاعده = به این صورت کار می‌کند: هنگامی که hledger با پرچم --auto اجرا می‌شود، هر جا که QUERY با ثبتی در دفتر روزنامه مطابقت داشته باشد، ثبت‌های آن قاعده دقیقاً زیر ثبت منطبق‌شده به آن تراکنش اضافه می‌شوند. توجه داشته باشید که این ثبت‌های تولیدشده موقتی هستند، و تنها در طول مدت گزارش و فقط زمانی که --auto استفاده می‌شود وجود دارند؛ آن‌ها توسط hledger در فایل دفتر روزنامه ذخیره نمی‌شوند.

ثبت‌ها می‌توانند حاوی رشته ویژه %account باشند که به نام حسابی که تطبیق یافته است بسط داده می‌شود.

مبالغ ثبت‌های تولیدشده می‌تواند به مبلغ ثبت منطبق‌شده وابسته باشد. بنابراین ثبت‌های خودکار می‌توانند مثلاً برای افزودن ثبت‌های مالیاتی با درصدی استاندارد مفید باشند. AMOUNT می‌تواند به شکل‌های زیر باشد:

• یک عدد بدون نماد ارز/کالا، مانند 2. نماد کالای ثبت منطبق‌شده به این اضافه خواهد شد.
• یک مبلغ معمولی با نماد ارز/کالا، مانند $2. این مقدار بدون تغییر استفاده خواهد شد.
• یک ستاره به همراه یک عدد، مانند *2. این کار مبلغ ثبت منطبق‌شده (و قیمت کل، در صورت وجود) را در آن عدد ضرب می‌کند.
• یک ستاره به همراه مبلغی دارای نماد ارز/کالا، مانند *$2. این کار مقدار را ضرب کرده و همچنین نماد ارز/کالا را با نماد جدید جایگزین می‌کند.

چند مثال:

; 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

$ 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

توجه داشته باشید که اتکای کامل به داده‌های تولیدشده‌ای مانند این معایبی دارد - قابلیت حمل کمتر، پایداری کمتر در آینده، دشواری بیشتر در حسابرسی توسط دیگران، و استحکام کمتر (به عنوان مثال، balance assertions شما به این وابسته خواهد بود که از --auto استفاده کنید یا خیر). یک راهکار جایگزین استفاده از ثبت‌های خودکار به صورت «یک‌باره» است - استفاده از آن‌ها برای کمک به ساخت یک مدخل پیچیده در دفتر روزنامه، مشاهده آن با hledger print --auto، و سپس کپی کردن آن خروجی در فایل دفتر روزنامه برای دائمی کردن آن..SS ثبت‌های خودکار و چندین فایل یک قاعدهٔ ثبت خودکار می‌تواند بر هر تراکنشی در فایل جاری، یا در هر فایل والد یا فایل فرزند تأثیر بگذارد. توجه داشته باشید که در حال حاضر این قواعد بر فایل‌های هم‌سطح تأثیری نخواهند داشت (زمانی که از چند -f/--file استفاده شده باشد - به #1212 مراجعه کنید).

ثبت‌های خودکار و تاریخ‌ها

تاریخ ثبت (یا تاریخ ثانویه) در ثبت منطبق‌شده، یا (با اولویت بالاتر) تاریخ ثبت در خودِ قاعدهٔ ثبت خودکار، در ثبت ایجادشده نیز استفاده خواهد شد.

ثبت‌های خودکار و تراز تراکنش / مبالغ استنتاج‌شده / ادعاهای موجودی

در حال حاضر، ثبت‌های خودکار اضافه می‌شوند:

• پس از این‌که مبالغ درج‌نشده استنتاج شدند، و تراکنش‌ها از نظر تراز بودن بررسی گردیدند،
• اما پیش از این‌که ادعاهای موجودی بررسی شوند.

توجه داشته باشید که این بدان معناست که مدخل‌های دفتر روزنامه باید هم پیش از اضافه شدن ثبت‌های خودکار و هم پس از آن تراز باشند. این سازوکار در hledger نسخهٔ 1.12+ تغییر کرد؛ برای پیش‌زمینه به #893 مراجعه کنید.

این همچنین بدین معنی است که نمی‌توانید بیش از یک ثبت خودکار با مبلغ درج‌نشده را برای یک تراکنش معین اعمال کنید، زیرا در استنتاج مبالغ ناتوان خواهد بود.

برچسب‌های ثبت خودکار

ثبت‌های خودکار دارای چند برچسب اضافی خواهند بود:

• generated-posting:= QUERY - نشان می‌دهد که این مورد توسط یک قاعدهٔ ثبت خودکار ایجاد شده است، و عبارت جستجو (query) را نمایش می‌دهد
• _generated-posting:= QUERY - یک برچسب پنهان که در خروجی hledger نمایش داده نمی‌شود. این برچسب می‌تواند برای تطبیق ثبت‌هایی به کار رود که "همین حالا" ایجاد شده‌اند، نه ثبت‌هایی که در گذشته ایجاد و در دفتر روزنامه ذخیره شده‌اند.

همچنین، به هر تراکنشی که توسط قواعد ثبت خودکار تغییر یافته باشد، این برچسب‌ها اضافه خواهند شد:

• modified: - این تراکنش تغییر یافته است
• _modified: - یک برچسب پنهان که در یادداشت‌ها ظاهر نمی‌شود؛ این تراکنش "همین حالا" تغییر یافته است.

ثبت‌های خودکار تنها روی تراکنش‌های پیش‌بینی

نکته: می‌توانید با افزودن tag:_generated-transaction به QUERY آن‌ها، ثبت‌های خودکاری ایجاد کنید که تنها بر تراکنش‌های پیش‌بینی اعمال شوند و نه تراکنش‌های ثبت‌شده. این ویژگی هنگام تولید مدخل‌های جدید دفتر روزنامه برای ذخیره شدن در دفتر روزنامه می‌تواند مفید باشد.

ساختارهای نحوی دیگر

قالب دفتر روزنامهٔ hledger از چندین قابلیت دیگر پشتیبانی می‌کند، که عمدتاً برای آسان‌تر ساختن تعامل‌پذیری با Ledger یا تبدیل از آن هستند. توجه داشته باشید که برخی از قابلیت‌های زیر قدرتمند هستند و می‌توانند در موارد خاص سودمند باشند، اما به‌طور کلی، ویژگی‌های این بخش کم‌اهمیت‌تر تلقی می‌شوند یا حتی استفاده از آن‌ها به بیشتر کاربران توصیه نمی‌شود. معایب آن‌ها ذکر شده است تا به شما در تصمیم‌گیری برای استفاده از آن‌ها کمک کند.

تخصیص‌های موجودی

تخصیص‌های موجودی به سبک Ledger نیز پشتیبانی می‌شوند. این‌ها شبیه به ادعاهای موجودی هستند، اما در سمت چپ علامت مساوی هیچ مبلغ ثبتی وجود ندارد؛ در عوض این مبلغ به‌طور خودکار محاسبه می‌شود تا شرط ادعا برآورده شود. این ویژگی می‌تواند هنگام ورود داده‌ها، مثلاً هنگام تنظیم موجودی‌های اولیه، کار را راحت‌تر کند:

; 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

یا هنگام تطبیق موجودی با واقعیت:

; no cash left; update balance, record any untracked spending as a generic expense
2016/1/15
  assets:cash    = $0
  expenses:misc

مبلغ محاسبه‌شده به موجودی حساب در آن کالا (commodity) در آن نقطه بستگی دارد (که خود به ثبت‌های دارای تاریخ قبلیِ آن کالا در آن حساب از زمان آخرین ادعا یا تخصیص موجودی وابسته است).

معایب: استفاده از تخصیص‌های موجودی باعث می‌شود دفتر روزنامهٔ شما از صراحت کمتری برخوردار باشد؛ برای آگاهی از مبلغ دقیق ثبت‌شده، به جای خواندن مستقیم آن، باید hledger را اجرا کنید یا خودتان محاسبات را انجام دهید. همچنین، تحمیل موجودی‌ها توسط تخصیص موجودی می‌تواند خطاها را پنهان کند. این موارد سبب می‌شوند داده‌های مالی شما کمتر قابل‌حمل، کمتر مقاوم در برابر تغییرات آتی، و در حسابرسی کمتر قابل‌اعتماد باشند..SS انتساب‌های تراز و هزینه‌ها یک هزینه (cost) در انتساب تراز باعث می‌شود که مقدار محاسبه‌شده، آن هزینه را به همراه داشته باشد:

2019/1/1
  (a)             = $1 @ €2

$ hledger print --explicit
2019-01-01
    (a)         $1 @ €2 = $1 @ €2

انتساب‌های تراز و چندین فایل

انتساب‌های تراز مانند تصدیق‌های تراز (balance assertions) با چندین فایل برخورد می‌کنند. آن‌ها موجودی را از فایل‌های دیگری که پیش‌تر از فایل جاری وارد (include) شده‌اند مشاهده می‌کنند، اما از فایل‌های هم‌سطح یا والد قبلی خیر.

تاریخ‌های ثبت درون قلاب

برای تنظیم تاریخ‌های ثبت و تاریخ‌های ثبت ثانویه، نحوِ تاریخ درون قلاب در Ledger نیز پشتیبانی می‌شود: [DATE]، [DATE=DATE2] یا [=DATE2] در یادداشت‌های ثبت (posting comments). دستور hledger تلاش خواهد کرد هر دنباله‌ای درون قلاب از نویسه‌های 0123456789/-.= را به این روش تجزیه کند. با این نحو، DATE سال خود را از تراکنش استنتاج می‌کند و DATE2 سال خود را از DATE برمی‌دارد.

معایب: نحوی مضاعف برای یادگیری، افزونگی با برچسب‌های date:/date2: در hledger، و شباهت گیج‌کننده به نحو تاریخ دسته (lot date) در Ledger.

دستورالعمل D

D AMOUNT

این دستورالعمل، یک کالای پیش‌فرض را تعیین می‌کند تا برای هر مقدار فاقد کالای پس از آن (یعنی اعداد ساده) که هنگام تجزیه دفتر روزنامه مشاهده می‌شود، به کار رود. این اثر تا دستورالعمل بعدی D یا پایان فایل جاری ادامه دارد.

به دلایل تاریخی یا سازگاری، D همچنین مانند یک دستورالعمل commodity عمل می‌کند (تنظیم نشانه‌گذار اعشاری کالا برای تجزیه، و سبک نمایش برای خروجی). بنابراین آرگومان آن تنها یک نماد کالا نیست، بلکه مقداری کامل است که سبک نمایش را نشان می‌دهد. مقدار حتماً باید شامل یک نشانه‌گذار اعشاری (نقطه یا ویرگول) باشد. به عنوان مثال:

; 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

برهم‌کنش با سایر دستورالعمل‌ها:

برای تنظیم سبک نمایش کالا، دستورالعمل commodity بالاترین اولویت را دارد و پس از آن دستورالعمل D قرار می‌گیرد.

برای تشخیص نشانه‌گذار اعشاری کالا هنگام تجزیه، decimal-mark بالاترین اولویت را دارد، سپس commodity، و در نهایت D.

برای بررسی نمادهای کالا با دستور check، وجود یک دستورالعمل commodity الزامی است (hledger check commodities دستورالعمل‌های D را نادیده می‌گیرد).

معایب: حذف نمادهای کالا داده‌های مالی شما را کمتر صریح، کمتر قابل حمل و در حسابرسی کمتر قابل اعتماد می‌کند. این کار معمولاً یک میان‌بُر ناپایدار است؛ دیر یا زود تمایل خواهید داشت چندین کالا را ردیابی کنید. دستور D با قابلیت‌هایی که نسبت به commodity و decimal-mark مازاد هستند، سربارگذاری شده است. همچنین سازوکار آن با D در Ledger متفاوت است.

دستورالعمل apply account

این دستورالعمل، یک حساب والد پیش‌فرض تعیین می‌کند که تا زمان رسیدن به دستورالعمل end apply account یا پایان فایل جاری، به ابتدای تمام حساب‌ها در ورودی‌های پس از آن اضافه خواهد شد. به عنوان مثال:

apply account home
2010/1/1
    food    $10
    cash
end apply account

معادل است با:

2010/01/01
    home:food           $10
    home:cash          $-10

دستورالعمل‌های account و همچنین هر محتوای واردشده (include) نیز تحت تأثیر قرار می‌گیرند.

نام‌های حسابی که از طریق hledger add یا hledger-web وارد شوند تحت تأثیر قرار نمی‌گیرند.

نام‌های مستعار حساب (در صورت وجود)، پس از اضافه شدن حساب والد به ابتدای نام اعمال می‌شوند.

معایب: این کار می‌تواند داده‌های مالی شما را در حسابرسی کمتر صریح، کمتر قابل حمل و کمتر قابل اعتماد سازد..SS رهنمود Y Y YEAR

یا (شکل‌های منسوخ‌شده برای سازگاری رو به عقب):

year YEAR apply year YEAR

فاصله اختیاری است. این دستور یک سال پیش‌فرض را تعیین می‌کند تا برای تاریخ‌های پس از آن که سالی را مشخص نکرده‌اند استفاده شود. برای مثال:

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

معایب: حذف سال (دست‌کم از تاریخ‌های اصلی تراکنش‌ها) باعث می‌شود داده‌های مالی شما کمتر صریح، با قابلیت حمل کمتر و در حسابرسی کمتر قابل اعتماد باشند. چنین تاریخ‌هایی ممکن است از رهنمود Y متناظر خود جدا شوند؛ برای مثال هنگام ارزیابی بخشی از دفتر روزنامه در ویرایشگر متن. نبود رهنمود Y باعث می‌شود گزارش‌ها وابسته به تاریخ امروز شوند.

تاریخ‌های ثانویه

تاریخ ثانویه پس از تاریخ اصلی و به دنبال علامت مساوی نوشته می‌شود: DATE1=DATE2. اگر سال حذف شود، سالِ تاریخ اصلی در نظر گرفته می‌شود. هنگام اجرای گزارش‌ها، تاریخ اصلی (سمت چپ) به‌طور پیش‌فرض استفاده می‌شود، اما با پرچم --date2 (گزینه‌های --aux-date یا --effective نیز برای کاربران Ledger کار می‌کنند)، تاریخ ثانویه (سمت راست) به جای آن به کار خواهد رفت.

معنای تاریخ‌های ثانویه به شما بستگی دارد. برای مثال می‌تواند به این صورت باشد: "تاریخ اصلی، تاریخ تسویه بانک است و تاریخ ثانویه، در صورت تفاوت، تاریخ آغاز تراکنش است".

در عمل، این قابلیت معمولاً موجب سردرگمی می‌شود:

• باید معنای تاریخ‌های اصلی و ثانویه را به یاد داشته باشید و همواره آن را رعایت کنید.
• دفترداری شما را به دو حالت تقسیم می‌کند و باید به خاطر بسپارید که کدام حالت برای یک گزارش مشخص مناسب است.
• معمولاً اعتبارسنجی‌های تراز (balance assertions) تنها با یکی از این حالت‌ها کار خواهند کرد.
• داده‌های مالی شما را پیچیده‌تر، با قابلیت حمل کمتر و در یک حسابرسی با وضوح کمتر همراه می‌سازد.
• با تمامی امکانات دیگر تداخل پیدا می‌کند و هزینه‌ای پیوسته برای توسعه‌دهندگان پدید می‌آورد.
• موجب حواس‌پرتی کاربران تازه‌کار و حامیان پروژه می‌شود.
• تاریخ‌های ثبت (posting dates) ساده‌تر هستند و کارایی بهتری دارند.

بنابراین تاریخ‌های ثانویه رسماً در hledger منسوخ شده‌اند و تنها برای سازگاری با Ledger باقی مانده‌اند؛ توصیه می‌کنیم به جای آن‌ها از posting dates استفاده کنید.

یادداشت‌های ستاره‌دار

خطوطی که با * (ستاره) آغاز می‌شوند نیز خطوط یادداشت (کامنت) هستند. این قابلیت به کاربران Emacs اجازه می‌دهد سرتیترهای org را در دفتر روزنامه خود درج کنند تا بتوانند هنگام مشاهده در org mode، آن را مانند یک ساختار سلسله‌مراتبی جمع، باز و پیمایش کنند.

معایب: یک نحو نامتعارف دیگر برای نوشتن کامنت که باید آموخته شود. قابلیت حمل دفتر روزنامه شما را کاهش می‌دهد. همچنین جابه‌جایی به حالت Emacs org صرفاً برای جمع/باز کردن، به معنای از دست دادن مزایای ledger mode بود؛ امروزه می‌توانید حالت outshine را به ledger mode بیفزایید تا بدون از دست دادن امکانات ledger mode از جمع‌وباز کردن متن نیز بهره‌مند شوید..SS "عبارت‌های ارزش‌گذاری (Valuation expressions)" نرم‌افزار Ledger اجازه می‌دهد یک تابع ارزش‌گذاری یا مقدار در پرانتزهای مضاعف پس از یک مبلغ نوشته شود. hledger این موارد را نادیده می‌گیرد.

ثبت‌های مجازی (Virtual postings)

ثبتی که پرانتزهایی در اطراف نام حساب دارد، مانند (some:account) 10، یک ثبت مجازی نامتوازن نامیده می‌شود. این ثبت‌ها در تراز کردن تراکنش شرکت نمی‌کنند. (و اگر آن‌ها را بدون مبلغ بنویسید، همواره مقدار صفر استنباط می‌شود.) این موارد گاهی اوقات می‌توانند برای شرایط خاص مناسب باشند، اما دفترداری دوطرفه را نقض می‌کنند و قابلیت انتقال داده‌های شما را میان برنامه‌های مختلف کاهش می‌دهند، بنابراین بسیاری از افراد اصلاً از آن‌ها استفاده نمی‌کنند.

ثبتی که دارای قلاب (کروشه) در اطراف نام حساب باشد ([some:account])، یک ثبت مجازی متوازن نامیده می‌شود. مجموع ثبت‌های مجازی متوازن در یک تراکنش، درست مانند ثبت‌های عادی اما به‌صورت جداگانه از آن‌ها، باید به صفر برسد. این موارد نیز بخشی از دفترداری دوطرفه نیستند، اما دست‌کم متوازن هستند. یک مثال:

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

ثبت‌های عادی، که نام حساب آن‌ها نه درون پرانتز است و نه درون قلاب، ثبت‌های واقعی نامیده می‌شوند. می‌توانید با استفاده از پرچم -R/--real یا پرس‌وجوی real:1، ثبت‌های مجازی را از گزارش‌ها مستثنی کنید.

سایر دستورالعمل‌های Ledger (Other Ledger directives)

سایر دستورالعمل‌های Ledger زیر در حال حاضر پذیرفته می‌شوند اما نادیده گرفته می‌شوند. این ویژگی به hledger امکان می‌دهد فایل‌های بیشتری از Ledger را بخواند، اما توجه داشته باشید که در صورت استفاده از این موارد، ممکن است گزارش‌های hledger با گزارش‌های Ledger تفاوت داشته باشند.

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

همچنین برای مقایسه تفصیلی نحو hledger و Ledger به https://hledger.org/ledger.html مراجعه کنید.

هزینه‌های مجازی Ledger (Ledger virtual costs)

در Ledger، عبارت‌های (@) UNITCOST و (@@) TOTALCOST هزینه‌های مجازی هستند که قیمت‌های بازار ایجاد نمی‌کنند. در hledger، این موارد معادل @ و @@ هستند.

نحو لات‌های Ledger (Ledger lot syntax)

در Ledger، این یادداشت‌های اختیاریِ پس از یک مبلغ، به تعیین مبنای هزینه (بهای تمام‌شده) یک لات تازه خریداری‌شده، یا انتخاب لات(های) موجود برای واگذاری کمک می‌کنند:

• {LOTUNITCOST} و {{LOTTOTALCOST}} (قیمت لات)
• [LOTDATE] (تاریخ لات)
• (LOTNOTE) (یادداشت لات)

نرم‌افزار hledger هنوز خود لات‌ها را محاسبه نمی‌کند، اما این یادداشت‌ها را می‌پذیرد و آن‌ها را در قالب‌های خروجی txt، beancount و json دستور print نمایش می‌دهد. این بدان معناست که می‌توانید از این نحو در دفترهای روزنامه hledger خود استفاده کنید (در صورت نیاز، همراه با یک ثبت اضافی بدون مبلغ برای کمک به تراز شدن تراکنش‌ها)، و هر زمان که خواستید لات‌ها و سود سرمایه‌ای را محاسبه کنید، از دستور print برای برون‌بری به Ledger یا Beancount بهره ببرید..SS "هزینه‌های لات ثابت در Ledger (Ledger fixed lot costs)"

•

{=UNITCOST} و {{=TOTALCOST}} (قیمت ثابت)

احتمالاً معادل با @/@@ است، اما مطمئن نیستم.

Beancount نشانه‌گذاری ساده‌تر و رفتار متفاوتی دارد:

•

@ UNITCOST و @@ TOTALCOST

•

{UNITCOST} و {{TOTALCOST}}

•

{}، {YYYY-MM-DD}، {"LABEL"}، {UNITCOST, "LABEL"}، {UNITCOST, YYYY-MM-DD, "LABEL"}

در حال حاضر، hledger

• از @ و @@ پشتیبانی می‌کند
• نشانه‌گذاری {UNITCOST}/{{TOTALCOST}} را می‌پذیرد، اما آن را نادیده می‌گیرد
• و سایر موارد را رد می‌کند.

دستورهای پاکسازی داده / تولید داده

پس از الگوی فایلِ source، می‌توانید | (پایپ) و یک دستور پاکسازی داده (یا زنجیره‌ای از دستورها) بنویسید. اگر قوانین CSV در hledger کافی نیستند، می‌توانید داده‌های بارگیری‌شده را در اینجا با یک دستور یا اسکریپت شل پیش‌پردازش کنید تا برای تبدیل مناسب‌تر شوند. این دستور توسط شل پیش‌فرض شما، در دایرکتوریِ فایل قوانین اجرا خواهد شد، محتوای فایل داده را به عنوان ورودی استاندارد دریافت خواهد کرد و باید صفر یا چند خط از مقادیر جدا شده با نویسه (CSV) را که برای تبدیل توسط قوانین CSV مناسب هستند، در خروجی ارائه دهد.

مثال‌ها:

source ./paypal.json | paypalcsv
source data/simplefin.json | simplefincsv - 'chase.*card'
source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2
source History_for_Account_Z20144832*.csv   # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g'

یا اینکه، پس از source می‌توانید | و یک دستور تولید داده را (بدون الگوی فایل پیش از |) بنویسید. این دستور هیچ ورودی‌ای دریافت نمی‌کند و باید صفر یا چند خط از مقادیر جدا شده با نویسه را که برای تبدیل توسط قوانین CSV مناسب هستند، در خروجی تولید کند.

مثال‌ها:

source | paypaljson | paypalcsv
source | paypalcsv data/paypal.json 
source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card'
source | simplefincsv data/simplefin.json 'unify.*checking'

(اسکریپت‌های paypal* و simplefin* در bin/ قرار دارند)

هر زمان که hledger یکی از این دستورها را اجرا کند، آن دستور را در stderr بازتاب (echo) خواهد داد. اگر دستور خروجی خطا تولید کند اما با موفقیت خاتمه یابد، hledger خروجی خطا را به عنوان یک هشدار نمایش می‌دهد. اگر دستور با شکست مواجه شود، hledger نیز ناموفق خواهد بود و خروجی خطا را در پیام خطا نمایش می‌دهد.

اضافه‌شده در نسخهٔ 1.50؛ آزمایشی..SS archive با افزودن archive به یک فایل قوانین، دستور import هر فایل داده یا خروجی دستور دادهٔ پردازش‌شده با موفقیت را در یک دایرکتوری data/ مجاور بایگانی خواهد کرد. نام فایل بایگانی بر اساس فایل قوانین و تاریخ ویرایش و پسوند فایل داده (یا برای دستوری که داده تولید می‌کند، تاریخ جاری و پسوند ".csv") تعیین خواهد شد. فایل دادهٔ اصلی، در صورت وجود، حذف خواهد شد.

همچنین، در این حالت import قدیمی‌ترین فایل منطبق با الگوی glob در قانون source را ترجیح می‌دهد، نه جدیدترین را. (بنابراین اگر چندین بارگیری وجود داشته باشد، ابتدا قدیمی‌ترین‌ها وارد و بایگانی می‌شوند.)

بایگانی کردن اختیاری است، اما می‌تواند برای عیب‌یابی قوانین CSV، بازتولید مدخل‌ها با قوانین بهبودیافته، بررسی تغییرات در CSV بانک شما و غیره مفید باشد.

در نسخهٔ 1.50 افزوده شد؛ آزمایشی.

encoding

encoding ENCODING

hledger به‌طور معمول انتظار دارد متن‌های غیر ascii با کدگذاری متن locale سیستم باشند. اگر نیاز به خواندن فایل‌های CSV با کدگذاری دیگری دارید، می‌توانید با افزودن encoding ENCODING به قوانین CSV خود این کار را انجام دهید. برای مثال: encoding iso-8859-1.

کدگذاری‌های زیر پشتیبانی می‌شوند:

ascii, utf-8, utf-16, utf-32, iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9, iso-8859-10, iso-8859-11, iso-8859-13, iso-8859-14, iso-8859-15, iso-8859-16, cp1250, cp1251, cp1252, cp1253, cp1254, cp1255, cp1256, cp1257, cp1258, koi8-r, koi8-u, gb18030, macintosh, jis-x-0201, jis-x-0208, iso-2022-jp, shift-jis, cp437, cp737, cp775, cp850, cp852, cp855, cp857, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, cp874, cp932.

در نسخهٔ 1.42 افزوده شد.

separator

می‌توانید از قانون separator برای خواندن انواع دیگر داده‌های جداشده با نویسه (character-separated) استفاده کنید. آرگومان می‌تواند هر تک‌نویسهٔ جداکننده یا کلمات tab یا space (بدون حساسیت به بزرگی و کوچکی حروف) باشد. برای مثال، برای مقادیر جداشده با کاما (CSV):

separator ,

یا برای مقادیر جداشده با نقطه‌ویرگول (SSV):

separator ;

یا برای مقادیر جداشده با تب (TSV):

separator TAB

اگر فایل ورودی دارای پسوند فایل .csv، .ssv یا .tsv (یا پیشوند csv:، ssv: یا tsv:) باشد، جداکنندهٔ مناسب به‌طور خودکار استنتاج می‌شود و نیازی به این قانون نخواهید داشت..SS skip

skip N

واژه skip به همراه یک عدد (یا بدون عدد، به معنای ۱) به hledger می‌گوید که این تعداد خط غیرخالی را در ابتدای داده‌های ورودی نادیده بگیرد. هر زمان که داده‌های CSV شما حاوی خطوط سرآیند باشد، به این مورد نیاز خواهید داشت. توجه داشته باشید که خطوط خالی به‌طور خودکار نادیده گرفته می‌شوند، بنابراین نیازی به شمارش آن‌ها نیست.

دستور skip کاربرد دومی نیز دارد: می‌توان از آن درون بلوک‌های if (که در ادامه توضیح داده شده) استفاده کرد تا در صورت برقرار بودن شرط، یک یا چند رکورد نادیده گرفته شوند. رکوردهایی که به این صورت رد می‌شوند نادیده گرفته خواهند شد، با این استثنا که همچنان باید CSV معتبر باشند.

date-format

date-format DATEFMT

این یک قاعده کمکی برای فیلدهای date (و date2) است. اگر تاریخ‌های CSV شما به قالب YYYY-MM-DD، YYYY/MM/DD یا YYYY.MM.DD نیستند، باید یک قاعده date-format اضافه کنید که آن‌ها را با یک الگوی تجزیه تاریخ به سبک strptime توصیف کند - پیوند زیر را ببینید: https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime الگو باید مقدار تاریخ CSV را به‌طور کامل تجزیه کند. چند مثال:

# MM/DD/YY
date-format %m/%d/%y

# D/M/YYYY
# The - makes leading zeros optional.
date-format %-d/%-m/%Y

# YYYY-Mmm-DD
date-format %Y-%h-%d

# 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

توجه داشته باشید که در حال حاضر هیچ‌گونه پشتیبانی از محلی‌سازی (locale) برای مواردی مانند %b وجود ندارد و مقداردهی LC_TIME کمکی نخواهد کرد.

timezone

timezone TIMEZONE

هنگامی که CSV حاوی تاریخ-زمان‌هایی است که به‌طور ضمنی در منطقه‌ای زمانی غیر از منطقه شما قرار دارند اما حاوی اطلاعات صریح منطقه زمانی نیستند، می‌توانید از این قاعده برای اعلام منطقه زمانی بومی CSV استفاده کنید؛ این کار به جلوگیری از خطای جابه‌جایی یک‌روزه تاریخ‌ها (off-by-one) کمک می‌کند.

هنگامی که تاریخ-زمان‌های CSV حاوی اطلاعات منطقه زمانی هستند، به این قاعده نیازی نخواهید داشت؛ در عوض، از %Z در date-format استفاده کنید (یا %z، %EZ، %Ez؛ پیوند formatTime در بالا را ببینید).

در هر یک از این حالات، hledger تبدیلی آگاه از منطقه زمانی انجام داده و تاریخ-زمان‌های CSV را به منطقه زمانی جاری سیستم شما محلی‌سازی می‌کند. اگر ترجیح می‌دهید محلی‌سازی به منطقه زمانی دیگری انجام شود، برای نمونه جهت بازتولیدپذیری، می‌توانید (دست‌کم در یونیکس) منطقه زمانی خروجی را با متغیر محیطی TZ تنظیم کنید؛ برای مثال:

$ TZ=-1000 hledger print -f foo.csv  # or TZ=-1000 hledger import foo.csv

قاعده timezone در حال حاضر نام‌های مناطق زمانی را تشخیص نمی‌دهد، به جز "UTC"، "GMT"، "EST"، "EDT"، "CST"، "CDT"، "MST"، "MDT"، "PST" یا "PDT". برای سایر موارد، از قالب عددی استفاده کنید: +HHMM یا -HHMM..SS newest-first ابزار hledger تلاش می‌کند تا اطمینان حاصل کند که تراکنش‌های تولیدشده دارای ترتیب زمانی خواهند بود، از جمله تراکنش‌های مربوط به یک روز یکسان. معمولاً این ابزار می‌تواند ترتیب رکوردهای CSV را به‌طور خودکار تشخیص دهد. اما اگر با یک فایل CSV مواجه شود که تمام رکوردهای آن دارای تاریخی یکسان باشند، فرض را بر این می‌گذارد که رکوردها از قدیمی‌ترین به جدیدترین مرتب شده‌اند. اگر در واقعیت رکوردهای CSV معمولاً از جدیدترین به قدیمی‌ترین باشند، مانند:

2022-10-01, txn 3...
2022-10-01, txn 2...
2022-10-01, txn 1...

می‌توانید قاعده newest-first را اضافه کنید تا به hledger در تولید تراکنش‌ها با ترتیب درست کمک نمایید.

# same-day CSV records are newest first
newest-first

intra-day-reversed

اگر رکوردهای CSV در یک روز معین برعکس ترتیب کلی رکوردها مرتب شده باشند، می‌توانید قاعده intra-day-reversed را برای بهبود ترتیب مدخل‌های دفتر کل اضافه کنید. به‌عنوان مثال، در اینجا ترتیب کلی رکوردها از جدیدترین به قدیمی‌ترین است، اما رکوردهای همان روز از قدیمی‌ترین به جدیدترین مرتب شده‌اند:

2022-10-02, txn 3...
2022-10-02, txn 4...
2022-10-01, txn 1...
2022-10-01, txn 2...

# transactions within each day are reversed with respect to the overall date order
intra-day-reversed

decimal-mark

decimal-mark .

یا:

decimal-mark ,

ابزار hledger هنگام تجزیه اعداد، به‌طور خودکار نقطه یا ویرگول را به‌عنوان نشانگر اعشار می‌پذیرد (رجوع کنید به Amounts). با این حال، اگر هر یک از اعداد در فایل CSV شامل نشانگرهای گروه‌بندی ارقام مانند ویرگول‌های جداکننده هزارگان باشند، باید با استفاده از این قاعده نشانگر اعشار را به‌طور صریح مشخص کنید تا از خطای تجزیه اعداد جلوگیری شود.

فیلدهای CSV و فیلدهای hledger

این موضوع می‌تواند گیج‌کننده باشد، بنابراین اجازه دهید با یک مرور کلی شروع کنیم:

• فیلدهای CSV توسط فایل داده شما ارائه می‌شوند. نام‌گذاری آن‌ها بر اساس موقعیت مکانی‌شان در رکورد CSV و با شروع از ۱ انجام می‌شود. همچنین می‌توانید یک نام خوانا به آن‌ها اختصاص دهید.
• فیلدهای hledger از پیش تعریف‌شده هستند؛ date، description، account1، amount1 و account2 برخی از آن‌ها هستند. آن‌ها بیشتر با بخش‌هایی از یک مدخل دفتر کل تراکنش مطابقت دارند.
• فیلدهای CSV و فیلدهای hledger تنها فیلدهایی هستند که با آن‌ها کار خواهید کرد؛ شما نمی‌توانید فیلدهای جدید یا متغیرهایی مانند یک زبان برنامه‌نویسی تعریف کنید. (اما می‌توانید در مرحله پیش‌پردازش، پیش از اجرای قواعد، فیلدهای CSV اضافی را به داده‌ها اضافه نمایید.)
• برای هر رکورد CSV، مقادیری را به یک یا چند مورد از فیلدهای hledger اختصاص می‌دهید تا یک تراکنش (مدخل دفتر کل) ایجاد شود. مقادیر می‌توانند متنی ایستا، مقادیر فیلد CSV از رکورد جاری، یا ترکیبی از این‌ها باشند.
• برای موارد ساده، می‌توانید نام یک فیلد CSV را هم‌نام با یکی از فیلدهای hledger تعیین کنید؛ در این صورت مقدار آن به‌طور خودکار به آن فیلد hledger اختصاص خواهد یافت.
• فیلدهای CSV فقط قابل خواندن هستند و امکان نوشتن در آن‌ها وجود ندارد. آن‌ها در سمت راست و با یک پیشوند % قرار می‌گیرند. به‌عنوان مثال:

•

فیلدهای hledger فقط قابل نوشتن هستند و خوانده نمی‌شوند. آن‌ها در سمت چپ (یا در فهرست فیلدها) و بدون هیچ پیشوندی قرار می‌گیرند. به‌عنوان مثال:

تخصیص فیلد

HLEDGERFIELD FIELDVALUE

تخصیص فیلد روش انعطاف‌پذیرتری برای انتساب مقادیر CSV به فیلدهای hledger است. از آن‌ها می‌توان به‌جای فهرست فیلدها یا علاوه بر آن (به بالا مراجعه کنید) استفاده کرد.

برای انتساب یک مقدار به فیلد hledger، نام فیلد (هر یک از نام‌های فیلدها/شبه‌فیلدهای استاندارد hledger که در ادامه تعریف شده‌اند)، یک فاصله، و سپس یک مقدار متنی در همان خط بنویسید. این مقدار متنی می‌تواند فیلدهای CSV را درون‌یابی کند، که یا با موقعیت مبتنی بر ۱ آن‌ها در رکورد CSV (%N) یا با نامی که در فهرست فیلدها به آن‌ها داده شده است (%CSVFIELD) و گروه‌های تطابق عبارت باقاعده (\N) به آن‌ها ارجاع داده می‌شود.

چند مثال:

# تنظیم مقدار بر روی چهارمین فیلد CSV، همراه با افزودن " USD" در انتها
amount %4 USD
# ترکیب سه فیلد برای ساخت کامنت، شامل برچسب‌های note: و date:
comment note: %somefield - %anotherfield, date: %1

نکات:

• درون‌یابی فاصله‌های خالی ابتدا و انتها را حذف می‌کند (بنابراین یک مقدار CSV مانند " 1 " هنگام درون‌یابی به 1 تبدیل می‌شود) (#1051).
• درون‌یابی‌ها همیشه به یک فیلد CSV ارجاع می‌دهند - نمی‌توانید یک فیلد hledger را درون‌یابی کنید. (به «ارجاع به سایر فیلدها» در ادامه مراجعه کنید)..SS "نام‌های فیلد (Field names)" به دو نوع نام فیلد که در اینجا ذکر شده و فقط در فایل‌های قواعد CSV برنامهٔ hledger به کار می‌روند، توجه کنید:

1.

نام‌های فیلد CSV (در این مستندات CSVFIELD): می‌توانید ستون‌های CSV را به‌طور اختیاری برای ارجاع آسان نام‌گذاری کنید (چرا که hledger هنوز عناوین ستون‌ها را در یک فایل CSV به‌طور خودکار تشخیص نمی‌دهد)، از طریق نوشتن نام‌های دلخواه در یک فهرست fields، به عنوان مثال:

2.

نام‌های فیلد ویژهٔ hledger (در این مستندات HLEDGERFIELD): برای تولید تراکنش hledger از یک رکورد CSV، باید حداقل برخی از این‌ها را با نوشتن آن‌ها در سمت چپ یک انتساب فیلد مقداردهی کنید، به عنوان مثال:

در اینجا تمام نام‌های فیلد ویژهٔ موجود در hledger و آنچه هنگام مقداردهی به آن‌ها رخ می‌دهد آمده است:

فیلد date (date field)

مقداردهی به date تاریخ تراکنش را تعیین می‌کند.

فیلد date2 (date2 field)

فیلد date2 تاریخ ثانویهٔ تراکنش را، در صورت وجود، تعیین می‌کند.

فیلد status (status field)

فیلد status وضعیت تراکنش را، در صورت وجود، تعیین می‌کند.

فیلد code (code field)

فیلد code کد تراکنش را، در صورت وجود، تعیین می‌کند.

فیلد description (description field)

فیلد description شرح تراکنش را، در صورت وجود، تعیین می‌کند.

فیلد comment (comment field)

فیلد comment یادداشت تراکنش را، در صورت وجود، تعیین می‌کند.

فیلد commentN، که در آن N یک عدد است، یادداشت Nاُمین ثبت (posting) را تعیین می‌کند.

می‌توانید یادداشت‌های چندخطی را با نوشتن صریح \n در کد تعیین کنید. یادداشتی که با \n شروع شود، از یک خط جدید آغاز خواهد شد.

یادداشت‌ها طبق معمول می‌توانند شامل برچسب‌ها (tags) باشند.

یادداشت‌های ثبت همچنین می‌توانند حاوی تاریخ ثبت باشند. تاریخ ثانویه، یا تاریخی بدون سال، نادیده گرفته خواهد شد.

فیلد account (account field)

مقداردهی به accountN، که در آن N عددی از ۱ تا ۹۹ است، نام حسابِ Nاُمین ثبت را تعیین کرده و باعث تولید آن ثبت می‌شود.

در بیشتر مواقع دو ثبت وجود دارد، بنابراین مایلید account1 و account2 را تعیین کنید. معمولاً account1 با فایل CSV مرتبط است و یک‌بار با یک انتساب در سطح بالا مقداردهی می‌شود، در حالی که account2 بر اساس شرح هر تراکنش در قواعد شرطی مقداردهی می‌شود.

اگر نام حسابِ یک ثبت تعیین نشود اما مبلغ آن مشخص شده باشد (پایین را ببینید)، یک نام حساب پیش‌فرض انتخاب خواهد شد (مانند "expenses:unknown" یا "income:unknown").

فیلد amount (amount field)

روش‌های مختلفی برای تعیین مبالغ ثبت از روی CSV وجود دارد که در موقعیت‌های گوناگون مفید هستند.

1.

فیلد amount قدیمی‌ترین و ساده‌ترین حالت است. مقداردهی به این فیلد، مبلغ اولین و دومین ثبت را تعیین می‌کند. در ثبت دوم، علامت مبلغ منفی می‌شود؛ همچنین، اگر بهایی به آن پیوست شده باشد، به بهای تمام‌شده تبدیل خواهد شد.

2.

فیلدهای amount-in و amount-out دقیقاً مانند مورد بالا عمل می‌کنند، اما زمانی باید استفاده شوند که CSV دو فیلد مبلغ دارد (مانند "Debit" و "Credit"، یا "Inflow" و "Outflow"). هر فیلدی که مقدار غیرصفر داشته باشد، به عنوان مبلغ ثبت اول و دوم استفاده خواهد شد. در اینجا نکاتی برای جلوگیری از سردرگمی آمده است:

3.

فیلد amountN (که در آن N عددی از ۱ تا ۹۹ است) مبلغِ تنها یک ثبت را تعیین می‌کند: Nاُمین ثبت در تراکنش. معمولاً برای ایجاد یک تراکنش تراز (متوازن) به حداقل دو مورد از این انتساب‌ها نیاز خواهید داشت. همچنین می‌توانید برای نمایش تراکنش‌های پیچیده‌تر، بیش از دو ثبت تولید کنید. شماره‌های ثبت نیازی نیست متوالی باشند؛ همراه با قواعد if، شماره‌های ثبت بالاتر می‌توانند برای اطمینان از یک ترتیب مشخص برای ثبت‌ها مفید باشند.

4.

فیلدهای amountN-in و amountN-out دقیقاً مانند مورد بالا عمل می‌کنند، اما زمانی باید استفاده شوند که فایل CSV دو فیلد مبلغ دارد. این فیلدها معادل amount-in و amount-out هستند و نکات یادشده در مورد آن‌ها در اینجا نیز صدق می‌کند.

5.

به یاد داشته باشید که یک فهرست fields نیز می‌تواند انتساب‌ها را انجام دهد. بنابراین اگر در یک فهرست fields یک فیلد CSV را "amount" بنامید، این عمل معادل انتساب به amount به حساب می‌آید. (اگر این را نمی‌خواهید، در فهرست fields نام دیگری به آن بدهید، مانند "amount_".)

6.

موارد بالا پاسخگوی هر وضعیتی نیستند؛ اگر به انعطاف‌پذیری بیشتری نیاز دارید، از یک قاعدهٔ if برای تعیین شرطی مبالغ استفاده کنید. برای اطلاعات بیشتر در این مورد و به‌طور کلی دربارهٔ نحوهٔ تعیین مبالغ، به بخش "کار با CSV > تعیین مبالغ (Working with CSV > Setting amounts)" در زیر مراجعه کنید..SS فیلد currency currency یک نماد واحد پولی تعیین می‌کند تا به ابتدای مبالغ تمام ثبت‌ها افزوده شود. اگر مبالغ CSV نماد ارز ندارند، برای نمونه زمانی که در یک ستون جداگانه قرار دارند، می‌توانید از این مورد استفاده کنید.

currencyN نماد واحد پولی را تنها به ابتدای مبلغ ثبت Nام می‌افزاید.

فیلد balance

balanceN یک مبلغ راستی‌آزمایی تراز (یا اگر مبلغ ثبت خالی رها شود، یک انتساب تراز) را روی ثبت Nام تنظیم می‌کند.

balance نگارشی برای سازگاری با نسخه‌های پیش از 1.17 برنامهٔ hledger است؛ این مورد معادل balance1 می‌باشد.

می‌توانید نوع راستی‌آزمایی/انتساب را با قاعدهٔ balance-type تنظیم کنید (به بخش زیر مراجعه کنید).

برای اطلاعات بیشتر پیرامون تنظیم مبالغ و ارز، به نکات بخش Working with CSV در ادامه مراجعه کنید.

بلوک if

قواعد می‌توانند بسته به الگوهای موجود در داده‌های CSV، به‌صورت شرطی اعمال شوند. این ویژگی انعطاف‌پذیری بالایی فراهم می‌کند؛ به‌ویژه روشی است که از طریق آن می‌توانید تراکنش‌ها را دسته‌بندی کرده و (برای مثال) بر اساس شرح آن‌ها، نام حساب مناسب را انتخاب کنید. دو روش برای نوشتن قواعد شرطی وجود دارد: «بلوک‌های if» که در اینجا توضیح داده شده‌اند، و «جدول‌های if» که در ادامه شرح داده می‌شوند.

یک بلوک if شامل کلمهٔ if و یک یا چند عبارت «تطبیق‌دهنده» (می‌تواند یک کلمه یا عبارت باشد) در هر سطر است، که از همان سطر یا سطر بعدی آغاز می‌شوند؛ و به دنبال آن یک یا چند قاعدهٔ دندانه‌دار می‌آید. برای نمونه،

if MATCHER
 RULE

یا

if
MATCHER
MATCHER
MATCHER
 RULE
 RULE

اگر هر یک از تطبیق‌دهنده‌ها موفق شود، همهٔ قواعد دندانه‌دار اعمال خواهند شد. این قواعد معمولاً انتساب فیلدها هستند، اما قواعد ویژهٔ زیر نیز می‌توانند درون یک بلوک if استفاده شوند:

• skip - رکوردِ تطبیق‌یافتهٔ CSV را نادیده می‌گیرد (هیچ تراکنشی از آن ایجاد نمی‌کند)
• end - از باقی‌ماندهٔ فایل CSV جاری صرف‌نظر می‌کند.

چند مثال:

# اگر رکورد شامل «groceries» باشد، account2 را روی «expenses:groceries» تنظیم کن
if groceries
 account2 expenses:groceries

# اگر رکورد شامل هر یک از این عبارت‌ها باشد، account2 و یک توضیح تراکنش را مطابق نمایش داده‌شده تنظیم کن
if
monthly service fee
atm transaction fee
banking thru software
 account2 expenses:business:banking
 comment  XXX deductible ? check it

# اگر یک رکورد خالی مشاهده شود (با فرض پنج فیلد)، از بقیهٔ فایل CSV صرف‌نظر کن
if ,,,,
 end
دو نوع تطبیق‌دهنده وجود دارد:

1.

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

برای مثال: whole foods.

2.

یک تطبیق‌دهنده فیلد دارای شماره یا نام فیلد CSV با پیشوند درصد (%) قبل از الگو است.

برای مثال: %3 whole foods یا %description whole foods.

دستور hledger تلاش خواهد کرد تا الگو را صرفاً درون فیلد نام‌برده‌شدهٔ CSV تطبیق دهد.

هنگام استفاده از این‌ها، باید به دو نکته توجه داشت:

1.

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

برای مثال، هنگام خواندن یک رکورد SSV مانند:
2023-01-01 ; "Acme, Inc. " ;  1,000

تطبیق‌دهنده کل رکورد در عوض این مقدار را می‌بیند:
2023-01-01,Acme, Inc. ,1,000

2.

تطبیق‌دهنده‌های فیلد انتظار یک شماره فیلد CSV یا نام فیلد CSV تعریف‌شده با fields را دارند.
هر مقدار دیگری باعث می‌شود که با رشته خالی تطبیق داده شود و احتمالاً بدون هیچ پیامی ناموفق شود (این رفتار، استفاده مجدد از قوانین مشترک با فایل‌های مختلف CSV را آسان‌تر می‌کند).
در اینجا از نام فیلد hledger استفاده نکنید (به بخش فیلدهای CSV و فیلدهای hledger مراجعه کنید).

همچنین می‌توانید در ابتدای یک تطبیق‌دهنده از ! (و یک فاصله اختیاری) استفاده کنید تا آن را نقیض کنید.
برای مثال ! whole foods، ! %3 whole foods و !%description whole foods در صورتی تطبیق می‌یابند که عبارت "whole foods" وجود نداشته باشد.
اضافه‌شده در نسخه 1.32.

الگو، طبق معمول در hledger، یک عبارت باقاعده تعمیم‌یافته POSIX است که از مرزهای کلمه گنو (\b، \B، \< و \>) و هیچ چیز دیگری پشتیبانی نمی‌کند.
برای جزئیات و نکات بیشتر، به بخش «عبارت‌های باقاعده در قوانین CSV» در زیر مراجعه کنید.

چندین تطبیق‌دهنده (Multiple matchers)

هنگامی که یک بلوک if چندین تطبیق‌دهنده داشته باشد که هر کدام در خط خودش قرار دارد:

• به طور پیش‌فرض با یکدیگر OR می‌شوند (تطبیق هر یک از آن‌ها کافی است).
• خطوط تطبیق‌دهنده‌ای که با & (یا &&، از نسخه 1.42) شروع می‌شوند، با تطبیق‌دهنده بالایی AND می‌شوند (تمام موارد موجود در گروه AND شده باید تطبیق یابند).
• خطوط تطبیق‌دهنده‌ای که با & ! (از نسخه 1.41، یا && !، از نسخه 1.42) شروع می‌شوند، ابتدا نقیض شده و سپس با تطبیق‌دهنده بالایی AND می‌شوند.

همچنین می‌توانید چندین تطبیق‌دهنده را در همان خط با جداکننده && (عملگر AND) یا && ! (عملگر AND NOT) ترکیب کنید. برای مثال %description amazon && %date 2025-01-01 تنها در صورتی تطبیق می‌یابد که فیلد description شامل "amazon" و فیلد date شامل "2025-01-01" باشد. اضافه‌شده در نسخه 1.42.

گروه‌های تطبیق (Match groups)

اضافه‌شده در نسخه 1.32

تطبیق‌دهنده‌ها می‌توانند گروه‌های تطبیق تعریف کنند: بخش‌های پرانتزدار از عبارت باقاعده که برای ارجاع در انتساب‌های فیلد در دسترس هستند. گروه‌ها در پرانتزهای معمولی (( و )) محصور می‌شوند و می‌توانند تو در تو باشند. هر گروه با استفاده از نشانه \N در انتساب‌های فیلد قابل دسترسی است، که در آن N نمایه گروه تطبیق برای این بلوک شرطی است (مانند \1، \2 و غیره).

مثال: انتقال ثبتهای پرداخت کارت اعتباری به ابتدای دوره صورت‌حساب (آغاز ماه)، برای تطابق با نحوه نمایش آن‌ها در صورت‌حساب‌ها با استفاده از تاریخ‌های ثبت:

if %date (....-..)-..
  comment2 date:\1-01

مثالی دیگر: خواندن حساب هزینه از فیلد CSV، اما دور انداختن یک پیشوند:

if %account1 liabilities:family:(expenses:.*)
    account1 \1
«جدول‌های if» جایگزینی برای بلوک‌های if هستند؛ آن‌ها می‌توانند
تطبیق‌دهنده‌ها و انتساب‌های فیلد متعددی را در قالب جدولی فشرده‌تر بیان کنند، مانند
نمونه زیر:

if,HLEDGERFIELD1,HLEDGERFIELD2,...
MATCHERA,VALUE1,VALUE2,...
MATCHERB && MATCHERC,VALUE1,VALUE2,...  (*since 1.42*)
; Comment line that explains MATCHERD
MATCHERD,VALUE1,VALUE2,...
<empty line>

نخستین نویسه پس از if به عنوان جداکننده فیلد این جدول if در نظر گرفته می‌شود. این جداکننده ارتباطی با جداکننده استفاده‌شده در فایل CSV ندارد. باید یک نویسه غیرحرفی-عددی مانند , یا | باشد که در هیچ کجای دیگر جدول ظاهر نشود (نباید در نام فیلدها، تطبیق‌دهنده‌ها یا مقادیر استفاده شود و نمی‌توان آن را با یک بک‌اسلش گریز داد).

هر خط باید تعداد یکسانی جداکننده داشته باشد؛ مقادیر خالی مجاز هستند. می‌توان برای خوانایی بیشتر از نویسه‌های فاصله (whitespace) در خطوط تطبیق‌دهنده استفاده کرد (اما در حال حاضر نه در خط if). می‌توانید از خطوط توضیحات (کامنت) در بدنه جدول استفاده کنید. جدول باید با یک خط خالی (یا پایان فایل) خاتمه یابد.

یک جدول if مانند بالا به این صورت تفسیر می‌شود: تمام خطوط دارای تطبیق‌دهنده بررسی می‌شوند؛ هرگاه خطی با تطبیق‌دهنده موفق شود، تمام مقادیر آن خط به فیلدهای متناظر hledger انتساب می‌یابند؛ اگر چندین خط تطبیق یابند، خطوط بعدی فیلدهای انتساب‌یافته توسط خطوط قبلی را بازنویسی (override) خواهند کرد - دقیقاً همان رفتاری که توالی بلوک‌های if دارند.

جدول if نشان‌داده‌شده در بالا معادل این توالی از بلوک‌های if است:

if MATCHERA
  HLEDGERFIELD1 VALUE1
  HLEDGERFIELD2 VALUE2
  ...
if MATCHERB && MATCHERC
  HLEDGERFIELD1 VALUE1
  HLEDGERFIELD2 VALUE2
  ...
; Comment line which explains MATCHERD
if MATCHERD
  HLEDGERFIELD1 VALUE1
  HLEDGERFIELD2 VALUE2
  ...

مثال:

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

balance-type

ارزیابی‌های تراز (balance assertions) تولیدشده با مقداردهی به balanceN به‌طور پیش‌فرض از نوع ساده = هستند که یک ارزیابی تک‌کالایی و بدون احتساب زیرحساب‌ها است. ممکن است گونه‌های شامل زیرحساب‌ها را کاربردی‌تر بیابید؛ برای مثال اگر برای کمک به بودجه‌بندی، زیرحساب‌های مجازی برای checking ایجاد کرده باشید. می‌توانید با استفاده از قاعده balance-type نوع دیگری از ارزیابی را انتخاب کنید:

# balance assertions will consider all commodities and all subaccounts
balance-type ==*

انواع ارزیابی تراز برای ارجاع سریع در زیر آورده شده‌اند:

=    single commodity, exclude subaccounts
=*   single commodity, include subaccounts
==   multi commodity,  exclude subaccounts
==*  multi commodity,  include subaccounts

include RULESFILE

این دستور، محتویات یک فایل قوانین CSV دیگر را در این نقطه وارد می‌کند. RULESFILE یک مسیر فایل مطلق یا یک مسیر نسبی به دایرکتوری فایل فعلی است. این قابلیت می‌تواند برای به‌اشتراک‌گذاری قوانین مشترک بین چندین فایل قوانین مفید باشد؛ برای مثال:

# someaccount.csv.rules
## someaccount-specific rules
fields   date,description,amount
account1 assets:someaccount
account2 expenses:misc
## common rules
include categorisation.rules

کار با CSV

چند نکته:

بازخورد سریع

ایده خوبی است که در حین ایجاد یا عیب‌یابی قوانین CSV، بازخورد سریع دریافت کنید. در اینجا یک روش مناسب با استفاده از entr برگرفته از eradman.com/entrproject آورده شده است:

$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'

یک پرس‌وجوی desc: (برای مثال) برای انتخاب تنها یک یا چند تراکنش مورد نظر استفاده می‌شود. از "bash -c" برای اجرای چندین دستور استفاده شده است تا بتوانیم با هر بار اجرای مجدد دستور یک جداکننده چاپ کنیم و خواندن خروجی آسان‌تر شود.

CSV معتبر

توجه داشته باشید که hledger فقط CSVهای معتبر منطبق بر RFC 4180 و قالب‌های معادل SSV و TSV (مانند RFC 4180 اما با نقطه-ویرگول یا تب به‌عنوان جداکننده) را می‌پذیرد. این بدان معناست که برای مثال:

• مقادیر ممکن است در علامت نقل‌قول جفتی قرار گیرند یا نگیرند. قرار دادن در علامت نقل‌قول تکی مجاز نیست. (برای مثال 'A','B' رد می‌شود.)
• هنگامی که مقادیر در علامت نقل‌قول جفتی قرار می‌گیرند، فاصله‌ها در بیرون علامت نقل‌قول مجاز نیستند. (برای مثال "A", "B" رد می‌شود.)
• هنگامی که مقادیر درون علامت نقل‌قول قرار ندارند، نباید شامل علامت نقل‌قول جفتی باشند. (برای مثال A"A, B رد می‌شود.)

اگر CSV/SSV/TSV شما از این نظر معتبر نیست، لازم است پیش از خواندن آن با hledger، آن را تبدیل کنید. استفاده از sed یا یک تجزیه‌کننده آسان‌گیرتر CSV مانند کتابخانه csv در python را امتحان کنید.

پسوند فایل

برای کمک به hledger در انتخاب خواننده فایل CSV و نمایش پیام‌های خطای مناسب (و انتخاب نویسه جداکننده فیلد پیش‌فرض به شکل صحیح)، بهتر است فایل‌های CSV/SSV/TSV با پسوند نام فایل .csv، .ssv یا .tsv نام‌گذاری شوند. (اطلاعات بیشتر در این زمینه در بخش قالب‌های داده آمده است.)

هنگام خواندن فایل‌هایی با پسوند «اشتباه»، می‌توانید با اضافه کردن پیشوند csv:، ssv: یا tsv: به ابتدای مسیر فایل، از خواننده CSV (و جداکننده فیلد پیش‌فرض) اطمینان حاصل کنید؛ برای مثال:

$ hledger -f ssv:foo.dat print

همچنین در صورت نیاز می‌توانید نویسه جداکننده فیلد پیش‌فرض را با یک قاعده separator بازنویسی و لغو کنید.

خواندن CSV از ورودی استاندارد

هنگام خواندن CSV از stdin نیز به پیشوند قالب فایل نیاز خواهید داشت، چرا که hledger به طور پیش‌فرض قالب journal را در نظر می‌گیرد. برای مثال:

$ cat foo.dat | hledger -f ssv:- print
اگر برای خواندن هم‌زمان چندین فایل CSV از چندین گزینهٔ -f استفاده
کنید، hledger برای هر فایل CSV به دنبال یک فایل قواعد (rules) با نام متناظر خواهد گشت.
اما اگر یک فایل قواعد را با --rules مشخص کنید، آن فایل قواعد
برای همهٔ فایل‌های CSV استفاده خواهد شد.

خواندن فایل‌های مشخص‌شده با قاعده

به‌جای مشخص کردن یک فایل CSV در خط فرمان، می‌توانید یک فایل قواعد را مشخص کنید، مانند hledger -f foo.csv.rules CMD. به‌طور پیش‌فرض این کار داده‌ها را از foo.csv در همان دایرکتوری می‌خواند، اما می‌توانید یک قاعدهٔ source برای مشخص کردن فایل داده‌ای متفاوت اضافه کنید، که شاید در دایرکتوری بارگیری‌های مرورگر وب شما قرار داشته باشد.

این قابلیت در hledger 1.30 اضافه شده است، بنابراین آن را در بیشتر مثال‌های قواعد CSV نخواهید دید. اما این ویژگی به حذف بخشی از کارهای تکراری مدیریت بارگیری‌های CSV کمک می‌کند. نام‌های پیش‌فرض فایل‌های CSV در اکثر مؤسسات مالی شما متفاوت است و با یک الگوی glob قابل شناسایی است. بنابراین می‌توانید قاعده‌ای مانند source Checking1*.csv را در foo-checking.csv.rules قرار دهید و سپس به‌طور دوره‌ای روال کاری‌ای مانند زیر را دنبال کنید:

1.

بارگیری CSV از وب‌سایت Foo، با استفاده از پیش‌فرض‌های مرورگرتان

2.

اجرای hledger import foo-checking.csv.rules برای وارد کردن هرگونه تراکنش جدید

پس از وارد کردن (import)، می‌توانید به دلخواه خود: فایل CSV را دور بیندازید، یا آن را برای مدتی همان‌جا که هست رها کنید، یا آن را به بایگانی‌های خود منتقل کنید. اگر کاری انجام ندهید، دفعهٔ بعد مرورگر شما فایلی مانند Checking1-2.csv را ذخیره خواهد کرد، و hledger به دلیل نویسهٔ عام (wildcard) * و به این دلیل که جدیدترین است، از آن استفاده خواهد کرد.

تراکنش‌های معتبر

پس از خواندن یک فایل CSV،‏ hledger ورودی‌های دفترکل تولیدشده را همانند یک فایل دفترکل پس‌پردازش و اعتبارسنجی می‌کند - تراز کردن آن‌ها، اعمال تخصیص‌های تراز (balance assignments)، و استانداردسازی قالب مبالغ. هرگونه خطا در این مرحله به روش معمول با نمایش ورودی مشکل‌دار گزارش خواهد شد.

یک استثنا وجود دارد: در صورت ایجاد احکام تراز (balance assertions)، آن‌ها بررسی نخواهند شد، زیرا این احکام معمولاً تنها زمانی عمل می‌کنند که داده‌های CSV بخشی از دفترکل اصلی باشند. اگر نیاز دارید احکام تراز تولیدشده از CSV را فوراً بررسی کنید، آن را با لوله (pipe) به یک hledger دیگر بفرستید:

$ hledger -f file.csv print | hledger -f- print

حذف موارد تکراری، وارد کردن

هنگامی که یک فایل CSV را به‌طور دوره‌ای بارگیری می‌کنید (برای مثال دریافت آخرین تراکنش‌های بانکی‌تان)، فایل جدید ممکن است با فایل قدیمی هم‌پوشانی داشته باشد و شامل برخی از رکوردهای مشابه باشد.

دستور import اقدامات زیر را انجام می‌دهد: (الف) تراکنش‌های جدید را شناسایی می‌کند، و (ب) فقط همان تراکنش‌ها را به دفترکل اصلی شما پیوست (append) می‌کند. این دستور خنثی‌اثر (idempotent) است، بنابراین نیازی نیست به یاد داشته باشید که چند بار آن را اجرا کرده‌اید یا با کدام نسخه از CSV. (این دستور وضعیت را در یک فایل پنهان .latest.FILE.csv نگه می‌دارد.) این آسان‌ترین راه برای وارد کردن داده‌های CSV است. به عنوان مثال:

# download the latest CSV files, then run this command.
# Note, no -f flags needed here.
$ hledger import *.csv [--dry]

این روش برای بیشتر فایل‌های CSV کار می‌کند. (جایی که رکوردها ترتیب زمانی پایداری دارند، و رکوردهای جدید فقط در انتهای جدیدتر ظاهر می‌شوند.)

تعدادی ابزار و روال‌های کاری دیگر، چه اختصاصی hledger و چه غیر از آن، برای تبدیل، حذف تکرار، دسته‌بندی و مدیریت داده‌های CSV وجود دارند. ببینید:

• https://hledger.org/cookbook.html#setups-and-workflows
• https://plaintextaccounting.org -> data import/conversion

عبارت‌های منظم در قواعد CSV

عبارت‌های منظم در شرط‌های if (همچنین معروف به تطبیق‌دهنده‌ها یا matchers) عبارت‌های منظم گسترش‌یافتهٔ POSIX هستند که از مرزهای کلمهٔ گنو (\b، \B، \<، \>) نیز پشتیبانی می‌کنند، و نه چیز دیگر. (برای جزئیات بیشتر، Regular expressions را ببینید.)

در اینجا چند مثال آورده شده است که ممکن است در قواعد CSV مفید باشند:

• آیا فیلد "foo" واقعاً خالی است؟ if %foo ^$
• آیا خالی است یا فقط شامل نویسه‌های فاصله‌ای (whitespace) است؟ if %foo ^ *$
• آیا غیرخالی است؟ if %foo .
• آیا شامل نویسهٔ غیرفاصله‌ای است؟ if %foo [^ ]

آزمودن مقدار فیلدهای عددی کمی دشوارتر است. نمی‌توانید از پرس‌وجوهای hledger مانند amt:0 یا amt:>10 در قواعد CSV استفاده کنید. اما اغلب می‌توانید با یک عبارت منظم به همان نتیجه برسید.

توجه داشته باشید که محتوا و چیدمان فیلدهای عددی در CSV متفاوت است، و می‌تواند به مرور زمان تغییر کند (مثلاً اگر ارائه‌دهندهٔ داده را تغییر دهید). بنابراین عبارت‌های منظم عددی همیشه تا حدودی مختص به داده‌های CSV خاص شما هستند؛ و ایدهٔ خوبی است که در صورت امکان آن‌ها را با رویکرد دفاعی و مقاوم (defensive and robust) بنویسید.

در اینجا چند مثال آورده شده است:

• آیا foo شامل یک عدد غیرصفر است؟ if %foo [1-9]
• آیا منفی است؟ if %foo -
• آیا نامنفی است؟ if ! %foo -
• آیا >= 10 است؟ if %foo [1-9][0-9]+\. (با فرض ممیز اعشاری نقطه‌ای و بدون صفرهای ابتدایی)
• آیا >= 10 و < 20 است؟ if %foo \b1[0-9]\..SS تنظیم مقادیر در ادامهٔ فیلد مقدار در بالا، در اینجا نکات بیشتری برای تنظیم مقادیر آورده شده است:

1.

اگر مقدار در یک فیلد تکی CSV باشد:

2.

اگر مقدار در دو فیلد CSV باشد (مانند Debit و Credit، یا In و Out):

3.

اگر می‌خواهید مقدار ثبت ۲ به بهای تمام‌شده (cost) تبدیل شود:

از نحو بدون شمارهٔ amount (یا amount-in و amount-out) استفاده کنید.

4.

اگر CSV تنها شامل مقادیر مانده باشد و نه مقادیر تراکنش:

آن را به balanceN اختصاص دهید تا یک انتساب مانده روی ثبت N-ام تنظیم شود و باعث محاسبهٔ خودکار مقدار ثبت گردد. balance بدون شماره معادل balance1 است. در این وضعیت احتمال اینکه hledger نام حساب پیش‌فرض را اشتباه حدس بزند بیشتر است، بنابراین ممکن است لازم باشد آن را به‌طور صریح تنظیم کنید..SS علامت‌های مقدار (Amount signs) رفتار ویژه‌ای وجود دارد که تجزیه و معکوس کردن علامت‌های مقدار را آسان‌تر می‌کند. (این قابلیت فقط برای مقادیر کامل کار می‌کند، نه برای مقادیر هزینه مانند COST در amount1 AMT @ COST):

•

اگر مقدار با یک علامت مثبت آغاز شود:

آن علامت حذف خواهد شد: +AMT تبدیل می‌شود به AMT

•

اگر مقدار درون پرانتز باشد:

پرانتزهای آن حذف شده و علامت آن معکوس می‌شود: (AMT) تبدیل می‌شود به -AMT

•

اگر مقدار دو علامت منفی داشته باشد (یا دو جفت پرانتز، یا یک علامت منفی و پرانتز):

اثر یکدیگر را خنثی کرده و حذف خواهند شد: --AMT یا -(AMT) تبدیل می‌شود به AMT

•

اگر مقدار فقط شامل یک علامت باشد (یا فقط یک جفت پرانتز):

آن علامت حذف شده و به یک مقدار خالی تبدیل می‌شود. "+" یا "-" یا "()" تبدیل می‌شود به "".

تنظیم یک مقدار روی قدر مطلق آن، یعنی نادیده گرفتن علامت آن، (بدون پیش‌پردازش CSV) امکان‌پذیر نیست.

تنظیم ارز/کالا (Setting currency/commodity)

اگر نماد ارز/کالا در فیلد(های) مقدارِ فایل CSV گنجانده شده باشد:

2023-01-01,foo,$123.00

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

fields date,description,amount

2023-01-01 foo
    expenses:unknown         $123.00
    income:unknown          $-123.00

اگر ارز به صورت یک فیلد جداگانه در CSV ارائه شده باشد:

2023-01-01,foo,USD,123.00

می‌توانید آن را به شبه‌فیلد currency تخصیص دهید، که این ویژگی خاص را دارد که به ابتدای هر مقدار در تراکنش اضافه می‌شود (در سمت چپ، بدون فاصله جداکننده):

fields date,description,currency,amount

2023-01-01 foo
    expenses:unknown       USD123.00
    income:unknown        USD-123.00

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

fields date,description,cur,amt
amount %amt %cur

2023-01-01 foo
    expenses:unknown        123.00 USD
    income:unknown         -123.00 USD

توجه داشته باشید که از نام فیلد موقتی (cur) استفاده کردیم که currency نیست - چرا که در غیر این صورت اثر پیش‌افزودن فعال می‌شد، چیزی که در اینجا نمی‌خواهیم..SS ارقام اعشار مبلغ هنگامی که داده‌های CSV را می‌خوانید، مثلاً با دستوری مانند hledger -f foo.csv print، hledger دقت اعشار هر کالا (و دیگر شیوه‌های نمایش آن) را از روی مبالغ استنتاج می‌کند - بسیار شبیه به خواندن یک فایل دفتر روزنامه بدون دستورالعمل‌های commodity (پیوند را ببینید).

توجه داشته باشید که شیوه‌های نمایش کالا از اعداد موجود در داده‌های اصلی CSV استنتاج نمی‌شوند؛ بلکه از مبالغ تولیدشده توسط قواعد CSV استنباط می‌گردند.

هنگامی که داده‌های CSV را با دستور import وارد می‌کنید، به عنوان مثال hledger import foo.csv، گام دیگری نیز وجود دارد: import تلاش می‌کند مدخل‌های جدید را با شیوه‌های موجود در دفتر روزنامه مطابقت دهد. بنابراین برای هر کالا - فرض کنید EUR باشد - دستور import موارد زیر را برمی‌گزیند:

1.

شیوه اعلان‌شده برای EUR با یک دستورالعمل commodity در دفتر روزنامه

2.

در غیر این صورت، شیوه استنتاج‌شده از مبالغ EUR در دفتر روزنامه

3.

در غیر این صورت، شیوه استنتاج‌شده از مبالغ EUR تولیدشده توسط قواعد CSV.

خلاصه (TLDR): اگر import دقت‌ها یا شیوه‌های مورد نظر شما را تولید نمی‌کند، یک دستورالعمل commodity برای مشخص کردن آن‌ها اضافه کنید.

ارجاع به فیلدهای دیگر

در انتساب فیلدها، شما تنها می‌توانید فیلدهای CSV را جای‌گذاری کنید، نه فیلدهای hledger را. در مثال زیر، هم یک فیلد CSV و هم یک فیلد hledger به نام amount1 وجود دارد، اما %amount1 همیشه به فیلد CSV اشاره دارد، نه فیلد hledger:

# Name the third CSV field "amount1"
fields date,description,amount1
# Set hledger's 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

در اینجا، از آنجا که فیلد amount1 در CSV وجود ندارد، %amount1 مقدار لفظی "amount1" را تولید خواهد کرد:

fields date,description,csvamount
amount1 %csvamount USD
# Can't interpolate amount1 here
comment %amount1

هنگامی که چندین انتساب فیلد به یک فیلد یکسان در hledger وجود دارد، تنها آخرین انتساب اعمال می‌شود. در اینجا، مقدار comment برابر با B خواهد بود، یا اگر عبارت "something" تطبیق داده شود مقدار آن C خواهد بود، اما هرگز A نخواهد بود:

comment A
comment B
if something
 comment C

نحوه ارزیابی قواعد CSV

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

1.

تمام فایل‌های قواعد الحاق‌شده (included)، از بالا به پایین و به روش اول‌عمق (بررسی بازگشتی هر فایل الحاق‌شده برای الحاق‌های بعدی، پیش از ادامه) درون‌ریزی می‌شوند.

2.

قواعد سطح بالا (date-format، fields، newest-first، skip و غیره) از بالا به پایین خوانده می‌شوند. منظور از "قواعد سطح بالا" قواعد غیرشرطی است. اگر قاعده‌ای بیش از یک بار تکرار شود، آخرین قاعده اعمال می‌شود؛ به استثنای قواعد skip/end که در آن‌ها اولین قاعده اولویت دارد.

3.

فایل CSV به عنوان متن خوانده می‌شود. هر نویسه غیر ASCII با استفاده از کدگذاری متنی تعیین‌شده توسط قاعده encoding، و در غیر این صورت با کدگذاری متنی لوکال (locale) سیستم، رمزگشایی خواهد شد.

4.

هر قاعده skip یا end در سطح بالا اعمال می‌شود. قاعده skip [N] بلافاصله از رکورد فعلی یا N رکورد بعدی CSV صرف‌نظر می‌کند؛ قاعده end بلافاصله از تمام رکوردهای باقیمانده CSV صرف‌نظر می‌کند (به طور معمول در سطح بالا استفاده نمی‌شود).

5.

اکنون رکوردهای باقیمانده CSV پردازش می‌شوند. برای هر رکورد CSV، به ترتیبی که در فایل آمده است:

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

• استخراج قواعد مشترک قابل استفاده با چندین فایل CSV درون یک common.rules، و افزودن include common.rules به فایل قواعد هر CSV.
• تقسیم بلوک‌های if به بلوک‌های if کوچک‌تر و استخراج بخش‌های پرکاربرد.

مثال‌های قواعد CSV

Bank of Ireland

در اینجا یک فایل CSV با دو فیلد مبلغ (Debit و Credit) و یک فیلد موجودی (Balance) آمده است که می‌توانیم از آن برای افزودن اعتبارسنجی‌های موجودی (balance assertions) استفاده کنیم؛ این کار الزامی نیست اما امکان بررسی خطای بیشتری را فراهم می‌کند:

Date,Details,Debit,Credit,Balance
07/12/2012,LODGMENT       529898,,10.0,131.21
07/12/2012,PAYMENT,5,,126

# 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 "balance"
# 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

$ 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

اعتبارسنجی‌های موجودی در بالا خطایی ایجاد نمی‌کنند، زیرا خواندن مستقیماً از CSV انجام می‌شود، اما اگر این مدخل‌ها به یک فایل journal وارد شوند، بررسی خواهند شد.

Coinbase

یک مثال ساده با داده‌های CSV از Coinbase. قیمت لحظه‌ای (spot price) با استفاده از نمادگذاری هزینه (cost notation) ثبت شده است. نام فیلد قدیمی amount به‌راحتی مبلغ ۲ (مبلغ posting دوم) را برابر با هزینه کل قرار می‌دهد.

# 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,"","","","Received 100.00 USDC from an external account"

# 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 @ %Spot_Price_at_Transaction %Spot_Price_Currency

$ hledger print -f coinbase.csv
2021-12-30 Received 100.00 USDC from an external account
    assets:coinbase:cc    100 USDC @ 0.740000 GBP
    income:unknown                 -74.000000 GBP
در اینجا تاریخچهٔ سفارش‌های amazon.com را تبدیل کرده و از یک بلوک if برای
ایجاد یک ثبت (posting) سوم در صورت وجود کارمزد استفاده می‌کنیم.
(در عمل احتمالاً این داده‌ها را به جای آن از بانک خود دریافت خواهید کرد، اما
این فقط یک مثال است.)

"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"

# amazon-orders.csv.rules
# رد کردن یک خط سربرگ
skip 1
# نام‌گذاری فیلدهای csv، و انتساب تاریخ، مبلغ و کد تراکنش.
# برای جلوگیری از سردرگمی، از نام‌های فیلد hledger یعنی "status" و "amount" پرهیز شد.
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

$ 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

Paypal

در اینجا یک فایل قوانین واقعی برای CSV (سفارشی‌شدهٔ) Paypal، همراه با برخی قوانین ویژهٔ Paypal و یک فایل قوانین دوم گنجانده‌شده آمده است:

"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""
"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""
"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""
"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""
"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""
"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""
"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""

# paypal-custom.csv.rules
# نکته‌ها:
# برون‌بری از Activity -> Statements -> Custom -> Activity download
# نوع تراکنش پیشنهادی: "Balance affecting"
# فیلدهای پیش‌فرض Paypal در سال ۲۰۱۸ عبارت بودند از:
# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"
# این فایل قوانین، فیلدهای دقیق‌تر زیر را که در "Customize report fields" پیکربندی شده‌اند، فرض می‌کند:
# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
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 ^[^-]
 account2 income:unknown
# اگر منفی باشد، هزینه است (یک بستانکار)
if %grossamount ^-
 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

# 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
$ 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@joyful.com, toemail:memberships@calmradio.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@joyful.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@joyful.com, toemail:support@patreon.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@joyful.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@joyful.com, toemail:tle@wikimedia.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@joyful.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@bene.fac.tor, toemail:simon@joyful.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:

تاریخ آغاز و پایان گزارش (Report start & end date)

بیشتر گزارش‌های hledger به‌طور پیش‌فرض کل دورهٔ زمانی بازنمایی‌شده توسط journal را نمایش می‌دهند. تاریخ آغاز گزارش، کهن‌ترین تاریخ تراکنش یا posting خواهد بود، و تاریخ پایان گزارش، تازه‌ترین تاریخ تراکنش، posting، یا قیمت بازار خواهد بود.

اغلب مایل خواهید بود دورهٔ کوتاه‌تری مانند ماه جاری را مشاهده کنید. می‌توانید تاریخ آغاز و/یا پایان را با گزینه‌های -b/--begin، -e/--end، یا -p/--period، یا یک آرگومان پرس‌وجوی date: که در ادامه توضیح داده شده‌اند مشخص کنید. همهٔ این‌ها ساختار نحو تاریخ هوشمند (smart date) را که آن نیز در ادامه شرح داده شده می‌پذیرند.

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

هنگامی که تاریخ‌ها توسط چندین گزینه مشخص شوند، آخرین گزینه (راست‌ترین) اعمال می‌شود. و هنگامی که پرس‌وجوهای date: و گزینه‌های تاریخ ترکیب شوند، دورهٔ گزارش اشتراک آن‌ها خواهد بود.

مثال‌ها:

-b 2016/3/17

شروع از روز سنت پاتریک ۲۰۱۶

-e 12/1

پایان در ابتدای ۱ دسامبر سال جاری

-p 'this month'

در طول ماه جاری

-p thismonth

مشابه بالا، فاصله‌ها اختیاری هستند

-b 2023

شروع از نخستین روز ۲۰۲۳

date:2023.. یا date:2023-

مشابه بالا

-b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020 :

در طول ژانویهٔ ۲۰۲۰ (کوچک‌ترین دورهٔ مشترک، با تقدم -p بر -b و -e)

تاریخ‌های هوشمند (Smart dates)

در رابط‌های کاربری hledger (البته نه در فایل journal)، می‌توانید به‌صورت اختیاری از نحو "smart date" استفاده کنید. تاریخ‌های هوشمند می‌توانند با کلمات انگلیسی نوشته شوند، نسبی باشند، و بخش‌هایی از آن‌ها حذف شده باشد. بخش‌های جاافتاده در صورت نیاز ۱ در نظر گرفته می‌شوند. بسته به زمینه، تاریخ‌های هوشمند می‌توانند به عنوان تاریخ‌ها یا دوره‌ها تفسیر شوند.

مثال‌ها:

2004-01-01، 2004/10/1، 2004.9.1، 20240504، 2024Q1 :

تاریخ‌های دقیق. سال باید دست‌کم چهار رقم داشته باشد، ماه باید ۱-۱۲ باشد، روز باید ۱-۳۱ باشد، جداکننده می‌تواند - یا / یا . یا بدون جداکننده باشد. حرف q می‌تواند بزرگ یا کوچک باشد و شمارهٔ سه‌ماهه باید ۱-۴ باشد.

2004-10

ابتدای ماه

2004q3

ابتدای سه‌ماههٔ سوم سال ۲۰۰۴

q3

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

2004

ابتدای سال

10/1 یا oct یا october

۱ اکتبر در سال جاری

21

روز ۲۱ام در ماه جاری

yesterday, today, tomorrow

-1، 0، 1 روز از امروز

last/this/next day/week/month/quarter/year

-1، 0، 1 دوره از دورهٔ جاری

last/this/next tuesday

رخداد قبلی روز نام‌برده، یا رخداد بعدیِ پس از امروز

last/this/next february

رخداد قبلی روز ۱امِ ماه نام‌برده، یا رخداد بعدیِ پس از ماه جاری

in n days/weeks/months/quarters/years

n دوره از دورهٔ جاری

n days/weeks/months/quarters/years ahead

n دوره پس از دورهٔ جاری

n days/weeks/months/quarters/years ago

-n دوره از دورهٔ جاری

20181201

۸ رقم YYYYMMDD با سال، ماه و روز معتبر

201812

۶ رقم YYYYMM با سال و ماه معتبر

تاریخ‌های بدون جداکننده مجاز هستند اما در صورت اشتباه تایپی ممکن است نتایج غیرمنتظره‌ای ایجاد کنند:

• 20181301 (YYYYMMDD با ماه نامعتبر) به عنوان یک سال هشت‌رقمی تجزیه می‌شود
• 20181232 (YYYYMMDD با روز نامعتبر) خطای تجزیه می‌دهد
• 201801012 (یک YYYYMMDD معتبر که در ادامهٔ آن ارقام اضافه آمده است) خطای تجزیه می‌دهد

معنای تاریخ‌های نسبی به تاریخ امروز (today) بستگی دارد. اگر نیاز به آزمایش یا بازتولید گزارش‌های قدیمی دارید، می‌توانید از گزینهٔ --today برای بازنویسی آن استفاده کنید. (به استثنای قواعد تراکنش‌های دوره‌ای، که تحت تأثیر --today قرار نمی‌گیرند.).SS بازه‌های گزارش می‌توان یک بازه گزارش مشخص کرد تا گزارش‌هایی مانند register، balance یا activity چنددوره‌ای شوند و هر زیردوره را در قالب یک سطر یا ستون جداگانه نمایش دهند.

بازه‌های استاندارد زیر را می‌توان با پرچم‌های خط فرمان فعال کرد:

• -D/--daily
• -W/--weekly
• -M/--monthly
• -Q/--quarterly
• -Y/--yearly

بازه‌های پیچیده‌تر را می‌توان با استفاده از -p/--period مشخص کرد که در ادامه شرح داده شده‌اند.

تنظیمات تاریخ

تنظیم تاریخ شروع

اگر به hledger اجازه دهید تاریخ شروع یک گزارش را استنباط کند، آن را برای راحتی در گزارش‌های دوره‌ای، به مرز طبیعی پیشینِ بازه گزارش تنظیم می‌کند. (اگر چنین چیزی را نمی‌خواهید، یک تاریخ شروع مشخص کنید.)

برای نمونه، اگر نخستین تراکنش در دفتر روزنامه در ۱۰ ژانویه باشد:

• دستور hledger register (بدون بازه گزارش) گزارش را در ۱۰ ژانویه آغاز خواهد کرد.
• دستور hledger register --monthly گزارش را در مرز ماه پیشین، یعنی ۱ ژانویه آغاز می‌کند.
• دستور hledger register --monthly --begin 1/5 گزارش را در ۵ ژانویه آغاز می‌کند [1].

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

تنظیم تاریخ پایان

تاریخ پایان یک گزارش همیشه طوری تنظیم می‌شود که شامل تعداد کاملی از بازه‌ها باشد، به‌گونه‌ای که آخرین زیردوره دارای طولی یکسان با سایر زیردوره‌ها باشد.

برای نمونه، اگر آخرین تراکنش دفتر روزنامه در ۲۰ فوریه باشد:

• دستور hledger register گزارش را در ۲۰ فوریه به پایان می‌رساند.
• دستور hledger register --monthly گزارش را در پایان فوریه به پایان می‌رساند.
• دستور hledger register --monthly --end 2/14 نیز گزارش را در پایان فوریه به پایان می‌رساند (نادیده گرفتن تاریخ پایان درخواست‌شده).
• دستور hledger register --monthly --begin 1/5 --end 2/14 گزارش را در ۴ مارس به پایان می‌رساند [1].

[1] از hledger نسخه 1.29 به بعد.

سربرگ‌های دوره

در زیردوره‌های غیر استاندارد، hledger سربرگ‌های "STARTDATE..ENDDATE" را نشان می‌دهد. در زیردوره‌های استاندارد (یعنی شروع در یک مرز بازه طبیعی)، سربرگ‌های فشرده‌تری را خواهید دید که معمولاً مطلوب‌تر هستند. (اگرچه در حال حاضر، نام ماه‌ها به انگلیسی خواهد بود.)

بنابراین اگر تاریخ شروع را مشخص می‌کنید و سربرگ‌های فشرده می‌خواهید: شروع سال را برای گزارش‌های سالانه، شروع فصل را برای گزارش‌های سه‌ماهه، شروع ماه را برای گزارش‌های ماهانه و غیره انتخاب کنید. (به یاد داشته باشید، می‌توانید مثلاً -b 2024 یا 1/1 را به عنوان میان‌بری برای شروع سال، یا 2024-04 یا 202404 یا Apr را برای شروع ماه یا فصل بنویسید.)

برای گزارش‌های هفتگی، تاریخی را انتخاب کنید که دوشنبه (Monday) باشد. (می‌توانید تاریخ‌های متفاوتی را امتحان کنید تا زمانی که سربرگ‌های کوتاه را ببینید، یا مثلاً بنویسید -b '3 weeks ago'.)

عبارت‌های دوره

گزینه -p/--period یک عبارت دوره را مشخص می‌کند، که روشی فشرده برای بیان تاریخ شروع، تاریخ پایان و/یا بازه گزارش است.

در اینجا نمونه‌ای از یک عبارت دوره با تاریخ شروع و پایان آورده شده است (مشخص‌کننده فصل نخست سال ۲۰۰۹):

چندین کلیدواژه مانند "from" و "to" برای خوانایی بهتر پشتیبانی می‌شوند؛ این کلیدواژه‌ها اختیاری هستند. "to" می‌تواند به صورت ".." یا "-" نیز نوشته شود. فاصله‌ها نیز اختیاری هستند، تا زمانی که دو تاریخ به هم نچسبند. بنابراین موارد زیر معادل عبارت بالا هستند:

تاریخ‌ها از نوع تاریخ‌های هوشمند (smart dates) هستند، بنابراین اگر سال جاری ۲۰۰۹ باشد، موارد زیر نیز معادل عبارت بالا خواهند بود:

اگر تنها یک تاریخ را مشخص کنید، تاریخ شروع یا پایان ناموجود برابر با زودترین یا دیرترین تاریخ تراکنش در دفتر روزنامه خواهد بود:

همچنین می‌توانید با نوشتن یک تاریخ تکی جزئی یا کامل، یک دوره را مشخص کنید:

یا با استفاده از ساختار فصلی "Q" (غیرحساس به حروف کوچک و بزرگ):.PP

عبارت‌های دوره به همراه بازه گزارش (Period expressions with a report interval)

یک عبارت دوره می‌تواند با یک بازه گزارش نیز آغاز شود، که با یک فاصله یا کلمه in از تاریخ‌های شروع/پایان (در صورت وجود) جدا می‌شود:

بازه‌های گزارش پیچیده‌تر (More complex report intervals)

برخی بازه‌های پیچیده‌تر را می‌توان در عبارت‌های دوره مشخص کرد، مانند:

• biweekly (هر دو هفته یک‌بار)
• fortnightly
• bimonthly (هر دو ماه یک‌بار)
• every day|week|month|quarter|year
• every N days|weeks|months|quarters|years

هفتگی در یک روز دلخواه:

• every Nth day of week (پسوندهای th، nd، rd یا st همگی پس از عدد پذیرفته می‌شوند)
• every WEEKDAYNAME (نام انگلیسی روز هفته به‌صورت کامل یا سه‌حرفی، بدون حساسیت به حروف بزرگ و کوچک)

ماهانه در یک روز دلخواه:

• every Nth day [of month] (31st day با آخرین روز هر ماه تطبیق داده خواهد شد)
• every Nth WEEKDAYNAME [of month]

سالانه در یک ماه و روز دلخواه:

• every MM/DD [of year] (شماره ماه و شماره روزِ ماه)
• every MONTHNAME DDth [of year] (نام انگلیسی ماه به‌صورت کامل یا سه‌حرفی، بدون حساسیت به حروف بزرگ و کوچک، و شماره روزِ ماه)
• every DDth MONTHNAME [of year] (معادل با مورد بالا)

مثال‌ها:

نمایش ترازهای تاریخی در پایان روز پانزدهم هر ماه (N تاریخ پایان است و طبق معمول، خود آن روز شامل نمی‌شود):

$ hledger balance -H -p "every 16th day"

دسته‌بندی ثبت‌ها از ابتدای چهارشنبه تا انتهای سه‌شنبه بعد (N هم تاریخ شروع (شامل) و هم تاریخ پایان (غیرشامل) است):

$ hledger register checking -p "every 3rd day of week"
این شکل ویژه نیز پشتیبانی می‌شود:

•

every WEEKDAYNAME,WEEKDAYNAME,... (نام‌های کامل یا سه‌حرفی
روزهای هفته به انگلیسی، بدون حساسیت به بزرگی و کوچکی حروف)

همچنین، weekday و weekendday کوتاه‌نوشت‌هایی برای
mon,tue,wed,thu,fri و sat,sun هستند.

این قابلیت عمدتاً برای استفاده با --forecast در نظر گرفته شده است، تا
تراکنش‌های دوره‌ای را در روزهای دلخواهی از هفته ایجاد کند.
استفاده از آن با -p ممکن است کاربرد کمتری داشته باشد، زیرا هر هفته را
به زیردوره‌هایی با طول نابرابر تقسیم می‌کند که غیرمعمول است.
(مرتبط: #1632)

مثال‌ها:

ترکیب گزینه‌های عمق

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

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

• دستور --depth assets=3 --depth expenses=2 --depth 1 حساب‌های حاوی "assets" را تا عمق ۳، حساب‌های حاوی "expenses" را تا عمق ۲، و تمام حساب‌های دیگر را تا عمق ۱ جمع می‌کند.
• دستور --depth assets=1 --depth savings=2 حساب assets:bank:savings را تا عمق ۲ جمع می‌کند (نه عمق ۱؛ زیرا "savings" نسبت به "assets" با بخش عمیق‌تری از نام حساب تطابق دارد).

توجه داشته باشید که در حال حاضر، برای لغو یک گزینه سفارشی عمق --depth REGEX=NUM با گزینه‌ای پس از آن، گزینه بعدی باید از همان REGEX استفاده کند..SH "پرس‌وجوها (QUERIES)" بسیاری از دستورهای hledger آرگومان‌های پرس‌وجو را می‌پذیرند که دامنهٔ عملکرد آن‌ها را محدود کرده و امکان گزارش‌گیری از زیرمجموعهٔ دقیقی از داده‌هایتان را فراهم می‌کنند. در اینجا یک نمای کلی و سریع از پرس‌وجوهای hledger آمده است:

•

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

•

الگوهایی که شامل فاصله یا نویسه‌های خاص دیگر هستند باید درون نقل‌قول تکی یا دوتایی قرار گیرند:

•

الگوها در واقع عبارات باقاعده (regular expressions) هستند، بنابراین می‌توانید برای دقت بیشتر فرانویسه‌های عبارت باقاعده را اضافه کنید (یا ممکن است لازم باشد نویسه‌های خاصی را با بک‌اسلش فراردهی کنید؛ بخش "Regular expressions" در بالا را ببینید):

•

برای تطبیق چیزی به جز نام حساب، می‌توانید یک پیشوند نوع پرس‌وجو اضافه کنید، مانند:

•

برای نفی یک پرس‌وجو، پیشوند not: را اضافه کنید:

•

چندین عبارت پرس‌وجو را می‌توان به صورت پرس‌وجوهای جداشده با فاصله ترکیب کرد؛ برای نمونه: hledger print date:2022 desc:amazon desc:amzn (نمایش تراکنش‌های با تاریخ سال 2022 که شرح آن‌ها شامل "amazon" یا "amzn" است).

•

یا با انعطاف‌پذیری بیشتر به صورت پرس‌وجوهای بولی (boolean). برای نمونه: hledger print expr:'date:2022 and (desc:amazon or desc:amzn) and not date:202210'

تمامی دستورهای hledger از یک زبان پرس‌وجوی یکسان استفاده می‌کنند، اما دستورهای مختلف ممکن است پرس‌وجو را به روش‌های گوناگونی تفسیر کنند. ما هنوز دستورها را شرح نداده‌ایم (این مورد در «بخش ۴: دستورها» (PART 4: COMMANDS) در ادامه خواهد آمد) اما اساس کار به شرح زیر است:

• دستورهای تراکنش‌محور (print، aregister، close، import، descriptions...) تلاش می‌کنند تراکنش‌ها (شامل ثبت‌های تراکنش) را تطبیق دهند.
• دستورهای ثبت‌محور (register، balance، balancesheet، incomestatement، accounts...) تلاش می‌کنند ثبت‌ها (postings) را تطبیق دهند. ثبت‌ها ویژگی‌های تراکنش خود را برای اهداف پرس‌وجو به ارث می‌برند، بنابراین فیلدهای تراکنش مانند تاریخ یا شرح همچنان می‌توانند در یک پرس‌وجوی ثبت مورد ارجاع قرار گیرند.
• تعداد کمی از دستورها به روش‌های خاص‌تری تطبیق می‌دهند. (مانند aregister، که یک آرگومان اول ویژه دارد.).SS انواع پرس‌وجو (Query types) انواع پرس‌وجوهای موجود در زیر آمده است:

پرس‌وجوی acct:

acct:REGEX، یا صرفاً REGEX

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

این نوع پرس‌وجوی پیش‌فرض است، بنابراین معمولاً نیازی به نوشتن پیشوند "acct:" نیست.

پرس‌وجوی amt:

amt:N, amt:'<N', amt:'<=N', amt:'>N', amt:'>=N'

ثبت‌های با مقدار تک‌کالایی برابر، کمتر، یا بیشتر از N را تطبیق می‌دهد. (ثبت‌های دارای مقادیر چندکالایی بررسی نمی‌شوند و همیشه مطابقت خواهند داشت.) برای پنهان کردن علامت‌های کوچکتری/بزرگتری از پوسته خط فرمان، amt: نیازمند علامت نقل‌قول است.

این مقایسه دو حالت دارد: اگر پیش از N علامت + یا - آمده باشد (یا ۰ باشد)، دو عدد دارای علامت با یکدیگر مقایسه می‌شوند. در غیر این صورت، اندازه قدر مطلق اعداد بدون در نظر گرفتن علامت مقایسه خواهد شد.

به یاد داشته باشید که amt: مقادیر ثبت‌ها را مطابقت می‌دهد، نه تراز حساب‌ها را.

پرس‌وجوی code:

code:REGEX

تطبیق بر اساس کد تراکنش (مانند شماره چک).

پرس‌وجوی cur:

cur:REGEX

ثبت‌ها یا تراکنش‌هایی را تطبیق می‌دهد که شامل هر مقداری باشند که نماد ارز/کالای آن به‌طور کامل با REGEX تطبیق یابد. (برخلاف روش معمول تطبیق میانی در hledger. برای انجام تطبیق میانی، .*REGEX.* را وارد کنید.) توجه داشته باشید که برای تطبیق نویسه‌های خاصی که در عبارت باقاعده معنای ویژه دارند، باید آن‌ها را با \ گریزدهی (escape) کنید. و برای نویسه‌هایی که برای پوسته شما معنای خاص دارند، معمولاً به یک سطح گریزدهی بیشتر نیاز خواهید داشت. به عنوان مثال برای تطبیق علامت دلار: cur:\\$ یا cur:'\$'

پرس‌وجوی desc:

desc:REGEX

توضیحات تراکنش را مطابقت می‌دهد.

پرس‌وجوی date:

date:PERIODEXPR

تاریخ‌ها (یا با پرچم --date2، تاریخ‌های ثانویه) را در دوره زمانی مشخص‌شده مطابقت می‌دهد. عبارت PERIODEXPR یک عبارت دوره زمانی است. مثال‌ها:

date:2016، date:thismonth، date:2/1-2/15، date:2021-07-27..nextquarter.

عبارت PERIODEXPR می‌تواند شامل یک بازه گزارش‌گیری باشد (از نسخه 1.52). در خط فرمان، این معادل تعیین یک بازه گزارش‌گیری با استفاده از گزینه‌های خط فرمان است. در سایر محیط‌ها (مانند hledger-ui و hledger-web)، بازه گزارش‌گیری ممکن است نادیده گرفته شود.

پرس‌وجوی date2:

date2:PERIODEXPR

اگر از تاریخ‌های ثانویه استفاده می‌کنید: این پرس‌وجو تاریخ‌های ثانویه را در دوره زمانی مشخص‌شده تطبیق می‌دهد. این پرس‌وجو تحت تأثیر پرچم --date2 قرار نمی‌گیرد. هرگونه بازه گزارش‌گیری در PERIODEXPR نادیده گرفته خواهد شد..SS پرس‌وجوی depth: depth:[REGEXP=]N

تطبیق (یا بسته به دستور، نمایش) حساب‌ها در این عمق یا بالاتر از آن؛ به صورت اختیاری تنها برای حساب‌هایی که با یک عبارت باقاعده ارائه‌شده مطابقت دارند. برای قوانین دقیق، بخش Depth را ببینید.

پرس‌وجوی note:

note:REGEX

تطبیق یادداشت‌های تراکنش (بخشی از توضیحات که در سمت راست | قرار دارد، یا کل توضیحات در صورتی که نویسهٔ | وجود نداشته باشد).

پرس‌وجوی payee:

payee:REGEX

تطبیق نام‌های دریافت‌کننده/پرداخت‌کنندهٔ تراکنش (بخشی از توضیحات که در سمت چپ | قرار دارد، یا کل توضیحات در صورتی که نویسهٔ | وجود نداشته باشد).

پرس‌وجوی real:

real:, real:0

تطبیق ثبت‌های (postings) واقعی یا مجازی، به ترتیب.

پرس‌وجوی status:

status:, status:!, status:*

تطبیق تراکنش‌های بدون علامت، در انتظار یا تسویه‌شده، به ترتیب.

پرس‌وجوی type:

type:TYPECODES

تطبیق بر اساس نوع حساب (بخش Declaring accounts > Account types را ببینید). TYPECODES یک یا چند کد تک‌حرفی نوع حساب از ALERXCVG، بدون حساسیت به بزرگی و کوچکی حروف است. توجه داشته باشید که type:A، type:E و type:R با زیرنوع‌های مربوط به خود یعنی C (نقدینگی - Cash)، V (تبدیل - Conversion) و G (سود - Gain) نیز تطبیق خواهند یافت. انواع خاصی از نام‌های مستعار حساب (alias) می‌توانند انواع حساب را مختل کنند؛ بخش Rewriting accounts > Aliases and account types را ببینید.

پرس‌وجوی tag:

tag:NAMEREGEX[=VALREGEX]

تطبیق بر اساس نام برچسب، و به‌طور اختیاری بر اساس مقدار برچسب نیز. نکته:

•

هر دو عبارت باقاعده تطبیق میانی انجام می‌دهند. اگر به تطبیق کامل نیاز دارید، از ^ و $ استفاده کنید.

برای مثال: tag:'^fullname$'، tag:'^fullname$=^fullvalue$

• برای تطبیق مقادیر با نادیده گرفتن نام‌ها، از tag:.=VALREGEX استفاده کنید.
• حساب‌ها برچسب‌های حساب‌های والد خود را نیز به ارث می‌برند.
• ثبت‌ها برچسب‌های حساب و تراکنش خود را نیز به ارث می‌برند.
• تراکنش‌ها نیز برچسب‌های ثبت‌های خود را دریافت می‌کنند.

پرس‌وجوهای منفی

پرس‌وجوی not:

not:QUERY

می‌توانید not: را به ابتدای یک پرس‌وجو اضافه کنید تا تطبیق نقیض شود.

برای مثال: not:equity، not:desc:apple

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

• هر یک از عبارت‌های شرح AND
• هر یک از عبارت‌های حساب AND
• هر یک از عبارت‌های وضعیت AND
• تمام عبارت‌های دیگر.

دستور print کمی متفاوت است و تراکنش‌هایی را نمایش می‌دهد که:

• با هر یک از عبارت‌های شرح مطابقت داشته باشند AND
• دارای ثبت‌هایی باشند که با هر یک از عبارت‌های مثبت حساب مطابقت دارند AND
• هیچ ثبتی نداشته باشند که با هر یک از عبارت‌های منفی حساب مطابقت داشته باشد AND
• با تمام عبارت‌های دیگر مطابقت داشته باشند.

پرس‌وجوهای بولی

می‌توانید عبارت‌های پرس‌وجوی پیچیده‌تر "بولی" بنویسید که در گیومه قرار گرفته و پیشوند expr: دارند. این عبارت‌ها می‌توانند زیرپرس‌وجوها را با عملگرهای NOT،‏ AND و OR (غیرحساس به حروف بزرگ و کوچک) و پرانتزها برای گروه‌بندی ترکیب کنند. برای مثال، جهت نمایش تراکنش‌هایی که هم شامل حساب‌های cash و هم expenses هستند:

hledger print expr:'cash AND expenses'

پیشوند و گیومه‌های دربرگیرنده الزامی هستند، بنابراین hledger print cash AND expenses را ننویسید. این حالت یک پرس‌وجوی جداشده با فاصله خواهد بود که تراکنش‌های شامل حساب‌هایی با هر یک از "cash"،‏ "and" یا "expenses" در نامشان را نشان می‌دهد.

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

hledger print expr:'cash expenses'
hledger print cash expenses

محدودیتی در مورد پرس‌وجوهای date: وجود دارد: آن‌ها را نمی‌توان درون عبارت‌های OR استفاده کرد.

در واقع، سه نوع پرس‌وجوی بولی وجود دارد: expr: برای استفادهٔ عمومی، و گونه‌های any: و all: که می‌توانند همراه با print مفید باشند.

پرس‌وجوی expr:

expr:'QUERYEXPR'

برای مثال، expr:'date:lastmonth AND NOT (food OR rent)' به این معنی است: "تطبیق مواردی که تاریخ آن‌ها در ماه گذشته است و food یا rent در نام حساب آن‌ها وجود ندارد".

هنگام استفاده از expr: با دستورهای مبتنی بر تراکنش مانند print، عبارت‌های پرس‌وجوی مبتنی بر ثبت مانند acct: و amt: در صورتی منطبق بر تراکنش در نظر گرفته می‌شوند که با هر یک از ثبت‌های آن مطابقت داشته باشند.

بنابراین، hledger print expr:'cash and amt:>0' به این معنی است: "نمایش تراکنش‌هایی با (حداقل یک ثبت شامل یک حساب cash) و (حداقل یک ثبت با مبلغ مثبت)".

پرس‌وجوی any:

any:'QUERYEXPR'

مانند expr: است، اما هنگامی که با دستورهای مبتنی بر تراکنش مانند print استفاده می‌شود، تراکنش را تنها در صورتی مطابقت می‌دهد که یک ثبت بتواند با تمام QUERYEXPR مطابقت داشته باشد.

بنابراین، hledger print any:'cash and amt:>0' به این معنی است: "نمایش تراکنش‌هایی که در آن‌ها حداقل یک ثبت، مبلغ مثبتی را به یک حساب cash منظور می‌کند"..SS پرسمان all: all:'QUERYEXPR'

مشابه expr: است، اما هنگامی که با دستورهای تراکنش‌محور مانند print استفاده می‌شود، تراکنش را تنها در صورتی مطابقت می‌دهد که تمام ثبت‌ها (postings) با تمام بخش‌های QUERYEXPR مطابقت داشته باشند (و حداقل یک ثبت وجود داشته باشد).

بنابراین، hledger print all:'cash and amt:0' به این معنی است: "تراکنش‌هایی را نشان بده که در آن‌ها همهٔ ثبت‌ها مربوط به یک حساب نقدی (cash) بوده و مقدار مبلغ آن‌ها صفر باشد".

یا hledger print all:'cash or checking' یعنی "تراکنش‌هایی را نشان بده که تنها به حساب‌های نقدی (cash) و/یا جاری (checking) مربوط می‌شوند".

پرسمان‌ها و گزینه‌های دستور

برخی پرسمان‌ها را می‌توان به صورت گزینه‌های خط فرمان نیز بیان کرد: depth:2 معادل --depth 2 است، date:2023 معادل -p 2023 است، و غیره. هنگامی که گزینه‌های دستور و آرگومان‌های پرسمان را با هم ترکیب می‌کنید، عموماً پرسمان حاصل اشتراک آن‌ها خواهد بود.

پرسمان‌ها و نام‌های مستعار حساب

هنگامی که نام‌های حساب با --alias یا alias بازنویسی می‌شوند، acct: با نام قدیم یا جدید حساب مطابقت خواهد داشت.

پرسمان‌ها و ارزش‌گذاری

هنگامی که مبالغ در گزارش‌های بهای تمام‌شده یا ارزش به کالاها/ارزهای دیگر تبدیل می‌شوند، cur: و amt: با نماد کالای قدیمی و مقدار مبلغ پیشین مطابقت داده می‌شوند، نه موارد جدید. (به‌جز در hledger 1.22، شمارهٔ #1625.)

--forecast

روش دیگری نیز وجود دارد: با گزینهٔ --forecast، ابزار hledger می‌تواند بر اساس قوانین تراکنش‌های دوره‌ای تعریف‌شده در دفتر روزنامه، "تراکنش‌های پیش‌بینی" موقتی را برای اهداف گزارش‌گیری تولید کند. هر قاعده می‌تواند چندین تراکنش تکرارشونده ایجاد کند، بنابراین با تغییر یک قاعده می‌توانید تعداد زیادی از تراکنش‌های پیش‌بینی‌شده را دگرگون کنید.

تراکنش‌های پیش‌بینی معمولاً پس از پایان تراکنش‌های عادی آغاز می‌شوند. به‌طور پیش‌فرض، آنها بعد از آخرین تاریخ تراکنش عادی شما، یا امروز (هر کدام که دیرتر باشد) شروع شده و شش ماه پس از امروز خاتمه می‌یابند. (قوانین دقیق کمی پیچیده‌تر هستند و در ادامه ارائه شده‌اند.)

این بازه، "دورهٔ پیش‌بینی" نامیده می‌شود که لزومی ندارد با دورهٔ گزارش‌گیری یکسان باشد. می‌توانید با دادن یک آرگومان عبارت دوره به گزینهٔ --forecast آن را بازنویسی کنید - برای مثال جهت پیش‌بینی برای آینده‌ای دورتر، یا اجبار تراکنش‌های پیش‌بینی به هم‌پوشانی با تراکنش‌های عادی خود - مانند --forecast=..2099 یا --forecast=2023-02-15... توجه داشته باشید که علامت = الزامی است.

بررسی تراکنش‌های پیش‌بینی (Inspecting forecast transactions)

دستور print بهترین دستور برای بررسی و عیب‌یابی تراکنش‌های پیش‌بینی است. برای مثال:

~ monthly from 2022-12-20    rent
    assets:bank:checking
    expenses:rent           $1000

$ hledger print --forecast --today=2023/4/21
2023-05-20 rent
    ; generated-transaction: ~ monthly from 2022-12-20
    assets:bank:checking
    expenses:rent                  $1000
2023-06-20 rent
    ; generated-transaction: ~ monthly from 2022-12-20
    assets:bank:checking
    expenses:rent                  $1000
2023-07-20 rent
    ; generated-transaction: ~ monthly from 2022-12-20
    assets:bank:checking
    expenses:rent                  $1000
2023-08-20 rent
    ; generated-transaction: ~ monthly from 2022-12-20
    assets:bank:checking
    expenses:rent                  $1000
2023-09-20 rent
    ; generated-transaction: ~ monthly from 2022-12-20
    assets:bank:checking
    expenses:rent                  $1000

در اینجا هیچ تراکنش عادی وجود ندارد، بنابراین تراکنش‌های پیش‌بینی‌شده از اولین موعد پس از تاریخ امروز آغاز می‌شوند. (شما در حالت معمول از --today استفاده نخواهید کرد؛ این گزینه صرفاً برای تکرارپذیر ساختن این مثال‌ها آورده شده است.).SS "گزارش‌های پیش‌بینی (Forecast reports)" تراکنش‌های پیش‌بینی همان‌طور که انتظار می‌رود بر تمام گزارش‌ها تأثیر می‌گذارند. برای نمونه:

$ 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

$ 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 

برچسب‌های پیش‌بینی (Forecast tags)

تراکنش‌های پیش‌بینی ایجادشده با --forecast دارای یک برچسب پنهان، _generated-transaction هستند. بنابراین اگر زمانی نیاز به تطبیق تراکنش‌های پیش‌بینی داشتید، می‌توانید از tag:_generated-transaction (یا صرفاً tag:generated) در یک پرس‌وجو استفاده کنید.

برای عیب‌یابی، می‌توانید پرچم --verbose-tags را اضافه کنید. سپس، برچسب‌های آشکار generated-transaction نیز افزوده خواهند شد، به‌گونه‌ای که می‌توانید آن‌ها را با دستور print مشاهده کنید. مقدار آن‌ها مشخص می‌کند کدام قاعده دوره‌ای عامل ایجاد آن بوده است.

دوره پیش‌بینی، با جزئیات (Forecast period, in detail)

تاریخ‌های آغاز و پایان پیش‌بینی به‌گونه‌ای انتخاب می‌شوند که به‌طور پیش‌فرض در تقریباً همه موقعیت‌ها عملکرد مفیدی داشته باشند، در عین حال که انعطاف‌پذیر نیز باقی بمانند. در اینجا قواعد دقیق (به‌امید خدا) برای کمک به عیب‌یابی آورده شده است:

دوره پیش‌بینی از تاریخ زیر آغاز می‌شود:

•

تاریخ متأخرتر بین

•

در غیر این صورت (اگر آن موارد در دسترس نباشند): تاریخ متأخرتر بین

•

در غیر این صورت (اگر هیچ‌یک از این‌ها موجود نباشد): امروز.

دوره پیش‌بینی در تاریخ زیر پایان می‌یابد:

•

تاریخ متقدم‌تر بین

• در غیر این صورت: تاریخ پایان گزارش مشخص‌شده با -e/-p/date:
• در غیر این صورت: ۱۸۰ روز (~۶ ماه) پس از امروز.

عیب‌یابی پیش‌بینی (Forecast troubleshooting)

هنگامی که --forecast آن‌طور که انتظار دارید عمل نمی‌کند، یکی از این نکات باید مفید باشد:

• به یاد داشته باشید که از گزینه --forecast استفاده کنید.
• به یاد داشته باشید که حداقل یک قاعده تراکنش دوره‌ای در دفترکل خود داشته باشید.
• با دستور print --forecast آزمایش کنید.
• خطاهای نگارشی یا تاریخ‌های آغاز/پایان بیش از حد محدودکننده را در قاعده تراکنش دوره‌ای خود بررسی کنید.
• حداقل ۲ فاصله بین عبارت دوره قاعده و فیلدهای توضیحات قرار دهید.
• بررسی کنید که آیا تراکنش‌های عادی دارای تاریخ آینده مانع از نمایش تراکنش‌های پیش‌بینی‌شده شده‌اند یا خیر.
• تنظیم صریح تاریخ‌های آغاز و/یا پایان گزارش را با -b، -e، -p یا date: امتحان کنید.
• افزودن پرچم -E را برای تشویق به نمایش دوره‌های خالی/تراکنش‌های صفر امتحان کنید.
• تنظیم صریح تاریخ‌های آغاز و/یا پایان پیش‌بینی را با --forecast=START..END امتحان کنید.
• به بخش «دوره پیش‌بینی، با جزئیات» در بالا مراجعه کنید.
• بررسی درون موتور: به عنوان نمونه --debug=2 را اضافه کنید..SH بودجه‌بندی با گزارش --budget در دستور balance، هر قاعده تراکنش دوره‌ای، اهداف بودجه‌ای تکرارشونده را در حساب‌های مشخص‌شده تولید می‌کند و می‌توان اهداف و عملکرد واقعی را با یکدیگر مقایسه کرد. مستندات دستور balance را در ادامه ببینید.

می‌توانید اهداف بودجه و تراکنش‌های پیش‌بینی را به‌طور هم‌زمان، از یک قاعده یا قواعد تراکنش دوره‌ای متفاوت ایجاد کنید: hledger bal -M --budget --forecast ...

همچنین ببینید: بودجه‌بندی و پیش‌بینی (Budgeting and Forecasting).

سبک نمایش کالا

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

نخست، اگر یک دستورالعمل D وجود داشته باشد که کالای پیش‌فرض را اعلان می‌کند، نماد آن کالا و قالب مبلغ به تمام مبالغ بدون نماد در دفتر روزنامه (journal) اعمال می‌شود.

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

# 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

اما برای راحتی، در صورتی که دستورالعمل commodity وجود نداشته باشد، hledger سبک‌های نمایش کالا را از مبالغ آن به همان صورت که در دفتر روزنامه نوشته شده‌اند استنتاج می‌کند (به‌استثنای مبالغ بهای تمام‌شده و مبالغ موجود در قواعد تراکنش دوره‌ای یا قواعد ثبت خودکار). برنامه از موارد زیر استفاده می‌کند:

• محل قرارگیری نماد و نشانگر اعشار اولین مبلغ دیده‌شده
• نشانگرهای گروه‌بندی ارقامِ اولین مبلغی که دارای نشانگرهای گروه‌بندی ارقام باشد
• و بیشترین تعداد ارقام اعشار دیده‌شده در تمام مبالغ.

و به‌عنوان راه‌حل جایگزین (fallback)، اگر هیچ مبلغ مناسبی یافت نشود، از یک سبک پیش‌فرض استفاده خواهد کرد، مانند $1000.00 (نماد در سمت چپ بدون فاصله، نقطه به‌عنوان نشانگر اعشار، و دو رقم اعشار).

در نهایت، سبک‌های کالا را می‌توان با گزینه خط فرمان -c/--commodity-style بازنویسی کرد.

گرد کردن

مبالغ در داخل برنامه به‌صورت اعداد اعشاری تا ۲۵۵ رقم اعشار ذخیره می‌شوند. آن‌ها در گزارش‌های print و گزارش‌های مشابه print با دقت اصلی‌شان در دفتر روزنامه نمایش داده می‌شوند، و در سایر گزارش‌ها به دقت نمایشی خود (تعداد ارقام اعشار مشخص‌شده توسط سبک نمایش کالا) گرد می‌شوند. هنگام گرد کردن، hledger از گرد کردن بانکی (banker's rounding؛ گرد کردن به نزدیک‌ترین رقم زوج) استفاده می‌کند. بنابراین برای مثال 0.5 در صورت نمایش با صفر رقم اعشار به‌صورت "0" ظاهر می‌شود.

نشانگرهای اعشار پایانی

اگر تعجب می‌کنید که چرا گزارش print شما گاهی نشانگرهای اعشار پایانی را بدون هیچ رقم اعشاری نشان می‌دهد؛ این کار را هنگام نمایش مبالغی انجام می‌دهد که نشانگرهای گروه‌بندی ارقام دارند اما رقم اعشار ندارند، تا ابهام‌زدایی شده و امکان بازخوانی مطمئن آن‌ها فراهم شود (بخش Decimal marks را ببینید). برای مثال:

commodity $1,000.00
2023-01-02
    (a)      $1000

$ hledger print
2023-01-02
    (a)        $1,000.

اگر این موضوع مشکلی ایجاد می‌کند (مثلاً هنگام برون‌بری به Ledger)، می‌توانید با غیرفعال کردن نشانگرهای گروه‌بندی ارقام، مثلاً با -c/--commodity (برای هر کالای متأثر)، از آن جلوگیری کنید:

$ hledger print -c '$1000.00'
2023-01-02
    (a)          $1000

یا با وادار کردن print به نمایش همیشگی ارقام اعشار، با --round:

$ hledger print -c '$1,000.00' --round=soft
2023-01-02
    (a)      $1,000.00
به‌طور کلی‌تر، خروجی hledger به سه دسته کلی تقسیم می‌شود که
مبالغ را برای سازگاری با مصرف‌کنندگان گوناگون، کمی متفاوت قالب‌بندی می‌کنند:

۱.
"خروجی قابل خواندن برای hledger" - باید برای hledger (و
انسان‌ها) قابل خواندن باشد

• این خروجی توسط گزارش‌هایی تولید می‌شود که مدخل‌های کامل دفتر روزنامه را نشان می‌دهند:
  print، import، close،
  rewrite و غیره.

• مبالغ را با دقت اصلی آن‌ها در دفتر روزنامه نمایش می‌دهد، که ممکن است
  از یک مبلغ تا مبلغ دیگر یکدست نباشد.

• در صورت نیاز، یک نشانگر اعشار پایانی اضافه می‌کند تا از نمایش مبالغ
  مبهم جلوگیری شود.

• می‌تواند به‌طور قابل اطمینان تجزیه شود (دست‌کم توسط hledger و ledger2beancount، اما
  شاید نه توسط Ledger..).

۲.
"خروجی خوانا برای انسان" - معمولاً برای انسان‌ها

• این خروجی توسط تمام گزارش‌های دیگر تولید می‌شود.

• مبالغ را با دقت‌های نمایش استاندارد نشان می‌دهد، که در هر کالا (commodity)
  یکدست خواهد بود.

• مبالغ مبهم را بدون تغییر نمایش می‌دهد.

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

۳.
"خروجی ماشین‌خوان" - معمولاً برای سایر نرم‌افزارها

• این خروجی توسط تمام گزارش‌ها هنگامی که قالب خروجی‌ای مانند
  csv، tsv، json یا sql انتخاب
  شده باشد، تولید می‌شود.

• مبالغ را مانند ۱ یا ۲ نشان می‌دهد، اما بدون نشانگرهای جداساز ارقام.

• می‌تواند به‌طور قابل اطمینان تجزیه شود (در صورت نیاز، نشانگر اعشار می‌تواند با
  -c/--commodity-style تغییر داده شود).

ثبت بهای تمام‌شده (Recording costs)

ما چندین روش برای ثبت تراکنش‌های شامل بهای تمام‌شده را بررسی خواهیم کرد. این روش‌ها همچنین در بخش hledger Cookbook > Cost notation خلاصه شده‌اند.

بهای تمام‌شده را می‌توان به‌صورت صریح در دفتر روزنامه، با استفاده از نمادگذاری @ UNITCOST یا @@ TOTALCOST که در Journal > Costs شرح داده شده است، ثبت کرد:

حالت ۱

2022-01-01
  assets:dollars    $-135
  assets:euros       €100 @ $1.35   ; $1.35 per euro (unit cost)

حالت ۲

2022-01-01
  assets:dollars    $-135
  assets:euros       €100 @@ $135   ; $135 total cost

معمولاً نوشتن بهای تمام‌شده واحد (حالت ۱) ترجیح داده می‌شود؛ این کار ممکن است زحمت بیشتری داشته باشد و نیازمند توجه بیشتر به ارقام اعشار باشد؛ اما مبنای بهای تمام‌شده هر واحد را مشخص می‌کند و فروش سهام را آسان‌تر می‌سازد.

بهای تمام‌شده را همچنین می‌توان به‌صورت ضمنی رها کرد، و hledger بهایی را که با یک تراکنش تراز (balanced) همخوانی داشته باشد استنتاج خواهد کرد:

حالت ۳

2022-01-01
  assets:dollars    $-135
  assets:euros       €100

در اینجا، hledger بهای @@ €100 را به مبلغ نخست پیوست می‌کند (می‌توانید آن را با hledger print -x مشاهده کنید). این شکل از ثبت راحت به نظر می‌رسد، اما معایبی دارد:

• برخی از بررسی‌های خطا را فدا می‌کند. برای نمونه، اگر تصادفاً به‌جای €100 مقدار €10 را می‌نوشتید، hledger قادر به تشخیص این اشتباه نبود.
• نسبت به ترتیب ثبت‌ها (postings) حساس است - اگر ترتیب معکوس می‌شد، مدخل متفاوتی استنتاج می‌شد و گزارش‌ها متفاوت می‌بودند.
• خواندن مبنای بهای تمام‌شده به ازای هر واحد آسان نیست.

بنابراین عموماً این نوع مدخل توصیه نمی‌شود. می‌توانید با استفاده از -s (حالت strict)، یا با اجرای hledger check balanced اطمینان حاصل کنید که هیچ‌یک از این موارد را ندارید..SS گزارش‌گیری به بهای تمام‌شده (Reporting at cost) اکنون هنگامی که پرچم -B/--cost را به گزارش‌ها اضافه می‌کنید ("B" برگرفته از پرچم -B/--basis/--cost در Ledger است)، هر مقداری که با بهای تمام‌شده نشانه‌گذاری شده باشد، (در خروجی گزارش) به کالای بهای تمام‌شده‌اش تبدیل خواهد شد. یعنی آن‌ها "به بهای تمام‌شده" یا "به قیمت فروش" نمایش داده خواهند شد.

چند نکته که باید توجه داشت:

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

ثبت‌های تبدیل سرمایه (Equity conversion postings)

در ورودی‌های بالا مشکلی وجود دارد - آن‌ها نمادگذاری مرسوم دفترداری دوطرفه (DEB) نیستند، و به دلیل تبدیل "جادویی" یک کالا به کالای دیگر، باعث عدم تعادل در معادله حسابداری می‌شوند. این مسئله به صورت یک جمع کل غیرصفر در گزارش‌های تراز مانند hledger bse نشان داده می‌شود.

برای بیشتر کاربران hledger، این موضوع در عمل اهمیتی ندارد و می‌توان با خیال آسوده آن را نادیده گرفت! اما اگر می‌خواهید بیشتر بدانید، به خواندن ادامه دهید.

دفترداری دوطرفه (DEB) مرسوم، از یک جفت ثبت سرمایه (equity posting) اضافی برای متوازن ساختن تراکنش استفاده می‌کند. البته می‌توانید این کار را در hledger نیز انجام دهید:

حالت ۴

2022-01-01
    assets:dollars      $-135
    assets:euros         €100
    equity:conversion    $135
    equity:conversion   €-100

اکنون تراکنش طبق DEB استاندارد کاملاً متوازن است و مجموع کل در hledger bse به هم نخواهد ریخت.

همچنین، hledger همچنان می‌تواند بهای تمام‌شده را برای گزارش‌گیری بهای تمام‌شده استنتاج کند، اما این کار به طور پیش‌فرض انجام نمی‌شود - باید پرچم --infer-costs را به این شکل اضافه کنید:

$ hledger print --infer-costs
2022-01-01 one hundred euros purchased at $1.35 each
    assets:dollars       $-135 @@ €100
    assets:euros                  €100
    equity:conversion             $135
    equity:conversion            €-100

$ hledger bal --infer-costs -B
               €-100  assets:dollars                                                                                                                                              
                €100  assets:euros                                                                                                                                                
--------------------                                                                                                                                                              
                   0                                                                                                                                                              

در ادامه برخی از معایب این نوع ورودی آورده شده است:

• مبنای بهای تمام‌شده به ازای هر واحد به آسانی خوانا نیست.
• به جای -B باید به خاطر داشته باشید که -B --infer-costs را وارد کنید.
• گزینه --infer-costs تنها زمانی کار می‌کند که hledger بتواند دو ثبت equity:conversion را شناسایی کرده و آن‌ها را با دو ثبت غیرسرمایه‌ای تطبیق دهد. بنابراین نوشتن مدخل روزنامه در یک قالب خاص اهمیت بیشتری پیدا می‌کند. توضیحات بیشتر در این باره در زیر آمده است.

استنتاج ثبت‌های تبدیل سرمایه (Inferring equity conversion postings)

آیا می‌توان در جهت دیگر عمل کرد؟ بله، اگر تراکنش‌هایی دارید که با نمادگذاری بهای تمام‌شده @/@@ نوشته شده‌اند، در صورت افزودن پرچم --infer-equity، hledger می‌تواند ثبت‌های سرمایه غایب را استنتاج کند. به عنوان مثال:

2022-01-01
  assets:dollars  -$135
  assets:euros     €100 @ $1.35

$ hledger print --infer-equity
2022-01-01
    assets:dollars                    $-135
    assets:euros               €100 @ $1.35
    equity:conversion:$-€:€           €-100
    equity:conversion:$-€:$         $135.00

نام‌های حساب سرمایه به صورت "equity:conversion:A-B:A" و "equity:conversion:A-B:B" خواهند بود که در آن A نماد کالایی است که به ترتیب الفبایی اول است. می‌توانید بخش "equity:conversion" را با اعلان حسابی با نوع حساب V/Conversion سفارشی‌سازی کنید.

توجه داشته باشید اگر از check accounts یا check --strict استفاده می‌کنید، باید اعلان‌های حساب را برای این موارد به روزنامه خود اضافه کنید. (و برخلاف ثبت‌های عادی، ثبت‌های سرمایه تولیدشده برچسب‌ها را از اعلان‌های حساب به ارث نمی‌برند.).SS ترکیب هزینه‌ها و ثبت‌های تبدیل حقوق صاحبان سهام در نهایت، می‌توانید هم‌زمان از هر دو نماد هزینه @/@@ و ثبت‌های حقوق صاحبان سهام (equity) استفاده کنید. این کار در تئوری بهترین حالت ممکن را فراهم می‌کند - حفظ معادله حسابداری، آشکار ساختن بهای تمام‌شده بر مبنای هر واحد، و ارائه انعطاف‌پذیری بیشتر در نحوه نوشتن مدخل:

حالت ۵

2022-01-01 one hundred euros purchased at $1.35 each
    assets:dollars      $-135
    equity:conversion    $135
    equity:conversion   €-100
    assets:euros         €100 @ $1.35

تمام حالت‌های دیگر بالا (معمولاً) می‌توانند با دستور زیر به این فرم نهایی بازنویسی شوند:

$ hledger print -x --infer-costs --infer-equity

معایب:

• قالب دقیق مدخل دفتر روزنامه اهمیت بیشتری پیدا می‌کند. اگر hledger نتواند ثبت‌های هزینه و equity را تشخیص داده و با یکدیگر تطبیق دهد، خطای تراز نبودن تراکنش صادر خواهد کرد.
• دستور add هنوز این نوع مدخل را نمی‌پذیرد (#2056).
• این پرجزئیات‌ترین قالب است.

پیش‌نیازهای تشخیص ثبت‌های تبدیل حقوق صاحبان سهام

گزینه --infer-costs نیازمندی‌های خاصی دارد (برخلاف --infer-equity که همیشه کار می‌کند). این گزینه هزینه‌ها را فقط در تراکنش‌هایی استنتاج می‌کند که دارای موارد زیر باشند:

• دو ثبت غیر از حقوق صاحبان سهام (non-equity)، با کالاهای (commodities) متفاوت. ترتیب آن‌ها مهم است: هزینه به اولین مورد از آن‌ها افزوده خواهد شد.
• دو ثبت در حساب‌های تبدیل equity، در کنار یکدیگر، که دو ثبتِ غیر از equity را تراز کنند. این تراز بودن با همان دقتی (تعداد ارقام اعشار) بررسی می‌شود که در مقدار ثبتِ تبدیل استفاده شده است. حساب‌های تبدیل equity عبارت‌اند از:

و چندین گروه چهارثبتی از این دست می‌توانند در یک تراکنش واحد در کنار یکدیگر قرار گیرند. هنگامی که --infer-costs ناموفق باشد، هزینه‌ای را در آن تراکنش استنتاج نمی‌کند و خطایی نیز صادر نمی‌کند (یعنی تا جایی که بتواند هزینه‌ها را استنتاج می‌کند).

خواندن مدخل‌های حالت ۵ دفتر روزنامه، که نماد هزینه و ثبت‌های حقوق صاحبان سهام را ترکیب می‌کنند، دقیقاً همین نیازمندی‌ها را دارد. هنگامی که خواندن چنین مدخلی ناموفق باشد، hledger خطای "unbalanced transaction" (تراکنش ناتراز) صادر می‌کند.

استنتاج هزینه و حقوق صاحبان سهام به‌صورت پیش‌فرض؟

آیا --infer-costs و --infer-equity باید به‌طور پیش‌فرض فعال باشند؟ استفاده همیشگی از آن‌ها را امتحان کنید، برای مثال با یک نام مستعار پوسته (alias):

alias h="hledger --infer-equity --infer-costs"

و مشکلاتی که می‌یابید را به ما اطلاع دهید.

-V: ارزش در کالا(های) پیش‌فرض

پرچم -V/--market گونه‌ای از -X است که در آن نیازی نیست COMM را مشخص کنید. در عوض تلاش می‌کند بر اساس قیمت‌های بازار معتبر در تاریخ(های) ارزش‌گذاری، یک کالای ارزش‌گذاری پیش‌فرض را برای هر کالای اصلی حدس بزند.

گزینهٔ -V اغلب می‌تواند میان‌بر مناسبی برای -X MYCURRENCY باشد، اما نه همیشه؛ بسته به داده‌های شما ممکن است چندین کالای ارزش‌گذاری را حدس بزند. معمولاً هدف تبدیل به یک کالای واحد است، بنابراین بهتر است از -X استفاده کنید، مگر اینکه مطمئن باشید -V همان کاری را انجام می‌دهد که می‌خواهید.

تاریخ ارزش‌گذاری

قیمت‌های بازار می‌توانند روز به روز تغییر کنند. دستور hledger از قیمت‌های موجود در یک تاریخ ارزش‌گذاری مشخص (یا در بیش از یک تاریخ) استفاده خواهد کرد. به‌طور پیش‌فرض، hledger از تاریخ‌های "end" (پایان) برای ارزش‌گذاری استفاده می‌کند. به‌طور دقیق‌تر:

•

برای گزارش‌های تک‌دوره‌ای (از جمله گزارش‌های عادی print و register):

•

برای گزارش‌های چنددوره‌ای، ارزش‌گذاری هر دوره بر اساس آخرین روز آن انجام می‌شود.

این رفتار را می‌توان با گزینهٔ --value که در ادامه توضیح داده شده سفارشی کرد؛ این گزینه می‌تواند یکی از تاریخ‌های "then"،‏ "end"،‏ "now" یا "custom" را انتخاب کند.

یافتن قیمت بازار

برای تبدیل کالای A به ارزش بازار آن در کالای دیگر B، برنامهٔ hledger به ترتیب اولویت زیر به دنبال یک قیمت بازار (نرخ تبدیل) مناسب می‌گردد:

1.

یک قیمت بازار اعلام‌شده یا قیمت بازار استنتاج‌شده: آخرین قیمت بازار A در B در تاریخ ارزش‌گذاری یا پیش از آن، همان‌طور که با یک دستورالعمل P اعلام شده، یا (با پرچم --infer-market-prices) از هزینه‌ها استنتاج شده است.

2.

یک قیمت بازار معکوس: معکوس یک قیمت بازار اعلام‌شده یا استنتاج‌شده از B به A.

3.

یک زنجیرهٔ مستقیم از قیمت‌های بازار: قیمتی ترکیبی که از ترکیب کوتاه‌ترین زنجیره از قیمت‌های بازار «مستقیم» ("forward"، تنها مورد ۱ در بالا) که از A به B می‌رسد تشکیل شده است.

4.

هر زنجیره‌ای از قیمت‌های بازار: زنجیره‌ای از هر نوع قیمت بازار، شامل هر دو نوع قیمت مستقیم و معکوس (موارد ۱ و ۲ در بالا)، که از A به B منتهی می‌شوند.

طول این زنجیره‌های قیمت محدودیت دارد؛ اگر hledger بدون یافتن یک زنجیرهٔ کامل یا تمام کردن همهٔ احتمالات به آن حد برسد، متوقف خواهد شد (همراه با پیام "gave up" که در خروجی --debug=2 قابل مشاهده است). این محدودیت در حال حاضر ۱۰۰۰ است.

مبالغی که هیچ قیمت بازار مناسبی برای آن‌ها پیدا نشود، تبدیل نخواهند شد..SS --infer-market-prices: قیمت‌های بازار از روی تراکنش‌ها به‌طور معمول، ارزش بازار در hledger کاملاً توسط دستورالعمل‌های P در دفتر روزنامه شما کنترل شده و به آن‌ها نیازمند است. از آن‌جا که افزودن و به‌روزرسانی آن‌ها می‌تواند کاری خسته‌کننده باشد، و از آن‌جا که تراکنش‌ها معمولاً با قیمتی نزدیک به ارزش بازار انجام می‌شوند، چرا از بهاهای ثبت‌شده به‌عنوان قیمت‌های بازار اضافی (همان‌طور که Ledger انجام می‌دهد) استفاده نکنیم؟ افزودن پرچم --infer-market-prices به -V، -X یا --value این قابلیت را فعال می‌کند.

بنابراین برای نمونه، hledger bs -V --infer-market-prices قیمت‌های بازار را هم از دستورالعمل‌های P و هم از تراکنش‌ها دریافت خواهد کرد. اگر هر دو در یک روز رخ دهند، دستورالعمل P اولویت دارد.

یک نکته منفی وجود دارد: گزارش‌های ارزش ممکن است گاهی اوقات به شیوه‌هایی گیج‌کننده یا ناخواسته تحت تأثیر ورودی‌های دفتر روزنامه قرار گیرند. اگر این اتفاق برای شما رخ داد، تمام این بخش «گزارش ارزش» (Value reporting) را با دقت بخوانید، و برای عیب‌یابی سعی کنید --debug یا --debug=2 را اضافه کنید.

گزینه --infer-market-prices می‌تواند قیمت‌های بازار را از موارد زیر استنتاج کند:

• تراکنش‌های چندکالایی با قیمت‌های صریح (@/@@)
• تراکنش‌های چندکالایی با قیمت‌های ضمنی (بدون @، دو کالا، نامتوازن). (در این موارد، ترتیب ثبت‌ها اهمیت دارد. hledger print -x می‌تواند برای عیب‌یابی مفید باشد.)
• تراکنش‌های چندکالایی با ثبت‌های سرمایه (equity postings)، در صورتی که بها با --infer-costs استنتاج شده باشد.

در حال حاضر یک محدودیت (باگ) وجود دارد: هنگامی که کالای ارزش‌گذاری مشخص نشده باشد، قیمت‌های استنتاج‌شده با --infer-market-prices بر خلاف قیمت‌های P، به انتخاب کالای ارزش‌گذاری پیش‌فرض کمکی نمی‌کنند. بنابراین ممکن است تبدیل صورت نگیرد زیرا هیچ کالای ارزش‌گذاری شناسایی نشده است (--debug=2 این موضوع را نشان خواهد داد). برای اطمینان، کالای ارزش‌گذاری را مشخص کنید، برای نمونه:

• -X EUR --infer-market-prices، نه -V --infer-market-prices
• --value=then,EUR --infer-market-prices، نه --value=then --infer-market-prices

بهاها و قیمت‌های بازار علامت‌دار می‌توانند گیج‌کننده باشند. برای مرجع، رفتار فعلی از hledger 1.25 به بعد در این‌جا آورده شده است. (اگر فکر می‌کنید باید طور دیگری کار کند، شماره ۱۸۷۰# را ببینید.)

2022-01-01 Positive Unit prices
    a        A 1
    b        B -1 @ A 1
2022-01-01 Positive Total prices
    a        A 1
    b        B -1 @@ A 1
2022-01-02 Negative unit prices
    a        A 1
    b        B 1 @ A -1
2022-01-02 Negative total prices
    a        A 1
    b        B 1 @@ A -1
2022-01-03 Double Negative unit prices
    a        A -1
    b        B -1 @ A -1
2022-01-03 Double Negative total prices
    a        A -1
    b        B -1 @@ A -1

همه تراکنش‌های بالا متوازن در نظر گرفته می‌شوند (و در هر روز، آن دو تراکنش معادل یکدیگر به شمار می‌آیند). قیمت‌های بازار استنتاج‌شده برای B به شرح زیر است:

$ 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
هنگامی که یک کالای ارزش‌گذاری مشخص می‌کنید (-X COMM یا
--value TYPE,COMM):

دستور hledger تمام مبالغ را به COMM تبدیل می‌کند، هر جا که بتواند قیمت بازار
مناسبی بیابد (از جمله با معکوس کردن یا زنجیره‌سازی قیمت‌ها).

هنگامی که کالای ارزش‌گذاری را نامشخص رها می‌کنید (-V
یا --value TYPE):

برای هر کالای A، برنامه hledger یک کالای ارزش‌گذاری پیش‌فرض را به شرح
زیر و به ترتیب اولویت انتخاب می‌کند:

1.

کالای قیمتی از آخرین قیمت بازار اعلام‌شده با دستور P برای A در تاریخ ارزش‌گذاری
یا پیش از آن.

2.

کالای قیمتی از آخرین قیمت بازار اعلام‌شده با دستور P برای A در
هر تاریخی.
(این مورد امکان تبدیل را در صورتی که قیمت‌های استنباط‌شده قبل از تاریخ
ارزش‌گذاری وجود داشته باشند فراهم می‌کند.)

3.

اگر اصلاً هیچ دستور P وجود نداشته باشد (برای هر کالا یا تاریخی) و پرچم
--infer-market-prices استفاده شده باشد: کالای قیمتی
از آخرین قیمت استنباط‌شده از تراکنش برای A در تاریخ ارزش‌گذاری یا پیش
از آن.

این بدان معناست که:

• اگر دستورهای P داشته باشید، آن‌ها تعیین می‌کنند که -V کدام کالاها
  را و به چه چیزی تبدیل کند.

• اگر هیچ دستور P نداشته باشید و از پرچم
  --infer-market-prices استفاده کنید، بهای تمام‌شده آن را تعیین می‌کند.

مبالغی که هیچ کالای ارزش‌گذاری برای آن‌ها یافت نشود تبدیل نخواهند شد.

--value: ارزش‌گذاری منعطف

گزینه‌های -V و -X حالت‌های خاصی از گزینه جامع‌تر --value هستند:

--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

بخش TYPE هزینه یا ارزش، و تاریخ ارزش‌گذاری را انتخاب می‌کند:

--value=then

تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض، با استفاده از قیمت‌های بازار در تاریخ هر ثبت (posting).

--value=end

تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض، با استفاده از قیمت‌های بازار در آخرین روز دوره گزارش (یا در صورت نامشخص بودن، تاریخ پایان دفتر روزنامه)؛ یا در گزارش‌های چنددوره‌ای، قیمت‌های بازار در آخرین روز هر زیردوره.

--value=now

تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض با استفاده از قیمت‌های جاری بازار (در زمان تولید گزارش).

--value=YYYY-MM-DD

تبدیل مبالغ به ارزش آن‌ها در کالای ارزش‌گذاری پیش‌فرض با استفاده از قیمت‌های بازار در این تاریخ.

برای انتخاب یک کالای ارزش‌گذاری متفاوت، بخش اختیاری ,COMM را اضافه کنید: یک ویرگول، سپس نماد کالای مقصد. برای مثال: --value=now,EUR. برنامه hledger نهایت تلاش خود را برای تبدیل مبالغ به این کالا، با استنباط قیمت‌های بازار طبق توضیحات بالا، انجام خواهد داد.

مثال‌های ارزش‌گذاری

در اینجا چند مثال سریع از -V آورده شده است:

; 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

چه مقدار یورو دارم؟

$ hledger -f t.j bal -N euros
                €100  assets:euros

ارزش آن‌ها در پایان ۳ نوامبر چقدر است؟

$ hledger -f t.j bal -N euros -V -e 2016/11/4
             $110.00  assets:euros

ارزش آن‌ها پس از 2016/12/21 چقدر است؟ (هیچ تاریخ پایان گزارشی مشخص نشده است، پیش‌فرض امروز است)

$ hledger -f t.j bal -N euros -V
             $103.00  assets:euros

در اینجا چند مثال آورده شده است که اثر --value را، آن‌گونه که با print دیده می‌شود، نشان می‌دهند:

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 @ 5 B
2000-02-01
  (a)      1 A @ 6 B
2000-03-01
  (a)      1 A @ 7 B

نمایش بهای تمام‌شده هر ثبت:

$ hledger -f- print --cost
2000-01-01
    (a)             5 B
2000-02-01
    (a)             6 B
2000-03-01
    (a)             7 B

نمایش ارزش در آخرین روز دوره گزارش (2000-02-29):

$ hledger -f- print --value=end date:2000/01-2000/03
2000-01-01
    (a)             2 B
2000-02-01
    (a)             2 B

بدون تعیین دوره گزارش، آخرین تاریخ تراکنش یا تاریخ قیمت به عنوان تاریخ ارزش‌گذاری استفاده می‌شود (2000-04-01):

$ hledger -f- print --value=end
2000-01-01
    (a)             3 B
2000-02-01
    (a)             3 B
2000-03-01
    (a)             3 B

ارزش امروز نیز یکسان است (قیمت 2000-04-01 همچنان معتبر است):

$ hledger -f- print --value=now
2000-01-01
    (a)             4 B
2000-02-01
    (a)             4 B
2000-03-01
    (a)             4 B
نمایش ارزش در 2000/01/15:

$ 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

تعامل ارزش‌گذاری و پرس‌وجوها

هنگام تطبیق ثبت‌ها بر اساس پرس‌وجوها در حضور ارزش‌گذاری، رویدادهای زیر رخ می‌دهد:

1.

پرس‌وجو به دو بخش تقسیم می‌شود:

2.

ثبت‌ها بر اساس مبالغ پیش از ارزش‌گذاری با پرس‌وجوهای ارز و مبلغ تطبیق داده می‌شوند.

3.

ارزش‌گذاری روی ثبت‌ها اعمال می‌شود.

4.

ثبت‌ها بر اساس مبالغ پس از ارزش‌گذاری با سایر بخش‌های پرس‌وجو تطبیق داده می‌شوند.

مرتبط: #1625

اثر ارزش‌گذاری بر گزارش‌ها

در اینجا مرجعی برای چگونگی تأثیر ارزش‌گذاری بر هر بخش از گزارش‌های hledger' آورده شده است. این بخش ممکن است هنگام عیب‌یابی مفید باشد. اگر مشکلی یافتید، لطفاً آن را گزارش دهید؛ در حالت ایده‌آل همراه با یک نمونهٔ قابل بازتولید. مرتبط: #329، #1083.

نخست، یک واژه‌نامهٔ کوتاه:

cost (بهای تمام‌شده)

با استفاده از قیمت(های) ثبت‌شده در تراکنش(ها) محاسبه می‌شود.

value (ارزش)

ارزش بازار با استفاده از اعلان‌های قیمت بازار موجود، یا مقدار بدون تغییر در صورت پیدا نشدن نرخ تبدیل.

report start (آغاز گزارش)

نخستین روز از دورهٔ گزارش مشخص‌شده با -b یا -p یا date:، در غیر این صورت امروز.

report or journal start (آغاز گزارش یا دفتر روزنامه)

نخستین روز از دورهٔ گزارش مشخص‌شده با -b یا -p یا date:، در غیر این صورت نخستین تاریخ تراکنش در دفتر روزنامه، در غیر این صورت امروز.

report end (پایان گزارش)

آخرین روز از دورهٔ گزارش مشخص‌شده با -e یا -p یا date:، در غیر این صورت امروز.

report or journal end (پایان گزارش یا دفتر روزنامه)

آخرین روز از دورهٔ گزارش مشخص‌شده با -e یا -p یا date:، در غیر این صورت آخرین تاریخ تراکنش در دفتر روزنامه، در غیر این صورت امروز.

report interval (بازهٔ گزارش)

یک پرچم (-D/-W/-M/-Q/-Y) یا عبارت دوره که حالت چنددوره‌ای گزارش را فعال می‌کند (خواه یک زیردوره یا چندین زیردوره را نشان دهد).