التابع 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) التابع الحر (IOX)، فيما يمثل ext_enc الترميز الخارجي التابع الحر IO ويمثل int_enc الترميز الداخلي.

وضعية الفتح الخاصة بالتابع الحر (IO Open Mode) ¶ ↑

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

"r"  Read-only, starts at beginning of file  (default mode).
"r+" Read-write, starts at beginning of file.
"w"  Write-only, truncates existing file
     to zero length or creates a new file for writing.
"w+" Read-write, truncates existing file to zero length
     or creates a new file for reading and writing.
"a"  Write-only, each write call appends data at end of file.
     Creates a new file for writing if file does not exist.
"a+" Read-write, each write call appends data at end of file.
     Creates a new file for reading and writing if file does
     not exist.‎

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

"b"  Binary file mode
     Suppresses EOL <-> CRLF conversion on Windows. And
     sets external encoding to ASCII-8BIT unless explicitly
     specified.
"t"  Text file mode‎

عندما تكون وضعية فتح (open mode) التابع الحر الأصلي (IO) هي القراءة فقط (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 غير حساس لحالة الأحرف، بحيث تكون "bom | utf-8" صالحة أيضًا.)

خيارات ¶ ↑

يمكن استخدام opt بدلاً من mode لتحسين قابلية القراءة. المفاتيح التالية مدعومة:

mode

مثل الوسيط mode

flags

يحدد رايات فتح الملف على هيئة عدد صحيح. في حال إعطاء الوسيط mode، فسيتم تحديد هذا الوسيط باستخدام عملية "أو الثنائية" (bitwise-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 للتحكم في التحويل بين الترميز الخارجي والترميز الداخلي.

مثال 1 ¶ ↑

الناتج:

مثال 2 ¶ ↑

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

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

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

أمثلة

مثال على استخدام التابع new‎:

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

انظر أيضا

• التابع foreach: ينفذ التابع foreach الكتلة المعطاة على كل سطر في منفذ مجرى د/خ المسمى، حيث يتم فصل الأسطر بواسطة sep.
• التابع open: عند عدم تمرير كتلة، فسيكون التابع IO.open مرادفاً للتابع ::new. أما في حال تمرير الكتلة البرمجية، فسيُمرّر إليها io (انظر فقرة البنية العامة) كوسيط، وسيتم إغلاق مجرى د/خ (IO) تلقائيًا عند إنهاء الكتلة. في هذه الحالة، سيعيد التابع ::open قيمة الكتلة.

مصادر

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