包的声明#

包声明以关键字package开头, 后接root包至当前包路径上所有包的包名, 以.分隔(路径本身不是包名)

包声明的语法如下:

1
packageHeader
2
    : packageModifier? (MACRO NL*)? PACKAGE NL* fullPackageName end+
3
    ;
4

5
fullPackageName
6
    : (packageNameIdentifier NL* DOT NL*)* packageNameIdentifier
7
    ;
8

9
packageNameIdentifier
10
    : Ident
11
    | contextIdent
12
    ;
13

14
packageModifier
15
    : PUBLIC
16
    | PROTECTED
17
    | INTERNAL
18
    ;

每个包都有包名, 包名是这个包可唯一识别的标识符

除root包外, 包名必须和其所在的目录名一致

包声明必须在文件的首行(注释和空白字符不计), 每个文件只能有一个package声明

特别地, root包的文件可以不声明package, 对于不包含package声明的文件, 它会用default作为包名

1
// 省略包声明相当于'package default'
2

3
main() {
4
    println("Hello World")
5
}

package可以被internal、protected或者public修饰

package的默认修饰符(默认修饰符是指在省略情况下的修饰符语义, 这些默认修饰符也允许显式写出)为public

同一个包在不同文件中的package声明必须使用相同的访问修饰符修饰

特别地, root包不能被internal或者protected修饰

• internal表示仅当前包及子包(包括子包的子包)内可见

  当前包的子包(包括子包的子包)内可以导入这个包或者这个包的成员

• protected表示仅当前module内可见

  同一个module内的其它包可以导入这个包或者这个包的成员, 不同module的包无法访问

• public表示module内外均可见

  其它包可以导入这个包或者这个包的成员

仓颉中, 声明包的语法是包修饰词 package 包名

在.cj文件中声明包, 就表示此文件属于所声明的包, 当然 前提是目录结构合法

如果不显式声明包, 则package default

包名是一个路径, 如果是子包, 需要声明为package 父包.子包, 用.分割路径

修饰顶层元素#

在修饰顶层元素时不同访问修饰符的语义如下:

• private表示仅当前文件内可见

  不同的文件无法访问这类成员

• internal表示仅当前包及子包(包括子包的子包)内可见

  同一个包内可以不导入就访问这类成员, 当前包的子包(包括子包的子包)内可以通过导入来访问这类成员

• protected表示仅当前module内可见

  同一个包的文件可以不导入就访问这类成员, 不同包但是在同一个module内的其它包可以通过导入访问这些成员, 不同module的包无法访问

• public表示module内外均可见

  同一个包的文件可以不导入就访问这类成员, 其它包可以通过导入访问这些成员

	File	Package & Sub-Packages	Module	All Packages
private	Y	N	N	N
internal	Y	Y	N	N
protected	Y	Y	Y	N
public	Y	Y	Y	Y

不同顶层声明支持的访问修饰符和默认修饰符规定如下:

• pacakge支持使用internal、protected、public, 默认修饰符为public

• import支持使用全部访问修饰符, 默认修饰符为private

• 其他顶层声明支持使用全部访问修饰符, 默认修饰符为internal

除internal之外, C++中也存在另外三个修饰词, 但 C++中的访问修饰符是用于类成员的, 用来声明成员可访问性

仓颉中的访问修饰符, 还可以修饰包成员的可访问性

修饰非顶层成员#

在修饰非顶层成员时不同访问修饰符的语义如下:

private表示仅当前类型或扩展定义内可见

internal表示仅当前包及子包(包括子包的子包)内可见

protected表示当前module及当前类的子类可见

public表示module内外均可见

	Type/Extend	Package & Sub-Packages	Module & Sub-Classes	All Packages
private	Y	N	N	N
internal	Y	Y	N	N
protected	Y	Y	Y	N
public	Y	Y	Y	Y

类型成员的访问修饰符 可以不同于 类型本身

除接口外类型成员的默认修饰符(默认修饰符是指在省略情况下的修饰符语义, 这些默认修饰符也允许显式写出)是internal

接口中的成员函数和属性不可以写访问修饰符, 它们的访问级别等同于public

包内可见, 即表示 在本包内定义的实例, 可以通过实例访问类成员

protected是module以及子类可以见的, 也就表示 如果不同属一个module, 此类成员是无法访问的

protected和internal, 这两个修饰符, 在刚接触包可能会出现混淆:

一个是module及子类可见, 一个是当前包及子包可见, 但module就是一个包含父子关系的包链, 那么这两个有什么区别?

区别在于, protected修饰类成员, 父包也是可见的, 而internal只能当前包和子包

而private和public则是两个极端, 只类内可见 或 全部可见没有限制

访问修饰符的合法性检查#

仓颉的访问级别排序为public>protected>internal>private

类型的访问级别:

• 非泛型类型的访问级别 由 类型声明的访问修饰符 决定

• 泛型实例化类型的访问级别等同于该泛型类型与该泛型类型实参的访问级别中最低的一个

一个声明的访问修饰符 不得高于 该声明中用到的类型的访问修饰符的级别

具体地:

• 变量、属性声明的访问级别不得高于其类型的访问级别

• 函数声明的访问级别不得高于参数类型、返回值类型, 以及where约束中的类型上界的访问级别

• 类型别名的访问级别不得高于原类型的访问级别

• 类型声明的访问级别不得高于where约束中的类型上界的访问级别

• 子包的访问级别不得高于其父包的访问级别

• import的访问修饰符不得高于其导入声明的访问级别

1
private open class A {}
2

3
protected let a = A()                     // error: 使用 private 类型 A, 声明 protected 变量 a
4
let (a, b) = (A(), 1)                     // error: 使用 private 类型 A, 声明 internal 变量 a
5

6
func f(_: A) {}                           // error: 使用 private 类型 A, 声明 internal 函数 f
7
func f() { A() }                          // error: 使用 private 类型 A, 声明 internal 函数 f
8
func f<T>() where T <: A {}               // error: 使用 private 类型 A, 声明 internal 函数 f
9

10
public type X = A                         // error: 使用 private 类型 A, 声明 public 类型 X
11
public type ArrayA = Array<A>             // error: 使用 private 类型 A, 声明 public 类型 ArrayA
12

13
protected struct S<T> where T <: A {}     // error: 使用 private 类型 A, 约束 protected struct S<T>
14

15
// src/a.cj
16
public package a
17

18
// src/a/b/b.cj
19
protected package a.b                     // ok
20

21
// src/a/b/c/c.cj
22
public package a.b.c                      // error

当你在使用一个类型时, 可能使用这个类型进行 定义变量、声明别名、导入此包 等

这些操作也可以使用访问修饰符修饰, 所以你不能 在进行这些操作的时候 尝试使用更大权限的修饰符去进行提权

特别地, 类继承时 子类访问级别 与 父类访问级别、类型实现/继承接口时 子类型访问级别 与 父接口访问级别 不受上述规则限制

1
private open class A {}
2
public enum E { U | V }
3
interface I {}
4

5
public class C <: A {}                    // ok
6

7
public interface J <: I {}                // ok
8

9
extend E <: I {}                          // ok

继承和实现接口时, 不需要在意访问修饰符的限制

单导入#

单导入语法用来导入单个成员, 目标成员必须是对当前包可见的

导入的成员名称会作为当前作用域内可以访问的名称

import语法中的路径最后一个名称表示指定的成员, 这个名称可以是顶层变量、函数、类型, 也可以是包

下面是导入顶层变量、函数、类型的例子:

有两个包分别是a和b, 在b包中导入a包的成员

1
package a
2

3
public let x = 0
4
public func f() { 0 }
5
public class A {}

1
import a.x
2
import a.f
3
import a.A
4

5
private func g(_: A) { x + f() }        // ok

单导入, 是指导入某个包, 或包中的指定可见成员

需要导入完整的路径, 最后一个标识符可以在包内直接使用

如下所示的例子中, c是a的子包

1
package a.c
2

3
public let y = 1
4

5
import a

1
private func g(_: a.A) { a.x + a.f() }    // ok
2
privage func h(_: A) {                    // error: 未声明的标识符 A
3
    x + f()                               // error: 未声明的标识符 x and f
4
}
5
let _ = a.c.y                             // error: c 不是 a 的成员
6
let _ = a                                 // error: 未声明的标识符 a

1
import a.c
2

3
let _ = c.y                               // ok

单导入的成员被当前包成员遮盖时, 编译器会给出告警提示无用导入

1
import a.x                                // warning: 导入的 x 被遮盖
2
import a.f                                // warning: 导入的 f 被遮盖
3

4
func f() { 1 }
5

6
let x = 1
7
let _ = f()                               // ok, 调用在本包中定义的 f(), 值为 1

单导入, 如果导入包, 则可以通过包名访问目标包的可见成员

别名导入#

别名导入可以使用as语法为导入成员重命名

以别名导入的内容, 在当前包中只会以别名的形式引入作用域, 而不会引入原来的名称(但不禁止分别导入原名和别名)

导入的内容可以是包或者包的成员

1
package a
2

3
public let x = 0
4
public let y = 1
5
public func f() { 0 }

1
import a as pkgA
2
import a.x as x1
3
import a.x as x2          // ok
4

5
let _ = 5                 // error: 未声明的标识符 'x'
6
let _ = a.x               // error: 未声明的标识符 'a'
7
let _ = x1                // ok
8
let _ = x2                // ok
9
let _ = pkgA.x            // ok
10
let _ = pkgA.x1           // error: 'x1' 不是 'pkgA' 的成员

全导入#

全导入通过*语法导入其他包中所有对当前包可见的顶层成员(不包括子包)

示例如下:

1
package a
2

3
public let x = 0
4
public func f() { 0 }
5
public class A {}

1
import a.*
2

3
private func g(_: A) { x + f() }    // ok

与单导入不同, 当全导入的成员被当前包成员遮盖时, 编译器不会给出告警

1
import a.*
2

3
let x = 1
4
func f() { x }                      // ok, x 定义在本包中
5

6
let _ = f()                         // ok, 调用在本包中定义的 f(), 值为 1

全导入, 顾名思义 即 一次性导入目标包中的所有可见成员

导入的成员同样可以构成 重载和遮盖

如果导入的成员 不被当前包的成员遮盖, 但多个导入成员重名时, 编译器不会给出告警

但如果这些重名的导入不构成重载, 这个名字在本包中不可用, 在使用该名称时 编译器会因无法找到唯一的名称而报错

1
package b
2

3
public let x = 1
4
public func f(x: Int64) { x }

1
import a.*
2
import b.*
3

4
let _ = x                     // error: 不可确定的 x

如果导入的重名成员可以构成函数重载, 调用时会根据 [泛型函数重载] 和 [函数重载] 的规则进行函数决议

1
import a.*
2
import b.*
3

4
func f(b: Bool) { b }
5

6
let _ = f()                   // ok, 调用 a.f
7
let _ = f(1)                  // ok, 调用 b.f
8
let _ = f(true)               // ok, 调用在本包中定义的 f()

导入多个不构成遮盖也不构成重载的同名成员时, 不会警告, 只是会在调用时无法找到唯一可用名称报错

带访问修饰符的全导入 不会导入 比其访问级别低的声明

1
package a
2
protected import a.b.*
3
let _ = x                   // ok
4
let _ = y                   // ok
5
let _ = z                   // error: 未声明的标识符 'z'

1
package a.b
2

3
public let x = 0
4
protected let y = 1
5
internal let z = 2

包导入时, 也是可以使用访问修饰符的, 可以在导入成员时 指定原包中满足目标可访问等级的成员被导入

批量导入#

批量导入使用{}语法, 在一个import声明里同时导入多个成员

通常用来省略重复的包路径前缀

批量导入的{}中支持单导入、别名导入和全导入, 但不允许嵌套批量导入

1
import std.{
2
    time,
3
    fs as fileSystem,
4
    io.*,
5
    collection.{ HashMap, HashSet }       // syntax error
6
}

{}的前缀可以为空

1
import {
2
    std.time,
3
    std.fs as fileSystem,
4
    std.io.*,
5
}

使用批量导入语法与使用多个独立import的语法是等价的

1
import std.{
2
    os.process,
3
    time,
4
    io.*,
5
    fs as fileSystem
6
}

等价于:

1
import std.os.process
2
import std.time
3
import std.io.*
4
import std.fs as fileSystem

嵌套导入, 可以在{}前加上包路径, 然后在{}内批量添加要导入的成员, 用, 分隔

导入名称冲突检查#

如果多个单导入的名称产生重名(包括重复导入)且不构成函数重载, 并且该名字在本包中没有被遮盖, 编译器会给出名称冲突告警, 这个名字在本包中不可用, 在使用该名称时编译器会因无法找到唯一的名称而报错

若该名称被当前包成员遮盖时, 编译器会给出告警提示无用导入

1
package b
2

3
public let x = 1
4
public func f(x: Int64) { x }

1
package c
2
public let f = 0

1
import a.x                      // warning: 导入的 'x' 被遮盖
2
import a.x                      // warning: 导入的 'x' 被遮盖
3
import b.x                      // warning: 导入的 'x' 被遮盖
4

5
let x = 0
6
let y = x                       // y = 0

1
import a.x
2
import a.x                      // warning: 'x' 已经被导入了
3
import b.x                      // warning: 'x' 已经被导入了
4

5
let _ = x                       // error: 无法确定的 'x'

如果导入的重名成员之间或者导入的成员与当前包中的同名函数之间可以构成函数重载, 调用时会根据 [泛型函数重载] 和 [函数重载] 的规则进行函数决议

1
import a.f
2
import b.f
3

4
func f(b: Bool) { b }
5

6
let _ = f()                   // ok, 调用 'a.f'
7
let _ = f(1)                  // ok, 调用 'b.f'
8
let _ = f(true)               // ok, 调用 在本包中定义的 f()

当重复导入 但发生遮盖时, 不会出现错误, 只会出现被遮盖的警告

当重复导入 发生重载时, 更可以正常的使用

只有重复导入, 但没有发生重载也没有发生遮盖, 才会出现无法确定的目标的错误

多个别名导入同名, 或者别名导入 和本包定义同名时的处理规则 与单导入相同

1
import a.x as x1            // warning: 导入的 x1 被遮盖
2

3
let x1 = 10
4
let _ = x1                  // ok, 'x1' 在本包中被定义

1
package b
2

3
public let x = 1
4
public func f(x: Int64) { x }

1
import a.x as x1
2
import a.x as x1            // warning: 'x1' 已经被导入
3
import b.x as x1            // warning: 'x1' 已经被导入
4

5
let _ = x1                  // error: 无法确定的 'x1'

1
import a.f as g
2
import b.f as g
3

4
func g(b: Bool) { b }
5

6
let _ = g()                 // ok, 调用 'a.f'
7
let _ = g(1)                // ok, 调用 'b.f'
8
let _ = g(true)             // ok, 调用 在本包中定义的 'g'

如果导入名称冲突的其中一方来自全导入, 这种情况下编译器也不会给出报警, 但冲突的声明都不可用

批量导入依据其等价的单导入、别名导入、多导入做名称冲突检查

当导入的别名冲突时, 与单导入冲突处理相同

被遮盖就不用, 构成重载就按照重载规则调用

import的访问修饰符#

import可以被private、internal、protected、public访问修饰符修饰

其中, 被public、protected或者internal修饰的import可以把导入的成员重导出(如果这些导入的成员没有因为名称冲突或者被遮盖导致在本包中不可用)

其他包可以根据 [访问修饰符] 的访问规则通过import导入这些被重导出的对象

具体地:

• private import表示导入的内容仅当前文件内可访问, private是import的默认修饰符, 不写访问修饰符的import等价于private import

• internal import表示导入的内容在当前包及其子包(包括子包的子包)均可访问, 非当前包访问需要显式import

• protected import表示导入的内容在当前module内都可访问, 非当前包访问需要显式import

• public import表示导入的内容外部都可访问, 非当前包访问需要显式import

包导入也可以使用访问修饰符

如果导入其他成员, 则可以使用public、protected、internal修饰, 这些导入的成员 可以按照访问修饰符规则被重导出

但, 按照全导入时介绍的规则, 如果使用访问修饰符 修饰import, 那么只能导入目标包中满足访问修饰符限制的成员

在下面的例子中, b是a的子包, 在a中通过public import重导出了b中定义的函数f

1
package a
2

3
public let x = 0
4
public import a.b.f

1
internal package a.b
2

3
public func f() { 0 }

1
import a.f          // ok
2
let _ = f()         // ok

1
import a.f                          // ok
2
//// case 1
3
package demo
4

5
public import std.time.Duration     // warning: 导入的 'Duration' 被遮盖
6

7
struct Duration {}

1
//// case 2
2
package demo
3

4
public import std.time.Duration
5

6
// ./b.cj
7
package demo
8

9
func f() {
10
    let a: Duration = Duration.second       // ok,  访问重导出的 'Duration'
11
}

1
//// case 3
2
package demo.a
3

4
public let x = 0
5

6
// ./b/b.cj
7
package demo.b
8

9
public import demo.a.*              // warning: 导入的 'x' 被遮盖, 将不能重导出 'demo.a.x'
10

11
var x = 0

1
//// case 4
2
package demo.a
3

4
public let x = 0
5

6
// ./b/b.cj
7
package demo.b
8

9
public let x = 0
10

11
// ./c/c.cj
12
package demo.c
13

14
public import demo.a.*              // warning, 因为存在重复名称, 将不能重导出 'demo.a.x'
15
public import demo.b.*              // warning, 因为存在重复名称, 将不能重导出 'demo.b.x'

特别地, 包不可以被重导出: 如果被import导入的是包, 那么该import不允许被public、protected或者internal修饰

1
public import a.b                   // error: 不能重新导出包

如果是导入的包名, 只能用private即 默认修饰符

重导出, 非当前包才需要 显式import

被遮盖的不能重导出