التابع new‎ الخاص بالصنف IO في روبي

يُعيد التابع new كائنًا جديدًا من النوع IO انطلاقا من واصف الملف (file descriptor) المعطى fd (انظر فقرة البنية العامة) ووفق الوضع mode. يمكن استخدام الوسيط opt لتحديد أجزاء من الوضع mode بطريقة أكثر قابلية للقراءة. انظر أيضًا صفحتي sysopen و for_fd.

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

وضع الفتح (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 Open Mode)

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

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

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

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

عندما تكون وضعية فتح (open mode) مجرى د/خ الأصلي هي القراءة فقط (read only)، فلن يكون بالإمكان تغيير الوضع لجعله قابلا للكتابة. وبالمثل، لا يمكن تغيير وضعية الفتح من الكتابة إلى القراءة فقط.

عند محاولة إجراء مثل هذا التغيير، سيُطلق خطأ في مواقع مختلفة بحسب للنظام المستخدم.

ترميز مجرى د/خ (IO Encoding)

عند تحديد الترميز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-set غير حساس لحالة الأحرف، ما يجعل "bom | utf-8" صالحة أيضًا.)

خيارات

يمكن استخدام الوسيط opt بدلاً من mode لأجل مقروئية أفضل.

المفاتيح التالية مدعومة:

• mode: مثل الوسيط mode

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

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

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

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

المعاملات

fd‎

واصف الملف

mode‎

الوضعية

opt‎

خيارات

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

يُعيد التابع new كائنًا جديدًا من النوع IO.

أمثلة

المثال الأول

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

الناتج:

Hello
World

المثال الثاني

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: عند عدم تمرير كتلة، فسيكون التابع IO.open مرادفاً للتابع new.

مصادر

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