src/web/model_api.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 module model_api
  16
  17 import web_base
  18 import highlight
  19 import uml
  20
  21 # Specific handler for nitweb API.
  22 abstract class APIHandler
  23         super ModelHandler
  24
  25         # The JSON API does not filter anything by default.
  26         #
  27         # So we can cache the model view.
  28         var view: ModelView is lazy do
  29                 var view = new ModelView(model)
  30                 view.min_visibility = private_visibility
  31                 view.include_fictive = true
  32                 view.include_empty_doc = true
  33                 view.include_attribute = true
  34                 view.include_test_suite = true
  35                 return view
  36         end
  37
  38         # Try to load the mentity from uri with `/:id`.
  39         #
  40         # Send 400 if `:id` is null.
  41         # Send 404 if no entity is found.
  42         # Return null in both cases.
  43         fun mentity_from_uri(req: HttpRequest, res: HttpResponse): nullable MEntity do
  44                 var id = req.param("id")
  45                 if id == null then
  46                         res.error 400
  47                         return null
  48                 end
  49                 var mentity = find_mentity(view, id)
  50                 if mentity == null then
  51                         res.error 404
  52                 end
  53                 return mentity
  54         end
  55 end
  56
  57 # Group all api handlers in one router.
  58 class APIRouter
  59         super Router
  60
  61         # Model to pass to handlers.
  62         var model: Model
  63
  64         # ModelBuilder to pass to handlers.
  65         var modelbuilder: ModelBuilder
  66
  67         # Mainmodule to pass to handlers.
  68         var mainmodule: MModule
  69
  70         init do
  71                 use("/list", new APIList(model, mainmodule))
  72                 use("/search", new APISearch(model, mainmodule))
  73                 use("/random", new APIRandom(model, mainmodule))
  74                 use("/entity/:id", new APIEntity(model, mainmodule))
  75                 use("/code/:id", new APIEntityCode(model, mainmodule, modelbuilder))
  76                 use("/uml/:id", new APIEntityUML(model, mainmodule))
  77         end
  78 end
  79
  80 # Search mentities from a query string.
  81 #
  82 # Example: `GET /search?q=Arr`
  83 class APISearch
  84         super APIHandler
  85
  86         redef fun get(req, res) do
  87                 var q = req.string_arg("q")
  88                 if q == null then
  89                         res.error 400
  90                         return
  91                 end
  92                 var arr = new JsonArray
  93                 for mentity in view.mentities do
  94                         if mentity.name.has_prefix(q) then arr.add mentity
  95                 end
  96                 res.json arr
  97         end
  98 end
  99
 100 # List all mentities.
 101 #
 102 # MEntities can be filtered on their kind using the `k` parameter.
 103 # Allowed kinds are `package`, `group`, `module`, `class`, `classdef`, `property`, `propdef`.
 104 #
 105 # List size can be limited with the `n` parameter.
 106 #
 107 # Example: `GET /list?k=module?n=10`
 108 class APIList
 109         super APIHandler
 110
 111         # List mentities depending on the `k` kind parameter.
 112         fun list_mentities(req: HttpRequest): Array[MEntity] do
 113                 var k = req.string_arg("k")
 114                 var mentities = new Array[MEntity]
 115                 if k == "package" then
 116                         for mentity in view.mpackages do mentities.add mentity
 117                 else if k == "group" then
 118                         for mentity in view.mgroups do mentities.add mentity
 119                 else if k == "module" then
 120                         for mentity in view.mmodules do mentities.add mentity
 121                 else if k == "class" then
 122                         for mentity in view.mclasses do mentities.add mentity
 123                 else if k == "classdef" then
 124                         for mentity in view.mclassdefs do mentities.add mentity
 125                 else if k == "property" then
 126                         for mentity in view.mproperties do mentities.add mentity
 127                 else if k == "propdef" then
 128                         for mentity in view.mpropdefs do mentities.add mentity
 129                 else
 130                         for mentity in view.mentities do mentities.add mentity
 131                 end
 132                 return mentities
 133         end
 134
 135         # Limit mentities depending on the `n` parameter.
 136         fun limit_mentities(req: HttpRequest, mentities: Array[MEntity]): Array[MEntity] do
 137                 var n = req.int_arg("n")
 138                 if n != null then
 139                         return mentities.sub(0, n)
 140                 end
 141                 return mentities
 142         end
 143
 144         redef fun get(req, res) do
 145                 var mentities = list_mentities(req)
 146                 mentities = limit_mentities(req, mentities)
 147                 res.json new JsonArray.from(mentities)
 148         end
 149 end
 150
 151 # Return a random list of MEntities.
 152 #
 153 # Example: `GET /random?n=10&k=module`
 154 class APIRandom
 155         super APIList
 156
 157         # Randomize mentities order.
 158         fun randomize_mentities(req: HttpRequest, mentities: Array[MEntity]): Array[MEntity] do
 159                 var res = mentities.to_a
 160                 res.shuffle
 161                 return res
 162         end
 163
 164         redef fun get(req, res) do
 165                 var mentities = list_mentities(req)
 166                 mentities = limit_mentities(req, mentities)
 167                 mentities = randomize_mentities(req, mentities)
 168                 res.json new JsonArray.from(mentities)
 169         end
 170 end
 171
 172 # Return the JSON representation of a MEntity.
 173 #
 174 # Example: `GET /entity/core::Array`
 175 class APIEntity
 176         super APIHandler
 177
 178         redef fun get(req, res) do
 179                 var mentity = mentity_from_uri(req, res)
 180                 if mentity == null then return
 181                 res.json mentity.api_json(self)
 182         end
 183 end
 184
 185
 186 # Return a UML representation of MEntity.
 187 #
 188 # Example: `GET /entity/core::Array/uml`
 189 class APIEntityUML
 190         super APIHandler
 191
 192         redef fun get(req, res) do
 193                 var mentity = mentity_from_uri(req, res)
 194                 var dot
 195                 if mentity isa MClassDef then mentity = mentity.mclass
 196                 if mentity isa MClass then
 197                         var uml = new UMLModel(view, mainmodule)
 198                         dot = uml.generate_class_uml.write_to_string
 199                 else if mentity isa MModule then
 200                         var uml = new UMLModel(view, mentity)
 201                         dot = uml.generate_package_uml.write_to_string
 202                 else
 203                         res.error 404
 204                         return
 205                 end
 206                 res.send render_svg(dot)
 207         end
 208
 209         # Render a `dot` string as a svg image.
 210         fun render_svg(dot: String): String do
 211                 var proc = new ProcessDuplex("dot", "-Tsvg")
 212                 var svg = proc.write_and_read(dot)
 213                 proc.close
 214                 proc.wait
 215                 return svg
 216         end
 217 end
 218
 219 # Return the source code of MEntity.
 220 #
 221 # Example: `GET /entity/core::Array/code`
 222 class APIEntityCode
 223         super APIHandler
 224
 225         # Modelbuilder used to access sources.
 226         var modelbuilder: ModelBuilder
 227
 228         redef fun get(req, res) do
 229                 var mentity = mentity_from_uri(req, res)
 230                 if mentity == null then return
 231                 var source = render_source(mentity)
 232                 if source == null then
 233                         res.error 404
 234                         return
 235                 end
 236                 res.send source
 237         end
 238
 239         # Highlight `mentity` source code.
 240         private fun render_source(mentity: MEntity): nullable HTMLTag do
 241                 var node = modelbuilder.mentity2node(mentity)
 242                 if node == null then return null
 243                 var hl = new HighlightVisitor
 244                 hl.enter_visit node
 245                 return hl.html
 246         end
 247 end