التابع ARGF.read في روبي

يقرأ التابع read عددًا محددًا من البايتات من المجرى ARGF.

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

 read([length [, outbuf]]) → string, outbuf, or nil
يعالج هذا التابع جميع الملفات الممرَّرة في سطر الأوامر وكأنَّها ملفٌ واحدٌ، لذلك يعيد جميع محتويات هذا الملف الزائف (pseudo file) عند استدعائه دون تمرير أي وسائط. 
إذا كانت قيمة الوسيط length عددًا صحيحًا موجبًا، فسيحاول التابع read قراءة عددًا من البايتات يساوي length دون إجراء أي تحويل (الوضع الثنائي [binary mode]). في حال كان length عددًا صحيحًا (integer)، تكون السلسلة النصية الناتجة مكتوبة بالترميز ASCII-8BIT دائمًا. 
لاحظ أنَّ التابع read يسلك نفس سلوك الدالة fread()‎ في لغة C. هذا يعني أنَّ التابع يحاول تنفيذ استدعاءات النظام للدالة read(2)‎ لقراءة البيانات وفق الطول المحدد. إذا كنت تريد أن تسلك هذه الدالة سلوك استدعاءٍ وحيدٍ للدالة read(2)‎، فيمكنك استخدام التابع ‎readpartial أو التابع read_nonblock.

المعاملات

length عددٌ صحيحٌ موجب يحدد عدد البايتات المراد قراءتها. إن أعطيت القيمة nil لهذا الوسيط، فستستمر عملية القراءة من الملف حتى الوصول إلى محرف نهاية الملف (EOF). outbuf سلسلةٌ نصيةٌ تستعمل لتخزين البيانات المقروءة من المجرى ARGF. ملاحظة: إن حوى هذا الوسيط أية بيانات سابقة قبل استدعاء الدالة read، فستكتب البيانات الجديدة التي تُقرَأ من المجرى فوق تلك البيانات القديمة.

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

تعاد سلسلة نصية تمثل البيانات التي قُرئت من المجرى ARGF. تعاد القيمة nil عند الوصول إلى نهاية الملف (EOF) وقبل قراءة أي شيء منه. يعاد عددٌ من البايتات أقل مما هو محدد في الوسيط length عند الوصول إلى نهاية الملف (EOF) أثناء القراءة منه. إن لم يعطَ الوسيط length أو كانت قيمته تساوي nil، فلن تتوقف عملية القراءة حتى يصل التابع إلى نهاية الملف (EOF) وستجرى عملية تحويل للترميز إذا كان ذلك ممكنًا. يمكن أن تعاد سلسلة نصية حتى لو صودفت نهاية الملف (EOF) قبل قراءة أية بيانات. إذا كان length يساوي 0، فسيعيد التابع سلسلة نصية فارغة (""). إن أعطي الوسيط "" الاختياري، فستُخزَّن البيانات التي تُقرَأ من المجرى outbuf في هذا الوسيط ثمَّ يعاد.

أمثلة

مثالٌ على استخدام التابع read:

 $ echo "small" > small.txt
$ echo "large" > large.txt
$ ./glark.rb small.txt large.txt

ARGF.read      #=> "small\nlarge"
ARGF.read(200) #=> "small\nlarge"
ARGF.read(2)   #=> "sm"
ARGF.read(0)   #=> ""

انظر أيضًا

• التابع readbyte: يقرأ البايت التالي من المجرى ARGF ثمَّ يعيده على شكل عدد صحيح (Integer).
• التابع read_nonblock: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديَّةً عليا من المجرى ARGF في وضع عدم الحجز (non-blocking mode).
• التابع readchar: يقرأ المحرف التالي من المجرى ARGF ثم يعيده على شكل سلسلة نصية.
• التابع readline: يقرأ السطر التالي من الملف الحالي في المجرى ARGF.
• التابع readlines: يقرأ الملف الحالي في المجرى ARGF بشكل كامل.
• التابع readpartial: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديةً عليا من المجرى ARGF.
• * التابع gets: يقرأ التابع gets السطر الموالي في الملف الحالي في ARGF.
• التابع printf: يطبع الكائن أو الكائنات الممرَّرة إليه على المجرى ios بعد تنسيقها بشكل معين.
• التابع to_a: يقرأ الملف الحالي في المجرى ARGF بشكل كامل ثم يضع محتوياته في مصفوفة.
• التابع write: يكتب السلسلة النصية الممرَّرة إليها على المجرى ARGF في حال كان الوضع inplace مفعَّلًا.

مصادر

• قسم التابع read في الصنف ARGF في توثيق روبي الرسمي.