// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WMESSAGE_RESOURCE_BUNDLE_
#define WMESSAGE_RESOURCE_BUNDLE_

#include <string>
#include <vector>
#include "Wt/WDllDefs.h"

namespace Wt {

class WString;
class WMessageResources;
class WApplication;
class WebSession;

/*! \class WMessageResourceBundle Wt/WMessageResourceBundle Wt/WMessageResourceBundle
 *  \brief A class which manages text messages that may be adapted to the
 *         current locale.
 *
 * The resource bundle manages a number of resource files, which allow
 * the developer to conceptually manage its messages in a number of
 * libraries.
 *
 * For example, a WApplication may have a generic message library, that is
 * shared with many other libraries, with re-occurring messages (such as
 * 'welcome', 'add to shopping cart', and 'pay'), and a specific message
 * library for specific messages.
 */
class WT_API WMessageResourceBundle
{
public:
  /*! \brief Add a (series) of message resource files to be used.
   *
   * The <i>path</i> is not a URI, and relative paths will be resolved
   * with respect to the working directory of the server. The XML
   * files do not need to be deployed in the web server's docroot.
   *
   * When you give as <i>path</i>: /path/to/name, then the following message
   * resource files will be used:
   *  - /path/to/name.xml (default, English)
   *  - /path/to/name_nl.xml (for Dutch)
   *  - /path/to/name_fr.xml (for French)
   *  - etc...
   *
   * The message file that is used depends on the application's locale.
   *
   * A Message resource file must be formatted as follows:
   * \code
     <?xml version="1.0" encoding="UTF8"?>
     <messages>
       <message id='welcome-text'>
         Welcome dear visiter, {1} of the WFooBar magic website !
       </message>
       <message id='company-policy'>
         The company policy is to <b>please our share-holders</b>.
       </message>
     </messages>
     \endcode
   *
   * The encodings supported are ASCII, UTF8 (recommended) or UTF16.
   *
   * To refer the two messages defined in this resource file, use
   * WString::tr("welcome-text").\link WString::arg()
   * arg\endlink(userName) or WWidget::tr("company-policy").
   *
   * \sa WApplication::locale(), WString::tr(), WWidget::tr()
   */
  void use(const std::string& path, bool loadInMemory = true);

  /*! \brief Get the value for a particular string in the current locale.
   */
  std::wstring getValue(const WString& s);

  /*! \brief Get the UTF8-encoded value for a particular string in the
   *         current locale.
   */
  std::string getUTF8Value(const WString& s);

  /*! \brief Reread the message resources.
   */
  void refresh();

private:
  std::vector<WMessageResources *> messageResources_;

  WMessageResourceBundle();
  ~WMessageResourceBundle();

  void hibernate();

  bool resolveKey(const std::string& key, std::string& result);

  friend class WApplication;
  friend class WebSession;
  friend class WString;
};

}

#endif // WMESSAGE_RESOURCE_BUNDLE_
