src/model/README.md

   1 The meta model of Nit programs
   2
   3 These modules define the entities of the Nit meta-model like modules, classes, types and properties
   4 They also provide an API to build and query models.
   5 All model classes starts with the `M` letter (`MModule`, `MClass`, etc.)
   6
   7 The model is used by tools that need a higher view than a AST (see `parser`).
   8 The model represents What the programmer means.
   9
  10 Because of the specification of the Nit language, the model is complex and sometime difficult to understand.
  11
  12 ## POSet
  13
  14 There is a lot of classes and relation in the model.
  15 Most of there relations are based on posets (from the lib `poset`.)
  16
  17 Posets are *partially-ordered sets*; they are used to modelize hierarchies of things (eg. hierarchies of modules)
  18
  19 The poset is an expressive data structure that generalizes most services about hierarchies.
  20 This avoid the duplication of code and the over-specialization of services.
  21 The drawback is that a specific request on the model use an abstract vocabulary.
  22
  23 Example. you want the set of modules directly imported by another module.
  24 There is no specific method in `MModule` for that, the good way is to use services on the some posets
  25
  26 ~~~
  27 var res = mymodule.in_importation.direct_greaters
  28 ~~~
  29
  30 posets are used in two dual ways :
  31
  32  - by the whole hierarchy, most are in the `Model` and are named `something_somerelation_hierarchy` (eg. `Model::mmodule_importation_hierarchy`).
  33  - by the view on en entity in a specific hierarchy, they are in the `MEntity` subclasses and are name `in_somerelation`. (eg. `MModule::in_importation`).
  34
  35
  36 ## Refinement
  37
  38 The refinement is the cause of the biggest difficulty with the model since the relations between entities are relative to the module considered.
  39
  40 "How many method in this class?" -- It depends, what modules are you considering?
  41 "What is called by `x.foo` when `x` is dynamically a `Bar`?" -- It depends, in which main module?
  42
  43 This relativity cause most services on model entities to have an additional parameter for the module considered.