التابع `IO.new‎` في روبي

ينشئ التابع new كائنًا جديدًا من النوع IO انطلاقًا من واصف الملف (file descriptor) ووضع الفتح الممرَّرين إليه.

يُستدعَى التابع new عبر العديد من توابع الفتح الخاصة بالصنفين File و IO، مثل open و Kernel.open و File.open.

البنية العامة

new(fd [, mode] [, opt])→ io‎

المعاملات

`fd‎`

واصف الملف المراد فتحه.

`mode‎`

وضع الفتح الذي يحدد الكيفية والغرض من فتح الملف ذي الواصف fd.

وضع الفتح (Open Mode)

إن كان المعامل mode عددًا صحيحًا، فيجب أن يكون مزيجًا من الأوضاع المعرفة في File::Constants‏ (مثل File::RDONLY، أو File::WRONLY|File::CREAT). انظر صفحة open(2)‎ لمزيد من المعلومات.

إن كان mode سلسلة نصية، فيجب أن يكون وفق أحد الصيغ التالية:

fmode
fmode ":" ext_enc
fmode ":" ext_enc ":" int_enc
fmode ":" "BOM|UTF-*"‎

fmode هو سلسلة نصية تمثل وضعية فتح (open mode) المجرى IO، فيما يمثل ext_enc الترميز الخارجي للمجرى، ويمثل int_enc الترميز الداخلي.

وضعية الفتح الخاصة `IO`

تتيح روبي أوضاع الفتح التالية:

"r": القراءة فقط، بدءًا من بداية الملف (الوضع الافتراضي).
"+r": القراءة والكتابة، بدءًا من بداية الملف.
"w": الكتابة فقط مع إنشاء واحد جديد للكتابة فيه. ستُمسَح محتويات الملف إن كان موجودًا مسبقًا.
"w+‎": الكتابة والقراءة مع إنشاء واحد جديد للكتابة فيه والقراءة منه. ستُمسَح محتويات الملف إن كان موجودًا مسبقًا.
"a": الكتابة فقط مع إنشاء ملف جديد لأجل الكتابة إن لم يكن موجودًا؛ كل عملية كتابة ستضيف بيانات إلى نهاية الملف.
"a+‎": الكتابة والقراءة مع إنشاء ملف جديد لأجل الكتابة إن لم يكن موجودًا؛ كل عملية كتابة ستضيف بيانات إلى نهاية الملف.

يجب استخدام الأوضاع التالية بشكل منفصل، بالإضافة إلى واحد أو أكثر من الأوضاع التي ذُكرت آنفًا:

"b": الوضع الثنائي (Binary file mode). يمنع تحويل المحارف EOL <-> CRLF في نظام ويندوز. ويعين الترميز الخارجي إلى القيمة ASCII-8BIT، إلا إن حُدد ترميز آخر.
"t": الوضع النصي (Text file mode).

ملاحظة: عندما يكون وضع فتح المجرى الأصلي هو القراءة فقط (read only)، فلن يكون بالإمكان تغيير الوضع لجعله قابلًا للكتابة. وبالمثل، لا يمكن تغيير وضع الفتح من الكتابة إلى القراءة فقط. عند محاولة إجراء مثل هذا التغيير، سيُطلق خطأ في مواقع مختلفة بحسب للنظام المستخدم.

ترميز المجرى `IO`

عند تحديد الترميز ext_enc، سيتم وسم السلاسل النصية بذلك الترميز عند القراءة، وستُحوّل السلاسل النصية المُخرجة إلى الترميز المحدد عند الكتابة.

عند تحديد الترميزين ext_enc و int_enc سيتم تحويل السلاسل النصية المقروءة من ext_enc إلى int_enc عند الإدخال، كما سيتم تحويل السلاسل النصية المكتوبة من int_enc إلى ext_enc عند الإخراج. راجع صفحة Encoding لمزيد من التفاصيل حول تحويل ترميز المدخلات والمخرجات.

في حال استخدام أحد الترميزات "BOM | UTF-8" أو "BOM | UTF-16LE" أو "BOM | UTF16-BE"، ستتحقق روبي من BOM لترميز اليونيكود في مستند الإدخال لأجل تحديد الترميز بشكل صحيح. بالنسبة للترميز UTF-16، يجب أن تكون وضعية فتح الملف ثنائية (binary). آنذاك، يُحذف BOM، ويُستخدم الترميز الخارجي المُستنتَج من BOM. أما عند عدم وجود BOM، فسيتم استخدام ترميز اليونيكود المعطى باعتباره الترميز الخارجي ext_enc. (خيار ضبط الترميز مع BOM غير حساس لحالة الأحرف، ما يجعل "bom | utf-8" صالحًا أيضًا.)

`opt‎`

يمكن استخدام هذا المعامل لتحديد أجزاء من الوضع mode بطريقة أكثر قابلية للقراءة.

المفاتيح التالية متاحة لاستعمالها مع هذا المعامل:

mode:: مثل المعامل mode.

flags:: يحدد رايات فتح الملف على هيئة عدد صحيح. في حال إعطاء المعامل mode، فسيتم جمع هذا المعامل مع المعامل mode باستخدام العملية OR الثنائية.
external_encoding: الترميز الخارجي للمجرى IO.
internal_encoding: الترميز الداخلي للمجرى IO. العلامة "-" هي مرادف للترميز الداخلي الافتراضي. إن كانت قيمة هذا المفتاح تساوي nil، فلن يحدث أي تحويل.
encoding: يحدد الترميزين الخارجي والداخلي وفقًا للشكل "extern:intern".
textmode: إن كانت القيمة قيمةً صحيحةً (truth value)، فسيكون مثل الوضع "t" في المعامل mode.
binmode: إن كانت القيمة قيمةً صحيحةً (truth value)، فسيكون مثل الوضع "b" في المعامل mode.
autoclose: إن كانت قيمته تساوي false، فسيبقى fd مفتوحًا بعد إنهاء المجرى IO.

أيضًا، يمكن أن يكون للمعامل opt نفس مفاتيح التابع String.encode للتحكم في التحويل بين الترميز الخارجي والترميز الداخلي.

القيمة المعادة

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

أمثلة

مثال على استعمال التابع new بأبسط شكل له:

fd = IO.sysopen("/dev/tty", "w")
a = IO.new(fd,"w")
$stderr.puts "Hello"
a.puts "World"‎

الناتج:

Hello
World

مثال على استعمال التابع new مع تحديد المعامل mode والمعامل opt:

require 'fcntl'

fd = STDERR.fcntl(Fcntl::F_DUPFD)
io = IO.new(fd, mode: 'w:UTF-16LE', cr_newline: true)
io.puts "Hello, World!"

fd = STDERR.fcntl(Fcntl::F_DUPFD)
io = IO.new(fd, mode: 'w', cr_newline: true,
            external_encoding: Encoding::UTF_16LE)
io.puts "Hello, World!"

كلا المثالين أعلاه يطبعان "Hello, World!‎" وفق الترميز UTF-16LE في مجرى الخطأ القياسي، مع تحويل المحرف EOL الذي تم إنشاؤها من قبل puts إلى المحرف CR.

انظر أيضًا

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

مصادر

قسم التابع new‎ في الصنف IO‎ في توثيق روبي الرسمي.