عرض مصدر Kotlin/annotations

<noinclude>{{DISPLAYTITLE:التوصيفات (Annotations) في لغة Kotlin}}</noinclude>
== التصريح عن التوصيف (Annotation Declaration) ==
تُعدُّ التوصيفات إحدى الوسائل لإضافة بياناتٍ توصيفيّةٍ (metadata) إلى الشيفرة، وللتصريح عن التوصيف يُضاف المُحدِّد <code>annotation</code> قبل اسم الصنف، مثل:<syntaxhighlight lang="kotlin">
annotation class Fancy
</syntaxhighlight>وقد تُحدَّد بعض خواصّ التوصيفات (annotation attributes) باستخدام التوصيفات الآتية (meta-annotations) لتوصيفات الصنف:
* <code>‎@Target</code> لتحديد نوع العناصر التي يمكن توصيفها مثل الأصناف (classes) والدوال (functions) والخاصّيّات (properties) والتعابير (expressions) و... إلخ.
* ‎<code>@Retention</code> لتحديد فيما إن كان التوصيف مُخزَّنًا في ملفات الأصناف المُترجَمة، أو مرئيًا عبر انعكاسٍ (reflection) أثناء التنفيذ (runtime) (وكلاهما محقُّق بالحالة الافتراضية)
* ‎<code>@Repeatable</code> للسماح باستخدام نفس التوصيف على كائن واحدٍ لعدّة مرات
* ‎<code>@MustBeDocumented</code>  لتحديد التوصيف كجزءٍ من الواجهة العامّة (public API) يجب تضمينه في الصنف (class) أو ترويسة التابع (method signature) الموجودَين في التوثيق المُولَّد للواجهة API
'''مثال:'''<syntaxhighlight lang="kotlin">
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION,
        AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.EXPRESSION)
@Retention(AnnotationRetention.SOURCE)
@MustBeDocumented
annotation class Fancy
</syntaxhighlight>

=== الاستخدام (Usage) ===
ليكن الصنف Foo الآتي:<syntaxhighlight lang="kotlin">
@Fancy class Foo {
    @Fancy fun baz(@Fancy foo: Int): Int {
        return (@Fancy 1)
    }
}
</syntaxhighlight>لتوصيف الباني الأساسيّ (primary constructor) للصنف تجب إضافة الكلمة المفتاحيّة <code>constructor</code> إلى تصريحه مسبوقةً بالتوصيف كما في الشيفرة:<syntaxhighlight lang="kotlin">
class Foo @Inject constructor(dependency: MyDependency) {
    // ...
}
</syntaxhighlight>كما ويمكن توصيف الوصول (accessing) إلى الخاصّيّات (get أو set) كما في الشيفرة:<syntaxhighlight lang="kotlin">
class Foo {
    var x: MyDependency? = null
        @Inject set
}
</syntaxhighlight>

=== البواني (Constructors) ===
وقد يكون للتوصيفات بوانٍ تقبل المعاملات (parameters)، مثل:<syntaxhighlight lang="kotlin">
annotation class Special(val why: String)

@Special("example") class Foo {}
</syntaxhighlight>حيث يُسمَح بأنواع المعاملات الآتية:
* الأنواع الموافقة للأنواع الأساسيّة (primitive) في لغة Java  (مثل int و Long و... وإلخ.)
* السلاسل النصيّة (strings)
* الأصناف (classes) (بالصيغة <code>Foo::class</code>)
* الثوابت المتعدِّدة (enums)
* التوصيفات الأخرى
* مصفوفة (array) من أيّ من الأنواع السابقة
ولا يُسمَح أن تكون هذه الأنواع nullable لأن JVM لا تدعم تخزين القيمة <code>null</code> في خاصّة التوصيف (annotation attribute).

وعند استخدام التوصيف كمعاملٍ (parameter) لتوصيفٍ آخر فلا يُسبَق اسمه بالرمز <code>@</code> مثل:<syntaxhighlight lang="kotlin">
annotation class ReplaceWith(val expression: String)

annotation class Deprecated(
        val message: String,
        val replaceWith: ReplaceWith = ReplaceWith(""))

@Deprecated("This function is deprecated, use === instead", ReplaceWith("this === other"))
</syntaxhighlight>وعند تحديد الصنف (class) كوسيطٍ للتوصيف فيُستخدَم صنف Kotlin والمُسمّى <code>KClass</code> ، والذي يُحوِّله المُترجِم إلى صنف Java تلقائيًا بحيث تصبح شيفرة Java قادرةً على رؤية التوصيفات والوسائط بشكلٍ طبيعيّ، مثل:<syntaxhighlight lang="kotlin">
import kotlin.reflect.KClass

annotation class Ann(val arg1: KClass<*>, val arg2: KClass<out Any>)

@Ann(String::class, Int::class) class MyClass
</syntaxhighlight>

=== تعابير Lambdas ===
تُضاف التوصيفات لتعابير lambdas عبر تطبيقها على التابع <code>inoke()</code>‎ الذي من خلاله ستُولَّد بُنية lambda، وهذا يُفيد في بيئات العمل (frameworks ) مثل [http://www.paralleluniverse.co/quasar/ Quasar] التي تستخدِم التوصيفات للتحكم بالتزامن (concurrency)، مثل:<syntaxhighlight lang="kotlin">
annotation class Suspendable

val f = @Suspendable { Fiber.sleep(10) }
</syntaxhighlight>

== أهداف مواقع استخدام التوصيفات (Annotation Use-site Targets) ==
عند توصيف إحدى الخاصّيّات (property) أو معاملات الباني الأساسي (primary constructor parameter) فهناك الكثير من عناصر Java المُولَّدة من عناصر Kotlin الموافقة لها، وبالتالي تتعدّد المواقع المُمكِنة لاستخدام التوصيف في شيفرة Java bytecode المُولَّدة، ولتحديد كيفيّة توليد التوصيف بشكلٍ دقيقٍ، تُستخدَم الصيغة الآتية:<syntaxhighlight lang="kotlin">
class Example(@field:Ann val foo,    // توصيف حقل Java
              @get:Ann val bar,      // توصيف الوصول عبر getter
              @param:Ann val quux)   // توصيف باني أساسي
</syntaxhighlight>وبالإمكان استخدام نفس الصيغة السابقة لتوصيف كامل الملفّ، إذ يُوضَع التوصيف بالهدف <code>file</code> في المستوى الأعلى (top-level) من الملف قبل مُوجِّه الحزمة (package directive) أو قبل أيٍّ من عمليات الاستيراد (import) إن كان الملف واقعًا في الحزمة الافتراضية، مثل:<syntaxhighlight lang="kotlin">
@file:JvmName("Foo")

package org.jetbrains.demo
</syntaxhighlight>وعند وجود أكثر من توصيفٍ بنفس الهدف تُضاف الأقواس <code>[]</code> بعد الهدف مباشرةً ويُوضع كامل التوصيف داخلها وذلك لمنع التكرار ، مثل:<syntaxhighlight lang="kotlin">
class Example {
     @set:[Inject VisibleForTesting]
     var collaborator: Collaborator
}
</syntaxhighlight>تدعم لغة Kotlin القائمة الآتية من الأهداف:
* <code>file</code>
* <code>property</code> (توصيف هذا الهدف غير مرئيٍّ بالنسبة للغة Java)
* <code>field</code> 
* <code>get</code> (الحصول على الخاصّيّة عبر getter)
* <code>set</code> (ضبط الخاصّيّة عبر setter)
* <code>receiver</code> (معامل المستقبِل للدالة الإضافيّة [extension function] أو الخاصّيّة)
* <code>param</code> (معامل الباني [constructor])
* <code>setparam</code> (معامل ضبط الخاصّيّة عبر setter)
* <code>delegate</code> (حقل تخزين نسخة التعميم (delegate instance) من الخاصّيّات المُعمَّمة)
ولتوصيف معامل المستقبِل (receiver parameter) في الدالة الإضافيّة (extension function) تُستخدَم الصيغة الآتية:<syntaxhighlight lang="kotlin">
fun @receiver:Fancy String.myExtension() { }
</syntaxhighlight>وإن لم يُحدَّد هدف موقع الاستخدام (use-site target) فسيصبح الهدف بحسب توصيف ‎<code>@Target</code> من التوصيف المُستخدَم، أمّا إن كان هناك أكثرُ من هدفٍ محتملٍ، فسيتم اعتماد أولّ عنصرٍ ممكنٍ من هذه القائمة:
* <code>aram</code>
* <code>property</code>
* <code>field</code>

== التوصيفات في لغة Java ==
تتوافق التوصيفات في لغة Java بشكل تامّ مع لغة Kotlin، مثل:<syntaxhighlight lang="kotlin">
import org.junit.Test
import org.junit.Assert.*
import org.junit.Rule
import org.junit.rules.*

class Tests {
    // تطبيق التوصيف @Rule
    // على الوصول للخاصية عبر getter
    @get:Rule val tempFolder = TemporaryFolder()

    @Test fun simple() {
        val f = tempFolder.newFile()
        assertEquals(42, getTheAnswer())
    }
}
</syntaxhighlight>إذ لا يمكن استخدام الصيغة الاعتياديّة لاستدعاء الدالة لتمرير الوسائط (arguments passing) لأن ترتيب الوسائط في التوصيف المكتوب بلغة Java غير معرَّف، بل تُستخدَم بدلًا عن ذلك صيغة الوسائط المُسمّاة كما في الشيفرة:<syntaxhighlight lang="java">
// Java شيفرة
public @interface Ann {
    int intValue();
    String stringValue();
}
</syntaxhighlight>وفي لغة Kotlin بالشكل:<syntaxhighlight lang="kotlin">
// Kotlin شيفرة
@Ann(intValue = 1, stringValue = "abc") class C
</syntaxhighlight>وكما هو الحال في لغة Java فإن المعامل  <code>value</code> هو حالةٌ خاصةٌ لأن قيمته تُحدَّد بدون استخدام اسمٍ صريحٍ (explicit)، كما في الشيفرة:<syntaxhighlight lang="java">
// Java شيفرة
public @interface AnnWithValue {
    String value();
}
</syntaxhighlight>وفي لغة Kotlin:<syntaxhighlight lang="kotlin">
// Kotlin شيفرة
@AnnWithValue("abc") class C
</syntaxhighlight>

=== استخدام المصفوفات كمعاملات للتوصيف ===
إن كان الوسيط<code>value</code> في لغة Java  مصفوفةً فسيصبح معاملًا من النوع <code>vararg</code> في لغة Kotlin، مثل:<syntaxhighlight lang="java">
// Java شيفرة
public @interface AnnWithArrayValue {
    String[] value();
}
</syntaxhighlight>وفي لغة Kotlin تصبح الشيفرة:<syntaxhighlight lang="kotlin">
// Kotlin شيفرة
@AnnWithArrayValue("abc", "foo", "bar") class C
</syntaxhighlight>أمّا إن كانت الوسائط الأخرى على شكل مصفوفاتٍ فيجب استخدام صيغة القيم المباشرة (literals) للمصفوفة (بدءًا من الإصدار Kotlin 1.2 ) أو استخدام <code>arrayOf(...)</code>‎، مثل:<syntaxhighlight lang="java">
// Java شيفرة
public @interface AnnWithArrayMethod {
    String[] names();
}
</syntaxhighlight>وتصبح في لغة Kotlin:<syntaxhighlight lang="kotlin">
// Kotlin 1.2 بدءًا من الإصدار
@AnnWithArrayMethod(names = ["abc", "foo", "bar"]) 
class C

// الإصدارات الأقدم
@AnnWithArrayMethod(names = arrayOf("abc", "foo", "bar")) 
class D
</syntaxhighlight>

=== الوصول إلى الخاصّيّات (Properties) عبر نسخة التوصيف (Annotation Instance) ===
تظهر قيم نسخة التوصيف (annotation instance) وكأنها خاصّيّات في شيفرة Kotlin كما يلي:<syntaxhighlight lang="java">
// Java شيفرة
public @interface Ann {
    int value();
}
</syntaxhighlight>وتصبح في لغة Kotlin:<syntaxhighlight lang="kotlin">
// Kotlin شيفرة
fun foo(ann: Ann) {
    val i = ann.value
}
</syntaxhighlight>

== مصادر<span> </span> ==
* [https://kotlinlang.org/docs/reference/annotations.html صفحة التوصيفات في التوثيق الرسميّ للغة Kotlin]
[[تصنيف:Kotlin]]
[[تصنيف:Kotlin Java]]
[[تصنيف:Kotlin Annotations]]
[[تصنيف:Kotlin Property]]