-- File:	Message_MsgFile.cdl
-- Created:	26.04.01 18:24:38
-- Author:	OCC Team
---Copyright:	Open CASCADE S.A. 2007


class MsgFile from Message

    ---Purpose: A tool providing facility to load definitions of message strings from 
    --          resource file(s).
    --          
    --          The message file is an ASCII file which defines a set of messages. 
    --          Each message is identified by its keyword (string). 
    --          
    --          All lines in the file starting with the exclamation sign 
    --          (perhaps preceeding by spaces and/or tabs) are ignored as comments.
    --          
    --          Each line in the file starting with the dot character "." 
    --          (perhaps preceeding by spaces and/or tabs) defines the keyword. 
    --          The keyword is a string starting from the next symbol after dot 
    --          and ending at the symbol preceeding ending newline character "\n".
    --          
    --          All the lines in the file after the keyword and before next 
    --          keyword (and which are not comments) define the message for that 
    --          keyword. If the message consists of several lines, the message 
    --          string will contain newline symbols "\n" between parts (but not 
    --          at the end).
    --          
    --          The experimental support of Unicode message files is provided.
    --          These are distinguished by two bytes FF.FE or FE.FF at the beginning.
    --          
    --          The loaded messages are stored in static data map; all methods of that 
    --          class are also static.

uses

    CString,
    AsciiString from TCollection,
    ExtendedString from TCollection

is

    Load (myclass; theDirName, theFileName: CString) returns Boolean;
    	---Purpose: Load message file <theFileName> from directory <theDirName>
        --          or its sub-directory


    LoadFile (myclass; theFName: CString) returns Boolean;
    	---Purpose: Load the messages from the given file, additive to any previously
        --          loaded messages. Messages with same keywords, if already present,
        --          are replaced with the new ones.

    LoadFromEnv (myclass; envname: CString; filename: CString; ext: CString = "");
    	---Purpose: Loads the messages from the file with name (without extension)
    	--          given by environment variable.
    	--          Extension of the file name is given separately. If its not
    	--          defined, it is taken:
    	--          - by default from environment CSF_LANGUAGE,
    	--          - if not defined either, as "us".

    AddMsg (myclass; key: AsciiString from TCollection;
                     text: ExtendedString from TCollection) returns Boolean;
    	---Purpose: Adds new message to the map. Parameter <key> gives 
        --          the key of the message, <text> defines the message itself. 
        --          If there already was defined the message identified by the 
        --          same keyword, it is replaced with the new one.

    Msg (myclass; key: CString) returns ExtendedString from TCollection;
    	---C++: return const &
    Msg (myclass; key: AsciiString from TCollection) returns ExtendedString from TCollection;
    	---C++: return const &
    	---Purpose: Gives the text for the message identified by the keyword <key>
        --          If there are no messages with such keyword defined, 
        --          the error message is returned.
        --          In that case reference to static string is returned, it can
        --          be chenged with next call(s) to Msg().
        --          Note: The error message is constructed like 'Unknown message: <key>', and can 
        --                itself be customized by defining message with key Message_Msg_BadKeyword.

end MsgFile;