src/doc/doc_commands.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 # Parsing of commands understood by documentation tools.
  16 #
  17 # This can be through:
  18 # * `nitx` commands like `code: MEntity::name`
  19 # * `nitdoc` wikilinks like `[[doc: MEntity::name]]`
  20 module doc_commands
  21
  22 # A command aimed at a documentation tool like `nitdoc` or `nitx`.
  23 #
  24 # `DocCommand` are generally of the form `command: args`.
  25 interface DocCommand
  26
  27         # Original command string.
  28         fun string: String is abstract
  29
  30         # Command name.
  31         fun name: String is abstract
  32
  33         # Command arguments.
  34         #
  35         # FIXME: define a syntax
  36         fun args: Array[String] is abstract
  37
  38         # Command factory.
  39         #
  40         # Returns a concrete instance of `DocCommand` depending on the string.
  41         new(command_string: String) do
  42                 if command_string.has_prefix("doc:") then
  43                         return new ArticleCommand(command_string)
  44                 else if command_string.has_prefix("comment:") then
  45                         return new CommentCommand(command_string)
  46                 else if command_string.has_prefix("list:") then
  47                         return new ListCommand(command_string)
  48                 else if command_string.has_prefix("param:") then
  49                         return new ParamCommand(command_string)
  50                 else if command_string.has_prefix("return:") then
  51                         return new ReturnCommand(command_string)
  52                 else if command_string.has_prefix("new:") then
  53                         return new NewCommand(command_string)
  54                 else if command_string.has_prefix("call:") then
  55                         return new CallCommand(command_string)
  56                 else if command_string.has_prefix("code:") then
  57                         return new CodeCommand(command_string)
  58                 else if command_string.has_prefix("graph:") then
  59                         return new GraphCommand(command_string)
  60                 end
  61                 return new UnknownCommand(command_string)
  62         end
  63
  64         redef fun to_s do return string
  65 end
  66
  67 # Used to factorize initialization of DocCommands.
  68 abstract class AbstractDocCommand
  69         super DocCommand
  70
  71         redef var string
  72         redef var name is noinit
  73         redef var args = new Array[String]
  74
  75         init do
  76                 # parse command
  77                 var str = new FlatBuffer
  78                 var i = 0
  79                 while i < string.length do
  80                         var c = string[i]
  81                         i += 1
  82                         if c == ':' then break
  83                         str.add c
  84                 end
  85                 name = str.write_to_string
  86                 # parse args
  87                 args.add string.substring_from(i).trim
  88         end
  89 end
  90
  91 # A `DocCommand` not recognized by documentation tools.
  92 #
  93 # Used to provide warnings or any other behavior for unexisting commands.
  94 class UnknownCommand
  95         super AbstractDocCommand
  96 end
  97
  98 # A `DocCommand` that includes the documentation article of a `MEntity`.
  99 #
 100 # Syntax: `doc: MEntity::name`.
 101 class ArticleCommand
 102         super AbstractDocCommand
 103 end
 104
 105 # A `DocCommand` that includes the MDoc of a `MEntity`.
 106 #
 107 # Syntax: `comment: MEntity::name`.
 108 class CommentCommand
 109         super AbstractDocCommand
 110 end
 111
 112 # A `DocCommand` that includes a list of something.
 113 #
 114 # Syntax: `list:kind: <arg>`.
 115 class ListCommand
 116         super AbstractDocCommand
 117 end
 118
 119 # A `DocCommand` that includes the list of methods tanking a `MType` as parameter.
 120 #
 121 # Syntax: `param: MType`.
 122 class ParamCommand
 123         super AbstractDocCommand
 124 end
 125
 126 # A `DocCommand` that includes the list of methods returning a `MType` as parameter.
 127 #
 128 # Syntax: `param: MType`.
 129 class ReturnCommand
 130         super AbstractDocCommand
 131 end
 132
 133 # A `DocCommand` that includes the list of methods creating new instances of a specific `MType`
 134 #
 135 # Syntax: `new: MType`.
 136 class NewCommand
 137         super AbstractDocCommand
 138 end
 139
 140 # A `DocCommand` that includes the list of methods calling a specific `MProperty`.
 141 #
 142 # Syntax: `call: MEntity::name`.
 143 class CallCommand
 144         super AbstractDocCommand
 145 end
 146
 147 # A `DocCommand` that includes the source code of a `MEntity`.
 148 #
 149 # Syntax:
 150 # * `code: MEntity::name`
 151 # * `./src/file.nit` to include source code from a file.
 152 # * `./src/file.nit:1,2--3,4` to select code between positions.
 153 class CodeCommand
 154         super AbstractDocCommand
 155 end
 156
 157 # A `DocCommand` that display an graph for a `MEntity`.
 158 #
 159 # Syntax:
 160 # * `graph: MEntity::name`
 161 class GraphCommand
 162         super AbstractDocCommand
 163 end