doc/manual/module.md

   1 # Modules
   2
   3 `module` declares the name of a module. While optional it is recommended to use it, at least for documentation purpose. The basename of the source file must match the name declared with `module`. The extension of the source file must be `nit`.
   4
   5 A module is made of, in order:
   6
   7 -   the module declaration;
   8 -   module importations;
   9 -   class definitions (and refinements) ;
  10 -   top-level function definitions (and redefinitions) ;
  11 -   main instructions .
  12
  13 ## Module Importation
  14
  15 `import` declares dependencies between modules. By default (that is without any `import` declaration), a module publicly imports the module `standard`. Dependencies must not produce cycles. By importing a module, the importer module can see and use classes and properties defined in the imported module.
  16
  17 -   `import` indicates a public importation. Importers of a given module will also import its publicly imported modules. An analogy is using `#include` in a header file (`.h`) in C/C++.
  18
  19 -   `private import` indicates a private importation. Importers of a given module will not  automatically import its privately imported modules. An analogy is using `#include` in a body file (`.c`) in C/C++.
  20
  21 -   `intrude import` indicates an intrusive importation. `intrude` `import` bypasses the `private` visibility and gives to the importer module a full access on the imported module. Such an import may only be considered when modules are strongly bounded and developed together. The closest, but insufficient, analogy is something like including a body file in a body file in C/C++.
  22
  23 ## Visibility
  24
  25 By default, all classes, methods, constructors and virtual types are public which means freely usable by any importer module. Once something is public it belongs to the API of the module and should not be changed.
  26
  27 `private` indicates classes and methods that do not belong to the API. They are still freely usable inside the module but are invisible in other modules (except those that use `intrude import`).
  28
  29 `protected` indicates restricted methods and constructors. Such methods belong to the API of the module but they can only be used with the `self` receiver. Basically, `protected` methods are limited to the current class and its subclasses. Note that inside the module (and in
  30 intrude importers), there is still no restriction.
  31
  32 Visibility of attributes is more specific and is detailed in its own section.
  33
  34 ~~~
  35 module m1
  36 class Foo
  37     fun pub do ...
  38     protected fun pro
  39     do ...
  40     private fun pri
  41     do ...
  42 end
  43 private class Bar
  44     fun pri2 do ...
  45 end
  46 var x: Foo = ...
  47 var y: Bar = ...
  48 # All OK, it is
  49 # inside the module
  50 x.foo
  51 x.pro
  52 x.pro
  53 y.pri2
  54 ~~~
  55
  56 <!-- -->
  57
  58 ~~~
  59 module m2
  60 import m1
  61 class Baz
  62     super Foo
  63     fun derp
  64     do
  65         self.pro # OK
  66     end
  67 end
  68 var x: Foo = ...
  69 x.pub # OK
  70 x.pro # Compile error:
  71       # pro is protected
  72 x.pri # Compile error:
  73       # unknown method pri
  74
  75 var y: Bar
  76 # Compile error:
  77 # unknown class Bar
  78 ~~~
  79
  80 ## Visibility Coherence
  81
  82 In order to guarantee the coherence in the visibility, the following rules apply:
  83
  84 -   Classes and properties privately imported are considered private:     they are not exported and do not belong to the API of the importer.
  85
  86 -   Properties defined in a private class are private.
  87
  88 -   A static type is private if it contains a private class or a private     virtual type.
  89
  90 -   Signatures of public and protected properties cannot contain a private static type.
  91
  92 -   Bounds of public generic class and public virtual types cannot contain a private static type.