src/doc/html_templates/html_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 # HTML templates for Nit model MEntities.
  16 module html_model
  17
  18 import doc_base
  19 import doc_down
  20 import html_components
  21 import html::bootstrap
  22 import ordered_tree
  23
  24 redef class Location
  25         # Github url based on this location
  26         fun github(gitdir: String): String do
  27                 var base_dir = getcwd.join_path(gitdir).simplify_path
  28                 var file_loc = getcwd.join_path(file.filename).simplify_path
  29                 var gith_loc = file_loc.substring(base_dir.length + 1, file_loc.length)
  30                 return "{gith_loc}:{line_start},{column_start}--{line_end},{column_end}"
  31         end
  32 end
  33
  34 redef class MEntity
  35         # ID used as a HTML unique ID and in file names.
  36         #
  37         # **Must** match the following (POSIX ERE) regular expression:
  38         #
  39         # ~~~POSIX ERE
  40         # ^[A-Za-z_][A-Za-z0-9._-]*$
  41         # ~~~
  42         #
  43         # That way, the ID is always a valid URI component and a valid XML name.
  44         fun nitdoc_id: String is abstract
  45
  46         # URL of this entity’s Nitdoc page.
  47         fun nitdoc_url: String is abstract
  48
  49         # Returns the mentity name without short signature.
  50         #
  51         # * MProject: `foo`
  52         # * MGroup: `foo`
  53         # * MModule: `foo`
  54         # * MClass: `Foo[E]`
  55         # * MClassDef: `Foo[E]`
  56         # * MProperty: `foo(e)`
  57         # * MPropdef: `foo(e)`
  58         var html_name: String is lazy do return name.html_escape
  59
  60         # Returns a Link to the mentity `html_url`.
  61         #
  62         # Example: `<a href="html_url" title="mdoc.short_comment">html_short_name</a>
  63         var html_link: Link is lazy do
  64                 var tpl = new Link(nitdoc_url, html_name)
  65                 var mdoc = mdoc_or_fallback
  66                 if mdoc != null then
  67                         tpl.title = mdoc.short_comment
  68                 end
  69                 return tpl
  70         end
  71
  72         # A template link to the mentity `nitdoc_id`
  73         fun tpl_anchor: TplLink do
  74                 var tpl = new TplLink("#{nitdoc_id}", html_name)
  75                 var mdoc = mdoc_or_fallback
  76                 if mdoc != null then
  77                         tpl.title = mdoc.short_comment
  78                 end
  79                 return tpl
  80         end
  81
  82         # A template article that briefly describe the entity
  83         fun tpl_short_article: TplArticle do
  84                 var tpl = tpl_article
  85                 var mdoc = mdoc_or_fallback
  86                 if mdoc != null then
  87                         tpl.content = mdoc.tpl_short_comment
  88                 end
  89                 return tpl
  90         end
  91
  92         # A template article that describe the entity
  93         fun tpl_article: TplArticle do
  94                 var tpl = new TplArticle.with_title(nitdoc_id, tpl_title)
  95                 tpl.title_classes.add "signature"
  96                 tpl.subtitle = tpl_namespace
  97                 tpl.summary_title = html_name
  98                 return tpl
  99         end
 100
 101         # A template signature that contains modifiers and parameters
 102         fun tpl_declaration: Template is abstract
 103
 104         # A template namespace
 105         fun tpl_namespace: Template is abstract
 106
 107         # A template definition of the mentity
 108         # include name, sysnopsys, comment and namespace
 109         fun tpl_definition: TplDefinition is abstract
 110
 111         # A li element that can go in a list
 112         fun tpl_list_item: TplListItem do
 113                 var lnk = new Template
 114                 lnk.add new TplLabel.with_classes(tpl_css_classes)
 115                 lnk.add html_link
 116                 var mdoc = mdoc_or_fallback
 117                 if mdoc != null then
 118                         lnk.add ": "
 119                         lnk.add mdoc.tpl_short_comment
 120                 end
 121                 return new TplListItem.with_content(lnk)
 122         end
 123
 124         var tpl_css_classes = new Array[String]
 125
 126         # Box title for this mentity
 127         fun tpl_title: Template do
 128                 var title = new Template
 129                 title.add tpl_icon
 130                 title.add tpl_namespace
 131                 return title
 132         end
 133
 134         # Icon that will be displayed before the title
 135         fun tpl_icon: TplIcon do
 136                 var icon = new TplIcon.with_icon("tag")
 137                 icon.css_classes.add_all(tpl_css_classes)
 138                 return icon
 139         end
 140 end
 141
 142 redef class MConcern
 143         # Return a li element for `self` that can be displayed in a concern list
 144         private fun tpl_concern_item: TplListItem do
 145                 var lnk = new Template
 146                 lnk.add tpl_anchor
 147                 var mdoc = mdoc_or_fallback
 148                 if mdoc != null then
 149                         lnk.add ": "
 150                         lnk.add mdoc.tpl_short_comment
 151                 end
 152                 return new TplListItem.with_content(lnk)
 153         end
 154 end
 155
 156 redef class MProject
 157         redef var nitdoc_id = name.to_cmangle is lazy
 158         redef fun nitdoc_url do return root.nitdoc_url
 159
 160         redef fun tpl_declaration do
 161                 var tpl = new Template
 162                 tpl.add "<span>project "
 163                 tpl.add html_link
 164                 tpl.add "</span>"
 165                 return tpl
 166         end
 167
 168         redef fun tpl_namespace do return html_link
 169
 170         redef fun tpl_definition do
 171                 var tpl = new TplDefinition
 172                 var mdoc = mdoc_or_fallback
 173                 if mdoc != null then
 174                         tpl.comment = mdoc.tpl_comment
 175                 end
 176                 return tpl
 177         end
 178
 179         redef fun tpl_css_classes do return ["public"]
 180 end
 181
 182 redef class MGroup
 183         redef var nitdoc_id is lazy do
 184                 if parent != null then
 185                         return "{parent.nitdoc_id}__{name.to_cmangle}"
 186                 end
 187                 return name.to_cmangle
 188         end
 189
 190         redef fun nitdoc_url do return "group_{nitdoc_id}.html"
 191
 192         redef fun tpl_namespace do
 193                 var tpl = new Template
 194                 tpl.add mproject.tpl_namespace
 195                 if mproject.root != self then
 196                         tpl.add "::"
 197                         tpl.add html_link
 198                 end
 199                 return tpl
 200         end
 201
 202         redef fun tpl_declaration do
 203                 var tpl = new Template
 204                 tpl.add "<span>group "
 205                 tpl.add html_link
 206                 tpl.add "</span>"
 207                 return tpl
 208         end
 209
 210         redef fun tpl_definition do
 211                 var tpl = new TplDefinition
 212                 var mdoc = mdoc_or_fallback
 213                 if mdoc != null then
 214                         tpl.comment = mdoc.tpl_comment
 215                 end
 216                 return tpl
 217         end
 218 end
 219
 220 redef class MModule
 221         redef var nitdoc_id is lazy do
 222                 if mgroup != null then
 223                         if mgroup.mmodules.length == 1 then
 224                                 return "{mgroup.nitdoc_id}-"
 225                         else
 226                                 return "{mgroup.nitdoc_id}__{name.to_cmangle}"
 227                         end
 228                 end
 229                 return name.to_cmangle
 230         end
 231
 232         redef fun nitdoc_url do return "module_{nitdoc_id}.html"
 233
 234         redef fun tpl_declaration do
 235                 var tpl = new Template
 236                 tpl.add "<span>module "
 237                 tpl.add tpl_namespace
 238                 tpl.add "</span>"
 239                 return tpl
 240         end
 241
 242         redef fun tpl_namespace do
 243                 var tpl = new Template
 244                 if mgroup != null then
 245                         tpl.add mgroup.tpl_namespace
 246                         tpl.add "::"
 247                 end
 248                 tpl.add html_link
 249                 return tpl
 250         end
 251
 252         redef fun tpl_definition do
 253                 var tpl = new TplClassDefinition
 254                 var mdoc = mdoc_or_fallback
 255                 if mdoc != null then
 256                         tpl.comment = mdoc.tpl_comment
 257                 end
 258                 return tpl
 259         end
 260
 261         redef fun tpl_css_classes do return ["public"]
 262 end
 263
 264 redef class MClass
 265         redef var nitdoc_id = "{intro_mmodule.nitdoc_id}__{name.to_cmangle}" is lazy
 266         redef fun nitdoc_url do return "class_{nitdoc_id}.html"
 267         redef fun mdoc_or_fallback do return intro.mdoc
 268
 269         # Format: `Foo[E]`
 270         redef var html_name is lazy do
 271                 var tpl = new Template
 272                 tpl.add name.html_escape
 273                 if arity > 0 then
 274                         tpl.add "["
 275                         var parameter_names = new Array[String]
 276                         for p in mparameters do
 277                                 parameter_names.add(p.html_name)
 278                         end
 279                         tpl.add parameter_names.join(", ")
 280                         tpl.add "]"
 281                 end
 282                 return tpl.write_to_string
 283         end
 284
 285         redef fun tpl_declaration do return intro.tpl_declaration
 286         redef fun tpl_definition do return intro.tpl_definition
 287
 288         redef fun tpl_namespace do
 289                 var tpl = new Template
 290                 tpl.add intro_mmodule.mgroup.mproject.tpl_namespace
 291                 tpl.add "::<span>"
 292                 tpl.add html_link
 293                 tpl.add "</span>"
 294                 return tpl
 295         end
 296
 297         redef fun tpl_title do
 298                 var title = new Template
 299                 title.add tpl_icon
 300                 title.add html_link
 301                 return title
 302         end
 303
 304         redef fun tpl_icon do return intro.tpl_icon
 305
 306         fun tpl_signature: Template do
 307                 var tpl = new Template
 308                 if arity > 0 then
 309                         tpl.add "["
 310                         var parameter_names = new Array[String]
 311                         for p in mparameters do
 312                                 parameter_names.add(p.html_name)
 313                         end
 314                         tpl.add parameter_names.join(", ")
 315                         tpl.add "]"
 316                 end
 317                 return tpl
 318         end
 319
 320         redef fun tpl_css_classes do return intro.tpl_css_classes
 321 end
 322
 323 redef class MClassDef
 324         redef var nitdoc_id = "{mmodule.nitdoc_id}__{name.to_cmangle}" is lazy
 325         redef fun nitdoc_url do return "{mclass.nitdoc_url}#{nitdoc_id}"
 326
 327         redef fun mdoc_or_fallback do return mdoc or else mclass.mdoc_or_fallback
 328
 329         redef fun tpl_namespace do
 330                 var tpl = new Template
 331                 tpl.add mmodule.tpl_namespace
 332                 tpl.add "::<span>"
 333                 tpl.add mclass.html_link
 334                 tpl.add "</span>"
 335                 return tpl
 336         end
 337
 338         redef fun tpl_article do
 339                 var tpl = new TplArticle(nitdoc_id)
 340                 tpl.summary_title = "in {mmodule.html_name}"
 341                 tpl.title = tpl_declaration
 342                 tpl.title_classes.add "signature"
 343                 var title = new Template
 344                 title.add "in "
 345                 title.add mmodule.tpl_namespace
 346                 tpl.subtitle = title
 347                 var mdoc = mdoc_or_fallback
 348                 if mdoc != null then
 349                         tpl.content = mdoc.tpl_comment
 350                 end
 351                 return tpl
 352         end
 353
 354         redef fun tpl_title do
 355                 var title = new Template
 356                 title.add tpl_icon
 357                 title.add html_link
 358                 return title
 359         end
 360
 361         redef fun tpl_declaration do
 362                 var tpl = new Template
 363                 tpl.add tpl_modifiers
 364                 tpl.add html_link
 365                 tpl.add tpl_signature
 366                 return tpl
 367         end
 368
 369         fun tpl_signature: Template do
 370                 var tpl = new Template
 371                 var mparameters = mclass.mparameters
 372                 if not mparameters.is_empty then
 373                         tpl.add "["
 374                         for i in [0..mparameters.length[ do
 375                                 tpl.add "{mparameters[i].html_name}: "
 376                                 tpl.add bound_mtype.arguments[i].tpl_signature
 377                                 if i < mparameters.length - 1 then tpl.add ", "
 378                         end
 379                         tpl.add "]"
 380                 end
 381                 return tpl
 382         end
 383
 384         redef fun tpl_definition do
 385                 var tpl = new TplClassDefinition
 386                 var mdoc = mdoc_or_fallback
 387                 if mdoc != null then
 388                         tpl.comment = mdoc.tpl_comment
 389                 end
 390                 return tpl
 391         end
 392
 393         redef fun tpl_css_classes do
 394                 var set = new HashSet[String]
 395                 if is_intro then set.add "intro"
 396                 for m in mclass.intro.modifiers do set.add m.to_cmangle
 397                 for m in modifiers do set.add m.to_cmangle
 398                 return set.to_a
 399         end
 400
 401         fun tpl_modifiers: Template do
 402                 var tpl = new Template
 403                 for modifier in modifiers do
 404                         if modifier == "public" then continue
 405                         tpl.add "{modifier.html_escape} "
 406                 end
 407                 return tpl
 408         end
 409 end
 410
 411 redef class MProperty
 412         redef var nitdoc_id = "{intro_mclassdef.mclass.nitdoc_id}__{name.to_cmangle}" is lazy
 413         redef fun nitdoc_url do return "property_{nitdoc_id}.html"
 414
 415         redef fun mdoc_or_fallback do return intro.mdoc
 416
 417         redef fun tpl_namespace do
 418                 var tpl = new Template
 419                 tpl.add intro_mclassdef.mclass.tpl_namespace
 420                 tpl.add "::<span>"
 421                 tpl.add intro.html_link
 422                 tpl.add "</span>"
 423                 return tpl
 424         end
 425
 426         redef fun tpl_declaration do return intro.tpl_declaration
 427
 428         fun tpl_signature: Template do return new Template
 429
 430         redef fun tpl_title do return intro.tpl_title
 431
 432         redef fun tpl_icon do return intro.tpl_icon
 433
 434         redef fun tpl_css_classes do return intro.tpl_css_classes
 435 end
 436
 437 redef class MPropDef
 438         redef var nitdoc_id = "{mclassdef.nitdoc_id}__{name.to_cmangle}" is lazy
 439         redef fun nitdoc_url do return "{mproperty.nitdoc_url}#{nitdoc_id}"
 440
 441         redef fun mdoc_or_fallback do return mdoc or else mproperty.mdoc_or_fallback
 442
 443         redef fun tpl_namespace do
 444                 var tpl = new Template
 445                 tpl.add mclassdef.tpl_namespace
 446                 tpl.add "::"
 447                 tpl.add html_link
 448                 return tpl
 449         end
 450
 451         redef fun tpl_article do
 452                 var tpl = new TplArticle(nitdoc_id)
 453                 tpl.summary_title = "in {mclassdef.html_name}"
 454                 var title = new Template
 455                 title.add "in "
 456                 title.add mclassdef.html_link
 457                 tpl.title = title
 458                 tpl.subtitle = tpl_declaration
 459                 var mdoc = mdoc_or_fallback
 460                 if mdoc != null then
 461                         tpl.content = mdoc.tpl_comment
 462                 end
 463                 return tpl
 464         end
 465
 466         redef fun tpl_definition do
 467                 var tpl = new TplDefinition
 468                 var mdoc = mdoc_or_fallback
 469                 if mdoc != null then
 470                         tpl.comment = mdoc.tpl_comment
 471                 end
 472                 return tpl
 473         end
 474
 475         redef fun tpl_declaration do
 476                 var tpl = new Template
 477                 tpl.add tpl_modifiers
 478                 tpl.add html_link
 479                 tpl.add tpl_signature
 480                 return tpl
 481         end
 482
 483         redef fun tpl_css_classes do
 484                 var set = new HashSet[String]
 485                 if is_intro then set.add "intro"
 486                 for m in mproperty.intro.modifiers do set.add m.to_cmangle
 487                 for m in modifiers do set.add m.to_cmangle
 488                 return set.to_a
 489         end
 490
 491         fun tpl_modifiers: Template do
 492                 var tpl = new Template
 493                 for modifier in modifiers do
 494                         if modifier == "public" then continue
 495                         tpl.add "{modifier.html_escape} "
 496                 end
 497                 return tpl
 498         end
 499
 500         fun tpl_signature: Template do return new Template
 501
 502         redef fun tpl_list_item do
 503                 var lnk = new Template
 504                 lnk.add new TplLabel.with_classes(tpl_css_classes.to_a)
 505                 var atext = html_link.text
 506                 var ahref = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}"
 507                 var atitle = html_link.title
 508                 var anchor = new Link.with_title(ahref, atext, atitle)
 509                 lnk.add anchor
 510                 var mdoc = mdoc_or_fallback
 511                 if mdoc != null then
 512                         lnk.add ": "
 513                         lnk.add mdoc.tpl_short_comment
 514                 end
 515                 return new TplListItem.with_content(lnk)
 516         end
 517
 518         fun tpl_inheritance_item: TplListItem do
 519                 var lnk = new Template
 520                 lnk.add new TplLabel.with_classes(tpl_css_classes.to_a)
 521                 lnk.add mclassdef.mmodule.tpl_namespace
 522                 lnk.add "::"
 523                 var atext = mclassdef.html_link.text
 524                 var ahref = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}"
 525                 var atitle = mclassdef.html_link.title
 526                 var anchor = new Link.with_title(ahref, atext, atitle)
 527                 lnk.add anchor
 528                 var mdoc = mdoc_or_fallback
 529                 if mdoc != null then
 530                         lnk.add ": "
 531                         lnk.add mdoc.tpl_short_comment
 532                 end
 533                 var li = new TplListItem.with_content(lnk)
 534                 li.css_classes.add "signature"
 535                 return li
 536         end
 537 end
 538
 539 redef class MAttributeDef
 540         redef fun tpl_signature do
 541                 var tpl = new Template
 542                 if static_mtype != null then
 543                         tpl.add ": "
 544                         tpl.add static_mtype.tpl_signature
 545                 end
 546                 return tpl
 547         end
 548 end
 549
 550 redef class MMethod
 551         redef fun tpl_signature do
 552                 var tpl = new Template
 553                 var params = new Array[String]
 554                 for param in intro.msignature.mparameters do
 555                         params.add param.name.html_escape
 556                 end
 557                 if not params.is_empty then
 558                         tpl.add "("
 559                         tpl.add params.join(", ")
 560                         tpl.add ")"
 561                 end
 562                 return tpl
 563         end
 564 end
 565
 566 redef class MMethodDef
 567         redef fun tpl_signature do return msignature.tpl_signature
 568 end
 569
 570 redef class MVirtualTypeProp
 571         redef fun html_link do return mvirtualtype.html_link
 572         redef fun tpl_signature do return html_link
 573 end
 574
 575 redef class MVirtualTypeDef
 576         redef fun tpl_signature do
 577                 var tpl = new Template
 578                 if bound == null then return tpl
 579                 tpl.add ": "
 580                 tpl.add bound.tpl_signature
 581                 return tpl
 582         end
 583 end
 584
 585 redef class MType
 586         fun tpl_signature: Template is abstract
 587 end
 588
 589 redef class MClassType
 590         redef fun html_link do return mclass.html_link
 591         redef fun tpl_signature do return html_link
 592 end
 593
 594 redef class MNullableType
 595         redef fun tpl_signature do
 596                 var tpl = new Template
 597                 tpl.add "nullable "
 598                 tpl.add mtype.tpl_signature
 599                 return tpl
 600         end
 601 end
 602
 603 redef class MGenericType
 604         redef fun tpl_signature do
 605                 var lnk = html_link
 606                 var tpl = new Template
 607                 tpl.add new Link.with_title(lnk.href, mclass.name.html_escape, lnk.title)
 608                 tpl.add "["
 609                 for i in [0..arguments.length[ do
 610                         tpl.add arguments[i].tpl_signature
 611                         if i < arguments.length - 1 then tpl.add ", "
 612                 end
 613                 tpl.add "]"
 614                 return tpl
 615         end
 616 end
 617
 618 redef class MParameterType
 619         redef fun html_link do
 620                 return new Link.with_title("{mclass.nitdoc_url}#FT_{name.to_cmangle}", name, "formal type")
 621         end
 622         redef fun tpl_signature do return html_link
 623 end
 624
 625 redef class MVirtualType
 626         redef fun html_link do return mproperty.intro.html_link
 627         redef fun tpl_signature do return html_link
 628 end
 629
 630 redef class MSignature
 631         redef fun tpl_signature do
 632                 var tpl = new Template
 633                 if not mparameters.is_empty then
 634                         tpl.add "("
 635                         for i in [0..mparameters.length[ do
 636                                 tpl.add mparameters[i].tpl_signature
 637                                 if i < mparameters.length - 1 then tpl.add ", "
 638                         end
 639                         tpl.add ")"
 640                 end
 641                 if return_mtype != null then
 642                         tpl.add ": "
 643                         tpl.add return_mtype.tpl_signature
 644                 end
 645                 return tpl
 646         end
 647 end
 648
 649 redef class MParameter
 650         fun tpl_signature: Template do
 651                 var tpl = new Template
 652                 tpl.add "{name}: "
 653                 tpl.add mtype.tpl_signature
 654                 if is_vararg then tpl.add "..."
 655                 return tpl
 656         end
 657 end
 658
 659 redef class ConcernsTree
 660
 661         private var seen = new HashSet[MConcern]
 662
 663         redef fun add(p, e) do
 664                 if seen.has(e) then return
 665                 seen.add e
 666                 super(p, e)
 667         end
 668
 669         fun to_tpl: TplList do
 670                 var lst = new TplList.with_classes(["list-unstyled", "list-definition"])
 671                 for r in roots do
 672                         var li = r.tpl_concern_item
 673                         lst.add_li li
 674                         build_list(r, li)
 675                 end
 676                 return lst
 677         end
 678
 679         private fun build_list(e: MConcern, li: TplListItem) do
 680                 if not sub.has_key(e) then return
 681                 var subs = sub[e]
 682                 var lst = new TplList.with_classes(["list-unstyled", "list-definition"])
 683                 for e2 in subs do
 684                         if e2 isa MGroup and e2.is_root then
 685                                 build_list(e2, li)
 686                         else
 687                                 var sli = e2.tpl_concern_item
 688                                 lst.add_li sli
 689                                 build_list(e2, sli)
 690                         end
 691                 end
 692                 li.append lst
 693         end
 694 end
 695
 696
 697 ################################################################################
 698 # Additions to `model_ext`.
 699
 700 redef class MRawType
 701         redef fun tpl_signature do
 702                 var tpl = new Template
 703
 704                 for part in parts do
 705                         if part.target != null then
 706                                 tpl.add part.target.as(not null).html_link
 707                         else
 708                                 tpl.add part.text.html_escape
 709                         end
 710                 end
 711                 return tpl
 712         end
 713 end
 714
 715 redef class MInnerClass
 716         redef fun nitdoc_url do return inner.nitdoc_url
 717         redef fun tpl_signature do return inner.tpl_signature
 718 end
 719
 720 redef class MInnerClassDef
 721         redef fun nitdoc_url do return inner.nitdoc_url
 722
 723         redef fun tpl_anchor do return inner.tpl_anchor
 724         redef fun html_link do return inner.html_link
 725         redef fun tpl_signature do return inner.tpl_signature
 726
 727         redef fun tpl_definition do
 728                 var tpl = new TplClassDefinition
 729                 var mdoc = mdoc_or_fallback
 730                 if mdoc != null then
 731                         tpl.comment = mdoc.tpl_comment
 732                 end
 733                 return tpl
 734         end
 735 end