- Changed DocBook version to 4.3, 5.0 is not officially released yet and most

  people don't have the required tools for it
- Improved miniswig to parse documentation comments (this can be used to
  automatically generate docbook text similar to what javadoc or doxygen do)
- swig makes use of the # num file preprocessor directives now. This improves
  error messages and comments in the code.

SVN-Revision: 2466

diff --git a/docs/scripting/scripting.xml b/docs/scripting/scripting.xml
index efbf97c..bb5b15f 100644 (file)
--- a/docs/scripting/scripting.xml
+++ b/docs/scripting/scripting.xml
@@ -22,17 +22,19 @@ Suite 330, Boston, MA 02111-1307, USA.
 
 -->
 <!--<?xml-stylesheet type="text/xsl" href="/home/ondra/src/docbook-xsl-1.68.1/xhtml/docbook.xsl" ?>-->
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V5.0/EN" "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
 
 <article xml:lang="en">
 
-<artheader>
+<articleinfo>
 <title>SuperTux Scripting Documentation</title>
 <author><firstname>Ondra</firstname><surname>Hosek</surname></author>
-</artheader>
+</articleinfo>
 <para>Since May 2005, SuperTux sports a Squirrel scripting interface useful for level designers who want to add some interactive pep to their levels. This document poses as a reference article for those who want to explore the various objects of the SuperTux scripting model.</para>
 <sect1><title>What is Squirrel?</title>
-<para>One of your first questions might be, &quot;What does a rodent have to do with a penguin?&quot; <link xlink:href="http://squirrel.sourceforge.net/">Squirrel</link> is a language with a syntax not much unlike other C-like languages (C, C++, Java, ...). In the current implementation, it is integrated as elements in the SuperTux level files.</para>
+<para>One of your first questions might be, &quot;What does a rodent have to do
+with a penguin?&quot; <ulink url="http://squirrel.sourceforge.net/">Squirrel</ulink> is a language with a syntax not much unlike other C-like languages (C, C++, Java, ...). In the current implementation, it is integrated as elements in the SuperTux level files.</para>
 </sect1>
 <sect1><title>Squirrel, Scheme and SuperTux</title>
 <para>I have no clue if the developers simply chose Squirrel just because the name so nicely integrates into the series of words &quot;SuperTux&quot; and &quot;Scheme&quot;. Currently, the Squirrel code is integrated in string arguments of Scheme elements in SuperTux level files. (Whew.) This is an example code block inside a level:

diff --git a/src/scripting/wrapper.cpp b/src/scripting/wrapper.cpp
index 42017ae..dbde0ec 100644 (file)
--- a/src/scripting/wrapper.cpp
+++ b/src/scripting/wrapper.cpp
@@ -1,8 +1,10 @@
 /**
- * WARNING: This file is automatically generated from './build/i686-pc-linux-gnu/optimize/miniswig.tmp' - do not change
+ * WARNING: This file is automatically generated from:
+ *  'src/scripting/wrapper.interface.h'
+ * DO NOT CHANGE
  */
-
 #include <config.h>
+
 #include <new>
 #include <assert.h>
 #include <string>

diff --git a/src/scripting/wrapper.h b/src/scripting/wrapper.h
index 35f7184..b8d5439 100644 (file)
--- a/src/scripting/wrapper.h
+++ b/src/scripting/wrapper.h
@@ -1,5 +1,7 @@
 /**
- * WARNING: This file is automatically generated from './build/i686-pc-linux-gnu/optimize/miniswig.tmp' - do not change
+ * WARNING: This file is automatically generated from:
+ *  'src/scripting/wrapper.interface.h'
+ * DO NOT CHANGE
  */
 #ifndef __supertux_WRAPPER_H__
 #define __supertux_WRAPPER_H__

diff --git a/tools/miniswig/create_wrapper.cpp b/tools/miniswig/create_wrapper.cpp
index 2233f83..6956ced 100644 (file)
--- a/tools/miniswig/create_wrapper.cpp
+++ b/tools/miniswig/create_wrapper.cpp
@@ -8,11 +8,14 @@
 void
 WrapperCreator::create_wrapper(Namespace* ns)
 {
+    std::string fromfile = original_file != "" ? original_file : inputfile;
+
     // hpp file
     hppout
         << "/**\n"
-        << " * WARNING: This file is automatically generated from '"
-        << inputfile << "' - do not change\n"
+        << " * WARNING: This file is automatically generated from:\n"
+        << " *  '" << fromfile << "'\n"
+        << " * DO NOT CHANGE\n"
         << " */\n"
         << "#ifndef __" << modulename << "_WRAPPER_H__\n"
         << "#define __" << modulename << "_WRAPPER_H__\n"
@@ -27,11 +30,12 @@ WrapperCreator::create_wrapper(Namespace* ns)
     
     // cpp header
     out << "/**\n"
-        << " * WARNING: This file is automatically generated from '"
-        << inputfile << "' - do not change\n"
+        << " * WARNING: This file is automatically generated from:\n"
+        << " *  '" << fromfile << "'\n"
+        << " * DO NOT CHANGE\n"
         << " */\n"
-        << "\n"
         << "#include <config.h>\n"
+        << "\n"
         << "#include <new>\n"
         << "#include <assert.h>\n"
         << "#include <string>\n"

diff --git a/tools/miniswig/globals.h b/tools/miniswig/globals.h
index 362559b..51cef65 100644 (file)
--- a/tools/miniswig/globals.h
+++ b/tools/miniswig/globals.h
@@ -9,6 +9,16 @@ extern CompilationUnit* unit;
 extern bool search_down;
 extern Namespace* search_namespace;
 extern Namespace* current_namespace;
+extern std::string last_docucomment;
+// the first file indicated by # 1 "..."
+// (this is what the C preprocessor outputs so that you know which was the
+// original file before preprocessing
+extern std::string original_file;
+// the filename where the current fragment came from (before it was included by
+// the preprocessor)
+extern std::string current_file;
+// get line number inside the current_file
+int getCurrentLine();
 
 // config/output
 extern std::istream* input;

diff --git a/tools/miniswig/lexer.ll b/tools/miniswig/lexer.ll
index 71d54ed..8a2e9a6 100644 (file)
--- a/tools/miniswig/lexer.ll
+++ b/tools/miniswig/lexer.ll
@@ -1,6 +1,8 @@
 %{
 #include <math.h>
 #include <stdlib.h>
+#include <string.h>
+#include <iostream>
 #include "tree.h"
 #include "parser.hpp"
 #include "globals.h"
@@ -12,6 +14,16 @@
     input->read(buf, max_size);                             \
     result = input->gcount();                               \
 }
+
+std::string last_docucomment;
+std::string original_file;
+std::string current_file;
+int offset_lnum;
+
+int getCurrentLine()
+{
+    return yylineno - offset_lnum;
+}
     
 %}
 
@@ -21,10 +33,30 @@
 
 %%
 
+#[ \t]+[0-9]+[ \t]+.*                         {
+    int lnum;
+    char file[1024];
+    if(sscanf(yytext, "# %d \"%1023[^\"]\"", &lnum, file) == 2) {
+        offset_lnum = yylineno - lnum + 1;
+        current_file = file;
+        if(original_file == "")
+            original_file = file;
+    } else {
+        std::cerr << "Warning: Parse error in processor info directive.\n";
+    }
+}
 #.*                                     /* ignore preprocessor directives */
 [[:space:]]+                            /* eat spaces */
-\/\*.*\*\/                              /* eat comment */
-\/\/[^\n]*\n                            /* eat comment */        
+\/\*.*\*\/                              {
+    if(yytext[2] == '*' && yytext[3] != '/') { // It's a docu comment...
+        last_docucomment = std::string(yytext+3, strlen(yytext)-5);
+    }
+}
+\/\/[^\n]*\n                            {
+    if(yytext[2] == '/') { // it's a docu comment...
+        last_docucomment = std::string(yytext+3, strlen(yytext)-4);
+    }
+}
 class                                   { return T_CLASS; }
 struct                                  { return T_STRUCT; }
 static                                  { return T_STATIC; }

diff --git a/tools/miniswig/main.cpp b/tools/miniswig/main.cpp
index f28e3f7..2a5b1ed 100644 (file)
--- a/tools/miniswig/main.cpp
+++ b/tools/miniswig/main.cpp
@@ -80,6 +80,7 @@ int main(int argc, char** argv)
             std::cerr << "Couldn't open file '" << input << "' for reading.\n";
             return 1;
         }
+        current_file = inputfile;
         unit = new CompilationUnit();
         Namespace* std_namespace = new Namespace();
         std_namespace->name = "std";

diff --git a/tools/miniswig/parser.yy b/tools/miniswig/parser.yy
index 6c25c9e..d405dde 100644 (file)
--- a/tools/miniswig/parser.yy
+++ b/tools/miniswig/parser.yy
@@ -40,7 +40,8 @@ public:
     ParseError(const std::string& message) throw()
     {
         std::ostringstream msg;
-        msg << "Parse error in line " << yylineno << ": "
+        msg << "Parse error in '" << current_file
+            << "' line " << getCurrentLine() << ": "
             << message;
         this->message = msg.str();
     }
@@ -141,6 +142,8 @@ class_declaration:
             current_class = new Class();
             current_class->name = $2;
             free($2);
+            current_class->docu_comment = last_docucomment;
+            last_docucomment = "";
             current_visibility = ClassMember::PROTECTED;
         }
     class_body '}' ';'
@@ -187,6 +190,8 @@ constructor_declaration:
         {
             currentFunction = new Function();
             currentFunction->type = Function::CONSTRUCTOR;
+            currentFunction->docu_comment = last_docucomment;
+            last_docucomment = "";
             free($1);
         }
     parameter_list ')' ';'
@@ -200,6 +205,8 @@ destructor_declaration:
         {
             currentFunction = new Function();
             currentFunction->type = Function::DESTRUCTOR;
+            currentFunction->docu_comment = last_docucomment;
+            last_docucomment = "";
             free($3);
             $$ = currentFunction;
         }
@@ -223,6 +230,8 @@ function_declaration:
             delete $2;
             currentFunction->name = $3;
             free($3);
+            currentFunction->docu_comment = last_docucomment;
+            last_docucomment = "";
         }                           
     parameter_list ')' abstract_declaration ';'
         {

diff --git a/tools/miniswig/tree.h b/tools/miniswig/tree.h
index 387012e..2e7149c 100644 (file)
--- a/tools/miniswig/tree.h
+++ b/tools/miniswig/tree.h
@@ -161,6 +161,7 @@ public:
         DESTRUCTOR
     };
     FuncType type;
+    std::string docu_comment;
     std::string name;
     Type return_type;
     std::vector<Parameter> parameters;
@@ -175,6 +176,7 @@ public:
     }
     
     std::vector<ClassMember*> members;
+    std::string docu_comment;
 };
 
 class Namespace {