PRINT

PRINT:vname:format[:strftime|:valstrftime|:valstrfduration]

بسته به زمینه کاربرد، مؤلفه مقدار (بدون پسوند، valstrftime یا valstrfduration) یا مؤلفه زمان (strftime) از یک VDEF با استفاده از format چاپ می‌شود. مشخص کردن یک vname که توسط یک DEF یا CDEF تولید شده باشد، خطا است.

هر متنی در format دقیقاً به همان صورت چاپ می‌شود، با یک استثنا: نویسه درصد یک رشته فرمت‌دهنده را مشخص می‌کند. این رشته می‌تواند به صورت زیر باشد:

برای چاپ مقادیر:

%%

صرفاً یک نویسه واقعی '%' را چاپ می‌کند

%#.#le

اعدادی مانند 1.2346e+04 را چاپ می‌کند. اعداد صحیح اختیاری # بیانگر عرض فیلد و دقت اعشار هستند.

%#.#lf

اعدادی مانند 12345.6789 (%5.4lf) را با عرض فیلد و دقت اختیاری چاپ می‌کند.

%s

این را پس از %le، %lf یا %lg قرار دهید. این عبارت با یکای متناسب مرتبه بزرگی SI جایگزین شده و مقدار بر همان اساس مقیاس‌بندی می‌شود (123456 -> 123.456 k).

%S

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

اگر مقدار یک VDEF را PRINT می‌کنید، می‌توانید با الحاق رشته :strftime به قالب (format)، زمان مرتبط با آن را نیز چاپ کنید. توجه داشته باشید که RRDtool از تابع strftime کتابخانه C سیستم‌عامل شما استفاده می‌کند. این بدان معناست که مشخص‌کننده‌های تبدیل ممکن است متفاوت باشند. اگر مطمئن نیستید، صفحه راهنما (man page) را بررسی کنید. در ادامه فهرستی از مشخص‌کننده‌های تبدیل که معمولاً به طور سراسری پشتیبانی می‌شوند آمده است. قالب‌بندی مقادیری که با :valstrftime به عنوان برچسب زمانی (timestamp) تفسیر می‌شوند نیز به همین ترتیب انجام می‌گیرد.

%a

نام اختصاری روز هفته بر اساس موقعیت مکانی (locale) جاری.

%A

نام کامل روز هفته بر اساس موقعیت مکانی (locale) جاری.

%b

نام اختصاری ماه بر اساس موقعیت مکانی (locale) جاری.

%B

نام کامل ماه بر اساس موقعیت مکانی (locale) جاری.

%c

نمایش ترجیحی تاریخ و زمان برای موقعیت مکانی (locale) جاری.

%d

روز ماه به صورت یک عدد ده‌دهی (در بازه 01 تا 31).

%H

ساعت به صورت یک عدد ده‌دهی با استفاده از ساعت ۲۴ ساعته (در بازه 00 تا 23).

%I

ساعت به صورت یک عدد ده‌دهی با استفاده از ساعت ۱۲ ساعته (در بازه 01 تا 12).

%j

روز سال به صورت یک عدد ده‌دهی (در بازه 001 تا 366).

%m

ماه به صورت یک عدد ده‌دهی (در بازه 01 تا 12).

%M

دقیقه به صورت یک عدد ده‌دهی (در بازه 00 تا 59).

%p

بسته به مقدار زمان ارائه‌شده، `AM' یا `PM'، یا رشته‌های متناظر برای موقعیت مکانی (locale) جاری. ظهر به عنوان `pm' و نیمه‌شب به عنوان `am' در نظر گرفته می‌شود. توجه داشته باشید که در بسیاری از موقعیت‌های مکانی قالب نوشتاری `pm' پشتیبانی نمی‌شود و در چنین مواردی %p یک رشته خالی برمی‌گرداند.

%s

ثانیه به صورت یک عدد ده‌دهی (در بازه 00 تا 61).

%S

ثانیه‌های سپری‌شده از مبدأ زمانی یونیکس (1.1.1970) (وابسته به libc و غیر استاندارد!).

%U

شماره هفته در سال جاری به صورت یک عدد ده‌دهی، در بازه 00 تا 53، با در نظر گرفتن اولین یکشنبه به عنوان نخستین روز هفته 01. همچنین %V و %W را ببینید.

%V

شماره هفته سال جاری بر اساس استاندارد ISO 8601:1988 به صورت یک عدد ده‌دهی، در بازه 01 تا 53، که در آن هفته 1 نخستین هفته‌ای است که حداقل 4 روز در سال جاری داشته باشد، و دوشنبه به عنوان اولین روز هفته در نظر گرفته می‌شود. همچنین %U و %W را ببینید.

%w

روز هفته به صورت ده‌دهی، در بازه 0 تا 6، که یکشنبه برابر با 0 است. همچنین %u را ببینید.

%W

شماره هفته سال جاری به صورت یک عدد ده‌دهی، در بازه 00 تا 53، با در نظر گرفتن نخستین دوشنبه به عنوان اولین روز هفته 01.

%x

نمایش ترجیحی تاریخ برای موقعیت مکانی (locale) جاری بدون بخش زمان.

%X

نمایش ترجیحی زمان برای موقعیت مکانی (locale) جاری بدون بخش تاریخ.

%y

سال به صورت یک عدد ده‌دهی بدون قرن (در بازه 00 تا 99).

%Y

سال به صورت یک عدد ده‌دهی به همراه قرن.

%Z

منطقه زمانی یا نام یا مخفف آن.

%%

یک نویسه واقعی `%'.

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

- تمام نویسه‌هایی که مشخص‌کننده تبدیل نیستند بدون تغییر کپی می‌شوند
- یک مشخص‌کننده تبدیل دارای قالب '%' [ ['0'] minwidth ] [ '.' precision ] conversion-specifier است

که در آن conversion-specifier یکی از موارد زیر است:

%

یک '%' خام خروجی داده می‌شود، width و precision نادیده گرفته می‌شوند

W

تعداد هفته‌ها

d

تعداد روزها، باقی‌مانده بر تعداد هفته‌ها

D

تعداد روزها

h

تعداد ساعت‌ها، باقی‌مانده بر تعداد روزها

H

تعداد ساعت‌ها.IP m 4 تعداد دقیقه‌ها، به پیمانه تعداد ساعت‌ها

M

تعداد دقیقه‌ها

s

تعداد ثانیه‌ها، به پیمانه تعداد دقیقه‌ها

S

تعداد ثانیه‌ها

f

تعداد میلی‌ثانیه‌ها، به پیمانه ثانیه‌ها

PRINT:vname:CF:format

منسوخ شده است. در اسکریپت‌های جدید از شکل جدید این دستور استفاده کنید. شکل نخست این دستور برای استفاده با vnameهای CDEF است.

GRAPH

GPRINT:vname:format

این مشابه "PRINT" است، اما درون نمودار چاپ می‌شود.

GPRINT:vname:CF:format

منسوخ شده است. در اسکریپت‌های جدید از شکل جدید این دستور استفاده کنید. این مشابه "PRINT" است، اما درون نمودار چاپ می‌شود.

COMMENT:text

متن عیناً در بخش راهنمای (legend) نمودار چاپ می‌شود. توجه داشته باشید که در RRDtool 1.2 باید دونقطه‌ها در متن COMMENT را به همان روشی که در دستورهای *PRINT با نوشتن '\:' گریز می‌دهید، گریزدهی کنید.

VRULE:time#color[:[legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]

یک خط عمودی در time رسم می‌کند. رنگ آن از سه عدد هگزادسیمال تشکیل شده است که مولفه‌های رنگی rgb (مقدار 00 خاموش و FF بیشینه است) قرمز، سبز و آبی را مشخص می‌کنند و به‌دنبال آن‌ها یک آلفای اختیاری می‌آید. به‌صورت اختیاری، یک جعبه و رشتهٔ راهنما در بخش راهنما (legend) چاپ می‌شود. time می‌تواند یک عدد یا متغیری از یک VDEF باشد. استفاده از vnameهای حاصل از DEF یا CDEF در اینجا خطا است. خط‌های خط‌چین را می‌توان با استفاده از اصلاح‌کنندهٔ dashes رسم کرد. برای جزئیات بیشتر به LINE مراجعه کنید.

HRULE:value#color[:[legend][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]

یک خط افقی در value رسم می‌کند. HRULE بسیار شبیه به LINE عمل می‌کند، به‌جز اینکه هیچ تأثیری بر مقیاس نمودار نخواهد داشت. اگر یک HRULE بیرون از ناحیهٔ رسم نمودار باشد، به‌سادگی قابل مشاهده نخواهد بود و به‌طور پیش‌فرض در راهنما نیز ظاهر نخواهد شد.

LINE[width]:value[#color][:[legend][:STACK][:skipscale][:dashes[=on_s[,off_s[,on_s,off_s]...]][:dash-offset=offset]]]

خطی با عرض مشخص‌شده روی نمودار رسم می‌کند. width می‌تواند یک عدد ممیز شناور باشد. اگر رنگ مشخص نشود، رسم به‌صورت 'نامرئی' انجام می‌شود. این ویژگی زمانی مفید است که بخواهید چیز دیگری را روی این خط پشته کنید. همچنین جعبه و رشتهٔ راهنما اختیاری است و در صورت تعیین شدن، در بخش راهنما چاپ خواهد شد. مقدار value می‌تواند توسط DEF، VDEF و CDEF تولید شود. اگر از اصلاح‌کنندهٔ اختیاری STACK استفاده شود، این خط بر روی عنصر قبلی که می‌تواند یک LINE یا یک AREA باشد، پشته می‌شود.

به‌طور معمول تابع رسم نمودار اطمینان حاصل می‌کند که کل LINE یا AREA در نمودار قابل مشاهده باشد. در صورت لزوم، مقیاس نمودار بر همین اساس تغییر خواهد کرد. هر LINE یا AREA را می‌توان با افزودن گزینهٔ skipscale از این فرایند مستثنی کرد.

اصلاح‌کنندهٔ dashes سبک خط‌چین را فعال می‌کند. بدون گزینه‌های بیشتر، یک خط‌چین متقارن با طول قطعه‌های ۵ پیکسل رسم خواهد شد. الگوی خط‌چین را می‌توان تغییر داد اگر در پی پارامتر dashes= یک مقدار یا تعداد زوجی (۱، ۲، ۴، ۶، ...) از مقادیر مثبت بیاید. هر مقدار، طول بخش‌های متناوب on_s و off_s رسم خط را مشخص می‌کند. پارامتر dash-offset یک جابه‌جایی (offset) را درون الگو مشخص می‌کند که رسم خط از آنجا آغاز می‌شود.

هنگامی که رنگی تعیین نمی‌کنید، نمی‌توانید راهنما تعیین کنید. اگر می‌خواهید از STACK استفاده کنید، از شکل "LINEx:<value>::STACK" بهره ببرید.

AREA:value[#color[#color2]][:[legend][:STACK][:skipscale][:gradheight=y]

به LINE مراجعه کنید، با این حال ناحیهٔ بین محور x و خط پر خواهد شد.

اگر color2 مشخص شده باشد، ناحیه با یک گرادیان پر خواهد شد.

پارامتر gradheight می‌تواند سه رفتار مختلف ایجاد کند. اگر gradheight > 0 باشد، گرادیان دارای ارتفاع ثابتی است که از خط شروع شده و به سمت پایین می‌رود. اگر gradheight < 0 باشد، گرادیان از ارتفاعی ثابت بالای محور x شروع شده و به سمت محور x پایین می‌رود. اگر height == 0 باشد، گرادیان از خط به سمت محور x امتداد می‌یابد.

مقدار پیش‌فرض برای gradheight برابر با 50 است.

TICK:vname#rrggbb[aa][:fraction[:legend]]

به‌ازای هر مقدار از vname که غیرصفر و غیر از *UNKNOWN* باشد، یک نشانک (یک خط عمودی تیک‌مانند) رسم می‌کند. آرگومان fraction طول نشانک را به‌صورت کسری از محور y مشخص می‌کند؛ مقدار پیش‌فرض 0.1 (۱۰٪ از محور) است. توجه داشته باشید که تعیین رنگ اختیاری نیست. نشانک‌های TICK به‌طور معمول از لبهٔ پایینی ناحیهٔ رسم نمودار آغاز می‌شوند. اگر کسر منفی باشد، آن‌ها از لبهٔ بالایی ناحیهٔ رسم نمودار آغاز می‌شوند.

SHIFT:vname:offset

با استفاده از این دستور، RRDtool عنصرهای پس از آن را با جابه‌جایی (انحراف) مشخص‌شده رسم می‌کند. به‌عنوان مثال، می‌توانید یک جابه‌جایی ( 7*24*60*60 = ) 604'800 ثانیه‌ای را تعیین کنید تا یک هفته «به عقب نگاه کنید». حتماً به بینندهٔ نمودار خود بگویید که این کار را کرده‌اید... همانند سایر عنصرهای رسم نمودار، در اینجا نیز می‌توانید یک عدد یا یک متغیر را مشخص کنید.

TEXTALIGN:{left|right|justified|center}

برچسب‌ها در زیر نمودار قرار می‌گیرند. هنگامی که از سمت چپ سرریز کنند، به خط بعدی می‌شکنند. به‌طور پیش‌فرض، خط‌ها از هر دو طرف تراز (justified) می‌شوند. تابع TEXTALIGN به شما امکان می‌دهد این پیش‌فرض را تغییر دهید. این یک دستور است و نه یک گزینه، بنابراین می‌توانید مقدار پیش‌فرض را چندین بار در فهرست آرگومان‌های خود تغییر دهید.

STACK:vname#color[:legend]

منسوخ شده است. به‌جای آن از اصلاح‌کننده‌های STACK در سایر دستورها استفاده کنید!

چند نکته دربارهٔ پشته‌بندی (stacking)

هنگام پشته‌بندی، یک عنصر بالای محور X قرار نمی‌گیرد بلکه بر روی عنصر قبلی گذاشته می‌شود. باید چیزی وجود داشته باشد تا بتوان روی آن پشته‌بندی کرد.

می‌توانید از یک LINE یا AREA نامرئی (invisible) برای پشته‌سازی روی آن استفاده کنید.

یک مقدار unknown باعث می‌شود که کل پشته از آن لحظه به بعد ناشناخته شود. شما نمی‌دانید از کجا شروع کنید (مقدار ناشناخته) و در نتیجه نمی‌دانید در کجا به پایان برسانید.

اگر می‌خواهید مطمئن شوید که متغیر خاصی را نمایش خواهید داد، اطمینان حاصل کنید که هرگز روی مقدار ناشناخته پشته‌بندی نکنید. برای این کار از یک دستور CDEF همراه با IF و UN استفاده کنید..SH "نکاتی درباره آرگومان‌های راهنما (NOTES on legend arguments)"

گریز دادن دو‌نقطه (Escaping the colon)

وجود یک دونقطه ':' در یک آرگومان legend پایان راهنما را مشخص می‌کند. برای وارد کردن یک ':' به عنوان بخشی از یک راهنما، دونقطه باید با یک بک‌اسلش '\:' گریز داده شود (escape شود). توجه داشته باشید که بسیاری از محیط‌ها بک‌اسلش‌ها را خودشان پردازش می‌کنند، بنابراین ممکن است برای ارسال یکی از آن‌ها به rrd_graph، نوشتن دو بک‌اسلش لازم باشد.

قالب‌بندی رشته (String Formatting)

متنی که در زیر نمودار اصلی چاپ می‌شود را می‌توان با افزودن نویسه‌های گریز ویژه در انتهای متن قالب‌بندی کرد. هر زمان که چنین نویسه‌ای ظاهر شود، تمام متن در انتظار با توجه به نویسه مشخص‌شده بر روی نمودار قرار می‌گیرد.

نشانگرهای معتبر عبارتند از: \j برای تراز دوطرفه (justified)، \l برای چپ‌چین، \r برای راست‌چین و \c برای وسط‌چین. در بخش بعدی مثالی وجود دارد که نحوه استفاده از قالب‌بندی وسط‌چین را نشان می‌دهد.

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

به طور معمول دو نویسه فاصله بین هر دو موردی که در نمودار چاپ می‌شود، درج می‌گردد. فاصله پس از یک رشته را می‌توان با قرار دادن یک \g در انتهای رشته حذف کرد. همچنین \g هر فاصله‌ای را در صورتی که در انتهای رشته باشد نادیده می‌گیرد. این قابلیت می‌تواند در پیوند با %s برای حذف رشته‌های واحد خالی استفاده شود.

GPRINT:a:MAX:%lf%s\g

یک مورد خاص COMMENT:\s است که مقداری فضای عمودی اضافی پیش از قرار دادن سطر بعدی راهنماها درج می‌کند.

اگر می‌خواهید راهنماهای چپ‌چین و راست‌چین را در یک سطر داشته باشید، از COMMENT:\u برای بازگشت به یک سطر قبل مانند این استفاده کنید:

COMMENT:left\l
COMMENT:\u
COMMENT:right\r

همچنین یک کنترل 'nop' برای شرایطی وجود دارد که می‌خواهید یک رشته واقعاً به توالی نویسه بک‌اسلش منتهی شود: \.

COMMENT:OS\2\.

هنگام استفاده از قلم با فاصله متناسب در نمودار خود، نویسه‌های تب یا توالی \t عناصر راهنما را تراز (line-up) می‌کنند. توجه داشته باشید که تب‌های درج‌شده نسبت به ابتدای عنصر راهنمای فعلی هستند!

از آنجا که RRDtool 1.3 از Pango برای رندر کردن متن استفاده می‌کند، می‌توانید از نشانه‌گذاری Pango بهره ببرید. Pango از برچسب‌های xml با نام span برای دستورالعمل‌های قالب‌بندی درون‌خطی استفاده می‌کند.

یک مثال ساده از یک رشته نشانه‌گذاری‌شده می‌تواند چنین باشد:

<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!

فهرست کامل ویژگی‌ها برای برچسب span (برگرفته از مستندات pango):

font_desc

یک رشته توصیف قلم، مانند "Sans Italic 12"؛ توجه داشته باشید که هر ویژگی دیگر span این توصیف را بازنویسی (override) خواهد کرد. بنابراین اگر "Sans Italic" و همچنین یک ویژگی style="normal" داشته باشید، Sans عادی دریافت خواهید کرد، نه ایتالیک.

font_family

نام یک خانواده قلم

face

مترادفی برای font_family

size

اندازه قلم بر حسب یک ۱۰۲۴ام یک پوینت (point)، یا یکی از اندازه‌های مطلق 'xx-small'، 'x-small'، 'small'، 'medium'، 'large'، 'x-large'، 'xx-large'، یا یکی از اندازه‌های نسبی 'smaller' یا 'larger'. اگر می‌خواهید اندازه مطلق را مشخص کنید، معمولاً آسان‌تر است که از قابلیت تعیین توصیف جزئی قلم با استفاده از 'font_desc' بهره ببرید؛ می‌توانید به جای size='12800' از font_desc='12.5' استفاده کنید.

style

یکی از موارد 'normal'، 'oblique'، 'italic'

weight

یکی از موارد 'ultralight'، 'light'، 'normal'، 'bold'، 'ultrabold'، 'heavy'، یا یک وزن عددی

variant

'normal' یا 'smallcaps'

stretch

یکی از موارد 'ultracondensed'، 'extracondensed'، 'condensed'، 'semicondensed'، 'normal'، 'semiexpanded'، 'expanded'، 'extraexpanded'، 'ultraexpanded'

foreground

یک مشخصه رنگ RGB مانند '#00FF00' یا نام یک رنگ مانند 'red'

background

یک مشخصه رنگ RGB مانند '#00FF00' یا نام یک رنگ مانند 'red'

underline

یکی از موارد 'none'، 'single'، 'double'، 'low'، 'error'

underline_color

رنگ زیرخط‌ها؛ یک مشخصه رنگ RGB مانند '#00FF00' یا نام یک رنگ مانند 'red'

rise

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

strikethrough

'true' یا 'false' برای تعیین این که روی متن خط کشیده شود یا خیر

strikethrough_color

رنگ خطوط خط‌خوردگی؛ یک مشخصه رنگ RGB مانند '#00FF00' یا نام یک رنگ مانند 'red'

fallback

'true' یا 'false' برای تعیین فعال بودن قلم جایگزین (fallback). در صورت غیرفعال بودن، نویسه‌ها تنها از نزدیک‌ترین قلم منطبق در سیستم برداشته می‌شوند. هیچ جایگزینی با قلم‌های دیگر سیستم که ممکن است نویسه‌های موجود در متن را داشته باشند انجام نخواهد شد. قلم جایگزین (fallback) به طور پیش‌فرض فعال است. بیشتر برنامه‌ها نباید fallback را غیرفعال کنند.

lang

یک کد زبان که مشخص‌کننده زبان متن است

letter_spacing

فاصله میان حروف بر حسب یک ۱۰۲۴ام یک پوینت.

gravity

یکی از موارد 'south'، 'east'، 'north'، 'west'، 'auto'.

gravity_hint

یکی از موارد 'natural'، 'strong'، 'line'.

برای صرفه‌جویی در تایپ، میانبرهایی نیز وجود دارند:

b

پررنگ (Bold)

big

قلم را به صورت نسبی بزرگ‌تر می‌کند، معادل با <span size="larger">

i

مورب (Italic)

s

خط‌خورده (Strike through)

sub

زیرنویس (Subscript)

sup

بالانویس (Superscript)

small

قلم را به صورت نسبی کوچک‌تر می‌کند، معادل با <span size="smaller">

tt

قلم تک‌فاصله (Monospace font)

u

زیرخط (Underline).SH "همچنین ببینید (SEE ALSO)" rrdgraph نمایی کلی از چگونگی عملکرد rrdtool graph ارائه می‌دهد. rrdgraph_data به تفصیل DEF، CDEF و VDEF را شرح می‌دهد. rrdgraph_rpn زبان RPN مورد استفاده در عبارت‌های ?DEF را شرح می‌دهد. صفحهٔ rrdgraph_graph تمام توابع graph و print را شرح می‌دهد.

حتماً برای نکات و ترفندها rrdgraph_examples را مطالعه کنید.