src/web/web_base.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 # Base classes used by `nitweb`.
  16 module web_base
  17
  18 import model::model_views
  19 import model::model_json
  20 import doc_down
  21 import popcorn
  22 import popcorn::pop_config
  23 import popcorn::pop_repos
  24
  25 # Nitweb config file.
  26 class NitwebConfig
  27         super AppConfig
  28
  29         redef var default_db_name = "nitweb"
  30
  31         # Model to use.
  32         var model: Model
  33
  34         # MModule used to flatten model.
  35         var mainmodule: MModule
  36
  37         # Modelbuilder used to access sources.
  38         var modelbuilder: ModelBuilder
  39
  40         # The JSON API does not filter anything by default.
  41         #
  42         # So we can cache the model view.
  43         var view: ModelView is lazy do
  44                 var view = new ModelView(model)
  45                 view.min_visibility = private_visibility
  46                 view.include_fictive = true
  47                 view.include_empty_doc = true
  48                 view.include_attribute = true
  49                 view.include_test_suite = true
  50                 return view
  51         end
  52 end
  53
  54 # Specific handler for the nitweb API.
  55 abstract class APIHandler
  56         super Handler
  57
  58         # App config.
  59         var config: NitwebConfig
  60
  61         # Find the MEntity ` with `full_name`.
  62         fun find_mentity(model: ModelView, full_name: nullable String): nullable MEntity do
  63                 if full_name == null then return null
  64                 return model.mentity_by_full_name(full_name.from_percent_encoding)
  65         end
  66
  67         # Try to load the mentity from uri with `/:id`.
  68         #
  69         # Send 400 if `:id` is null.
  70         # Send 404 if no entity is found.
  71         # Return null in both cases.
  72         fun mentity_from_uri(req: HttpRequest, res: HttpResponse): nullable MEntity do
  73                 var id = req.param("id")
  74                 if id == null then
  75                         res.api_error(400, "Expected mentity full name")
  76                         return null
  77                 end
  78                 var mentity = find_mentity(config.view, id)
  79                 if mentity == null then
  80                         res.api_error(404, "MEntity `{id}` not found")
  81                 end
  82                 return mentity
  83         end
  84 end
  85
  86 # A Rooter dedicated to APIHandlers.
  87 class APIRouter
  88         super Router
  89
  90         # App config
  91         var config: NitwebConfig
  92 end
  93
  94 redef class HttpResponse
  95
  96         # Return an HTTP error response with `status`
  97         #
  98         # Like the rest of the API, errors are formated as JSON:
  99         # ~~~json
 100         # { "status": 404, "message": "Not found" }
 101         # ~~~
 102         fun api_error(status: Int, message: String) do
 103                 json(new APIError(status, message), status)
 104         end
 105 end
 106
 107 # An error returned by the API.
 108 #
 109 # Can be serialized to json.
 110 class APIError
 111         super Jsonable
 112
 113         # Reponse status
 114         var status: Int
 115
 116         # Response error message
 117         var message: String
 118
 119         # Json Object for this error
 120         var json: JsonObject is lazy do
 121                 var obj = new JsonObject
 122                 obj["status"] = status
 123                 obj["message"] = message
 124                 return obj
 125         end
 126
 127         redef fun serialize_to(v) do json.serialize_to(v)
 128 end
 129
 130 # Fullname representation that can be used to build decorated links
 131 #
 132 # * MPackage: `mpackage_name`
 133 # * MGroup: `(mpackage_name::)mgroup_name`
 134 class Namespace
 135         super Array[nullable NSEntity]
 136         super NSEntity
 137         serialize
 138
 139         redef fun to_s do return self.join("")
 140         redef fun serialize_to(v) do to_a.serialize_to(v)
 141 end
 142
 143 # Something that goes in a Namespace
 144 #
 145 # Can be either:
 146 # * a `NSToken` for tokens like `::`, `>` and `$`
 147 # * a `MSRef` for references to mentities
 148 interface NSEntity
 149         super Jsonable
 150 end
 151
 152 # A reference to a MEntity that can be rendered as a link.
 153 #
 154 # We do not reuse `MEntityRef` ref since NSRef can be found in a ref and create
 155 # an infinite loop.
 156 class NSRef
 157         super NSEntity
 158         serialize
 159
 160         # The mentity to link to/
 161         var mentity: MEntity
 162
 163         redef fun serialize_to(v) do
 164                 var obj = new JsonObject
 165                 obj["web_url"] = mentity.web_url
 166                 obj["api_url"] = mentity.api_url
 167                 obj["name"] = mentity.name
 168                 obj.serialize_to(v)
 169         end
 170 end
 171
 172 # A namespace token representation
 173 #
 174 # Used for namespace tokens like `::`, `>` and `$`
 175 redef class String
 176         super NSEntity
 177 end
 178
 179 redef class MEntity
 180
 181         # URL to `self` within the web interface.
 182         fun web_url: String do return "/doc/" / full_name
 183
 184         # URL to `self` within the JSON api.
 185         fun api_url: String do return "/api/entity/" / full_name
 186
 187         redef fun json do
 188                 var obj = super
 189                 obj["namespace"] = namespace
 190                 obj["web_url"] = web_url
 191                 obj["api_url"] = api_url
 192                 return obj
 193         end
 194
 195         # Get the full json repesentation of `self` with MEntityRefs resolved.
 196         fun api_json(handler: APIHandler): JsonObject do return full_json
 197
 198         # Return `self.full_name` as an object that can be serialized to json.
 199         fun namespace: nullable Namespace do return null
 200
 201         # Return a new NSRef to `self`.
 202         fun to_ns_ref: NSRef do return new NSRef(self)
 203 end
 204
 205 redef class MEntityRef
 206         redef fun json do
 207                 var obj = super
 208                 obj["namespace"] = mentity.namespace
 209                 obj["web_url"] = mentity.web_url
 210                 obj["api_url"] = mentity.api_url
 211                 obj["name"] = mentity.name
 212                 obj["mdoc"] = mentity.mdoc_or_fallback
 213                 obj["visibility"] = mentity.visibility
 214                 var modifiers = new JsonArray
 215                 for modifier in mentity.collect_modifiers do
 216                         modifiers.add modifier
 217                 end
 218                 obj["modifiers"] = modifiers
 219                 var mentity = self.mentity
 220                 if mentity isa MMethod then
 221                         obj["msignature"] = mentity.intro.msignature
 222                 else if mentity isa MMethodDef then
 223                         obj["msignature"] = mentity.msignature
 224                 else if mentity isa MVirtualTypeProp then
 225                         obj["bound"] = to_mentity_ref(mentity.intro.bound)
 226                 else if mentity isa MVirtualTypeDef then
 227                         obj["bound"] = to_mentity_ref(mentity.bound)
 228                 end
 229                 return obj
 230         end
 231
 232         redef fun full_json do
 233                 var obj = super
 234                 obj["location"] = mentity.location
 235                 return obj
 236         end
 237 end
 238
 239 redef class MDoc
 240
 241         # Add doc down processing
 242         redef fun json do
 243                 var obj = new JsonObject
 244                 obj["html_synopsis"] = html_synopsis.write_to_string
 245                 obj["html_documentation"] = html_documentation.write_to_string
 246                 return obj
 247         end
 248 end
 249
 250 redef class MPackage
 251         redef fun namespace do return new Namespace.from([to_ns_ref])
 252 end
 253
 254 redef class MGroup
 255         redef fun namespace do
 256                 var p = parent
 257                 if p == null then
 258                         return new Namespace.from([to_ns_ref, ">": nullable NSEntity])
 259                 end
 260                 return new Namespace.from([p.namespace, to_ns_ref, ">": nullable NSEntity])
 261         end
 262 end
 263
 264 redef class MModule
 265         redef fun namespace do
 266                 var mgroup = self.mgroup
 267                 if mgroup == null then
 268                         return new Namespace.from([to_ns_ref])
 269                 end
 270                 return new Namespace.from([mgroup.mpackage.to_ns_ref, "::", to_ns_ref: nullable NSEntity])
 271         end
 272
 273         private fun ns_for(visibility: MVisibility): nullable Namespace do
 274                 if visibility <= private_visibility then return namespace
 275                 var mgroup = self.mgroup
 276                 if mgroup == null then return namespace
 277                 return mgroup.mpackage.namespace
 278         end
 279 end
 280
 281 redef class MClass
 282         redef fun namespace do
 283                 return new Namespace.from([intro_mmodule.ns_for(visibility), "::", to_ns_ref: nullable NSEntity])
 284         end
 285 end
 286
 287 redef class MClassDef
 288         redef fun namespace do
 289                 if is_intro then
 290                         return new Namespace.from([mmodule.ns_for(mclass.visibility), "$", to_ns_ref: nullable NSEntity])
 291                 else if mclass.intro_mmodule.mpackage != mmodule.mpackage then
 292                         return new Namespace.from([mmodule.namespace, "$", mclass.namespace: nullable NSEntity])
 293                 else if mclass.visibility > private_visibility then
 294                         return new Namespace.from([mmodule.namespace, "$", mclass.to_ns_ref: nullable NSEntity])
 295                 end
 296                 return new Namespace.from([mmodule.full_name, "$::", mclass.intro_mmodule.to_ns_ref: nullable NSEntity])
 297         end
 298 end
 299
 300 redef class MProperty
 301         redef fun namespace do
 302                 if intro_mclassdef.is_intro then
 303                         return new Namespace.from([intro_mclassdef.mmodule.ns_for(visibility), "::", intro_mclassdef.mclass.to_ns_ref, "::", to_ns_ref: nullable NSEntity])
 304                 else
 305                         return new Namespace.from([intro_mclassdef.mmodule.namespace, "::", intro_mclassdef.mclass.to_ns_ref, "::", to_ns_ref: nullable NSEntity])
 306                 end
 307         end
 308 end
 309
 310 redef class MPropDef
 311         redef fun namespace do
 312                 var res = new Namespace
 313                 res.add mclassdef.namespace
 314                 res.add "$"
 315
 316                 if mclassdef.mclass == mproperty.intro_mclassdef.mclass then
 317                         res.add to_ns_ref
 318                 else
 319                         if mclassdef.mmodule.mpackage != mproperty.intro_mclassdef.mmodule.mpackage then
 320                                 res.add mproperty.intro_mclassdef.mmodule.ns_for(mproperty.visibility)
 321                                 res.add "::"
 322                         else if mproperty.visibility <= private_visibility then
 323                                 if mclassdef.mmodule.namespace_for(mclassdef.mclass.visibility) != mproperty.intro_mclassdef.mmodule.mpackage then
 324                                         res.add "::"
 325                                         res.add mproperty.intro_mclassdef.mmodule.to_ns_ref
 326                                         res.add "::"
 327                                 end
 328                         end
 329                         if mclassdef.mclass != mproperty.intro_mclassdef.mclass then
 330                                 res.add mproperty.intro_mclassdef.to_ns_ref
 331                                 res.add "::"
 332                         end
 333                         res.add to_ns_ref
 334                 end
 335                 return res
 336         end
 337 end
 338
 339 redef class MClassType
 340         redef var web_url = mclass.web_url is lazy
 341 end
 342
 343 redef class MNullableType
 344         redef var web_url = mtype.web_url is lazy
 345 end
 346
 347 redef class MParameterType
 348         redef var web_url = mclass.web_url is lazy
 349 end
 350
 351 redef class MVirtualType
 352         redef var web_url = mproperty.web_url is lazy
 353 end
 354
 355 redef class POSetElement[E]
 356         super Jsonable
 357
 358         # Return JSON representation of `self`.
 359         fun json: JsonObject do
 360                 assert self isa POSetElement[MEntity]
 361                 var obj = new JsonObject
 362                 obj["greaters"] = to_mentity_refs(greaters)
 363                 obj["direct_greaters"] = to_mentity_refs(direct_greaters)
 364                 obj["direct_smallers"] = to_mentity_refs(direct_smallers)
 365                 obj["smallers"] = to_mentity_refs(smallers)
 366                 return obj
 367         end
 368
 369         redef fun serialize_to(v) do json.serialize_to(v)
 370 end