عرض مصدر JavaScript/function*

<noinclude>{{DISPLAYTITLE:الدوال المولدة في JavaScript}}</noinclude>
التصريح عن الدالة المولدة ('''generator''' '''function''' '''declaration''') يُعرِّف دالة مولدِّةً التي تُعيد الكائن <code>[[JavaScript/Generator|Generator]]</code>. لاحظ أنَّ التصريح عن الدوال المولدة يكون عبر الكلمة المحجوزة <code>function</code> ويليها رمز النجمة <code>*</code>.

يمكن أيضًا تعريف الدوال المولِّدة عبر الدالة البانية <code>[[JavaScript/GeneratorFunction|GeneratorFunction]]</code> وعبر تعابير تعريف الدوال المولدة (<code>[[JavaScript/Function* Expression|function* expression]]</code>).
==البنية العامة==
<syntaxhighlight lang="javascript">
function* name([param[, param[, ... param]]]) {
   statements
}
</syntaxhighlight>
=== <code>name</code> ===
اسم الدالة

=== <code>param</code> ===
اسم الوسيط المُرَّر إلى الدالة، العدد الأقصى للوسائط التي يمكن تمريرها إلى الدالة يختلف حسب المحرِّك الذي يُفسِّر اللغة.

=== <code>statements</code> ===
التعابير البرمجية التي تُشكِّل جسم الدالة.

== الوصف ==
المولِّدات هي الدوال التي يمكن الخروج منها والعودة إليها لاحقًا، وسيُحفَظ سياقها (أي ارتباطات المتغيرات) بين عمليات الدخول والخروج.

استدعاء دالة مولِّدة لن يؤدي إلى تنفيذ جسم الدالة مباشرة، وإنما سيُعاد كائن iterator للدالة، وعند استدعاء الدالة <code>next()‎</code> في كائن iterator فسيُنفَّذ جسم الدالة من البداية إلى أوّل تعبير <code>[[JavaScript/yield|yield]]</code>، الذي يُحدِّد ما هي القيمة التي سيُعيدها iterator؛ أو تعبير <code>[[JavaScript/yield*|yield*]]</code>‎ الذي يحوِّل التنفيذ إلى دالة مولِّدة أخرى.

الدالة <code>next()‎</code> ستُعيد كائنًا له الخاصية <code>value</code> التي تحتوي على القيم المُعادة من تعبير <code>[[JavaScript/yield|yield]]</code> وخاصية أخرى باسم <code>done</code> التي تُشير إذا كانت الدالة المولِّدة قد كانت آخر قيمة أعطتها (yielded) هي قيمة منطقية (Boolean).

استدعاء الدالة <code>next()‎</code> مع تمرير وسيط إليها سيؤدي إلى استئناف عمل الدالة المولِّدة مع وضع التعبير الذي مُرِّر إليها مكان آخر تعبير <code>[[JavaScript/yield|yield]]</code> الذي توقف التنفيذ عنده آخر مرة.

سيؤدي التعبير البرمجي <code>[[JavaScript/return|return]]</code> إلى إعادة الخاصية <code>done</code> عند تنفيذه في المولِّدات، وإذا أُعيدتَ قيمة مع التعبير <code>[[JavaScript/return|return]]</code> فستُمرَّر إلى الخاصية <code>value</code>؛ انتبه إلى أنَّ المولِّدات التي أعادت قيمةً لا تستطيع أن تعطي (yield) أيّة قيمة أخرى.

== أمثلة ==

=== مثال بسيط ===
<syntaxhighlight lang="javascript">
function* idMaker() {
  var index = 0;
  while (index < 3)
    yield index++;
}

var gen = idMaker();

console.log(gen.next().value); // 0
console.log(gen.next().value); // 1
console.log(gen.next().value); // 2
console.log(gen.next().value); // undefined
// ...
</syntaxhighlight>

=== مثال مع استخدام <code>yield*‎</code> ===
<syntaxhighlight lang="javascript">
function* anotherGenerator(i) {
  yield i + 1;
  yield i + 2;
  yield i + 3;
}

function* generator(i) {
  yield i;
  yield* anotherGenerator(i);
  yield i + 10;
}

var gen = generator(10);

console.log(gen.next().value); // 10
console.log(gen.next().value); // 11
console.log(gen.next().value); // 12
console.log(gen.next().value); // 13
console.log(gen.next().value); // 20

</syntaxhighlight>

=== تمرير وسائط إلى المولِّدات ===
<syntaxhighlight lang="javascript">
function* logGenerator() {
  console.log(0);
  console.log(1, yield);
  console.log(2, yield);
  console.log(3, yield);
}

var gen = logGenerator();

// سيبدأ أوّل استدعاء للدالة من بدايتها
// حتى الوصول إلى أوّل تعبير yield
gen.next();             // 0
gen.next('pretzel');    // 1 pretzel
gen.next('california'); // 2 california
gen.next('mayonnaise'); // 3 mayonnaise
</syntaxhighlight>

=== إعادة قيمة في المولِّدات ===
<syntaxhighlight lang="javascript">
function* yieldAndReturn() {
  yield "Y";
  return "R";
  yield "unreachable";
}

var gen = yieldAndReturn()
console.log(gen.next()); // { value: "Y", done: false }
console.log(gen.next()); // { value: "R", done: true }
console.log(gen.next()); // { value: undefined, done: true }
</syntaxhighlight>

=== لا يمكن إنشاء كائن من المولِّدات ===
لاحظ أنَّ المثال الآتي لن يعمل لعدم القدرة على إنشاء كائن من دالة مولِّدة:<syntaxhighlight lang="javascript">
function* f() {}
var obj = new f; // TypeError: f is not a constructor

</syntaxhighlight>

==دعم المتصفحات==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|39
|26
|غير مدعومة
|26
|10
|}
على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة.

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/# ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/7.0/# ECMAScript 2016].
* معيار [http://www.ecma-international.org/ecma-262/6.0/# ECMAScript 2015 (6th Edition)]‎. 
[[تصنيف:JavaScript]]
[[تصنيف:JavaScript Statement]]