src/script/api/doxygen_filter.awk

   1 # $Id: doxygen_filter.awk 23650 2011-12-21 14:30:08Z yexo $
   2
   3 # This file is part of OpenTTD.
   4 # OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   5 # OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   6 # See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   7
   8 #
   9 # Awk script to automatically generate the code needed
  10 # to export the script APIs to Squirrel.
  11 #
  12 # Note that arrays are 1 based...
  13 #
  14
  15
  16 BEGIN {
  17         cls = ""
  18         api_selected = ""
  19         cls_in_api = ""
  20         cls_level = 0
  21         skip_function_body = "false"
  22         skip_function_par = 0
  23         RS = "\r|\n"
  24         apis = tolower(api)
  25         if (apis == "gs") apis = "game"
  26 }
  27
  28 {
  29         gsub(/Script/, api)
  30 }
  31
  32 {
  33         if (skip_function_body == "true") {
  34                 input = $0
  35                 gsub(/[^{]/, "", input)
  36                 skip_function_par += length(input)
  37                 if (skip_function_par > 0) {
  38                         input = $0
  39                         gsub(/[^}]/, "", input)
  40                         skip_function_par -= length(input)
  41                         if (skip_function_par == 0) skip_function_body = "false"
  42                 }
  43         }
  44         if (skip_function_body == "true") next
  45 }
  46
  47 /@file/ {
  48         gsub(/script/, apis)
  49 }
  50
  51 /^([     ]*)\* @api/ {
  52         if (api == "Script") {
  53                 api_selected = "true"
  54                 next
  55         }
  56
  57         # By default, classes are not selected
  58         if (cls_level == 0) api_selected = "false"
  59
  60         gsub("^([        ]*)", "", $0)
  61         gsub("* @api ", "", $0)
  62
  63         if ($0 == "none") {
  64                 api_selected = "false"
  65         } else if ($0 == "-all") {
  66                 api_selected = "false"
  67         } else if (match($0, "-" apis)) {
  68                 api_selected = "false"
  69         } else if (match($0, apis)) {
  70                 api_selected = "true"
  71         }
  72
  73         next
  74 }
  75
  76 # Ignore forward declarations of classes
  77 /^(     *)class(.*);/ { next; }
  78 # We only want to have public functions exported for now
  79 /^(     *)class/     {
  80         if (cls_level == 0) {
  81                 if (api_selected == "") {
  82                         print "Class '"$2"' has no @api. It won't be published to any API." > "/dev/stderr"
  83                         api_selected = "false"
  84                 }
  85                 public = "false"
  86                 cls_param[0] = ""
  87                 cls_param[1] = 1
  88                 cls_param[2] = "x"
  89                 cls_in_api = api_selected
  90                 api_selected = ""
  91                 cls = $2
  92
  93                 if (cls_in_api == "true") {
  94                         print comment_buffer
  95                         print
  96                         print "public:"
  97                         comment_buffer = ""
  98                 }
  99         } else if (cls_level == 1) {
 100                 if (api_selected == "") api_selected = cls_in_api
 101
 102                 if (api_selected == "true") {
 103                         print comment_buffer
 104                         print
 105                         print "public:"
 106                         comment_buffer = ""
 107                 }
 108                 api_selected = ""
 109         } else {
 110                 print "Classes nested too deep" > "/dev/stderr"
 111                 exit 1
 112         }
 113         cls_level++
 114         next
 115 }
 116 /^(     *)public/    { if (cls_level == 1) comment_buffer = ""; public = "true";  next; }
 117 /^(     *)protected/ { if (cls_level == 1) comment_buffer = ""; public = "false"; next; }
 118 /^(     *)private/   { if (cls_level == 1) comment_buffer = ""; public = "false"; next; }
 119
 120 # Ignore special doxygen blocks
 121 /^#ifndef DOXYGEN_API/          { doxygen_skip = "true"; next; }
 122 /^#ifdef DOXYGEN_API/           { doxygen_skip = "next"; next; }
 123 /^#endif \/\* DOXYGEN_API \*\// { doxygen_skip = "false"; next; }
 124 /^#else/                         {
 125         if (doxygen_skip == "next") {
 126                 doxygen_skip = "true";
 127         } else {
 128                 doxygen_skip = "false";
 129         }
 130         next;
 131 }
 132 { if (doxygen_skip == "true") next }
 133
 134 /^#/ {
 135         next
 136 }
 137
 138 # Store comments
 139 /\/\*\*.*\*\//   { comment_buffer = $0; comment = "false"; next; }
 140 /\/\*.*\*\//     { comment_buffer = ""; comment = "false"; next; }
 141 /\/\*\*/         { comment_buffer = $0 "\n"; comment = "true";  next; }
 142 /\/\*/           { comment_buffer = ""; comment = "false";  next; }
 143 /\*\//           { comment_buffer = comment_buffer $0; comment = "false"; next; }
 144 {
 145         if (comment == "true" && !match($0, /@api/))
 146         {
 147                 if (match($0, /@game /) && api != "GS") next;
 148                 if (match($0, /@ai /) && api != "AI") next;
 149                 gsub("@game ", "", $0);
 150                 gsub("@ai ", "", $0);
 151                 comment_buffer = comment_buffer $0 "\n"; next;
 152         }
 153 }
 154
 155
 156 # We need to make specialized conversions for structs
 157 /^(     *)struct/ {
 158         comments_so_far = comment_buffer
 159         comment_buffer = ""
 160         cls_level++
 161
 162         # Check if we want to publish this struct
 163         if (api_selected == "") api_selected = cls_in_api
 164         if (api_selected == "false") {
 165                 api_selected = ""
 166                 next
 167         }
 168         api_selected = ""
 169
 170         if (public == "false") next
 171
 172         print comments_so_far
 173         print $0
 174
 175         next
 176 }
 177
 178 # We need to make specialized conversions for enums
 179 /^(     *)enum/ {
 180         comments_so_far = comment_buffer
 181         comment_buffer = ""
 182         cls_level++
 183
 184         # Check if we want to publish this enum
 185         if (api_selected == "") api_selected = cls_in_api
 186         if (api_selected == "false") {
 187                 api_selected = ""
 188                 next
 189         }
 190         api_selected = ""
 191
 192         if (public == "false") next
 193
 194         in_enum = "true"
 195
 196         print comments_so_far
 197         print $0
 198
 199         next
 200 }
 201
 202 # Maybe the end of the class, if so we can start with the Squirrel export pretty soon
 203 /};/ {
 204         comment_buffer = ""
 205         cls_level--
 206         if (cls_level != 0) {
 207                 if (in_enum == "true") print
 208                 in_enum = "false"
 209                 next
 210         }
 211         if (cls == "") {
 212                 next
 213         }
 214         if (cls_in_api == "true") print
 215         next;
 216 }
 217
 218 # Empty/white lines
 219 /^([    ]*)$/ {
 220         print $0
 221
 222         next
 223 }
 224
 225 # Skip non-public functions
 226 { if (public == "false") next }
 227
 228 # Add enums
 229 {
 230         if (in_enum == "true") {
 231                 print comment_buffer
 232                 comment_buffer = ""
 233                 gsub("=([^/]*),", ",", $0)
 234                 print $0
 235
 236                 # Check if this a special error enum
 237                 if (match(enums[enum_size], ".*::ErrorMessages") != 0) {
 238                         # syntax:
 239                         # enum ErrorMessages {
 240                         #       ERR_SOME_ERROR, // [STR_ITEM1, STR_ITEM2, ...]
 241                         # }
 242
 243                         ##TODO: don't print the STR_*
 244                 }
 245                 next
 246         }
 247 }
 248
 249 # Add a const (non-enum) value
 250 /^[     ]*static const \w+ \w+ = -?\(?\w*\)?\w+;/ {
 251         if (api_selected == "") api_selected = cls_in_api
 252         if (api_selected == "false") {
 253                 api_selected = ""
 254                 comment_buffer = ""
 255                 next
 256         }
 257         print comment_buffer
 258         print $0
 259         comment_buffer = ""
 260         next
 261 }
 262
 263 # Add a method to the list
 264 /^.*\(.*\).*$/ {
 265         if (cls_level != 1) next
 266         if (!match($0, ";")) {
 267                 gsub(/ :$/, ";")
 268                 skip_function_body = "true"
 269         }
 270         if (match($0, "~")) {
 271                 if (api_selected != "") {
 272                         print "Destructor for '"cls"' has @api. Tag ignored." > "/dev/stderr"
 273                         api_selected = ""
 274                 }
 275                 next
 276         }
 277
 278         # Check if we want to publish this function
 279         if (api_selected == "") api_selected = cls_in_api
 280         if (api_selected == "false") {
 281                 api_selected = ""
 282                 comment_buffer = ""
 283                 next
 284         }
 285         api_selected = ""
 286
 287         print comment_buffer
 288         print $0
 289         comment_buffer = ""
 290
 291         next
 292 }