Documentation|libcommon|HexLex: Improved apidoc for HexLex

doomsday/plugins/common/include/hexlex.h

@@ -30,21 +30,46 @@
 class HexLex
 {
 public:
-    HexLex();
+    /**
+     * Construct a new lexer and optionally prepare a script for parsing.
+     *
+     * @param script      If non-zero, prepare this script for parsing.
+     * @param sourcePath  If non-zerp, set this as the script source path.
+     */
+    HexLex(Str const *script = 0, Str const *sourcePath = 0);
     ~HexLex();
 
     /**
      * Prepare a new script for parsing. It is assumed that the @a script data
      * remains available until parsing is completed (or the script is replaced).
      *
-     * @param script      The script source to be parsed.
-     * @param sourcePath  Used to identify the script in log messages. A copy is made.
+     * @param script  The script source to be parsed.
+     */
+    void parse(Str const *script);
+
+    /**
+     * Change the source path used to identify the script in log messages.
+     *
+     * @param sourcePath  New source path to apply. A copy is made.
      */
-    void parse(Str const *script, Str const *sourcePath);
+    void setSourcePath(Str const *sourcePath = 0);
 
+    /**
+     * Attempt to read the next token from the script. @c true is returned if a
+     * token was parsed (or the previously parsed token was @em unread); otherwise
+     * @c false is returned (e.g., the end of the script was reached).
+     */
     bool readToken();
+
+    /**
+     * Returns a copy of the last read token.
+     */
     Str const *token();
 
+    /**
+     * Mark the last read token as @em unread, so that it will be re-read as the
+     * next read token.
+     */
     void unreadToken();
 
     Str const *readString();
@@ -55,6 +80,9 @@ class HexLex
     uint readMapNumber();
     Uri *readTextureUri(char const *defaultScheme);
 
+    /**
+     * Returns the line number at the current position in the script.
+     */
     int lineNumber() const;
 
 private:

doomsday/plugins/common/src/hexlex.cpp

@@ -44,7 +44,7 @@ void HexLex::syntaxError(char const *message)
               F_PrettyPath(Str_Text(&_sourcePath)), _lineNumber, message);
 }
 
-HexLex::HexLex()
+HexLex::HexLex(Str const *script, Str const *sourcePath)
     : _script(0)
     , _readPos(0)
     , _lineNumber(0)
@@ -53,6 +53,15 @@ HexLex::HexLex()
 {
     Str_InitStd(&_sourcePath);
     Str_InitStd(&_token);
+
+    if(script)
+    {
+        parse(script);
+    }
+    if(sourcePath)
+    {
+        setSourcePath(sourcePath);
+    }
 }
 
 HexLex::~HexLex()
@@ -61,10 +70,17 @@ HexLex::~HexLex()
     Str_Free(&_token);
 }
 
-void HexLex::parse(Str const *script, Str const *sourcePath)
+void HexLex::parse(Str const *script)
 {
     _script       = script;
+    _readPos      = 0;
+    _lineNumber   = 1;
+    _alreadyGot   = false;
+    Str_Clear(&_token);
+}
 
+void HexLex::setSourcePath(Str const *sourcePath)
+{
     if(!sourcePath)
     {
         Str_Clear(&_sourcePath);
@@ -73,11 +89,6 @@ void HexLex::parse(Str const *script, Str const *sourcePath)
     {
         Str_Copy(&_sourcePath, sourcePath);
     }
-
-    Str_Clear(&_token);
-    _readPos      = 0;
-    _lineNumber   = 1;
-    _alreadyGot   = false;
 }
 
 bool HexLex::readToken()

doomsday/plugins/common/src/p_sound.cpp

@@ -101,8 +101,7 @@ void SndInfoParser(Str const *path)
     {
         App_Log(DE2_RES_VERBOSE, "Parsing \"%s\"...", F_PrettyPath(Str_Text(path)));
 
-        HexLex lexer;
-        lexer.parse(script, path);
+        HexLex lexer(script, path);
 
         while(lexer.readToken())
         {

doomsday/plugins/hexen/src/p_anim.cpp

@@ -56,8 +56,7 @@ void AnimDefsParser(Str const *path)
 
     App_Log(DE2_RES_VERBOSE, "Parsing \"%s\"...", F_PrettyPath(Str_Text(path)));
 
-    HexLex lexer;
-    lexer.parse(script, path);
+    HexLex lexer(script, path);
 
     while(lexer.readToken())
     {

doomsday/plugins/hexen/src/p_mapinfo.cpp

@@ -100,8 +100,7 @@ void MapInfoParser(Str const *path)
     {
         App_Log(DE2_RES_VERBOSE, "Parsing \"%s\"...", F_PrettyPath(Str_Text(path)));
 
-        HexLex lexer;
-        lexer.parse(script, path);
+        HexLex lexer(script, path);
 
         while(lexer.readToken())
         {

doomsday/plugins/hexen/src/sn_sonix.cpp

@@ -108,8 +108,7 @@ void SndSeqParser(Str const *path)
 
     App_Log(DE2_RES_VERBOSE, "Parsing \"%s\"...", F_PrettyPath(Str_Text(path)));
 
-    HexLex lexer;
-    lexer.parse(script, path);
+    HexLex lexer(script, path);
 
     int i = SS_MAX_SCRIPTS;