src/model/model_base.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Copyright 2012 Jean Privat <jean@pryen.org>
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #     http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16
  17 # The abstract concept of model and related common things
  18 module model_base
  19 import location
  20
  21 # The container class of a Nit object-oriented model.
  22 # A model knows modules, classes and properties and can retrieve them.
  23 class Model
  24         super MEntity
  25
  26         redef fun model do return self
  27
  28         # Place-holder object that means no-location
  29         #
  30         # See `MEntity::location`
  31         var no_location = new Location(null, 0, 0, 0, 0)
  32 end
  33
  34 # A named and possibly documented entity in the model.
  35 # This class is useful to generalize presentation of entities to the human.
  36 abstract class MEntity
  37         # The short (unqualified) name of this model entity.
  38         #
  39         # The short-name is based from the identifiers used to declare or denote the entity.
  40         # It is usually globally ambiguous but is often enough in a precise local context.
  41         #
  42         # It is suitable to use the short-name in message to the user.
  43         # However, special care must be used in case of potential ambiguities or name conflict.
  44         fun name: String is abstract
  45
  46         # A fully-qualified name of this model entity.
  47         #
  48         # The full-name is based on the short name and is usually prefixed by the name of an outer entity.
  49         # Usually the quad (`::`) is used to separate the different names.
  50         #
  51         # The full-name is expected to be unique and unambiguous in lawful Nit models for the same kind of entity.
  52         #
  53         # It is often suitable to use it in message to the user.
  54         # However, some full-name could be long and verbose,
  55         #
  56         # See the specific implementation in subclasses for details.
  57         fun full_name: String is abstract
  58
  59         # A fully-qualified C-like identifier of this model entity.
  60         #
  61         # The C-name is a name that respects the rule of identifiers in the C language:
  62         # it is only made of alphanumeric characters and starts with a letter (or a underscore).
  63         #
  64         # The C-name can be seen as a mangled version of the `full_name`.
  65         # Therefore, it is expected to be unique and unambiguous in lawful Nit models for the same kind of entity.
  66         #
  67         # The C-name is used by tools that need some identifiers in generated files to designate the
  68         # entity.
  69         #
  70         # Is is not suitable to use it directly with the user (e.g. in message) and
  71         # indirect use should be restricted (e.g. to name a web-page)
  72         fun c_name: String is abstract
  73
  74         # The origin of the definition.
  75         #
  76         # Most model entities are defined in a specific place in the source base.
  77         #
  78         # Because most model entities have one,
  79         # it is simpler for the client to have a non-nullable return value.
  80         # For entities that lack a location, mock-up special locations are used instead.
  81         # By default it is `model.no_location`.
  82         fun location: Location do return model.no_location
  83
  84         # A Model Entity has a direct link to its model
  85         fun model: Model is abstract
  86
  87         # The indication that the entity did not pass some semantic verifications.
  88         #
  89         # This simple flag is set by a given analysis to say that the entity is broken and unusable in
  90         # an execution.
  91         # When an entity status is set to broken, it is usually associated with a error message.
  92         #
  93         # If it is safe to do so, clients of the model SHOULD just skip broken entities in their processing.
  94         # Clients that do not care about the executability (e.g. metrics) MAY still process the entity or
  95         # perform specific checks to determinate the validity of the entity.
  96         #
  97         # Note that the broken status is not propagated to enclosing and enclosed entities.
  98         # e.g. a broken method does not make the whole module broken.
  99         var is_broken = false is writable
 100
 101         # Is `self` created for internal purpose?
 102         #
 103         # Fictive entities are used internally but they should not be
 104         # exposed to the final user.
 105         var is_fictive: Bool = false is writable
 106
 107         # Is `self` created for unit testing purpose?
 108         #
 109         # See `nitunit`.
 110         var is_test: Bool = false is writable
 111 end
 112
 113 # Something that represents a concern
 114 abstract class MConcern
 115         super MEntity
 116         # The concern that contains `self` or null if `self` is the root of the concern hierarchy
 117         fun parent_concern: nullable MConcern is abstract
 118 end
 119
 120 # A visibility (for modules, class and properties)
 121 # Valid visibility are:
 122 #
 123 #  * `intrude_visibility`
 124 #  * `public_visibility`
 125 #  * `protected_visibility`
 126 #  * `none_visibility`
 127 #  * `private_visiblity`
 128 #
 129 # Note this class is basically an enum.
 130 # FIXME: use a real enum once user-defined enums are available
 131 class MVisibility
 132         super Comparable
 133         redef type OTHER: MVisibility
 134
 135         redef var to_s: String
 136
 137         private var level: Int
 138
 139         # TODO: private init because enumeration.
 140
 141         # Is self give less visibility than other
 142         # none < private < protected < public < intrude
 143         redef fun <(other)
 144         do
 145                 return self.level < other.level
 146         end
 147 end
 148
 149 # A `Comparator` to sort mentities by their names.
 150 class MEntityNameSorter
 151         super Comparator
 152
 153         redef type COMPARED: MEntity
 154
 155         # Returns `a.name <=> b.name`.
 156         redef fun compare(a, b) do return a.name <=> b.name
 157 end
 158
 159 # The visibility level `intrude`
 160 fun intrude_visibility: MVisibility do return once new MVisibility("intrude", 5)
 161 # The visibility level `public`
 162 fun public_visibility: MVisibility do return once new MVisibility("public", 4)
 163 # The visibility level `protected`
 164 fun protected_visibility: MVisibility do return once new MVisibility("protected", 3)
 165 # The visibility level `private`
 166 fun private_visibility: MVisibility do return once new MVisibility("private", 2)
 167 # The visibility level `none` (no visibility)
 168 fun none_visibility: MVisibility do return once new MVisibility("none", 1)