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