How to use module string tables.

The module string table is useful to declare error descriptions, error specific explanations and generically messages that the module may display to its users.

Module message tables can be internationalized through the Falcon Module Internationalization support.

Some macros are provided in module.h to help build module string tables, and are meant to be used under a certain pattern.

Applying the module table to the module is a matter of four simple steps.

First, each module willing to create an internationalizable module table should create two related files: <modulename>_st.h and <modulename>_st.c(pp)

Second, create the table declaring it in the header file using the FAL_MODSTR macro, like in the following example:

      // My module string table mymod_st.h
      // Message IDS (identifiers) must be unique.

      #include \<falcon/message_defs.h\>

      FAL_MODSTR( MSG0, "Message 0" );
      FAL_MODSTR( MSG1, "Message 1" );
      FAL_MODSTR( MSG2, "Message 2" );

If the program is being compiled in c++ mode, it is possible to declare a namespace around the FAL_MODSTR marcors for better encapsulation. The semicomma ";" at the end of each macro are optional.

Second, write the C/C++ table implementation. This is only required to declare the macro FALCON_REALIZE_STRTAB before including the string table definition:

      // Module string table realize file mymod_st.cpp

      #define FALCON_REALIZE_STRTAB
      #include "mymod_st.h"

Third, the main module file (usually called something as <modname>.cpp) must first include the string table at top level, and then realize it by declaring FALCON_DECLARE_MODULE, setting it to the local variable pointer used to instance the module, and then include the string table:

   #include \<module.h\>
   #include "mymod_st.h"

   FALCON_MODULE_DECL( const Falcon::EngineData &data )
   {
      // setup DLL engine common data
      data.set();

      // Module declaration
      Falcon::Module *self = new Falcon::Module();

      // Declare "self" as the variable holding the module
      #define FALCON_DECLARE_MODULE self
      #include "mymod_st.h"
      ...
   }

Fourth, retreive the strings from the VM using the Falcon::VMachine::moduleString method. That method actually peeks the current module for the desired string id. In example:

   #include "mymod_st.h"

   FALCON_FUNC aFuncIn_MyModule( Falcon::VMachine *vm )
   {
      const String *tlstring = vm->moduleString( MSG0 );
      // do something with tlstring
   }

The same can be achieved with Module::getString provided it is possible to access the module:

   #include "mymod_st.h"

   // MyNewModule extends Falcon::Module
   void MyNewModule::some_method(...)
   {
      const String *tlstring = this->getString( MSG0 );
      // do something with tlstring
   }

The macro FAL_STR( id ), defined as "vm->moduleString( id )" can be used as a handy shortcut for a standard compliant extension function.