diff --git a/README.ar.md b/README.ar.md index 49bec24..9ad1028 100644 --- a/README.ar.md +++ b/README.ar.md @@ -1,4 +1,7 @@ # مـؤجلات (Promises) + +
+ [[English]](README.md) مكتبة بسيطة لدعم المؤجلات (promises) في لغة الأسس. @@ -11,23 +14,21 @@ يمكن تثبيت هذه المكتبة باستعمال التعليمات البرمجية التالية: -
- ``` اشمل "مـحا"؛ مـحا.اشمل_ملف("Alusus/Promises"، "مـؤجلات.أسس")؛ ``` -
+
``` import "Apm"; Apm.importFile("Alusus/Promises"); ``` -## مثال +
-
+## مثال ``` اشمل "مـتم/طـرفية"؛ @@ -91,8 +92,6 @@ Apm.importFile("Alusus/Promises"); اختبر_مؤجلة_ثم()؛ ``` -
- ``` import "Srl/Console"; import "Srl/errors"; @@ -111,7 +110,6 @@ class Num { handler this = ref[Num] this.val = value.val; } - func testPromise { Console.print("Test Promise:\n"); // Num نقوم بإنشاء مؤجلة نمط القيمة المرجعة لها هو @@ -132,7 +130,6 @@ func testPromise { } testPromise(); - func testPromiseThen { Console.print("\nTest Promise.then:\n"); // Num نقوم بإنشاء مؤجلة نمط القيمة المرجعة لها هو @@ -157,104 +154,183 @@ testPromiseThen(); ### الصنف مـؤجلة (Promise) -
- ``` -صنف مـؤجلة [نـوع_الـنتيجة: نوع]{ +صنف مـؤجلة [نـوع_الـنتيجة: صنف]{ عرف الحالة: صـحيح = حـالة._جديد_؛ عرف النتيجة: نـوع_الـنتيجة؛ عرف الخطأ: سـندنا[خـطأ]؛ + + عملية هذا.قرر(نتيجة: نـوع_الـنتيجة)؛ + عملية هذا.قرر(م : سندنا[مـؤجلة[نـوع_الـنتيجة]])؛ + عملية هذا.ارفض(خطأ: سندنا[خـطأ])؛ + عملية هذه.تجاهل_النتيجة(): سندنا[مـؤجلة[صـحيح]]؛ + + عملية [نـوع_ثـم: صنف] هذا.ثم( + منادى: مغلفة (دخل: نـوع_الـنتيجة، مـؤجلة: سند[مـؤجلة[نـوع_ثـم]]) + ): سندنا[مـؤجلة[نـوع_ثـم]]؛ + + عملية هذا.اقبض( + منادى: مغلفة (خطأ: سندنا[خـطأ]، مـؤجلة: سند[مـؤجلة[نـوع_الـنتيجة]]) + ): سندنا[مـؤجلة[نـوع_الـنتيجة]]؛ + + دالة أنشئ (): سندنا[مـؤجلة[): سندنا[مـؤجلة[نـوع_الـنتيجة]]؛ + + دالة الكل ( + الدخل: مـصفوفة[سندنا[مـؤجلة[نـوع_الـنتيجة]]] + ): سندنا[مـؤجلة[مـصفوفة[نـوع_الـنتيجة]]]؛ + + عرف حـالة { + عرف _جديد_: 0؛ + عرف _مقرر_: 1؛ + عرف _مرفوض_: 2؛ + } } ``` -
+
``` class Promise [ResultType: type] { def status: Int = Status.NEW; def result: ResultType; def error: SrdRef[Error]; + + handler this.resolve(res: ResultType); + handler this.resolve(p: SrdRef[Promise[ResultType]]); + handler this.reject(err: SrdRef[Error]); + handler this.ignoreResult(): SrdRef[Promise[Int]]; + + handler [ThenType: type] this.then( + callback: closure (input: ResultType, promise: ref[Promise[ThenType]]) + ): SrdRef[Promise[ThenType]]; + + handler this.catch( + callback: closure (err: SrdRef[Error], promise: ref[Promise[ResultType]]) + ): SrdRef[Promise[ResultType]]; + + function new (): SrdRef[Promise[ResultType]]; + + function all ( + inputs: Array[SrdRef[Promise[ResultType]]] + ): SrdRef[Promise[Array[ResultType]]]; + + def Status: { + def NEW: 0; + def RESOLVED: 1; + def REJECTED: 2; + } } ``` -هذا الصنف عبارة عن قالب لتخزين معلومات المؤجلة لمختلف أنواع النتائج. -`الحالة` (`status`) يعبر عن الحالة الحالية للمؤجلة. +
-`النتيجة` (`result`) النتيجة المرجعة من المؤجلة. +هذا الصنف عبارة عن قالب لتخزين معلومات المؤجلة لمختلف أنواع النتائج. -`الخطأ` (`error`) الخطأ الذي حصل أثناء محاولة تنفيذ المؤجلة. +#### الحالة (status) -### قرر (resolve) +``` +عرف الحالة: صـحيح؛ +``` -
+
``` -عرف قرر: (نتيجة: نـوع_الـنتيجة)؛ +def status: Int; ```
+يعبر عن الحالة الحالية للمؤجلة. + +#### النتيجة (result) + ``` -handler this.resolve(res: ResultType); +عرف النتيجة: نـوع_الـنتيجة؛ ``` -وظيفة يمكن عن طريقها اقرار المؤجلة بتحويل حالتها من `__جديد__` إلى `__مقرر__` و تخزين النتيجة. +
-المعطيات: +``` +def result: ResultType; +``` -`نتيجة` (`res`) النتيجة التي يجب تخزينها في المؤجلة على أنها نتيجة التنفيذ. +
-
+النتيجة المرجعة من المؤجلة. + +#### الخطأ (error) + +``` +عرف الخطأ: سـندنا[خـطأ]؛ +``` + +
``` -عرف قرر: (م: سـندنا[مـؤجلة[نـوع_الـنتيجة]])؛ +def error: SrdRef[Error]; ```
+الخطأ الذي حصل أثناء محاولة تنفيذ المؤجلة. + +#### قرر (resolve) + +``` +عملية هذا.قرر(نتيجة: نـوع_الـنتيجة)؛ +عملية هذا.قرر(م : سندنا[مـؤجلة[نـوع_الـنتيجة]])؛؛ +``` + +
+ ``` +handler this.resolve(res: ResultType); handler this.resolve(p: SrdRef[Promise[ResultType]]); ``` -قرر نتيجة المؤجلة الحالية باستخدام مؤجلة أخرى. المؤجلة الحالية ستنتظر انتهاء المؤجلة المعطاة -وتستلم نتيجتها سواء كانت مقررة أم مرفوضة. +
-`م` (`p`) المؤجلة المرجو انتظارها واستلام النتيجة منها. +وظيفة يمكن عن طريقها اقرار المؤجلة بتحويل حالتها من `__جديد__` إلى `__مقرر__` و تخزين النتيجة. -### ارفض (reject) +المعطيات: -
+* `نتيجة` (`res`) النتيجة التي يجب تخزينها في المؤجلة على أنها نتيجة التنفيذ. +* `م`(`p`): مؤجل آخر ستنتقل حالته في النهاية إلى المؤجل الحالي. سينتظر المؤجل الحالي اكتمال المؤجل المُعطى، وسيحمل نتيجته. + +### ارفض (reject) ``` -عرف ارفض: (خطأ: سندنا[خـطأ])؛ +عملية هذا.ارفض(خطأ: سندنا[خـطأ])؛ ``` -
+
``` handler this.reject(err: SrdRef[Error]); ``` +
+ وظيفة يمكن عن طريقها رفض المؤجلة بتحويل حالتها من `__جديد__` إلى `__مرفوض__` و تخزين الخطأ الذي حصل. المعطيات: -`خطأ` (`error`) الخطأ الذي يجب تخزينه في المؤجلة على أنه الخطأ الحاصل أثناء التنفيذ. +* `خطأ` (`error`) الخطأ الذي يجب تخزينه في المؤجلة على أنه الخطأ الحاصل أثناء التنفيذ. ### أنشئ (new) -
- ``` -عرف ارفض: (): سندنا[مـؤجلة[نـوع_الـنمط]]؛ +دالة أنشئ (): سندنا[مـؤجلة[نـوع_الـنتيجة]]؛ ``` -
+
``` function new (): SrdRef[Promise[ResultType]]; ``` +
+ قالب وظيفة يمكن عن طريقه إنشاء مؤجلة بنمط قيمة مرجعة محدد. القيمة المرجعة: @@ -263,15 +339,13 @@ function new (): SrdRef[Promise[ResultType]]; ### ثم (then) -
- ``` -عرف [نـوع_ثـم: نوع] ثم( - منادى: دالةـمغلفة(دخل: نـوع_الـنتيجة، مـؤجلة: سند[مـؤجلة[نـوع_ثـم]]) +عملية [نـوع_ثـم: صنف] هذا.ثم( + منادى: مغلفة (دخل: نـوع_الـنتيجة، مـؤجلة: سند[مـؤجلة[نـوع_ثـم]]) ): سندنا[مـؤجلة[نـوع_ثـم]]؛ ``` -
+
``` handler [ThenType: type] this.then( @@ -279,11 +353,13 @@ handler [ThenType: type] this.then( ): SrdRef[Promise[ThenType]]; ``` +
+ قالب وظيفة يمكن من خلاله تحديد ما يجب تنفيذه بعد أن يتم الإنتهاء من تنفيذ مؤجلة. المعطيات: -`منادى` (`callback`) عبارة عن دالة مغلفة تحدد ما الذي يجب تنفيذه كنتيجة للمؤجلة. +* `منادى` (`callback`) عبارة عن دالة مغلفة تحدد ما الذي يجب تنفيذه كنتيجة للمؤجلة. القيمة المرجعة: @@ -291,15 +367,13 @@ handler [ThenType: type] this.then( ### اقبض (catch) -
- ``` -عرف اقبض( - منادى: دالةـمغلفة(خطأ: سندنا[خـطأ]، مـؤجلة: سند[مـؤجلة[نـوع_الـنتيجة]]) +عملية هذا.اقبض( + منادى: مغلفة (خطأ: سندنا[خـطأ]، مـؤجلة: سند[مـؤجلة[نـوع_الـنتيجة]]) ): سندنا[مـؤجلة[نـوع_الـنتيجة]]؛ ``` -
+
``` handler this.catch( @@ -307,11 +381,13 @@ handler this.catch( ): SrdRef[Promise[ResultType]]; ``` +
+ وظيفة يمكن من خلالها تحديد ما يجب تنفيذه عند حدوث خطأ أثناء تنفيذ مؤجلة. المعطيات: -`منادى` (`callback`) عبارة عن دالة مغلفة تحدد ما الذي يجب تنفيذه عند حدوث الخطأ. +* `منادى` (`callback`) عبارة عن دالة مغلفة تحدد ما الذي يجب تنفيذه عند حدوث الخطأ. القيمة المرجعة: @@ -319,26 +395,28 @@ handler this.catch( ### الكل (all) -
- ``` -عرف الكل ( +دالة الكل ( الدخل: مـصفوفة[سندنا[مـؤجلة[نـوع_الـنتيجة]]] -): سندنا[مـؤجلة[نـوع_الـنتيجة]]؛ +): سندنا[مـؤجلة[مـصفوفة[نـوع_الـنتيجة]]]؛ ``` -
+
``` -function all (inputs: Array[SrdRef[Promise[ResultType]]]): SrdRef[Promise[Array[ResultType]]]; +function all ( + inputs: Array[SrdRef[Promise[ResultType]]] +): SrdRef[Promise[Array[ResultType]]]; ``` +
+ دالة يمكن من خلالها تحديد مجموعة من المؤجلات، بحيث تكون المؤجلة المرجعة محققة في حال تحققت كافة المؤجلات، و غير محققة في حال كانت واحدة على الأقل من المؤجلات غير محققة.. المعطيات: -`الدخل` (`inputs`) مجموعة المؤجلات التي تعتمد عليها المؤجلة التي يتم إرجاعها. +* `الدخل` (`inputs`) مجموعة المؤجلات التي تعتمد عليها المؤجلة التي يتم إرجاعها. القيمة المرجعة: @@ -346,18 +424,18 @@ function all (inputs: Array[SrdRef[Promise[ResultType]]]): SrdRef[Promise[Array[ ### تجاهل_النتيجة (ignoreResult) -
- ``` -عرف تجاهل_النتيجة: (): سندنا[مـؤجلة[صـحيح]]؛ +عملية هذه.تجاهل_النتيجة(): سندنا[مـؤجلة[صـحيح]]؛ ``` -
+
``` handler this.ignoreResult(): SrdRef[Promise[Int]]; ``` +
+ وظيفة يمكن من خلالها إهمال نتيجة مؤجلة. يمكن استعمال هذه الوظيفة لإهمال النتيجة في حال استعمال دالة `الكل` لمجموعة من المؤجلات بأصناف مختلفة. @@ -369,17 +447,15 @@ handler this.ignoreResult(): SrdRef[Promise[Int]]; ### حـالة (Status) -
- ``` -صنف حـالة { +عرف حـالة { عرف _جديد_: 0؛ عرف _مقرر_: 1؛ عرف _مرفوض_: 2؛ } ``` -
+
``` def Status: { @@ -389,6 +465,8 @@ def Status: { } ``` +
+ يستعمل هذا الصنف لتحديد حالة المؤجلة. ## المؤجلات العودية (recursive) @@ -429,8 +507,6 @@ def Status: { كي تستخدم العملية `أعد` داخل مغلفة `ثم` تحتاج لتغيير تعريف المعطى الثاني من `مـؤجلة` (`Promise`) إلى `مـؤجلة_ثم` (`ThenPromise`) ثم استخدام الدالة `أعد` (`retry`) على المؤجلة، كما في المثال التالي: -
- ``` عرف مؤجلة: سـندنا[مـؤجلة[رقـم]] = مـؤجلة[رقـم].أنشئ()؛ عرف ثم: سـندنا[مـؤجلة[نـص]] = مؤجلة.ثم[نـص]( @@ -446,7 +522,7 @@ def Status: { } ``` -
+
``` def promise: SrdRef[Promise[Num]] = Promise[Num].new(); @@ -463,13 +539,13 @@ for i = 0, i < 10, ++i { } ``` +
+ ### مـؤجلة_قبض (CatchPromise) كي تستخدم العملية `أعد` داخل مغلفة `اقبض` تحتاج لتغيير تعريف المعطى الثاني من `مـؤجلة` (`Promise`) إلى `مـؤجلة_قبض` (`CatchPromise`) ثم استخدام الدالة `أعد` (`retry`) على المؤجلة، كما في المثال التالي: -
- ``` عرف مؤجلة: سـندنا[مـؤجلة[رقـم]] = مـؤجلة[رقـم].أنشئ()؛ عرف اقبض: سـندنا[مـؤجلة[رقـم]] = مؤجلة.اقبض( @@ -490,7 +566,7 @@ for i = 0, i < 10, ++i { } ``` -
+
``` def promise: SrdRef[Promise[Num]] = Promise[Num].new(); @@ -511,7 +587,7 @@ for i = 0, i < 10, ++i { } ``` ---- +
## الرخصة @@ -519,3 +595,4 @@ for i = 0, i < 10, ++i { هذا المشروع مرخص بموجب رخصة غنو العمومية الصغرى الإصدار 3.0 (LGPL-3.0). راجع ملفات `COPYING` و `COPYING.LESSER` للحصول على التفاصيل. +
diff --git a/README.md b/README.md index 2cc6318..bac765e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Promises + [[عربي]](README.ar.md) A simple Promise library for Alusus Language. @@ -85,110 +86,121 @@ class Promise [ResultType: type] { def status: Int = Status.NEW; def result: ResultType; def error: SrdRef[Error]; + + handler this.resolve(res: ResultType); + handler this.resolve(p: SrdRef[Promise[ResultType]]); + handler this.reject(err: SrdRef[Error]); + handler this.ignoreResult(): SrdRef[Promise[Int]]; + + handler [ThenType: type] this.then( + callback: closure (input: ResultType, promise: ref[Promise[ThenType]]) + ): SrdRef[Promise[ThenType]]; + + handler this.catch( + callback: closure (err: SrdRef[Error], promise: ref[Promise[ResultType]]) + ): SrdRef[Promise[ResultType]]; + + function new (): SrdRef[Promise[ResultType]]; + + function all ( + inputs: Array[SrdRef[Promise[ResultType]]] + ): SrdRef[Promise[Array[ResultType]]]; + + def Status: { + def NEW: 0; + def RESOLVED: 1; + def REJECTED: 2; + } } ``` + A template Promise class where the promise result type is specified by the template argument. -`status` the current state of the promise. +#### status -`result` the result returned from the promise. +``` +def status: Int; +``` -`error` the error that happened while executing the promise. +The current state of the promise. -### resolve +#### result ``` -handler this.resolve(res: ResultType); +def result: ResultType; ``` +The result returned from the promise. -Resolve the promise by switching its status from `NEW` to `RESOLVED` and storing the result. - -parameters: - -`res` the result to be stored in the promise as the execution result. +#### error ``` -handler this.resolve(p: SrdRef[Promise[ResultType]]); +def error: SrdRef[Error]; ``` -Resolve the promise using another promise. The current promise will wait for the given -promise to be complete and will carry its result. +The error that happened while executing the promise. + +#### new -`p` the promise whose status will eventually propagate to the current promise. +``` +function new(): SrdRef[Promise[ResultType]]; +``` +Creates a new promise with a status of `new`. Returns a reference to the promise of the specified type. -### reject +#### resolve ``` -handler this.reject(err: SrdRef[Error]); +handler this.resolve(res: ResultType); +handler this.resolve(p: SrdRef[Promise[ResultType]]); ``` -Reject the promise by switching its status from `NEW` to `REJECTED` and storing the error. -parameters: +Resolve the promise by switching its status from `NEW` to `RESOLVED` and storing the result. -`error` the error to be stored in the promise as the error that stops the execution. +* `res`: The result to be stored in the promise as the execution result. +* `p`: Another promise whose status will eventually propagate to the current promise. The current promise will wait for the given promise to be complete and will carry its result. -### new +#### reject ``` -function new (): SrdRef[Promise[ResultType]]; +handler this.reject(err: SrdRef[Error]) ``` -Creates a new promise with a status of `new`. - -return value: +Reject the promise by switching its status from `NEW` to `REJECTED` and storing the error. -A reference to the promise of the specified type. +* `err`: The error to be stored in the promise as the error that stops the execution. -### then +#### then ``` handler [ThenType: type] this.then( callback: closure (input: ResultType, promise: ref[Promise[ThenType]]) ): SrdRef[Promise[ThenType]]; ``` -A template method to determine what needs to be executed after this promise is resolved. -parameters: +A template method to determine what needs to be executed after this promise is resolved. Returns a reference to a promise with the specified result type. -`callback` a closure to be called when the promise is resolved. +* `callback`: A closure to be called when the promise is resolved. -return value: - -A reference to a promise with the specified result type. - -### catch +#### catch ``` handler this.catch( callback: closure (err: SrdRef[Error], promise: ref[Promise[ResultType]]) ): SrdRef[Promise[ResultType]]; ``` -A method to determine what needs to be executed when an error occurred (when the promise is rejected). - -parameters: - -`callback` a closure to be called when the promsie is rejected. -return value: +A method to determine what needs to be executed when an error occurred (when the promise is rejected). Returns a reference to a promise with the specified result type. -A reference to a promise with the specified result type. +* `callback`: A closure to be called when the promise is rejected. -### all +#### all ``` -function all (inputs: Array[SrdRef[Promise[ResultType]]]): SrdRef[Promise[Array[ResultType]]]; +function all(inputs: Array[SrdRef[Promise[ResultType]]]): SrdRef[Promise[Array[ResultType]]]; ``` -Specify a set of promises, so that we consider the promise resolved when all of those promises are resolved, -and rejected when at least one of them is rejected. +Specify a set of promises, so that we consider the promise resolved when all of those promises are resolved, and rejected when at least one of them is rejected. Returns a reference to a promise with the specified result type. -parameters: +* `inputs`: A set of promises with the same result type. -`inputs` a set of promises with the same result type. - -return value: - -A reference to a promise with the specified result type. - -### ignoreResult +#### ignoreResult ``` handler this.ignoreResult(): SrdRef[Promise[Int]]; @@ -197,14 +209,9 @@ Ignore promise's result. This method can be used to ignore the result while using the `all` function, when the set of promises provied to `all` do not have the same result type, since `all` function needs a set of promises with the same type, otherwise, the -compiler will give us an error. - -return value: +compiler will give us an error. Returns a reference to a promise with an `Int` result type, and a result equal to `0`. This integer result has no meaning and is only used because using the type of Void was not straight forward. -A reference to a promise with an `Int` result type, and a result equal to `0`. This integer result has no meaning -and is only used because using the type of Void was not straight forward. - -### Status +#### Status ``` def Status: { @@ -213,7 +220,8 @@ def Status: { def REJECTED: 2; } ``` -This three states of a promsie. + +The three states of a promsie. ## Recursive Promises @@ -296,11 +304,8 @@ for i = 0, i < 10, ++i { } ``` ---- - ## License Copyright (C) 2026 Sarmad Abdullah -This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. - +This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the `COPYING` and `COPYING.LESSER` files for details. \ No newline at end of file