عرض مصدر Kotlin/visibility modifiers

<noinclude>{{DISPLAYTITLE:مُحدِّدات الوصول (Visibility Modifiers) في لغة Kotlin}}</noinclude>
تُعيِّن مُحدِّدات الوصول قابليةَ الوصول إلى كلٍّ من الأصناف (classes) والكائنات (objects) والواجهات (interfaces) والدوال (functions) والخاصّيّات (properties) ودوال الوصول إليها من النوع setters (لأن مُحدِّد الوصول إلى getter مماثلٌ للوصول إلى الخاصّيّة نفسها)، وهناك أربعة أنواعٍ من المُحدِّدات وهي: <code>private</code> و <code>protected</code> و <code>internal</code> و <code>public</code> والنوع الافتراضيّ منها هو <code>public</code> (يُستخدم عند عدم وجود تصريحٍ عن إحداها)، وفيما يلي شرح لكيفيّة تطبيق المُحدِّدات على أنواعٍ مختلفةٍ من التصريحات (declarations).

== الحزم (Packages) ==
يمكن تعريف كلٍّ من الدوال والخاصّيّات والأصناف والكائنات والواجهات في المستوى الأعلى (top-level) أيّ داخل الحزمة مباشرةً، مثل:<syntaxhighlight lang="kotlin">
package foo

fun baz() {}
class Bar {}
</syntaxhighlight>ويُلاحظ ما يلي:

- إذا لم تُحدَّد مرئية الوصول فهي عامّة <code>public</code> بالحالة الافتراضيّة، وهذا يعني أنّ العنصر سيكون متاحًا بأيّ مكانٍ.

- تحديد المرئية بالنوع الخاصّ <code>private</code> سيجعل من العنصر مرئيًا داخل الملفّ (file) الذي يحتوي على تصريحه فقط.

- تحديد المرئية بالنوع <code>internal</code> سيجعل العنصر مرئيًا داخل الوحدة (module) ذاتها.

- ولا يًتاح النوع <code>protected</code> في التصريحات ذات المستوى الأعلى (top-level).

ملاحظة: لاستخدام أيّ تصريحٍ مرئيٍّ بالمستوى الأعلى (top-level) في حزمةٍ أخرى تستطيع استخدام أمر الاستيراد <code>[[Kotlin/packages|import]]</code> للحصول عليه.

مثال:<syntaxhighlight lang="kotlin">
// اسم الملفexample.kt
package foo

private fun foo() {} // مرئي داخل الملف example.kt

public var bar: Int = 5 // الخاصية مرئية في كل مكان
    private set         // محدد الوصول هذا متاح فقط ضمن الملف example.kt
    
internal val baz = 6    // مرئي ضمن حدود الوحدة (module)
</syntaxhighlight>

== الأصناف (Classes) والواجهات (Interfaces) ==
عند التصريح عن العناصر المُعرَّفة داخل الأصناف تكون إحدى الحالات الآتية:

- مُحدِّد الوصول <code>private</code>: يعني أن العنصر مرئيٌّ داخل الصنف فقط (متضمنًا العناصر الأخرى الموجودة فيه).

- مُحدِّد الوصول <code>protected</code>: مثل مرئيّة المُحدِّد <code>private</code> ويُضاف عليه أن العنصر مرئيٌّ أيضًا في الأصناف الفرعيّة (subclasses) لهذا الصنف.

- مُحدِّد الوصول <code>internal</code>: إن أيّ عميلٍ (client) يستطيع الوصول للصنف الذي يحتوي على التصريحات (داخل هذه الوحدة [module])  يستطيع أيضًا رؤية العناصر الداخلية (internal) فيه.

- مُحدِّد الوصول <code>public</code>: إن أيّ عميلٍ (client) يستطيع الوصول للصنف الذي يحتوي على التصريحات يستطيع أيضًا رؤية العناصر العامّة (public) الموجودة فيه.

'''ملاحظة لمبرمجي Java:''' يختلف الأمر في Kotlin إذ إنّ الأصناف الخارجية (outer classes) لا تستطيع الوصول إلى أيّ من العناصر الخاصّة (private) الموجودة في أصنافها الداخلية (inner classes).

وعند إعادة تعريف عنصرٍ مُحدَّد بالوصول من النوع <code>protected</code> دون التحديد الصريح لمرئيّة الوصول له فإنّ المُحدِّد سيكون من النوع <code>protected</code> أيضًا.

مثال:<syntaxhighlight lang="kotlin">
open class Outer {
    private val a = 1
    protected open val b = 2
    internal val c = 3
    val d = 4  // عامٌّ بالحالة الافتراضية
    
    protected class Nested {
        public val e: Int = 5
    }
}

class Subclass : Outer() {
    // a غير مرئية
    // bو c و d مرئية
    // e مرئية
    // Nested الصنف مرئي 

    override val b = 5   // من النوع المحمي protected
}

class Unrelated(o: Outer) {
    // o.a, o.b غير مرئية
    // o.c , o.d مرئية لأنها في نفس الوحدة 
    // Outer.Nested غير مرئي
    // Nested::e غير مرئية أيضًا 
}
</syntaxhighlight>

=== البواني (Constructors) ===
تُستخدَم الصيغة الآتية لتحديد مرئية الباني الأساسي (primary constructor) في الصنف: (لاحظ عدم وجود الكلمة المفتاحية <code>constructor</code>)<syntaxhighlight lang="kotlin">
class C private constructor(a: Int) { ... }
</syntaxhighlight>إذ إنّ نوع الباني في الشيفرة السابقة من النوع الخاص (private) بسبب التصريح الواضح عن ذلك حيث أن الحالة الافتراضيّة للبواني هي العامّة (public) مما يجعلها مُتاحةً في كلّ مكانٍ يكون الصنف فيه مرئيًا (أي أن الباني الموجود في الصنف من النوع <code>internal</code> يكون مرئيًا في نفس الوحدة [module] فقط)

=== التصريحات المحلية (Local Declarations) ===
لا يمكن تحديد مرئيّة الوصول للتصريحات أو الدوال أو الأصناف المحليّة.

== الوحدات (Modules) ==
إن مُحدِّد الوصول <code>internal</code> يعني أنّ هذا العنصر مرئيٌّ في نفس الوحدة الموجود فيها، وبكلامٍ أكثر دقةٍ؛ إنّ الوحدة هي مجموعةٌ من الملفات المكتوبة بلغة Kotlin والتي تُترجَم (compiled) سويةً مثل:
* وحدة IntelliJ IDEA
* مشروع Maven
* مجموعةٌ مصدريةٌ (source set) في Gradle (باستثناء أنّ المجموعة المصدرية <code>test</code> تستطيع الوصول إلى التصريحات الداخليّة في <code>main</code>)
* مجموعة الملفات المُترجَمة عبر استدعاءٍ واحدٍ لمهمة Ant.

== مصادر ==
* [https://kotlinlang.org/docs/reference/visibility-modifiers.html صفحة مُحدِّدات الوصول في التوثيق الرسميّ للغة Kotlin]
[[تصنيف:Kotlin]]
[[تصنيف:Kotlin Modifiers]]
[[تصنيف:Kotlin Accessors]]
[[تصنيف:Kotlin Members]]