Node.js/readline

الاستقرار 2: مستقر

توفّر الوحدة readline واجهةً برمجيةً لقراءة سطر واحد من البيانات من المجرى القابل للقراءة (Readable) (مثل process.stdin) كل مرَّة على حدة. يمكن الوصول إليها باستخدام الأمر التالي:

const readline = require('readline');

يوضح المثال البسيط التالي الاستخدام الأساسي للوحدة readline:

const readline = require('readline');

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

rl.question('What do you think of Node.js? ', (answer) => {


‎‎‎  // في قاعدة بيانات (answer) للتنفيذ: سجل الجواب
  
console.log(`Thank you for your valuable feedback: ${answer}`);

  rl.close();
});

حالما تُستدعى هذه الشيفرة، لن ينتهي تطبيق Node.js حتى تُغلَق الواجهة readline.Interface لأنّها تنتظر أن تُستقبل البيانات في المجرى input.

الصنف Interface

أُضيف في الإصدار: 0.1.104.

تُنشَأ نُسَخ الصنف readline.Interface باستخدام التابع readline.createInterface()‎. ترفق كل نسخة مع مجرى الدخل input الوحيد القابل للقراءة ومجرى الخرج output الوحيد القابل للكتابة. يُستخدم المجرى output لطباعة الأوامر التي يدخلها المستخدم والتي تصل وتُقرأ من مجرى input.

الحدث 'close'

أُضيف في الإصدار: 0.1.98.

يُطلق الحدث 'close' عندما يحدث واحد مما يلي:

• يُستدعى التابع rl.close()‎ وقد تخلّت نسخة readline.Interface عن التحكم بمجريي الدخل input والخرج output.
• يستقبل المجرى input الحدث 'end' الخاص به.
• يستقبل مجرى الدخل input الإشارة EOT (نهاية الإرسال [end-of-transmission]) عبر ضغط المستخدم على المفتاحين  ‎<ctrl>-D‎.
• يستقبل مجرى الدخل input الإشارة SIGINT عبر ضغط المستخدم على المفتاحين ctrl>-C> ولا يوجد مستمع للحدث 'SIGINT' مُسجَّل على نسخة readline.Interface.

تُستدعَى الدالة المستمعة (listener) دون تمرير أي وسائط.

تُنهى النسخة readline.Interface حالما يُطلق الحدث 'close'.

الحدث 'line'

أُضيف في الإصدار:0.1.98.

يُطلق الحدث 'line' كلّما استقبل المجرى input محرف نهاية السطر (المحرف n\ أو r\ أو ‎\r\n). هذا يحدث عادةً عندما يضغط المستخدم المفاتيح <Enter> أو <Return>.

تُستدعى الدالة المستمعة مع سلسلة نصية متضمنةً سطرًا وحيدًا من الدخل المُستقبل.

rl.on('line', (input) => {
  console.log(`Received: ${input}`);
});

الحدث 'pause'

أُضيف في الإصدار: 0.7.5.

يُطلق الحدث 'pause' عندما  يحدث واحد مما يلي:

• يُوقف المجرى input مؤقتًا.
• لم يُوقف المجرى input ولكنه استقبل الحدث 'SIGCONT'. (انظر الحدثين 'SIGTSTP' و 'SIGCONT'.)

تُستدعى الدالة المستمعة دون تمرير أي وسائط.

rl.on('pause', () => {
  console.log('Readline paused.');
});

الحدث 'resume'

أضيف في الإصدار: 0.7.5.

يُطلق الحدث 'resume' عندما يُستأنَف المجرى input.

تُستدعى الدالة المستمعة دون تمرير أي وسائط.

rl.on('resume', () => {
  console.log('Readline resumed.');
});

الحدث 'SIGCONT'

أضيف في الإصدار: 0.7.5.

يُطلق الحدث 'SIGCONT' عندما تكون عملية Node.js قد انتقلت مسبقًا إلى الخلفية باستخدام المفتاحين ‎<ctrl>-Z (أي عبر استلام الإشارة SIGTSTP) ثمَّ أعيدت إلى المقدمة باستخدام الدالة fg(1p‎)‎.

إذا كان مجرى الدخل input متوقف مؤقتًا قبل استلام الإشارة SIGTSTP، فلن يُطلق هذا الحدث.

تُستدعى الدالة المستمعة دون تمرير أي وسائط.

rl.on('SIGCONT', () => {

 //  المجرى تلقائيًا‎‎‎`prompt`‎‎ سوف تستأنف 


rl.prompt();
});

الحدث 'SIGCONT' ليس مدعومًا على أنظمة ويندوز.

الحدث 'SIGINT'

أضيف في الإصدار: 0.3.0.

يُطلق الحدث 'SIGINT' عندما يستلم المجرى input الإشارة SIGINT عبر الضغط على المفتاحين ‎<ctrl>-C‎. إذا لم يوجد هناك أي مستمع مسجل للحدث 'SIGINT' عندما يتلقى المجرى input الإشارة SIGINT، فسيُطلق الحدث 'pause'.

تُستدعى دالة المنصت دون تمرير أي وسائط.

rl.on('SIGINT', () => {
  rl.question('Are you sure you want to exit? ', (answer) => {
    if (answer.match(/^y(es)?$/i)) rl.pause();
  });
});

الحدث 'SIGTSTP'

أُضيف في الإصدار: 0.7.5.

يُطلق الحدث 'SIGTSTP' عندما يتلقى المجرى input الإشارة SIGTSTP عبر ضغط المفتاحين ‎<ctrl>-Z‎‎. إذا لم يوجد هناك أي مستمع مسجل للحدث 'SIGTSTP' عندما يتلقى المجرى input الإشارة SIGTSTP، فستُرسل عملية Node.js إلى الخلفية.

عندما يُستأنَف البرنامج باستخدام الدالة fg(1p)‎، سيُطلق الحدثان 'pause' و 'SIGCONT'. يمكن استخدام ذلك لاستئناف المجرى input.

لن يُطلَق الحدثان 'pause' و'SIGCONT' إذا أُوقِف المجرى input قبل أن تُرسَل العملية إلى الخلفية.

تُستدعَى الدالة المستمعة دون تمرير أي وسائط.

rl.on('SIGTSTP', () => {

  // ويمنع البرنامج من الذهاب إلى الخلفية SIGTSTP هذا سيتجاهل الإشارة 
  console.log('Caught SIGTSTP.');

});

الحدث 'SIGTSTP' ليس مدعومًا على نظام ويندوز.

rl.close‎()‎

أضيف في الإصدار: 0.1.98.

يغلق التابع rl.close‎()‎ النسخة readline.Interface ويتخلى عن التحكم بمجريي الدخل input و الخرج output. عندما استدعائه، سيُطلَق الحدث 'close'.

لن يوقف استدعاء التابع rl.close‎()‎ إطلاق بقية الأحداث (بما فيها الحدث 'line') مباشرةً  من قِبَل النسخة readline.Interface.

rl.pause‎()‎

أضيف في الإصدار: 0.3.4.

يوقف التابع rl.pause‎()‎ المجرى input مؤقتًا، سامحًا له بالاستئناف لاحقًا عند الحاجة.

لن يوقف استدعاء rl.pause‎()‎ إطلاق بقية الأحداث (بما فيها الحدث 'line') مباشرةً  من قِبَل النسخة readline.Interface.

rl.prompt([preserveCursor‎]‎)‎

أضيف في الإصدار: 0.1.98.

• preserveCursor:‏ <boolean> قيمة منطقية إن كانت true، فستمنع المؤشر من إعادة تعيين موضعه إلى 0 (بداية المجرى).

يكتب التابع rl.prompt‎(‎)‎ النُسخ readline.Interface التي ضُبِط فيها المحث prompt إلى سطر جديد في المجرى output من أجل تزويد المستخدم بموقع جديد ليدخل البيانات فيه.

عند استدعاء التابع rl.prompt‎(‎)‎، سيستأنف المجرى input إذا كان قد أُوقف مؤقتًا.

إذا أُنشئت النسخة readline.Interface مع ضبط المجرى output إلى القيمة null أو undefined، فلن يُكتَب على المحث (prompt).

rl.question(query, callback‎)‎

أضيف في الإصدار: 0.3.3.

• Query:‏ <string> عبارة أو استعلام يرا كتابتها على المجرى output، مضافةً إلى بداية المِحَث.
• Callback:‏ <Function> دالة رد نداء التي يراد استدعاؤها مع مدخلات المستخدم عند الاستجابة إلى الاستعلام query.

يعرض التابع rl.question()‎ قيمة الاستعلام query عن طريق كتابته على المجرى output، بعد أن ينتظر مدخلات المستخدم ليكتبها على المجرى input. بعد ذلك، يستدعي التابع دالة رد النداء مُمرّرًا المدخلات المستلمة من الستخدم إليها كأول وسيط.

عند استدعائه، سوف يستأنف rl.question()‎ المجرى input إذا كان قد أُوقف مؤقتًا.

ذا أُنشئت النسخة readline.Interface مع ضبط المجرى output إلى القيمة null أو undefined، فلن يُكتَب الاستعلام query.

اطلع على المثال التالي الذي يشرح ما سبق:

rl.question('What is your favorite food? ', (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
});

لا تتبع دالة رد النداء المُمررة إلى التابع rl.question()‎ النموذج القياسي لقبول الكائن Error أو null كأول وسيط لها، إذ تُستدعَى دالة رد النداء مع تمرير الجواب الذي استُلِم من المستخدم كأول وسيط لها.

rl.resume()‎

أضيف في الإصدار: 0.3.4.

يستأنف التابع rl.resume()‎ المجرى input إذا أُوقِف مؤقتًا.

rl.setPrompt(prompt)‎

أضيف في الإصدار: 0.1.98.

• Prompt:‏ <string>

سوف يضبط التابع rl.setPrompt()‎ المِحَث الذي سيكتب على المجرى output كلما استدعي التابع rl.prompt()‎.

rl.write(data[, key]‎)‎

أضيف في الإصدار: 0.1.98.

• data:‏ <string>
• key:‏ <Object>
  • Ctrl:‏ <boolean> قيمة منطقية إن كانت true فستشير إلى المفتاح ‎<ctrl>‎‎.
  • Meta:‏ <boolean> قيمة منطقية إن كانت true فستشير إلى المفتاح <Meta>.
  • Shift:‏ <boolean> قيمة منطقية إن كانت true فستشير إلى المفتاح ‎<Shift>‎‎‎.
  • Name:‏ <string> سلسلة نصية تمثِّل اسم المفتاح.

سيكتب التابع rl.write()‎ إمّا قيمة المعامل data أو تسلسل المفتاح المعرّف من قبل المعامل key إلى المجرى output. الوسيط key مدعومٌ إذا كانت TTY هي طرفية كتابة فقط.

إذا كان المعامل key مُحددًا، فسيُتجاهَل المعامل data.

عند استدعاء ‎rl.write()‎، سيستأنف المجرى input إذا كان قد أُوقف مؤقتًا.

إذا أُنشئت النسخة readline.Interface مع ضبط المجرى output إلى القيمة null أو undefined، فلن تُكتَب قيمة المعامل data أو المعامل key.

rl.write('Delete this!');
// لحذف السطر المكتوب سابقًا Ctrl+u محاكي ضغط المفتاحين 
rl.write(null, { ctrl: true, name: 'u' });

سوف يكتب التابع rl.write()‎ البيانات إلى المجرى input‏ كما أعطيت من قبل المستخدم تمامًا.

readline.clearLine(stream, dir)‎

أُضيف في الإصدار: 0.7.7.

• stream:‏ <stream.Writable>
• dir:‏ <number>
  • 1-: على يسار المؤشر
  • 1: على يمين المؤشر
  • 0: كل السطر

يمسح التابع readline.clearLine()‎ السطر الحالي من المجرى TTY المُعطى انطلاقًا من مؤضع المؤشر الحالي وباتجاهٍ محدَّدٍ مُعرّف عبر المعامل dir.

readline.clearScreenDown(stream)‎

أُضيف في الإصدار: 0.7.7.

• stream:‏ <stream.Writable>

يمسح التابع readline.clearScreenDown()‎ مجرى TTY المعُطى من موقع المؤشر الحالي وبالاتجاه الأسفل.

readline.createInterface(options)‎

سجل التغييرات