src/doc/templates/term_model.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 # http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # Markdown templates for Nit model MEntities.
  16 #
  17 # This module introduces Markdown rendering services in model entities.
  18 # With the `no_color` option set to `false`, the output can be highlighted for console.
  19 module term_model
  20
  21 import model_collect
  22 import console
  23
  24 redef class MDoc
  25         # Returns the full comment formatted for the console
  26         fun cs_comment(no_color: nullable Bool, indent: nullable Int): String do
  27                 var res = new FlatBuffer
  28                 indent = indent or else 0
  29                 for line in content do
  30                         res.append "{" " * indent}{line}\n"
  31                 end
  32                 if no_color == null or not no_color then
  33                         return res.write_to_string.green
  34                 end
  35                 return res.write_to_string
  36         end
  37
  38         # Returns the synopsis formatted for the console
  39         fun cs_short_comment(no_color: nullable Bool): String do
  40                 if no_color == null or not no_color then
  41                         return content.first.green
  42                 end
  43                 return content.first
  44         end
  45 end
  46
  47 redef class MEntity
  48
  49         # Text icon to be displayed in front of the entity
  50         fun cs_icon(no_color: nullable Bool): String do
  51                 return public_visibility.cs_icon(no_color)
  52         end
  53
  54         # Source code location of this MEntity formatted for console
  55         fun cs_location(no_color: nullable Bool): String do
  56                 if no_color == null or not no_color then
  57                         return location.to_s.bold.gray
  58                 end
  59                 return location.to_s
  60         end
  61
  62         # Returns `self.full_name` formatted for console
  63         fun cs_full_name(no_color: nullable Bool): String do
  64                 if no_color == null or not no_color then
  65                         return full_name.bold.blue
  66                 end
  67                 return full_name
  68         end
  69
  70         # Returns `self` signature formatted for console.
  71         fun cs_signature(no_color: nullable Bool): String do return ""
  72
  73         # Returns the comment of this MEntity formatted for console.
  74         fun cs_comment(no_color: nullable Bool): nullable String do
  75                 var mdoc = mdoc_or_fallback
  76                 if mdoc == null then return null
  77                 # FIXME add markdown for console
  78                 return mdoc.cs_comment(no_color)
  79         end
  80
  81         # Returns the comment of this MEntity formatted for console.
  82         fun cs_short_comment(no_color: nullable Bool): nullable String do
  83                 var mdoc = mdoc_or_fallback
  84                 if mdoc == null then return null
  85                 return mdoc.cs_short_comment(no_color)
  86         end
  87
  88         # Returns the complete MEntity declaration (modifiers + name + signature).
  89         #
  90         # * MPackage: `package foo`
  91         # * MGroup: `group foo`
  92         # * MModule: `module foo`
  93         # * MClass: `private abstract class Foo[E: Object]`
  94         # * MClassDef: `redef class Foo[E]`
  95         # * MProperty: `private fun foo(e: Object): Int`
  96         # * MPropdef: `redef fun foo(e)`
  97         fun cs_declaration(no_color: nullable Bool): String do
  98                 var tpl = new FlatBuffer
  99                 tpl.append collect_modifiers.join(" ")
 100                 tpl.append " "
 101                 tpl.append name
 102                 tpl.append cs_signature(no_color)
 103                 if no_color == null or not no_color then
 104                         return tpl.write_to_string.bold
 105                 end
 106                 return tpl.write_to_string
 107         end
 108
 109         # Returns `self` as a list element that can be displayed in console.
 110         #
 111         # Displays `cs_icon`, `cs_name`, `cs_short_comment, `cs_namespace`,
 112         # `cs_declaration` and `cs_location`.
 113         fun cs_list_item(no_color: nullable Bool): String do
 114                 var tpl = new FlatBuffer
 115                 tpl.append " "
 116                 tpl.append cs_icon(no_color)
 117                 tpl.append " "
 118                 tpl.append cs_full_name(no_color)
 119                 var comment = cs_short_comment(no_color)
 120                 if comment != null then
 121                         tpl.append "\n   "
 122                         if no_color == null or not no_color then
 123                                 tpl.append "# ".green
 124                         else
 125                                 tpl.append "# "
 126                         end
 127                         tpl.append comment
 128                 end
 129                 tpl.append "\n   "
 130                 tpl.append cs_declaration(no_color)
 131                 tpl.append "\n   "
 132                 tpl.append cs_location(no_color)
 133                 return tpl.write_to_string
 134         end
 135
 136         # Source code associated to this MEntity.
 137         #
 138         # Uses `cs_location` to locate the source code.
 139         fun cs_source_code: String do
 140                 var tpl = new Buffer
 141                 tpl.append "\n~~~\n"
 142                 tpl.append location.text
 143                 tpl.append "\n~~~\n"
 144                 return tpl.write_to_string
 145         end
 146 end
 147
 148 redef class MClass
 149         redef fun cs_icon(no_color) do return intro.cs_icon(no_color)
 150         redef fun cs_signature(no_color) do return intro.cs_signature(no_color)
 151 end
 152
 153 redef class MClassDef
 154         redef fun cs_icon(no_color) do
 155                 if is_intro then return visibility.cs_icon(no_color)
 156                 return visibility.cs_visibility_color("*")
 157         end
 158
 159         # Returns the MClassDef generic signature with static bounds.
 160         redef fun cs_signature(no_color) do
 161                 var tpl = new FlatBuffer
 162                 var mparameters = mclass.mparameters
 163                 if not mparameters.is_empty then
 164                         tpl.append "["
 165                         for i in [0..mparameters.length[ do
 166                                 tpl.append "{mparameters[i].name}: "
 167                                 tpl.append bound_mtype.arguments[i].cs_signature(no_color)
 168                                 if i < mparameters.length - 1 then tpl.append ", "
 169                         end
 170                         tpl.append "]"
 171                 end
 172                 return tpl.write_to_string
 173         end
 174 end
 175
 176 redef class MProperty
 177         redef fun cs_icon(no_color) do return intro.cs_icon(no_color)
 178         redef fun cs_signature(no_color) do return intro.cs_signature(no_color)
 179 end
 180
 181 redef class MPropDef
 182         redef fun cs_icon(no_color) do
 183                 if is_intro then return visibility.cs_icon(no_color)
 184                 return visibility.cs_visibility_color("*", no_color)
 185         end
 186 end
 187
 188 redef class MAttributeDef
 189         redef fun cs_signature(no_color) do
 190                 var tpl = new FlatBuffer
 191                 var static_mtype = self.static_mtype
 192                 if static_mtype != null then
 193                         tpl.append ": "
 194                         tpl.append static_mtype.cs_signature(no_color)
 195                 end
 196                 return tpl.write_to_string
 197         end
 198 end
 199
 200 redef class MMethodDef
 201         redef fun cs_signature(no_color) do
 202                 if mproperty.is_root_init then
 203                         return new_msignature.as(not null).cs_signature(no_color)
 204                 end
 205                 return msignature.as(not null).cs_signature(no_color)
 206         end
 207 end
 208
 209 redef class MVirtualTypeDef
 210         redef fun cs_signature(no_color) do
 211                 var tpl = new FlatBuffer
 212                 var bound = self.bound
 213                 if bound == null then return tpl.write_to_string
 214                 tpl.append ": "
 215                 tpl.append bound.cs_signature(no_color)
 216                 return tpl.write_to_string
 217         end
 218 end
 219
 220 redef class MClassType
 221         redef fun cs_signature(no_color) do return name
 222 end
 223
 224 redef class MNullableType
 225         redef fun cs_signature(no_color) do
 226                 var tpl = new FlatBuffer
 227                 tpl.append "nullable "
 228                 tpl.append mtype.cs_signature(no_color)
 229                 return tpl.write_to_string
 230         end
 231 end
 232
 233 redef class MGenericType
 234         redef fun cs_signature(no_color) do
 235                 var tpl = new FlatBuffer
 236                 tpl.append mclass.name
 237                 tpl.append "["
 238                 for i in [0..arguments.length[ do
 239                         tpl.append arguments[i].cs_signature(no_color)
 240                         if i < arguments.length - 1 then tpl.append ", "
 241                 end
 242                 tpl.append "]"
 243                 return tpl.write_to_string
 244         end
 245 end
 246
 247 redef class MParameterType
 248         redef fun cs_signature(no_color) do return name
 249 end
 250
 251 redef class MVirtualType
 252         redef fun cs_signature(no_color) do return name
 253 end
 254
 255 redef class MSignature
 256         redef fun cs_signature(no_color) do
 257                 var tpl = new FlatBuffer
 258                 if not mparameters.is_empty then
 259                         tpl.append "("
 260                         for i in [0..mparameters.length[ do
 261                                 tpl.append mparameters[i].cs_signature(no_color)
 262                                 if i < mparameters.length - 1 then tpl.append ", "
 263                         end
 264                         tpl.append ")"
 265                 end
 266                 var return_mtype = self.return_mtype
 267                 if return_mtype != null then
 268                         tpl.append ": "
 269                         tpl.append return_mtype.cs_signature(no_color)
 270                 end
 271                 return tpl.write_to_string
 272         end
 273 end
 274
 275 redef class MParameter
 276         redef fun cs_signature(no_color) do
 277                 var tpl = new FlatBuffer
 278                 tpl.append "{name}: "
 279                 tpl.append mtype.cs_signature(no_color)
 280                 if is_vararg then tpl.append "..."
 281                 return tpl.write_to_string
 282         end
 283 end
 284
 285 redef class MVisibility
 286         # Visibility icon
 287         fun cs_icon(no_color: nullable Bool): String do
 288                 var icon
 289                 if self == private_visibility then
 290                         icon = cs_visibility_color("-", no_color)
 291                 else if self == protected_visibility then
 292                         icon = cs_visibility_color("#", no_color)
 293                 else
 294                         icon = cs_visibility_color("+", no_color)
 295                 end
 296                 if no_color != null and no_color then return icon
 297                 return icon.bold
 298         end
 299
 300         # Colorize `string` depending on the visibility
 301         fun cs_visibility_color(string: String, no_color: nullable Bool): String do
 302                 if no_color != null and no_color then return string
 303                 if self == private_visibility then
 304                         return string.red
 305                 else if self == protected_visibility then
 306                         return string.yellow
 307                 else
 308                         return string.green
 309                 end
 310         end
 311 end