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