عرض مصدر Ruby/calling methods

<noinclude>{{DISPLAYTITLE: استدعاء التوابع في لغة روبي}}</noinclude>
عندما تستدعي تابعًا، فإنّك تمرّر رسالة لكائن معيّن لأجل تنفيذ مهمّة معيّنة، ويتمّ ذلك في لغة روبي كالتّالي:<syntaxhighlight lang="ruby">
my_method()
</syntaxhighlight>لاحظ أنّ استخدام الأقواس المنحنية هنا اختياريّ:<syntaxhighlight lang="ruby">
my_method
</syntaxhighlight>المعتمد في هذا التّوثيق أن تُستخدّم الأقواس عند وجود المعامِلات لإزالة الالتباس، إلا في حالة وجود فرق بين وجود الأقواس وحذفها.

هذا القسم يغطّي فقط كيفيّة استدعاء التوابع، وستُشرَح كيفيّة [[Ruby/methods|تعريف التّوابع]] في قسم آخر.
==المستقبِل==
المستقبِل (Receiver) الافتراضي في لغة روبي هو <code>self</code> وهو الذي يُستخدَم في حال عدم تحديد أيّ مستقبل آخر. ولأجل تحديد مستقبِل، يستَدعى التابع بالشّكل التالي:<syntaxhighlight lang="ruby">
my_object.my_method
</syntaxhighlight>في هذه الحالة تُرسل رسالة <code>my_method</code> إلى الكائن <code>my_object</code>. فكلّ كائن يمكنه أن يكون مستقبِلًا لتابع ما؛ لكن حتى يتمّ ذلك، يجب أن يكون التابع مرئيًّا لهذا الكائن، وإلّا فسيظهر خطأ من نوع <code>[[Ruby/NoMethodError|NoMethodError]]</code>. 

يمكنك استخدام المعامل <code>.&</code> (متبوعًا بنقطة) لتعيّن <code>&</code> كمستقبل، حينها لن يُنفّذ التابع <code>my_method</code>، وستكون النتيجة <code>nil</code> عندما يكون المستقبِل <code>nil</code>، ولن تُقيَّم معامِلات التّابع <code>my_method</code> في هذه الحالة.

كما يمكنك استخدام <code>::</code> لتعيين المستقبل، لكنّ هذه الطريقة نادرة الاستخدام لأنّها قد تسبّب التباسًا مع الرمز <code>::</code> المستخدم في مجالات الأسماء (namespaces).
==الوسائط==
تدعم لغة روبي ثلاثة أنواع من الوسائط (arguments) التي يمكن تمريرها عند إرسال الرسائل وهي: الوسائط الموضعية، ووسائط القيم المفتاحية (أوالوسائط المسماة [named arguments])، ووسائط الكتلة البرمجية. كل رسالة تُرسَل تستخدم نوعًا أو اثنين أو كل هذه الأنواع، إلّا أنّها إذا استُخدمت معًا، فيجب أن تكون ضمن هذا الترتيب نفسه.

كلّ الوسائط في لغة روبي تُمرّر مرجعيًا ولا يؤجّل تقييمها. تفصل الوسائط بالفاصلة <code>,</code> بالشكل التالي:<syntaxhighlight lang="ruby">
my_method(1, '2', :three)
</syntaxhighlight>يُمكن أن تكون الوسائط على شكل تعبير برمجي [[Ruby/Hash|كالجدول Hash]]:<syntaxhighlight lang="ruby">
'key' => value
</syntaxhighlight>أو وسائط مسماة (Keyword arguments):<syntaxhighlight lang="ruby">
key: value
</syntaxhighlight>[[Ruby/Hash|الجداول Hash]] والوسائط المسماة يجب أن تكون متجاورة ويجب أن تتلو الوسائط الموضعيّة، ولا بأس في أن تُخلط فيما بينها:<syntaxhighlight lang="ruby">
my_method('a' => 1, b: 2, 'c' => 3)
</syntaxhighlight>
==الوسائط الموضعيّة==
تتبع الوسائط الموضعيّة (Positional Arguments) للرسالة اسم التابع مباشرة:<syntaxhighlight lang="ruby">
my_method(argument1, argument2)
</syntaxhighlight>في كثير من الحالات، لا تكون الأقواس ضروريّة عند إرسال الرسالة:<syntaxhighlight lang="ruby">
my_method argument1, argument2
</syntaxhighlight>لكنّها ضروريّة لإزالة الالتباس، فالمثال التّالي سيسبب خطأً في صيغة (<code>[[Ruby/SyntaxError|SyntaxError]]</code>)  بسبب أنّ مفسّر لغة روبي لن يعرف إلى من يجب إرسال الوسيط الثالث <code>argument3</code>:<syntaxhighlight lang="ruby">
method_one argument1, method_two argument2, argument3
</syntaxhighlight>إذا احتوى تعريف التابع على وسيط مبدوء برمز <code>*</code>، فالوسائط الموضعيّة الإضافيّة ستُسنَد إلى هذا الوسيط في التابع على هيئة مصفوفة.

إذا لم يحتوِ تعريف التابع على وسائط مسماة، فإنّ أيّة وسائط مسماة أو الوسائط ذات [[Ruby/Hash|النوع Hash]] ستُسند جميعها [[Ruby/Hash|كجدول Hash]] واحد إلى آخر وسيط في تعريف التابع:<syntaxhighlight lang="ruby">
def my_method(options)
 p options
end
my_method('a' => 1, b: 2) # تطبع: {'a'=>1, :b=>2}
</syntaxhighlight>إذا مُرر عدد كبير من الوسائط الموضعية، فسيسبب ذلك ظهور الخطأ <code>[[Ruby/ArgumentError|ArgumentError]]</code>.
==الوسائط الموضعية الافتراضية==
عندما تعرَّف وسائط افتراضية في تعريف التابع، فلست بحاجة إلى تزويده بكل الوسائط عند الاستدعاء، فالمفسّر سيملأ المعاملات الناقصة وفق الترتيب.

ففي أبسط الحالات، عندما تكون الوسائط الافتراضية هي الأخيرة في أقصى اليمين مثل:<syntaxhighlight lang="ruby">
def my_method(a, b, c = 3, d = 4)
 p [a, b, c, d]
end
</syntaxhighlight>لكلّ من المعاملين <code>c</code> و <code>d</code> قيمة افتراضية، فإذا مُرِّر معاملين فقط في استدعاء التابع مثل:<syntaxhighlight lang="ruby">
my_method(1, 2)
</syntaxhighlight>فستكون النتيجة كالتالي:<syntaxhighlight lang="text">
[1, 2, 3, 4] 
</syntaxhighlight>وإذا مرّرت ثلاثة معاملات:<syntaxhighlight lang="ruby">
my_method(1, 2, 5)
</syntaxhighlight>فستكون النتيجة:<syntaxhighlight lang="text">
[1, 2, 5, 4]
</syntaxhighlight>حيث يملأ مفسّر روبي المعاملات النّاقصة من اليسار إلى اليمين.

تسمح لغة روبي بأن توضع الوسائط الافتراضية في المنتصف بين الوسائط الموضعية الأخرى. لنأخذ هذا المثال الأكثر تعقيدًا: <syntaxhighlight lang="ruby">
def my_method(a, b = 2, c = 3, d)
 p [a, b, c, d]
end
</syntaxhighlight>هنا <code>b</code> و <code>c</code> يأخذان قيمًا افتراضيّة. فإذا مُرِّر معاملين فقط في استدعاء التابع بالشكل:<syntaxhighlight lang="ruby">
my_method(1, 4)
</syntaxhighlight>ستكون النتيجة:<syntaxhighlight lang="text">
[1, 2, 3, 4]
</syntaxhighlight>وإذا مُرِّر ثلاثة معاملات:<syntaxhighlight lang="ruby">
my_method(1, 5, 6)
</syntaxhighlight>ستكون النتيجة:<syntaxhighlight lang="text">
[1, 5, 3, 6]
</syntaxhighlight>من الصّعب وصف الذي يحصل هنا بالكلمات، لذلك سنشرحها باستخدام المتغيّرات وقيمها.

بداية تُسند القيمة 1 إلى <code>a</code>، ثمّ تسند القيمة 6 إلى <code>d</code>. وهكذا يبقى المعاملَين ذوَي القيمة الافتراضية. وطالما أنّ القيمة 5 لم تُسنَد بعد، فستعطى إلى <code>b</code>، ويحصل <code>c</code> على القيمة الافتراضية 3.
==الوسائط المسماة==
الوسائط المسماة تلي الوسائط الموضعية ويفصل بينها فواصل:<syntaxhighlight lang="ruby">
my_method(positional1, keyword1: value1, keyword2: value2)
</syntaxhighlight>إذا لم تظهر الوسائط المسماة عند استدعاء التابع رغم وجودها في تعريفه، فستأخذ القيمة الافتراضيّة المعرّفة فيه. أمّا إذا مُرّرت هذه الوسائط في الاستدعاء دون أن يحتوي عليها تعريف التّابع، فسيظهر حينئذ الخطأ <code>[[Ruby/ArgumentError|ArgumentError]]</code>.
==وسائط الكتل البرمجية==
وسائط الكتل البرمجيّة تمرّر كتلة برمجيّة من النّطاق الذي يستدعي التّابع، ويكون ترتيب هذه الوسائط دائمًا في نهاية الوسائط الممرّرة للتابع. وتُمرّر الكتلة البرمجيّة باستخدام <code>do.. end</code> أو الأقواس <code>{..}</code>:<syntaxhighlight lang="ruby">
my_method do
 # ...
end
</syntaxhighlight>أو:<syntaxhighlight lang="ruby">
my_method {
 # ...
}
</syntaxhighlight>تأخذ <code>do-end</code> أولويّة أدنى من القوسين <code>{}</code> المعقوصين؛ ففي المثال التّالي:<syntaxhighlight lang="ruby">
method_1 method_2 {
 # ...
}
</syntaxhighlight>تُرسل الكتلة البرمجيّة إلى التابع <code>method_2</code>؛ بينما في المثال:<syntaxhighlight lang="ruby">
method_1 method_2 do
 # ...
end
</syntaxhighlight>ترسل الكتلة إلى التابع <code>method_1</code>.

يمكن أن تستقبل الكتلة البرمجية وسائط من التابع المرسلة له. هذه الوسائط تعرّف بطريقة مشابهة لطريقة تعريفها في التوابع، وتمرّر ضمن <code>|...|</code> بعد كلمة <code>do</code> أو القوس المفتتح للكتلة:<syntaxhighlight lang="ruby">
my_method do |argument1, argument2|
 # ...
end
</syntaxhighlight>
==الوسائط المحلية للكتلة البرمجية==
يمكنك أيضًا تعريف وسائط محليّة على مستوى الكتلة البرمجيّة باستخدام الرّمز <code>;</code> في قائمة وسائط الكتلة. لاحظ أنّ إسناد قيم إلى هذه الوسائط ليس له أيّ تأثير على المتغيّرات المحليّة التي لها نفس الاسم والموجودة خارج هذه الكتلة في النطاق الذي يستدعي التابع:<syntaxhighlight lang="ruby">
def my_method
 yield self
end
place = "world"
my_method do |obj; place|
 place = "block"
 puts "hello #{obj} this is #{place}"
end
puts "place is: #{place}"
</syntaxhighlight>وتكون النتيجة:<syntaxhighlight lang="text">
hello main this is block
place is world
</syntaxhighlight>فالمتغيّر <code>place</code> ضمن الكتلة الممرّرة إلى التابع ليس نفسه المتغيّر <code>place</code> خارجها، وبالمقابل لو حذفنا <code>place ;</code> من وسائط الكتلة، فستكون النتيجة:<syntaxhighlight lang="text">
hello main this is block
place is block
</syntaxhighlight>
==التحويل من مصفوفة إلى وسائط==
ليكن لدينا هذا التابع:<syntaxhighlight lang="ruby">
def my_method(argument1, argument2, argument3)
end
</syntaxhighlight>يمكنك تحويل مصفوفة إلى سلسلة من الوسائط عن طريق تمرير المصفوفة مسبوقة برمز النجمة <code>*</code> (المسمى بمعامل الفصل):<syntaxhighlight lang="ruby">
arguments = [1, 2, 3]
my_method(*arguments)
</syntaxhighlight>أو:<syntaxhighlight lang="ruby">
arguments = [2, 3]
my_method(1, *arguments)
</syntaxhighlight>كلاهما مكافئ لما يلي:<syntaxhighlight lang="ruby">
my_method(1, 2, 3)
</syntaxhighlight>في حالة كان التابع يستقبل وسائط مسماة، فاستخدام معامل الفصل حينها سيحوّل [[Ruby/Hash|الجدول Hash]] الموجود في نهاية المصفوفة إلى وسائط مسماة:<syntaxhighlight lang="ruby">
def my_method(a, b, c: 3)
end
arguments = [1, 2, { c: 4 }]
my_method(*arguments)
</syntaxhighlight>يمكنك أيضًا استخدام الرمز <code>**</code> (سيأتي شرحه لاحقًا) لتحوّل عناصر [[Ruby/Hash|الجدول Hash]] إلى وسائط مسماة.

إذا لم يطابق عددُ الكائنات في المصفوفة عددَ المعاملات في التابع، فسيظهر الخطأ <code>[[Ruby/ArgumentError|ArgumentError]]</code>.

وإذا جاء معامل الفصل في بداية الوسائط عند الاستدعاء، فيجب استخدام الأقواس عندها منعًا لظهور تحذير (warning).
==التحويل من جدول Hash إلى وسائط مسماة==
لنأخذ هذا التابع على سبيل المثال:<syntaxhighlight lang="ruby">
def my_method(first: 1, second: 2, third: 3)
end
</syntaxhighlight>يمكنك تحويل محتوى [[Ruby/Hash|الجدول Hash]] إلى وسائط مسماة باستخدام المعامل <code>**</code>:<syntaxhighlight lang="ruby">
arguments = { first: 3, second: 4, third: 5 }
my_method(**arguments)
</syntaxhighlight>أو:<syntaxhighlight lang="ruby">
arguments = { first: 3, second: 4 }
my_method(third: 5, **arguments)
</syntaxhighlight>كلاهما مكافئ لما يلي:<syntaxhighlight lang="ruby">
my_method(first: 3, second: 4, third: 5)
</syntaxhighlight>استخدم المعامل <code>**</code> في تعريف التابع لتجمّع الوسائط المسماة أيًا كانت، إذ أنّها لن تُجمّع باستخدام المعامل <code>*</code>:<syntaxhighlight lang="ruby">
def my_method(*a, **kw)
 p arguments: a, keywords: kw
end
my_method(1, 2, '3' => 4, five: 6)
</syntaxhighlight>وتكون النتيجة:<syntaxhighlight lang="text">
{:arguments=>[1, 2, {"3"=>4}], :keywords=>{:five=>6}}
</syntaxhighlight>على عكس معامل الفصل الموضّح سابقًا، فإنّ المعامل <code>**</code> ليس له اسم معيّن متعارف عليه.
==التحويل من الكائنات <code>Proc</code> إلى كتل برمجية==
لنأخذ التابع التالي على سبيل المثال:<syntaxhighlight lang="ruby">
def my_method
 yield self
end
</syntaxhighlight>يمكنك تحويل كائن من النوع <code>[[Ruby/Proc|proc]]</code> أو <code>lambda</code> إلى كتلة برمجيّة باستخدام المعامل <code>&</code>:<syntaxhighlight lang="ruby">
argument = proc { |a| puts "#{a.inspect} was yielded" }
my_method(&argument)
</syntaxhighlight>إذا سبق في الاستدعاء معامل الفصل <code>*</code>، فيجب حينها استخدام الاقواس منعًا لظهور تحذير.

وكما هو الحال بالنّسبة للمعامل <code>**</code>،  فإنّ المعامل <code>&</code> أيضًا ليس له اسم معيّن متعارف عليه.
==البحث عن التوابع==
عندما ترسل رسالة، فإنّ مفسر روبي يبحث عن التابع الذي يطابق اسم مستقبل الرسالة؛ هذه التّوابع مخزّنة في [[:تصنيف:Ruby Class|أصناف]] (classes) و<nowiki/>[[:تصنيف:Ruby Module|وحدات]] (modules) يمرّ المفسّر عليها أثناء عمليّة البحث، ولا يبحث في كائناتها.

هذا هو الترتيب المتّبع في عمليّة البحث عن تابع للصنف أو الوحدة  R الخاصّ بمستقبل معين:
*وحدات R السابقة بترتيب عكسيّ.
*تابع مطابق في R.
*الوحدات المتضمّنة في R بترتيب عكسيّ.
وإذا كان للصنفّ R صنف أب (superclass)، فستكرّر العمليّة في الصنف الأب حتى يُعثَر على التابع، وتتوقّف عمليّة البحث متى عُثر على التابع.

وإذا لم يُعثر على أيّ نتيجة، فستعاد العمليّة من البداية لكن بالبحث عن <code>method_missing</code>، والتابع الافتراضيّ له <code>BasicObject.method_missing</code> والذي يسبّب ظهور الخطأ  <code>[[Ruby/NameError|NameError]]</code> عندما يستدعى.

عند تفعيل ميزة [[Ruby/refinements|التحسينات]] الاختبارية، فسيتغيّر ترتيب البحث عن التوابع، اقرأ توثيق [[Ruby/refinements|التحسينات]] لمزيد من التفاصيل.
==مصادر==
*[https://ruby-doc.org/core-2.5.1/doc/syntax/calling_methods_rdoc.html صفحة Calling Methods في توثيق روبي الرسمي.]
[[تصنيف: Ruby]]
[[تصنيف: Ruby Syntax]]