الصنف `IO` في روبي

الصنف IO هو أساس كل عمليات الإدخال والإخراج في روبي. مجرى الدخل/الخرج (I/O stream) قد يكون مزدوج الاتجاه (duplexed، أي في اتجاهين)، وبذلك قد يُستخدَم أكثر من مجرى واحد من مجاري نظام التشغيل.

الكثير من الأمثلة الواردة في في هذا القسم تستخدم الصنف File، وهو االصنف الفرعي (subclass) القياسي الوحيد للصنف IO، إذ يرتبط الصنفان ارتباطًا وثيقًا.

مثل الصنف File، فإنّ المكتبة Socket تشتق أصنافًا فرعيةً من الصنف IO (مثل TCPSocket أو UDPSocket).

يمكن أن ينشئ التابع Kernel.open كائنات من الصنف IO (أو File) من أنواع الوسائط التالية:

سلسلة نصية لتمثيل اسم ملف مناسب لنظام التشغيل المستخدم.
سلسلة نصية تبدأ بالمحرف "|" كناية عن عملية فرعية (subprocess). يتم استدعاء الجزء الذي يلي المحرف "|" من السلسلة النصية كعملية (process)؛ هذه العملية ستكون متصلة بقنوات الدخل/الخرج (د/خ) المناسبة.
إن كانت السلسلة النصية تساوي "‎|-‎"، فسيتم إنشاء نسخة (instance) أخرى من روبي كعملية فرعية.

يمكن فتح مجرى د/خ (IO) مع مختلف أوضاع الملفات (مثل وضع القراءة فقط [read-only] أو الكتابة فقط [write-only]) ووفق الترميزات المناسبة لأجل إجراء عمليات التحويل. انظر صفحة التابع new للتعرف على هذه الخيارات، وانظر صفحة Kernel.open لمزيد من التفاصيل حول مختلف تنسيقات الأوامر المذكورة أعلاه.

يمكن أيضًا استخدام التابع popen أو المكتبة Open3 أو التابع Process.spawn للتواصل مع العمليات الفرعية عبر مجرى د/خ.

ستُحول روبي أسماء المسارات بما يتوافق مع نظام التشغيل المستخدم إن أمكن. على سبيل المثال، في نظام ويندوز، سيُفتح اسم الملف "‎/gumby/ruby/test.rb" باعتباره "‎\gumby\ruby\test.rb".

عند تحديد اسم ملف بنمط ويندوز في سلسلة نصية، تذكر أن تهرِّب (escape) الخطوط المائلة العكسية مثل:

"C:\\gumby\\ruby\\test.rb"‎

سوف نستخدم في الأمثلة الموجودة في صفحات التوابع الخطوط المائلة للأمام على نمط اليونيكس؛ يمكن الحصول على المحرف الفاصل للمجلدات في المسارات الخاص بنظام التشغيل عبر الثابت File::ALT_SEPARATOR.

يوفر الثابت العام ARGF (يمكن الوصول إليه عبر ‎$<‎) مجرًى مشابهًا لمجرى د/خ (I/O)، والذي يسمح بالوصول إلى كافة الملفات المذكورة في سطر الأوامر (أو في المجرى STDIN في حال لم يذكر أي ملف). يمكن استخدام التابع ARGF.path وبديله ARGF.filename للوصول إلى اسم الملف الذي تتم قراءته حاليًا.

الملحقة io/console

توفر الملحقة io/console توابع للتفاعل مع وحدة التحكم (console). يمكن الوصول إلى وحدة التحكم (أو الطرفية) عبر التابع IO.console، أو من مجاري الدخل والخرج القياسية التي هي input و output و error.

استيراد io/console يؤدي إلى إضافة التوابع التالية:

IO::console
IO#raw
IO#raw!‎
IO#cooked
IO#cooked!‎
IO#getch
IO#echo=‎
IO#echo?‎
IO#noecho
IO#winsize
IO#winsize=‎
IO#iflush
IO#ioflush
IO#oflush

إليك المثال التالي حول استدعاء الملحقة io/console وإضافتها لاستعمال التابع winsize:

require 'io/console'
rows, columns = $stdout.winsize
puts "Your screen is #{columns} wide and #{rows} tall"‎

الثوابت

`EWOULDBLOCKWaitReadable`

اطلع على صفحة الصنف IO::EAGAINWaitReadable.

`EWOULDBLOCKWaitWritable`

اطلع على صفحة الصنف IO::EAGAINWaitWritable.

`SEEK_CUR`

يضبط موضع مؤشِّر عملية الدخل والخرج بدءًا من الموضع الحالي له.

`SEEK_DATA`

يضبط موضع مؤشِّر عملية الدخل والخرج إلى الموقع التالي الذي يحتوي على البيانات.

`SEEK_END`

يضبط موضع مؤشِّر عملية الدخل والخرج بدءًا من النهاية.

`SEEK_HOLE`

يضبط موضع مؤشِّر عملية الدخل والخرج إلى الفجوة التالية.

`SEEK_SET`

يضبط موضع مؤشِّر عملية الدخل والخرج بدءًا من البداية.

توابع الصنف العامة

`binread`

يفتح الملف ثم يحرِّك موضع المؤشر بمقدار محدد (في حال إعطائه) ثم يجلب جميع محتوى الملف بدءًا من موضع المؤشر وحتى نهاية الملف أو يجلب حجم محدَّد من البيانات.

`binwrite`

يشبه التابع write باستثناء أنه يفتح الملف في الوضع الثنائي (binary mode) وبالترميز ASCII-8BIT.

`copy_stream`

ينسخ بيانات من مجرى إلى مجرى آخر.

`for_fd`

يعد مرادفًا للتابع new.

`foreach`

ينفذ الكتلة المعطاة على كل سطر في منفذ مجرى د/خ المسمى.

`new`

ينشئ كائنًا جديدًا من النوع IO.

`open`

يشبه التابعَ new تمامًا عند استدعائه دون كتلة، أو يُمرّر الكائن IO الذي جرى إنشاؤه كوسيط إلى الكتلة المعطاة ثم يعيد الناتج الذي تعيده الكتلة.

`pipe`

ينشئ زوجًا من طرفي أنبوب (pipe endpoints) متصلين ببعضهما بعضًا ثم يعيدهما على هيئة مصفوفة من الكائنات IO.

`popen`

ينفذ الأمر المعطى كعملية فرعية (subprocess) مع توصيل المجرَيَين القياسيين للدخل والخرج للعملية الفرعية مع المجرى IO المُعاد.

`read`

يقرأ ملفًا محددًا بعد فتحه ثم يغلقه قبل إعادة الناتج.

`readlines`

يقرأ ملفًا بأكمله سطرًا سطرًا ثم يعيد تلك الأسطر في مصفوفة.

`select`

يستدعي استدعاء النظام select(2)‎. ويراقب المصفوفة المعطاة المكونة من مجاري د/خ (كائنات IO)، وينتظر حتى يكون واحد أو أكثر من تلك المجاري جاهزًا للقراءة، وجاهزًا للكتابة، ويكون له استثناءات معلقة (pending exceptions) على التوالي، ثم يعيد مصفوفة مؤلفة من مصفوفات مكونة من تلك المجاري.

`sysopen`

يفتح الملف الموجود في المسار المحدد، ثم يعيد واصف الملف الأساسي كعدد صحيح.

`try_convert`

يحاول تحويل الكائن المُمرَّر إليه إلى مجرى د/خ باستخدام التابع to_io.

`write`

يفتح ملفًا محدَّدًا ويكتب فيه السلسلة النصية المُمرَّرة إليه ثم يغلقه ويعيد عدد البايتات التي كتبها.

توابع النسخة العامة (Public Instance Methods)

‎`<<‎`

يكتب كائنًا في المجرى IO المعطى.

`advise`

يعلن عن نية الوصول إلى بيانات الملف الحالي وفق نمط محدد.

`autoclose`

يُعيّن عند استدعائه بالشكل autoclose = bool قيمة راية الإغلاق التلقائي (auto-close flag) إلى القيمة bool المنطقية.

`autoclose?‎`

يتحقق إن كان واصف الملف الأساسي لمجرى معين سيُغلق تلقائيًا عند الانتهاء منه.

`binmode`

يجعل مجرى د/خ في الوضع الثنائي (binary mode).

`binmode?‎`

يتحقق إن كان مجرى د/خ في الوضع الثنائي (binary mode).

`bytes`

يعد اسمًا بديلًا مهملًا للتابع each_byte.

`chars`

يعد اسمًا بديلًا مهملًا للتابع each_char.

`close`

يغلق المجرى الذي استدعي معه ويرسل (flushes) أي كتابات مُعلّقة إلى نظام التشغيل.

`close_on_exec‎`

يعين عند استدعائه بالشكل close_on_exec = bool قيمة الراية close-on-exec إلى القيمة bool.

`close_on_exec?‎`

يتحقق إن كانت الراية close-on-exec الخاصة بالمجرى الذي استدعي معه مضبوطة إلى القيمة true.

`close_read`

يغلق طرف القراءة الخاص بمجرى د/خ مزدوج (duplex).

`close_write`

يغلق طرف الكتابة الخاص بمجرى د/خ مزدوج (duplex).

`closed?‎`

يتحقق إن كان مجرى د/خ مغلقًا تمامًا.

`codepoints`

يعدُّ اسمًا بديلًا مهملًا للتابع each_codepoint.

`each`

ينفذ الكتلة المعطاة على كل سطر في المجرى الذي استُدعي معه.

`each_byte`

يستدعي الكتلة المعطاة على كل بايت (0..255) في المجرى الذي استدعي معه.

`each_char`

يستدعي الكتلة المعطاة على كل محرف في المجرى الذي استدعي معه.

`each_codepoint`

يمرر كل عدد من الأعداد الترتيبية (Integer ordinal) لكل محرف من المحارف الموجودة في المجرى الذي استدعي معه إلى الكتلة المعطاة.

`each_line`

ينفذ الكتلة المعطاة على كل سطر في المجرى الذي استدعي معه.

`eof`

يتحقق إن وصل المجرى الذي استدعي معه إلى نهاية الملف.

`eof?‎`

يتحقق إن وصل المجرى الذي استدعي معه إلى نهاية الملف.

`external_encoding`

يُعيد الكائن Encoding الذي يمثل ترميز الملف للمجرى الذي استدعي معه.

`fcntl`

يوفر آلية لإصدار أوامر منخفضة المستوى للتحكم في أو الاستعلام عن مجاري د/خالموجهة بالملفات (file-oriented I/O).

`fdatasync`

يكتب مباشرةً جميع البيانات المخزنة في مجرى د/خ على القرص.

`fileno`

يُعيد عددًا صحيحًا يمثل واصف الملف الرقمي للمجرى الذي استدعي معه.

`flush`

ينقل أي بيانات مخزَّنة في المجرى الذي استدعي معه إلى نظام التشغيل.

`fsync`

يكتب مباشرةً جميع البيانات المخزنة في المجرى الذي استدعي معه على القرص.

`getbyte`

يجلب البايت التالي من المجرى الذي استدعي معه.

`getc`

يجلب محرفًا واحدًا من المجرى الذي استدعي معه.

`gets`

يجلب السطر التالي من المجرى الذي استدعي معه.

`inspect`

يُعيد سلسلة نصية تصف المجرى الذي استُدعي معه.

`internal_encoding`

يعيد الترميز الخاص بالسلسلة النصية الداخلية في حال تحديد التحويل.

`ioctl`

يوفر آلية لإصدار أوامر منخفضة المستوى للتحكم في أو الاستعلام عن أجهزة مجاري د/خ.

`isatty`

يتحقق إن كان المجرى الذي استدعي معه مربوطًا بجهاز طرفي (tty).

`lineno`

يعيد رقم السطر الحالي في المجرى الذي استدعي معه. يجب أن يكون المجرى مفتوحًا في وضعية القراءة.

`lineno=‎`

يعيّن عند استدعاءه بالشكل lineno = integer رقم السطر الحالي يدويًا إلى القيمة integer.

`lines`

مرادف مُتجاوز للتابع each_line.

`pid`

يعيد معرف العملية (PID) الخاص بالعملية الفرعية (child process) المرتبطة بالمجرى الذي استدعي معه.

`pos`

يُعيد موضع المؤشر الحالي بدءًا من بداية الملف (بالبايت) للمجرى الذي استدعي معه.

`pos=‎`

يحرِّك عند استدعائه بالشكل pos = integer إلى موضع المؤشر الحالي إلى الموضع integer (بالبايت) للمجرى الذي استدعي معه.

`pread`

يقرأ من المجرى الذي استدعي معه عددًا محدَّدًا من البايتات باستخدام استدعاء النظام pread، ثم يُعيدها كسلسلة نصية من غير تعديل إزاحة (offset) الواصف الأساسي.

`print`

يكتب الكائن (أو الكائنات) المُمرَّرة إليه في المجرى الذي استدعي معه ثم يُعيد القيمة nil.

`printf`

ينسق الكائنات المُمرَّرة إليه ثم يكتبها في المجرى الذي استدعي معه.

putc

إن كان الوسيط المعطى obj عددًا، فسيكتب التابع putc الحرف الذي رمزه هو البايت الأقل دلالة (least-significant byte) فيobj. أما إن كان obj سلسلة نصية، فسيكتب أول حرف من obj في مجرى د/خ. خلاف ذلك، سيُطلق الاستثناء TypeError.