i18n.h

Go to the documentation of this file.

/*
 * i18n.h
 *
 * Copyright (c) 2010 Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Internationalization and localization--particularly, management of
 * localized strings.
 */

#ifndef WAVEPACKET_I18N_H__
#define WAVEPACKET_I18N_H__


// includes --------------------------------------------------------------------
#include "nstream/nstream.h"


namespace i18n {

////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup general
/// \defgroup i18n Internationalization (i18n) Library
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// simple struct for managing a locale specification
struct locale_t {
        // public enums
        enum eConstants {
                eLanguageOffset         = 0,    ///< internal use only
                eCountryOffset          = 3,    ///< internal use only
                eEncodingOffset         = 6,    ///< internal use only
                eBufferSize             = 8,    ///< use this for buffer sizes
                eMaxLength              = 15    ///< max size of locale string
        };

        // constructor, manipulators
        locale_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        string[eLanguageOffset] = 0;    // null language
                        string[eCountryOffset] = 0;     // null country
                        string[eEncodingOffset] = 0;    // null encoding
                }

        const char * getString(void) const throw() { return string; }

        /// is this a valid locale?
        bool isValid(void) const throw();

        /// NOTE: for now we use ISO 639-1 (2-character language codes), but
        ///     in the future this library could use ISO 639-2 (3-character
        ///     codes) if they become common enough.  Client code should use
        ///     the locale_t::eBufferSize constant to construct character
        ///     buffer arrays, to remain forward compatible.
        const char * getLanguageCode(OUT char * buffer) const throw() {
                        ASSERT(buffer, "null");
                        buffer[0] = string[eLanguageOffset];
                        buffer[1] = string[eLanguageOffset + 1];
                        buffer[2] = 0;
                        return buffer;
                }

        const char * getCountryCode(OUT char * buffer) const throw() {
                        ASSERT(buffer, "null");
                        buffer[0] = string[eCountryOffset];
                        buffer[1] = string[eCountryOffset + 1];
                        buffer[2] = 0;
                        return buffer;
                }

        const char * getEncoding(OUT char * buffer) const throw() {
                        ASSERT(buffer, "null");
                        strcpy(buffer, string + eEncodingOffset);
                        return buffer;
                }

        // data fields
        char    string[eMaxLength + 1]; // up to 15 characters
};



class Manager {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Manager(void) throw();

        // i18n::Manager class interface methods -------------------------------
        virtual const char * getLocale(void) const throw() = 0;

        /// given a named stream (nstream::Stream), parses all localeInfo
        ///     blocks relevant to this Manager's locale.
        virtual void parseStrings(IN nstream::Stream * stream) = 0;

        /// recursively walks all child Entries beneath the specified Folder,
        ///     and calls parseStrings() on each.  Caller can provide a filter
        ///     (only Entries whose full path includes the filter as a substring
        ///     will be visited).  For many projects, the locale name can be
        ///     used as a filter (since filenames/paths will include the
        ///     locale specifier).  The caller can also (optionally) provide a
        ///     set of valid filename extensions.
        /// Skips files and directories beginning with a dot ('.').
        virtual void parseFolder(IN nstream::Folder * folder,
                                IN const SetString * extensions = NULL,
                                IN const char * filter = NULL) = 0;

        /// retrieves the specified string.  Returns null if ID is not
        ///     recognized.
        virtual const char * getString(IN const char * id) const throw() = 0;

        // static class methods (factory methods) ------------------------------
        static smart_ptr<Manager>  create(IN const char * locale);
};



////////////////////////////////////////////////////////////////////////////////
//
//      public API
//
////////////////////////////////////////////////////////////////////////////////

/// given a locale string, of the form "xx_yy.zzzz", returns a locale_t
///  - xx: 2 character language code (ISO 639-1)
///  - yy: 2 character country code (ISO 3166)
///  - zzzz: encoding (arbitrary length, only "UTF-8" is supported right now)
void getLocaleFromString(IN const char * localeString,
                        OUT locale_t& locale);

/// is this a valid country code?  Based on ISO 3166
bool isValidCountryCode(IN const char * country_code);

/// is this a valid language code?  Only supports ISO 639-1 (2-character codes)
///     for now.
bool isValidLanguageCode(IN const char * language_code);


/// is this a valid encoding?  "valid" means "supported by this library", which
///     for right now is just "UTF-8"
bool isValidEncoding(IN const char * encoding);


/// returns the string from the given Manager.  If the string isn't found, a
///     general (probably English) error message is returned instead.  This is
///     handy if a missing string isn't fatal and you don't need richer error
///     messaging.  This will help missing strings be identified by the user.
const char * getString(IN const Manager * mgr,
                                IN const char * id);


/// attempt to determine the local host locale.  Can return NULL!
const char * getHostLocale(void);


};      // i18n namespace

/*@}*/  // end of documentation block

#endif  // WAVEPACKET_I18N_H__