.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>.
.Dd April 14, 2018
.Dt RUBY \&1 "Ruby Programmer's Reference Guide"
.Os UNIX
.Sh "نام (NAME)"
.Nm ruby
.Nd زبان اسکریپت‌نویسی تفسیری و شیءگرا
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl -copyright
.Op Fl -version
.Op Fl SUacdlnpswvy
.Op Fl 0 Ns Op Ar octal
.Op Fl C Ar directory
.Op Fl E Ar external Ns Op : Ns Ar internal
.Op Fl F Ns Op Ar pattern
.Op Fl I Ar directory
.Op Fl K Ns Op Ar c
.Op Fl T Ns Op Ar level
.Op Fl W Ns Op Ar level
.Op Fl e Ar command
.Op Fl i Ns Op Ar extension
.Op Fl r Ar library
.Op Fl x Ns Op Ar directory
.Op Fl - Ns Bro Cm enable Ns | Ns Cm disable Brc Ns - Ns Ar FEATURE
.Op Fl -dump Ns = Ns Ar target
.Op Fl -verbose
.Op Fl -crash-report Ns = Ns Ar template
.Op Fl -
.Op Ar program_file
.Op Ar argument ...
.Sh "توضیحات (DESCRIPTION)"
Ruby یک زبان اسکریپت‌نویسی تفسیری برای برنامه‌نویسی شیءگرای سریع و آسان است. این زبان ویژگی‌های متعددی برای پردازش فایل‌های متنی و انجام وظایف مدیریت سیستم (مشابه Perl) دارد. ساده، سرراست و توسعه‌پذیر است.
.Pp
اگر زبانی برای برنامه‌نویسی شیءگرای آسان می‌خواهید، یا از زشتی‌های Perl خوشتان نمی‌آید، یا مفهوم LISP را دوست دارید اما پرانتزهای بیش‌ازحد آن را نمی‌پسندید، ممکن است Ruby زبان انتخابی شما باشد.
.Sh "ویژگی‌ها (FEATURES)"
ویژگی‌های Ruby به شرح زیر است:
.Bl -tag -width 6n
.It Sy "تفسیری"
Ruby یک زبان تفسیری است، بنابراین برای اجرای برنامه‌های نوشته‌شده به Ruby نیازی به کامپایل مجدد آن‌ها ندارید.
.Pp
.It Sy "متغیرها بدون نوع هستند (نوع‌دهی پویا)"
متغیرها در Ruby می‌توانند حاوی داده‌هایی از هر نوع باشند. نیازی نیست نگران نوع متغیرها باشید. در نتیجه، بررسی زمان کامپایل ضعیف‌تری دارد.
.Pp
.It Sy "بدون نیاز به اعلان"
می‌توانید بدون هیچ‌گونه اعلانی از متغیرها در برنامه‌های Ruby خود استفاده کنید. نام متغیرها بیانگر حوزه دسترسی (اسکوپ) آن‌هاست - سراسری، کلاس، نمونه، یا محلی.
.Pp
.It Sy "ساختار نحوی ساده"
Ruby دارای ساختار نحوی ساده‌ای است که اندکی از Eiffel تأثیر گرفته است.
.Pp
.It Sy "بدون مدیریت حافظه در سطح کاربر"
Ruby از مدیریت خودکار حافظه بهره می‌برد. اشیایی که دیگر از جایی به آن‌ها ارجاع داده نمی‌شود، به‌طور خودکار توسط بازیافت حافظه (garbage collector) تعبیه‌شده در مفسر جمع‌آوری می‌شوند.
.Pp
.It Sy "همه‌چیز یک شیء است"
Ruby زبانی کاملاً شیءگرا است و از بدو پیدایش نیز چنین بوده است. حتی داده‌های بنیادینی مانند اعداد صحیح نیز شیء در نظر گرفته می‌شوند.
.Pp
.It Sy "کلاس، وراثت، و متدها"
Ruby به عنوان یک زبان شیءگرا، به‌طور طبیعی ویژگی‌های پایه‌ای مانند کلاس‌ها، وراثت، و متدها را داراست.
.Pp
.It Sy "متدهای یگانه (Singleton methods)"
Ruby قابلیت تعریف متدها را برای اشیای خاص دارد. برای مثال، می‌توانید با تعریف یک singleton method برای یک دکمه، عملیات فشردن دکمه را برای یک ویجت خاص تعریف کنید. یا اگر تمایل داشته باشید، می‌توانید سیستم شیءگرای مبتنی بر پیش‌نمونه (prototype-based) مختص به خود را با استفاده از متدهای یگانه بسازید.
.Pp
.It Sy "ترکیب (Mix-in) توسط ماژول‌ها"
Ruby عمداً وراثت چندگانه ندارد، زیرا منبعی از سردرگمی است. در عوض، Ruby توانایی به‌اشتراک‌گذاری پیاده‌سازی‌ها را در سراسر درخت وراثت دارد. این قابلیت اغلب
.Sq Mix-in
نامیده می‌شود.
.Pp
.It Sy "تکرارکننده‌ها (Iterators)"
Ruby برای تجرید حلقه‌ها دارای تکرارکننده (iterator) است.
.Pp
.It Sy "بستارها (Closures)"
در Ruby می‌توانید روال را به شیء تبدیل کنید.
.Pp
.It Sy "پردازش متن و عبارات منظم"
Ruby امکانات متعددی برای پردازش متن، همانند Perl، در اختیار دارد.
.Pp
.It Sy "چندزبانه‌سازی (M17N)، مستقل از مجموعه نویسه‌ها"
Ruby از برنامه‌نویسی چندزبانه پشتیبانی می‌کند. پردازش متون نوشته‌شده به زبان‌های طبیعی گوناگون و کدگذاری‌شده با کدبندی‌های مختلف نویسه، بدون وابستگی به Unicode آسان است.
.Pp
.It Sy "اعداد بزرگ (Bignums)"
با اعداد بزرگ درونی، می‌توانید به عنوان مثال !400 (فاکتوریل ۴۰۰) را محاسبه کنید.
.Pp
.It Sy "بازتاب و زبان‌های ویژه‌دامنه (DSLs)"
کلاس خود نمونه‌ای از کلاس Class است. تعریف کلاس‌ها و متدها مانند 1+1 یک عبارت (expression) است. بنابراین برنامه‌های شما حتی می‌توانند برنامه‌ها را بنویسند و ویرایش کنند. از این رو، می‌توانید برنامه کاربردی خود را در زبان برنامه‌نویسی خاص خود بر روی Ruby بنویسید.
.Pp
.It Sy "مدیریت استثناها"
مشابه Java(tm).
.Pp
.It Sy "دسترسی مستقیم به سیستم‌عامل"
Ruby می‌تواند بیشتر فراخوان‌های سیستمی
.Ux
را که اغلب در برنامه‌نویسی سیستم استفاده می‌شوند به کار بگیرد.
.Pp
.It Sy "بارگذاری پویا"
در اکثر سیستم‌های
.Ux
می‌توانید فایل‌های شیء را به‌صورت آنی (on-the-fly) در مفسر Ruby بارگذاری کنید.
.It Sy "کتابخانه‌های غنی"
علاوه بر
.Dq کتابخانه‌های توکار
و
.Dq کتابخانه‌های استاندارد
همراه با Ruby، حجم وسیعی از کتابخانه‌های شخص ثالث
.Pq Dq gems
از طریق سیستم مدیریت بسته موسوم به
.Sq RubyGems
(یعنی دستور
.Xr gem 1 Ns
) در دسترس هستند. از وب‌سایت RubyGems.org
.Pq Lk https://rubygems.org
دیدن کنید تا gemهای مورد نیاز خود را بیابید، و GitHub
.Pq Lk https://github
را برای بررسی نحوه توسعه و استفاده از آن‌ها کاوش کنید.
.El
.Pp
.Sh "گزینه‌ها (OPTIONS)"
مفسر Ruby گزینه‌های (سوئیچ‌های) خط فرمان زیر را می‌پذیرد. این گزینه‌ها بسیار شبیه به گزینه‌های
.Xr perl 1
هستند.
.Bl -tag -width "1234567890123" -compact
.Pp
.It Fl -copyright
اعلان کپی‌رایت را چاپ می‌کند و بلافاصله بدون اجرای هیچ اسکریپتی خارج می‌شود.
.Pp
.It Fl -version
نسخه مفسر Ruby را چاپ می‌کند و بلافاصله بدون اجرای هیچ اسکریپتی خارج می‌شود.
.Pp
.It Fl 0 Ns Op Ar octal
(رقم
.Dq zero . Ns
) جداکننده رکوردهای ورودی
.Pf ( Li "$/" )
را به صورت یک عدد در مبنای هشت (اکتال) مشخص می‌کند. اگر هیچ رقمی داده نشود، نویسه null به عنوان جداکننده در نظر گرفته می‌شود. سوئیچ‌های دیگر می‌توانند بعد از ارقام قرار گیرند.
.Fl 00
Ruby را در حالت پاراگراف قرار می‌دهد.
.Fl 0777
باعث می‌شود Ruby کل فایل را یک‌باره به صورت یک رشته واحد بخواند، زیرا هیچ نویسه مجازی با این مقدار وجود ندارد.
.Pp
.It Fl C Ar directory
.It Fl X Ar directory
باعث می‌شود Ruby به دایرکتوری مشخص‌شده تغییر مسیر دهد.
.Pp
.It Fl E Ar external Ns Op : Ns Ar internal
.It Fl -encoding Ar external Ns Op : Ns Ar internal
مقدار(های) پیش‌فرض را برای کدبندی‌های خارجی و داخلی تعیین می‌کند. مقادیر باید با دونقطه (:) از هم جدا شوند.
.Pp
می‌توانید بخش کدبندی داخلی را حذف کنید؛ در این صورت مقدار
.Pf ( Li "Encoding.default_internal" )
برابر nil خواهد بود.
.Pp
.It Fl -external-encoding Ns = Ns Ar encoding
.It Fl -internal-encoding Ns = Ns Ar encoding
کدبندی نویسه پیش‌فرض خارجی یا داخلی را مشخص می‌کند.
.Pp
.It Fl F Ar pattern
جداکننده فیلدهای ورودی
.Pf ( Li "$;" )
را مشخص می‌کند.
.Pp
.It Fl I Ar directory
برای اعلام مسیر بارگذاری اسکریپت‌های کتابخانه به Ruby به کار می‌رود. مسیر دایرکتوری به متغیر load-path
.Pf ( Li "$:" )
افزوده می‌شود.
.Pp
.It Fl K Ar kcode
کدبندی KANJI (ژاپنی) را مشخص می‌کند. مقدار پیش‌فرض برای کدبندی‌های اسکریپت
.Pf ( Li "__ENCODING__" )
و کدبندی‌های خارجی
.Pf ( Li "Encoding.default_external" )
برابر با مقدار مشخص‌شده خواهد بود.
.Ar kcode
می‌تواند یکی از موارد زیر باشد:
.Bl -hang -offset indent
.It Sy e
EUC-JP
.Pp
.It Sy s
Windows-31J (CP932)
.Pp
.It Sy u
UTF-8
.Pp
.It Sy n
ASCII-8BIT (BINARY)
.El
.Pp
.It Fl S
باعث می‌شود Ruby از متغیر محیطی
.Ev PATH
برای جستجوی اسکریپت استفاده کند، مگر اینکه نام آن با یک اسلش آغاز شود. این قابلیت برای شبیه‌سازی
.Li #!
در دستگاه‌هایی که از آن پشتیبانی نمی‌کنند، به روش زیر استفاده می‌شود:
.Bd -literal -offset indent
#! /usr/local/bin/ruby
# This line makes the next one a comment in Ruby \e
  exec /usr/local/bin/ruby -S $0 $*
.Ed
.Pp
در برخی سیستم‌ها
.Li "$0"
همیشه حاوی مسیر کامل نیست، بنابراین به سوئیچ
.Fl S
نیاز دارید تا در صورت لزوم به Ruby بگویید اسکریپت را جستجو کند (برای مدیریت فاصله‌های تعبیه‌شده و موارد مشابه). ساختاری بهتر از
.Li "$*"
استفاده از
.Li ${1+"$@"}
است، اما اگر اسکریپت توسط
.Xr csh 1
تفسیر شود، کار نخواهد کرد.
.Pp
.It Fl T Ns Op Ar level=1
بررسی‌های آلودگی داده (taint checks) را در سطح مشخص‌شده فعال می‌کند (پیش‌فرض: 1).
.Pp
.It Fl U
مقدار پیش‌فرض را برای کدبندی‌های داخلی
.Pf ( Li "Encoding.default_internal" )
بر روی UTF-8 تنظیم می‌کند.
.Pp
.It Fl W Ns Op Ar level=2
حالت پرگو (verbose) را در سطح مشخص‌شده فعال می‌کند، بدون اینکه پیام نسخه در ابتدا چاپ شود. سطح می‌تواند یکی از موارد زیر باشد:
.Bl -hang -offset indent
.It Sy 0
حالت پرگو «بی‌صدا» (silence) است. متغیر
.Li "$VERBOSE"
را به nil تنظیم می‌کند.
.Pp
.It Sy 1
حالت پرگو «متوسط» (medium) است. متغیر
.Li "$VERBOSE"
را به false تنظیم می‌کند.
.Pp
.It Sy 2 (پیش‌فرض)
حالت پرگو «پرگو» (verbose) است. متغیر
.Li "$VERBOSE"
را به true تنظیم می‌کند.
.Fl W Ns
2 مشابه
.Fl w
است.
.El
.Pp
.It Fl a
هنگامی که به همراه
.Fl n
یا
.Fl p
استفاده شود، حالت جداسازی خودکار (auto-split) را فعال می‌کند. در حالت جداسازی خودکار، Ruby دستور
.Dl $F = $_.split
را در ابتدای هر حلقه اجرا می‌کند.
.Pp
.It Fl -backtrace-limit Ns = Ns Ar num
حداکثر طول ردگیری پشته (backtrace) را به
.Ar num
خط محدود می‌کند (پیش‌فرض: 1-، به معنای نامحدود).
.Pp
.It Fl c
باعث می‌شود Ruby نحو اسکریپت را بررسی کرده و بدون اجرا خارج شود. در صورت عدم وجود خطای نحوی، Ruby عبارت
.Dq Syntax OK
را در خروجی استاندارد چاپ خواهد کرد.
.Pp
.It Fl d
.It Fl -debug
حالت اشکال‌زدایی را فعال می‌کند.
.Li "$DEBUG"
بر روی true تنظیم خواهد شد.
.Pp
.It Fl e Ar command
اسکریپت را از خط فرمان مشخص می‌کند و به Ruby می‌گوید بقیه آرگومان‌ها را برای یافتن نام فایل اسکریپت جستجو نکند.
.Pp
.It Fl h
.It Fl -help
خلاصه‌ای از گزینه‌ها را چاپ می‌کند.
.Pp
.It Fl i Ar extension
حالت ویرایش درجا (in-place-edit) را مشخص می‌کند. پسوند در صورت تعیین، به نام فایل قدیمی اضافه می‌شود تا یک نسخه پشتیبان ایجاد گردد. برای مثال:
.Bd -literal -offset indent
% echo matz > /tmp/junk
% cat /tmp/junk
matz
% ruby -p -i.bak -e '$_.upcase!' /tmp/junk
% cat /tmp/junk
MATZ
% cat /tmp/junk.bak
matz
.Ed
.Pp
.It Fl l
(حرف کوچک
.Dq ell . Ns
) پردازش خودکار انتهای خط را فعال می‌کند، به این معنی که ابتدا
.Li "$\e"
را به مقدار
.Li "$/"
تنظیم می‌کند، و ثانیاً هر خط خوانده‌شده را با استفاده از
.Li chomp!
کوتاه می‌کند.
.Pp
.It Fl n
باعث می‌شود Ruby یک حلقه پیرامون اسکریپت شما در نظر بگیرد، که سبب می‌شود مانند
.Nm sed
.Fl n
یا
.Nm awk
روی آرگومان‌های نام فایل تکرار کند.
.Bd -literal -offset indent
while gets
  ...
end
.Ed
.Pp
.It Fl p
تا حد زیادی مانند سوئیچ -n عمل می‌کند، اما مقدار متغیر
.Li "$_"
را در انتهای هر دور از حلقه چاپ می‌کند. برای مثال:
.Bd -literal -offset indent
% echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
MATZ
.Ed
.Pp
.It Fl r Ar library
باعث می‌شود Ruby کتابخانه را با استفاده از require بارگذاری کند. این گزینه هنگام استفاده از
.Fl n
یا
.Fl p
بسیار سودمند است.
.Pp
.It Fl s
تجزیه سوئیچ‌ها را برای سوئیچ‌های بعد از نام اسکریپت اما قبل از هرگونه آرگومان نام فایل (یا قبل از یک
.Fl - Ns
) فعال می‌کند. هر سوئیچی که در آنجا یافت شود از
.Li ARGV
حذف شده و متغیر متناظر در اسکریپت مقداردهی می‌شود. برای مثال:
.Bd -literal -offset indent
#! /usr/local/bin/ruby -s
# prints "true" if invoked with `-xyz' switch.
print "true\en" if $xyz
.Ed
.Pp
.It Fl v
حالت پرگو را فعال می‌کند. Ruby نسخه خود را در ابتدا چاپ کرده و متغیر
.Li "$VERBOSE"
را روی true تنظیم می‌کند. برخی متدها در صورتی که این متغیر true باشد، پیام‌های اضافی چاپ می‌کنند. اگر این سوئیچ داده شود و هیچ سوئیچ دیگری موجود نباشد، Ruby پس از چاپ نسخه خود خارج می‌شود.
.Pp
.It Fl w
حالت پرگو را بدون چاپ پیام نسخه در ابتدا فعال می‌کند. متغیر
.Li "$VERBOSE"
را روی true تنظیم می‌کند.
.Pp
.It Fl x Ns Op Ar directory
به Ruby اطلاع می‌دهد که اسکریپت درون یک پیام جاسازی شده است. محتوای زاید ابتدایی نادیده گرفته می‌شود تا به اولین خطی برسد که با
.Dq #!
آغاز شده و حاوی رشته
.Dq ruby
باشد. هر سوئیچ معناداری در آن خط اعمال خواهد شد. انتهای اسکریپت باید با یکی از موارد
.Li EOF ،
.Li "^D" ( Li "control-D" ) ،
.Li "^Z" ( Li "control-Z" )
یا کلمه رزروشده
.Li __END__
مشخص شود. اگر نام دایرکتوری مشخص شده باشد، Ruby پیش از اجرای اسکریپت به آن دایرکتوری تغییر مسیر می‌دهد.
.Pp
.It Fl y
.It Fl -yydebug
سازگاری این گزینه تضمین نشده است.
.Pp
حالت اشکال‌زدایی کامپایلر را فعال می‌کند. Ruby پیام‌های فراوانی از وضعیت داخلی را در طول کامپایل چاپ خواهد کرد. تنها زمانی این سوئیچ را مشخص کنید که قصد اشکال‌زدایی مفسر Ruby را داشته باشید.
.Pp
.It Fl -disable- Ns Ar FEATURE
.It Fl -enable- Ns Ar FEATURE
ویژگی
.Ar FEATURE
مشخص‌شده را غیرفعال (یا فعال) می‌کند.
.Bl -tag -width "--disable-rubyopt" -compact
.It Fl -disable-gems
.It Fl -enable-gems
کتابخانه‌های RubyGems را غیرفعال (یا فعال) می‌کند. به‌طور پیش‌فرض، Ruby آخرین نسخه از هر gem نصب‌شده را بارگذاری می‌کند. ثابت
.Li Gem
در صورت فعال بودن RubyGems برابر true و در غیر این صورت false است.
.Pp
.It Fl -disable-rubyopt
.It Fl -enable-rubyopt
متغیر محیطی
.Ev RUBYOPT
را نادیده می‌گیرد (یا در نظر می‌گیرد). به‌طور پیش‌فرض، Ruby این متغیر را در نظر می‌گیرد.
.Pp
.It Fl -disable-all
.It Fl -enable-all
تمام ویژگی‌ها را غیرفعال (یا فعال) می‌کند.
.Pp
.El
.Pp
.It Fl -dump Ns = Ns Ar target
تخلیه برخی اطلاعات.
.Pp
هدف مشخص‌شده را چاپ می‌کند.
.Ar target
می‌تواند یکی از موارد زیر باشد:
.Bl -hang -offset indent -width "version"
.It Sy version
چاپ توضیحات نسخه (مشابه
.Fl -version Ns
).
.It Sy usage
چاپ پیام راهنمای مختصر استفاده (مشابه
.Fl h Ns
).
.It Sy help
نمایش پیام راهنمای کامل (مشابه
.Fl -help Ns
).
.It Sy syntax
بررسی نحو (مشابه
.Fl c
.Fl -yydebug Ns
).
.Pp
.El
.Pp
یا یکی از موارد زیر که برای اشکال‌زدایی مفسر در نظر گرفته شده‌اند:
.Bl -hang -offset indent -width "parsetree"
.It Sy yydebug
فعال‌سازی حالت اشکال‌زدایی کامپایلر (مشابه
.Fl -yydebug Ns
).
.It Sy parsetree
چاپ نمایش متنی ساختار درخت نحو انتزاعی (AST) برنامه در Ruby.
.It Sy insns
چاپ فهرستی از دستورالعمل‌های بایت‌کد دی‌اسمبل شده.
.It Sy -optimize
غیرفعال‌سازی بهینه‌سازی‌های گوناگون برای چاپ فهرستی از دستورالعمل‌های بایت‌کد دی‌اسمبل شده.
.It Sy +error-tolerant
فعال‌سازی تجزیه خطاپذیر در صورت استفاده از yydebug یا parsetree.
.It Sy +comment
نشانه‌گذاری نمایش متنی AST برنامه با کد منبع مربوطه در Ruby.
.El
.Pp
.It Fl -verbose
حالت پرگو را بدون چاپ پیام نسخه در ابتدا فعال می‌کند. متغیر
.Li "$VERBOSE"
را روی true تنظیم می‌کند.
اگر این سوئیچ داده شود، و هیچ آرگومانی برای اسکریپت (فایل اسکریپت یا گزینه‌های
.Fl e Ns
) موجود نباشد، Ruby بلافاصله خارج می‌شود.
.Pp
.It Fl -crash-report Ns = Ns Ar template
الگوی نام مسیر را برای ذخیره گزارش خرابی تنظیم می‌کند. برای جزئیات به متغیر محیطی
.Ev RUBY_CRASH_REPORT
مراجعه کنید.
.El
.Pp
.Sh "محیط (ENVIRONMENT)"
.Bl -tag -width "RUBYSHELL" -compact
.It Ev RUBYLIB
فهرستی از دایرکتوری‌های جداشده با دونقطه (:) که به مسیر بارگذاری کتابخانه Ruby
.Pf ( Li "$:" )
اضافه می‌شوند. دایرکتوری‌های این متغیر محیطی پیش از مسیر بارگذاری استاندارد جستجو می‌شوند.
.Pp
به عنوان مثال:
.Dl RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
.Pp
.It Ev RUBYOPT
گزینه‌های اضافی Ruby.
.Pp
به عنوان مثال:
.Dl RUBYOPT="-w -Ke"
.Pp
توجه داشته باشید که RUBYOPT تنها می‌تواند شامل
.Fl d , Fl E , Fl I , Fl K , Fl r , Fl T , Fl U , Fl v , Fl w , Fl W, Fl -debug ,
.Fl -disable- Ns Ar FEATURE
و
.Fl -enable- Ns Ar FEATURE
باشد.
.Pp
.It Ev RUBYPATH
فهرستی از دایرکتوری‌های جداشده با دونقطه (:) که در صورت مشخص شدن پرچم
.Fl S ،
Ruby برای برنامه‌های Ruby در آن‌ها جستجو می‌کند. این متغیر بر متغیر محیطی
.Ev PATH
تقدم دارد.
.Pp
.It Ev RUBYSHELL
مسیر دستور پوسته سیستم. این متغیر محیطی تنها برای پلتفرم‌های mswin32، mingw32 و OS/2 فعال است. اگر این متغیر تعریف نشده باشد، Ruby به
.Ev COMSPEC
رجوع می‌کند.
.Pp
.It Ev RUBY_FREE_AT_EXIT
در صورت تنظیم، Ruby تلاش می‌کند تمام حافظه‌های تخصیص‌یافته به صورت پویا را آزاد کند.
معرفی‌شده در Ruby 3.3، پیش‌فرض: تنظیم‌نشده.
.Pp
.It Ev RUBY_IO_BUFFER_DEFAULT_SIZE
اندازه بافر پیش‌فرض سفارشی
.Li IO::Buffer .
.Pp
.It Ev RUBY_MAX_CPU
حداکثر تعداد رشته‌های بومی (native threads) استفاده‌شده توسط زمان‌بند M:N Threads.
معرفی‌شده در Ruby 3.3، پیش‌فرض: 8.
.Pp
.It Ev RUBY_MN_THREADS
در صورت تنظیم روی
.Li 1 ،
زمان‌بند رشته M:N بر روی Ractor اصلی فعال می‌شود.
معرفی‌شده در Ruby 3.3، پیش‌فرض: تنظیم‌نشده.
.Pp
.It Ev RUBY_PAGER
دستور صفحه‌بندی (pager) که برای گزینه
.Fl -help
استفاده خواهد شد.
معرفی‌شده در Ruby 3.0، پیش‌فرض: متغیر محیطی
.Ev PAGER .
.Pp
.It Ev RUBY_THREAD_TIMESLICE
برش زمانی پیش‌فرض رشته (thread quantum) را بر حسب میلی‌ثانیه تنظیم می‌کند.
معرفی‌شده در Ruby 3.4، پیش‌فرض: 100ms.
.Pp
.It Ev PATH
Ruby هنگام فراخوانی Kernel#system به متغیر محیطی
.Ev PATH
رجوع می‌کند.
.El
.Pp
و Ruby به برخی متغیرهای محیطی مرتبط با RubyGems وابسته است، مگر اینکه RubyGems غیرفعال شده باشد. راهنمای
.Xr gem 1
را مطابق زیر ببینید:
.Bd -literal -offset indent
% gem help
.Ed
.Pp
.Sh "محیط بازیافت حافظه (GC ENVIRONMENT)"
بازیافت حافظه (GC) در Ruby اشیاء را در خانه‌هایی (slots) با اندازه ثابت دنبال می‌کند، اما هر شیء ممکن است دارای تخصیص‌های حافظه کمکی باشد که توسط خانواده فراخوان‌های malloc در کتابخانه استاندارد C
.Pf ( Xr malloc 3 ،
.Xr calloc 3
و
.Xr realloc 3 )
مدیریت می‌شوند. در این مستندات، «heap» به هیپ اشیاء Ruby با خانه‌های اندازه ثابت اشاره دارد، در حالی که «malloc» به تخصیص‌های کمکی اشاره می‌کند که معمولاً «هیپ فرآیند» (process heap) نامیده می‌شوند.
بنابراین حداقل دو روش ممکن برای فعال شدن بازیافت حافظه وجود دارد:
.Bl -hang -offset indent
.It Sy 1
رسیدن به حد نصاب اشیاء.
.It Sy 2
رسیدن به حد نصاب malloc.
.Pp
.El
در Ruby 2.1، بازیافت حافظه نسلی (generational GC) معرفی شد و حد نصاب‌ها به نسل‌های جوان (young) و پیر (old) تقسیم شدند که دو روش دیگر را برای راه‌اندازی GC فراهم می‌کند:
.Bl -hang -offset indent
.It Sy 3
رسیدن به حد نصاب اشیای پیر.
.It Sy 4
رسیدن به حد نصاب malloc برای اشیای پیر.
.El
.Pp
در حال حاضر ۴ بخش ممکن وجود دارد که در آن‌ها بازیافت حافظه می‌تواند توسط متغیرهای محیطی زیر تنظیم دقیق شود:
.Bl -hang -compact -width "RUBY_GC_HEAP_n_INIT_SLOTS"
.Pp
.It Ev RUBY_GC_HEAP_ Ns Ar n Ns Ev _INIT_SLOTS
تخصیص اولیه خانه‌ها در یک هیپ معین. هیپ‌های موجود را می‌توان در کلیدهای
.Li GC.stat_heap
یافت.
.Ar n
یک عدد ده‌دهی بین 0 تا 4 است.
معرفی‌شده در Ruby 3.3.
.Pp
.It Ev RUBY_GC_HEAP_FREE_SLOTS
حداقل این تعداد خانه را پس از GC آماده نگه می‌دارد. اگر خانه‌های کافی وجود نداشته باشد، این تعداد خانه را تخصیص می‌دهد.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 4096.
.Pp
.It Ev RUBY_GC_HEAP_GROWTH_FACTOR
نرخ تخصیص خانه‌های هیپ را با این ضریب افزایش می‌دهد.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 1.8، حداقل: 1.0 (بدون رشد).
.Pp
.It Ev RUBY_GC_HEAP_GROWTH_MAX_SLOTS
نرخ تخصیص به این تعداد خانه محدود می‌شود، که از تخصیص بیش از حد به دلیل RUBY_GC_HEAP_GROWTH_FACTOR جلوگیری می‌کند.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 0 (بدون محدودیت).
.Pp
.It Ev RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR
یک GC کامل را زمانی اجرا می‌کند که تعداد اشیای پیر بیشتر از R * N باشد، که در آن R این ضریب و N تعداد اشیای پیر پس از آخرین GC کامل است.
معرفی‌شده در Ruby 2.1.1، پیش‌فرض: 2.0.
.Pp
.It Ev RUBY_GC_HEAP_REMEMBERED_WB_UNPROTECTED_OBJECTS_LIMIT_RATIO
برای محاسبه
.Li remembered_wb_unprotected_objects_limit
با استفاده از نسبتی از
.Li old_objects
به کار می‌رود.
معرفی‌شده در Ruby 3.3، پیش‌فرض: 0.1، حداقل: 0.0.
.It Ev RUBY_GC_MALLOC_LIMIT
حد نصاب اولیه تخصیص نسل جوان از خانواده malloc. بازیافت حافظه با رسیدن به این حد آغاز خواهد شد.
پیش‌فرض: 16MB.
.Pp
.It Ev RUBY_GC_MALLOC_LIMIT_MAX
حداکثر سقف تخصیص نسل جوان از malloc پیش از آغاز GC. از رشد بیش از حد malloc ناشی از RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR جلوگیری می‌کند.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 32MB.
.Pp
.It Ev RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR
سقف فراخوان‌های malloc نسل جوان را افزایش می‌دهد، که بسامد GC را کاهش داده اما رشد malloc را تا رسیدن به RUBY_GC_MALLOC_LIMIT_MAX افزایش می‌دهد.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 1.4، حداقل: 1.0 (بدون رشد).
.Pp
.It Ev RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO
هنگامی که تعداد خانه‌های آزاد کمتر از مقدار
.Li (total_slots * (این نسبت))
باشد، صفحه‌های اضافی تخصیص می‌دهد.
معرفی‌شده در Ruby 2.4، پیش‌فرض: 0.2، حداقل: 0.0، حداکثر: 1.0.
.Pp
.It Ev RUBY_GC_HEAP_FREE_SLOTS_MAX_RATIO
هنگامی که تعداد خانه‌های آزاد بیشتر از مقدار
.Li (total_slots * (این نسبت))
باشد، اجازه آزادسازی صفحه‌ها را می‌دهد.
معرفی‌شده در Ruby 2.4، پیش‌فرض: 0.4، حداقل:
.Li RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO ،
حداکثر: 1.0.
.Pp
.It Ev RUBY_GC_HEAP_FREE_SLOTS_GOAL_RATIO
خانه‌ها را برای برآورده کردن این فرمول تخصیص می‌دهد:
.Li free_slots = total_slots * goal_ratio
به عبارت دیگر،
.Li (total_slots * goal_ratio)
خانه آزاد آماده می‌کند. اگر این مقدار 0.0 باشد، مستقیماً از RUBY_GC_HEAP_GROWTH_FACTOR استفاده می‌شود.
معرفی‌شده در Ruby 2.4، پیش‌فرض: 0.65، حداقل:
.Li RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO ،
حداکثر:
.Li RUBY_GC_HEAP_FREE_SLOTS_MAX_RATIO .
.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT
حد نصاب اولیه تخصیص نسل پیر از malloc؛ با رسیدن به این حد، یک GC کامل آغاز می‌شود.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 16MB.
.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT_MAX
حداکثر سقف تخصیص نسل پیر از malloc پیش از آغاز یک GC کامل. از رشد بیش از حد malloc ناشی از RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR جلوگیری می‌کند.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 128MB.
.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR
سقف تخصیص malloc نسل پیر را افزایش می‌دهد، که بسامد GC کامل را کاهش داده اما رشد malloc را تا رسیدن به RUBY_GC_OLDMALLOC_LIMIT_MAX افزایش می‌دهد.
معرفی‌شده در Ruby 2.1، پیش‌فرض: 1.2، حداقل: 1.0 (بدون رشد).
.Pp
.It Ev RUBY_SHARED_FIBER_POOL_FREE_STACKS
در صورت تنظیم بر روی 1، پشته‌های فیبرهای به اشتراک‌گذاشته‌شده (pooled fibers) را آزاد می‌کند. در صورت تنظیم بر روی 0، پشته‌ها را آزاد نمی‌کند.
معرفی‌شده در Ruby 2.7، پیش‌فرض: 1 (بدون رشد).
.Pp
.El
.Sh "محیط اندازه پشته (STACK SIZE ENVIRONMENT)"
متغیرهای محیطی اندازه پشته وابسته به پیاده‌سازی هستند و ممکن است با نسخه‌های مختلف Ruby تغییر کنند. پشته ماشین مجازی (VM stack) برای کدهای خالص Ruby استفاده شده و توسط ماشین مجازی مدیریت می‌شود. پشته ماشین (Machine stack) توسط سیستم‌عامل استفاده می‌شود و کاربرد آن به افزونه‌های C و همچنین گزینه‌های کامپایلر C بستگی دارد. استفاده از مقادیر کمتر برای این متغیرها ممکن است به برنامه‌ها اجازه دهد فیبرها یا رشته‌های بیشتری را در حال اجرا نگه دارند؛ اما احتمال بروز استثناهای SystemStackError و خطاهای نقص بخش‌بندی (SIGSEGV) را افزایش می‌دهد. این متغیرهای محیطی از نسخه 2.0.0 Ruby در دسترس هستند. تمام مقادیر بر حسب بایت مشخص می‌شوند.
.Pp
.Bl -hang -compact -width "RUBY_THREAD_MACHINE_STACK_SIZE"
.It Ev RUBY_THREAD_VM_STACK_SIZE
اندازه پشته ماشین مجازی (VM) مورد استفاده در هنگام ایجاد رشته.
پیش‌فرض: 524288 (پردازنده ۳۲ بیتی) یا 1048575 (۶۴ بیتی).
.Pp
.It Ev RUBY_THREAD_MACHINE_STACK_SIZE
اندازه پشته ماشین مورد استفاده در هنگام ایجاد رشته.
پیش‌فرض: 524288 یا 1048575.
.Pp
.It Ev RUBY_FIBER_VM_STACK_SIZE
اندازه پشته ماشین مجازی مورد استفاده در هنگام ایجاد فیبر.
پیش‌فرض: 65536 یا 131072.
.Pp
.It Ev RUBY_FIBER_MACHINE_STACK_SIZE
اندازه پشته ماشین مورد استفاده در هنگام ایجاد فیبر.
پیش‌فرض: 262144 یا 524288.
.Pp
.El
.Sh "محیط گزارش خرابی (CRASH REPORT ENVIRONMENT)"
.Pp
.Bl -tag -compact -width "RUBY_CRASH_REPORT"
.It Ev RUBY_CRASH_REPORT
الگوی نام مسیر برای ذخیره گزارش خرابی.
پیش‌فرض: هیچ (none).
.El
.Ss "نام‌گذاری فایل‌های گزارش خرابی (Naming crash report files)"
الگو می‌تواند شامل مشخص‌کننده‌های
.Li \fB%\fP
باشد که هنگام ایجاد فایل گزارش خرابی با مقادیر زیر جایگزین می‌شوند:
.Pp
.Bl -hang -compact -width "%NNN"
.It Li \fB%%\fP
یک نویسه منفرد
.Li \fB%\fP .
.It Li \fB%e\fP
نام پایه (basename) فایل اجرایی.
.It Li \fB%E\fP
مسیر کامل فایل اجرایی، با اسلش‌های (\fB/\fP) جایگزین‌شده توسط علامت‌های تعجب (\fB!\fP).
.It Li \fB%f\fP
نام پایه برنامه،
.Li "$0" .
.It Li \fB%F\fP
مسیر کامل نام برنامه،
.Li "$0" ،
با اسلش‌های (\fB/\fP) جایگزین‌شده توسط علامت‌های تعجب (\fB!\fP).
.It Li \fB%p\fP
شناسه فرآیند (PID) فرآیند تخلیه‌شده.
.It Li \fB%t\fP
زمان تخلیه، بیان‌شده بر حسب ثانیه‌های سپری‌شده از مبدأ زمان یونیکس (Epoch)،
1970-01-01 00:00:00 +0000 (UTC).
.It Li \fB%NNN\fP
کد نویسه در مبنای هشت (اکتال).
.El
.Pp
یک نویسه منفرد
.Li \fB%\fP
در انتهای الگو از نام فایل خرابی حذف می‌شود، همان‌گونه که ترکیب یک
.Li \fB%\fP
با هر نویسه‌ای غیر از موارد فهرست‌شده در بالا نیز حذف می‌گردد. تمام نویسه‌های دیگر در الگو به بخش تحت‌اللفظی نام فایل خرابی تبدیل می‌شوند. الگو می‌تواند شامل نویسه‌های \(aq/\(aq باشد که به عنوان جداکننده نام دایرکتوری‌ها تفسیر می‌شوند.
.Ss "هدایت گزارش‌های خرابی با لوله به یک برنامه (Piping crash reports to a program)"
اگر نخستین نویسه این فایل نماد لوله (\fB|\fP) باشد، ادامه خط به عنوان خط فرمان یک برنامه (یا اسکریپت) برای اجرا تفسیر می‌شود.
.Pp
الگوی لوله پیش از بسط پارامترهای الگو، بر اساس فاصله‌ها به فهرستی از آرگومان‌ها تفکیک می‌شود.
.Sh "محیط متفرقه (MISC ENVIRONMENT)"
.Pp
.Bl -hang -compact -width "RUBY_TCP_NO_FAST_FALLBACK"
.It Ev RUBY_TCP_NO_FAST_FALLBACK
در صورت تنظیم بر روی
.Li 1 ،
قابلیت بازگشت سریع (fast fallback) را به‌طور پیش‌فرض در TCPSocket.new و Socket.tcp غیرفعال می‌کند. در صورت تنظیم بر روی
.Li 0
یا بدون مقدار رها شدن، قابلیت بازگشت سریع فعال خواهد بود.
معرفی‌شده در Ruby 3.4، پیش‌فرض: تنظیم‌نشده.
.El
.Sh "همچنین ببینید (SEE ALSO)"
.Bl -hang -compact -width "https://www.ruby-toolbox.com"
.It Lk https://www.ruby-lang.org
وب‌سایت رسمی.
.It Lk https://www.ruby-toolbox.com
کاتالوگ جامع کتابخانه‌های Ruby.
.El
.Pp
.Sh "گزارش باگ‌ها (BUGS)"
.Bl -bullet
.It
آسیب‌پذیری‌های امنیتی باید از طریق ایمیل به
.Mt security@ruby-lang.org
گزارش شوند. مشکلات گزارش‌شده پس از برطرف شدن منتشر خواهند شد.
.Pp
.It
سایر باگ‌ها و درخواست‌های قابلیت‌ها را می‌توان از طریق سیستم پیگیری مسائل Ruby
.Pq Lk https://bugs.ruby-lang.org
گزارش کرد. آسیب‌پذیری‌های امنیتی را از طریق این سیستم گزارش نکنید، چرا که آسیب‌پذیری‌ها را بلافاصله به‌صورت عمومی منتشر می‌کند.
.El
.Sh "نویسندگان (AUTHORS)"
Ruby توسط
.An Yukihiro Matsumoto Aq matz@netlab.jp
طراحی و پیاده‌سازی شده است.
.Pp
برای مشارکت‌کنندگان در Ruby به
.Aq Lk https://github.com/ruby/ruby/graphs/contributors
مراجعه کنید.