الفرق بين المراجعتين ل"Ruby/IO/new"
اذهب إلى التنقل
اذهب إلى البحث
وضعية الفتح الخاصة
ترميز المجرى
جميل-بيلوني (نقاش | مساهمات) ط (مراجعة وتدقيق.) |
|||
| سطر 1: | سطر 1: | ||
| − | <noinclude>{{DISPLAYTITLE: التابع <code>new | + | <noinclude>{{DISPLAYTITLE: التابع <code>IO.new</code> في روبي}}</noinclude> |
[[تصنيف: Ruby]] | [[تصنيف: Ruby]] | ||
[[تصنيف: Ruby Method]] | [[تصنيف: Ruby Method]] | ||
[[تصنيف: Ruby IO]] | [[تصنيف: Ruby IO]] | ||
| − | + | ينشئ التابع <code>new</code> كائنًا جديدًا من النوع <code>[[Ruby/IO|IO]]</code> انطلاقًا من واصف الملف (file descriptor) ووضع الفتح الممرَّرين إليه. | |
| − | + | يُستدعَى التابع <code>new</code> عبر العديد من توابع الفتح الخاصة بالصنفين <code>[[Ruby/File|File]]</code> و <code>[[Ruby/IO|IO]]</code>، مثل <code>[[Ruby/IO/open|open]]</code> و <code>[[Ruby/Kernel/open|Kernel.open]]</code> و <code>[[Ruby/File/open|File.open]]</code>. | |
| + | ==البنية العامة== | ||
| + | <syntaxhighlight lang="ruby">new(fd [, mode] [, opt])→ io</syntaxhighlight> | ||
| + | ==المعاملات== | ||
| + | ===<code>fd</code>=== | ||
| + | واصف الملف المراد فتحه. | ||
| + | |||
| + | ===<code>mode</code>=== | ||
| + | وضع الفتح الذي يحدد الكيفية والغرض من فتح الملف ذي الواصف <code>fd</code>. | ||
| − | == وضع الفتح (Open Mode) == | + | ==== وضع الفتح (Open Mode) ==== |
| − | إن كان | + | إن كان المعامل <code>mode</code> عددًا صحيحًا، فيجب أن يكون مزيجًا من الأوضاع المعرفة في <code>[[Ruby/File::Constants|File::Constants]]</code> (مثل <code>File::RDONLY</code>، أو <code>File::WRONLY|File::CREAT</code>). انظر صفحة <code>open(2)</code> لمزيد من المعلومات. |
إن كان <code>mode</code> [[Ruby/String|سلسلة نصية]]، فيجب أن يكون وفق أحد الصيغ التالية:<syntaxhighlight lang="ruby">fmode | إن كان <code>mode</code> [[Ruby/String|سلسلة نصية]]، فيجب أن يكون وفق أحد الصيغ التالية:<syntaxhighlight lang="ruby">fmode | ||
fmode ":" ext_enc | fmode ":" ext_enc | ||
fmode ":" ext_enc ":" int_enc | fmode ":" ext_enc ":" int_enc | ||
| − | fmode ":" "BOM|UTF-*"</syntaxhighlight><code>fmode</code> هو سلسلة نصية تمثل وضعية فتح (open mode) | + | fmode ":" "BOM|UTF-*"</syntaxhighlight><code>fmode</code> هو سلسلة نصية تمثل وضعية فتح (open mode) المجرى <code>[[Ruby/IO|IO]]</code>، فيما يمثل <code>ext_enc</code> الترميز الخارجي للمجرى، ويمثل <code>int_enc</code> الترميز الداخلي. |
| − | == وضعية الفتح الخاصة | + | ==== وضعية الفتح الخاصة <code rel="mw:WikiLink" href="./Ruby/IO" title="Ruby/IO">[[Ruby/IO|IO]]</code> ==== |
| − | تتيح روبي | + | تتيح روبي أوضاع الفتح التالية: |
| − | * "<code>r</code>": | + | * "<code>r</code>": القراءة فقط، بدءًا من بداية الملف (الوضع الافتراضي). |
* "<code>+r</code>": القراءة والكتابة، بدءًا من بداية الملف. | * "<code>+r</code>": القراءة والكتابة، بدءًا من بداية الملف. | ||
| − | * "<code>w</code>": الكتابة | + | * "<code>w</code>": الكتابة فقط مع إنشاء واحد جديد للكتابة فيه. ستُمسَح محتويات الملف إن كان موجودًا مسبقًا. |
| − | * "<code>w+</code>": الكتابة | + | * "<code>w+</code>": الكتابة والقراءة مع إنشاء واحد جديد للكتابة فيه والقراءة منه. ستُمسَح محتويات الملف إن كان موجودًا مسبقًا. |
| − | * "<code>a</code>": | + | * "<code>a</code>": الكتابة فقط مع إنشاء ملف جديد لأجل الكتابة إن لم يكن موجودًا؛ كل عملية كتابة ستضيف بيانات إلى نهاية الملف. |
| − | * "<code>a+</code>": الكتابة | + | * "<code>a+</code>": الكتابة والقراءة مع إنشاء ملف جديد لأجل الكتابة إن لم يكن موجودًا؛ كل عملية كتابة ستضيف بيانات إلى نهاية الملف. |
| − | يجب استخدام الأوضاع التالية بشكل منفصل، بالإضافة إلى واحد أو أكثر من الأوضاع | + | يجب استخدام الأوضاع التالية بشكل منفصل، بالإضافة إلى واحد أو أكثر من الأوضاع التي ذُكرت آنفًا: |
| − | * "<code>b</code>": الوضع الثنائي (Binary file mode). يمنع تحويل المحارف <code>EOL</code> <-> <code>CRLF</code> في نظام ويندوز. ويعين الترميز الخارجي | + | * "<code>b</code>": الوضع الثنائي (Binary file mode). يمنع تحويل المحارف <code>EOL</code> <-> <code>CRLF</code> في نظام ويندوز. ويعين الترميز الخارجي إلى القيمة ASCII-8BIT، إلا إن حُدد ترميز آخر. |
| − | * "t": الوضع النصي (Text file mode). | + | * "<code>t</code>": الوضع النصي (Text file mode). |
| − | عندما | + | '''ملاحظة''': عندما يكون وضع فتح المجرى الأصلي هو القراءة فقط (read only)، فلن يكون بالإمكان تغيير الوضع لجعله قابلًا للكتابة. وبالمثل، لا يمكن تغيير وضع الفتح من الكتابة إلى القراءة فقط. عند محاولة إجراء مثل هذا التغيير، سيُطلق خطأ في مواقع مختلفة بحسب للنظام المستخدم. |
| − | عند | + | ==== ترميز المجرى <code rel="mw:WikiLink" href="./Ruby/IO" title="Ruby/IO">[[Ruby/IO|IO]]</code> ==== |
| + | عند تحديد الترميز <code>ext_enc</code>، سيتم وسم [[Ruby/String|السلاسل النصية]] بذلك الترميز عند القراءة، وستُحوّل [[Ruby/String|السلاسل النصية]] المُخرجة إلى الترميز المحدد عند الكتابة. | ||
| − | + | عند تحديد الترميزين <code>ext_enc</code> و <code>int_enc</code> سيتم تحويل [[Ruby/String|السلاسل النصية]] المقروءة من <code>ext_enc</code> إلى <code>int_enc</code> عند الإدخال، كما سيتم تحويل [[Ruby/String|السلاسل النصية]] المكتوبة من <code>int_enc</code> إلى <code>ext_enc</code> عند الإخراج. راجع صفحة <code>[[Ruby/Encoding|Encoding]]</code> لمزيد من التفاصيل حول تحويل ترميز المدخلات والمخرجات. | |
| − | |||
| − | + | في حال استخدام أحد الترميزات "<code>BOM | UTF-8</code>" أو "<code>BOM | UTF-16LE</code>" أو "<code>BOM | UTF16-BE</code>"، ستتحقق روبي من <code>BOM</code> لترميز اليونيكود في مستند الإدخال لأجل تحديد الترميز بشكل صحيح. بالنسبة للترميز <code>UTF-16</code>، يجب أن تكون وضعية فتح الملف ثنائية (binary). آنذاك، يُحذف <code>BOM</code>، ويُستخدم الترميز الخارجي المُستنتَج من <code>BOM</code>. أما عند عدم وجود <code>BOM</code>، فسيتم استخدام ترميز اليونيكود المعطى باعتباره الترميز الخارجي <code>ext_enc</code>. (خيار ضبط الترميز مع BOM غير حساس لحالة الأحرف، ما يجعل "<code>bom | utf-8</code>" صالحًا أيضًا.) | |
| − | + | ===<code>opt</code>=== | |
| + | يمكن استخدام هذا المعامل لتحديد أجزاء من الوضع <code>mode</code> بطريقة أكثر قابلية للقراءة. | ||
| − | + | المفاتيح التالية متاحة لاستعمالها مع هذا المعامل: | |
| − | + | * <code>mode:</code>: مثل المعامل <code>mode</code>. | |
| − | + | * <code>flags:</code>: يحدد رايات فتح الملف على هيئة عدد صحيح. في حال إعطاء المعامل <code>mode</code>، فسيتم جمع هذا المعامل مع المعامل <code>mode</code> باستخدام العملية OR الثنائية. | |
| − | * <code> | + | * <code>external_encoding</code>: الترميز الخارجي للمجرى <code>[[Ruby/IO|IO]]</code>. |
| − | + | * <code>internal_encoding</code>: الترميز الداخلي للمجرى <code>[[Ruby/IO|IO]]</code>. العلامة "<code>-</code>" هي مرادف للترميز الداخلي الافتراضي. إن كانت قيمة هذا المفتاح تساوي <code>nil</code>، فلن يحدث أي تحويل. | |
| − | + | * <code>encoding</code>: يحدد الترميزين الخارجي والداخلي وفقًا للشكل "<code>extern:intern</code>". | |
| − | * <code>external_encoding</code>: الترميز الخارجي | + | * <code>textmode</code>: إن كانت القيمة قيمةً صحيحةً (truth value)، فسيكون مثل الوضع "<code>t</code>" في المعامل <code>mode</code>. |
| − | * <code>internal_encoding</code>: الترميز الداخلي | + | * <code>binmode</code>: إن كانت القيمة قيمةً صحيحةً (truth value)، فسيكون مثل الوضع "<code>b</code>" في المعامل <code>mode</code>. |
| − | * <code>encoding</code>: يحدد الترميزين الخارجي والداخلي | + | * <code>autoclose</code>: إن كانت قيمته تساوي <code>false</code>، فسيبقى <code>fd</code> مفتوحًا بعد إنهاء المجرى <code>[[Ruby/IO|IO]]</code>. |
| − | * <code>textmode</code>: إن كانت القيمة | + | أيضًا، يمكن أن يكون للمعامل <code>opt</code> نفس مفاتيح التابع <code>[[Ruby/String/encode|String.encode]]</code> للتحكم في التحويل بين الترميز الخارجي والترميز الداخلي. |
| − | * <code>binmode</code>: إن كانت القيمة | + | ==القيمة المعادة== |
| − | * <code>autoclose</code>: إن كانت قيمته تساوي <code>false</code>، فسيبقى <code>fd</code> | + | يعاد كائن جديد من النوع <code>[[Ruby/IO|IO]]</code>. |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | ==القيمة | ||
| − | |||
==أمثلة== | ==أمثلة== | ||
| − | + | مثال على استعمال التابع <code>new</code> بأبسط شكل له:<syntaxhighlight lang="ruby">fd = IO.sysopen("/dev/tty", "w") | |
| − | |||
| − | <syntaxhighlight lang="ruby">fd = IO.sysopen("/dev/tty", "w") | ||
a = IO.new(fd,"w") | a = IO.new(fd,"w") | ||
$stderr.puts "Hello" | $stderr.puts "Hello" | ||
| − | a.puts "World"</syntaxhighlight>الناتج:<syntaxhighlight lang=" | + | a.puts "World"</syntaxhighlight>الناتج:<syntaxhighlight lang="text">Hello |
| − | World</syntaxhighlight> | + | World</syntaxhighlight>مثال على استعمال التابع <code>new</code> مع تحديد المعامل <code>mode</code> والمعامل <code>opt</code>:<syntaxhighlight lang="ruby">require 'fcntl' |
| − | |||
| − | |||
| − | <syntaxhighlight lang="ruby">require 'fcntl' | ||
fd = STDERR.fcntl(Fcntl::F_DUPFD) | fd = STDERR.fcntl(Fcntl::F_DUPFD) | ||
| سطر 85: | سطر 74: | ||
io = IO.new(fd, mode: 'w', cr_newline: true, | io = IO.new(fd, mode: 'w', cr_newline: true, | ||
external_encoding: Encoding::UTF_16LE) | external_encoding: Encoding::UTF_16LE) | ||
| − | io.puts "Hello, World!"</syntaxhighlight>كلا المثالين أعلاه يطبعان "<code>Hello, World!</code>" وفق الترميز <code>UTF-16LE</code> في مجرى | + | io.puts "Hello, World!"</syntaxhighlight>كلا المثالين أعلاه يطبعان "<code>Hello, World!</code>" وفق الترميز <code>UTF-16LE</code> في مجرى الخطأ القياسي، مع تحويل المحرف <code>EOL</code> الذي تم إنشاؤها من قبل <code>[[Ruby/IO/puts|puts]]</code> إلى المحرف <code>CR</code>. |
| − | ==انظر | + | ==انظر أيضًا== |
| − | *التابع <code>[[Ruby/IO/open|open]]</code>: عند | + | *التابع <code>[[Ruby/IO/open|open]]</code>: يشبه التابعَ <code>new</code> تمامًا عند استدعائه دون كتلة، أو يُمرّر الكائن <code>IO</code> الذي جرى إنشاؤه كوسيط إلى الكتلة المعطاة ثم يعيد الناتج الذي تعيده الكتلة. |
| + | *التابع <code>[[Ruby/IO/sysopen|sysopen]]</code>: يفتح الملف الموجود في المسار المحدد، ثم يعيد واصف الملف الأساسي <nowiki/>[[Ruby/Integer|كعدد صحيح]]. | ||
| + | *التابع <code>[[Ruby/IO/for fd|for_fd]]</code>: يعد مرادفًا للتابع <code>new</code>. | ||
==مصادر== | ==مصادر== | ||
| − | *[http://ruby-doc.org/core-2.5.1/IO.html#method-c-new قسم | + | *[http://ruby-doc.org/core-2.5.1/IO.html#method-c-new قسم التابع new في الصنف IO في توثيق روبي الرسمي.] |
المراجعة الحالية بتاريخ 14:02، 19 ديسمبر 2018
ينشئ التابع 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.