الصنف `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

يحاول تحويل الوسيط المعطى إلى مجرى د/خ

write

يفتح الملف، ويتموضع اختياريا عند الإزاحة offset المعطاة

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

‎ <<‎

مجرى الإخراج النصي

advise

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

autoclose=

يُعيّن قيمة راية الإغلاق التلقائي.

autoclose?‎

يُعيد القيمة true إن كان واصف الملف الأساسي لمجرى د/خ سيُغله تلقائياً عند الانتهاء منه، وإلا سيُعيد false.

binmode

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

binmode?‎

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

bytes

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

chars

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

close

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

close_on_exec=‎

يعين الراية close-on-exec.

close_on_exec?‎

يُعيد القيمة true إن كانت الراية close_on_exec الخاصة بمجرى د/خ تساوي true.

close_read

يغلق طرف القراءة الخاص بمجرى مجرى د/خ

close_write

يغلق طرف الكتابة الخاص بمجرى د/خ

closed?‎

يعيد القيمة true ان كان مجرى د/خ مغلقًا

codepoints

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

each

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

each_byte

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

each_char

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

each_codepoint

ينفذ التابع الكتلة المعطاة، مع تمرير الرمز العددي (Integer ordinal) لكل حرف من الحروف الموجودة في مجرى د/خ، حيث يمرر رمز اليونيكود (codepoint) كوسيط.

each_line

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

eof

يُعيد القيمة true إن كان مجرى د/خ في نهاية الملف،

eof?‎

يُعيد القيمة true إن كان مجرى د/خ في نهاية الملف،

external_encoding

يُعيد الترميز الخاص بالملف.

fcntl

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

fdatasync

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

fileno

يُعيد عددا صحيحا يمثل واصف الملف الرقمي لمجرى د/خ

flush

ينقل (Flushes) أي بيانات مخزنة في مجرى د/خ إلى نظام التشغيل

fsync

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

getbyte

يحصل على البايت (0..255) التالي من مجرى د/خ . ويُعيد nil إن استُدعي عند نهاية الملف.

getc

يقرأ سلسلة نصية مُؤلفة من حرف واحد من مجرى د/خ. ويُعيد nil إن استُدعي عند نهاية الملف.

gets

يقرأ "السطر" الموالي من مجرى د/خ.

inspect

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

internal_encoding

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

ioctl

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

isatty

يُعيد القيمة true إن كان مجرى د/خ مربوطا بجهاز طرفي (tty)، أو يعيد false خلاف ذلك.

lineno

يعيد رقم السطر الحالي في مجرى د/خ.

lineno=‎

يعيّن يدويًا رقم السطر الحالي ويعطيه القيمة المحددة.

lines

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

pid

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

pos

يُعيد الإزاحة (offset) الحالية (بالبايت) في مجرى د/خ.

pos=‎

يسعى إلى التموضع عند الإزاحة المحددة (بالبايت) في مجرى د/خ

pread

يقرأ maxlen بايت من مجرى د/خ

print

يكتب الكائن(ات) المعطاة في مجرى د/خ. ثم يُعيد nil.

printf

ينسق ويكتب في مجرى د/خ،

putc

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