src/Message/Message_MsgFile.cdl

   1 -- Created on: 2001-04-26
   2 -- Created by: OCC Team
   3 -- Copyright (c) 2001-2014 OPEN CASCADE SAS
   4 --
   5 -- This file is part of Open CASCADE Technology software library.
   6 --
   7 -- This library is free software; you can redistribute it and/or modify it under
   8 -- the terms of the GNU Lesser General Public License version 2.1 as published
   9 -- by the Free Software Foundation, with special exception defined in the file
  10 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 -- distribution for complete text of the license and disclaimer of any warranty.
  12 --
  13 -- Alternatively, this file may be used under the terms of Open CASCADE
  14 -- commercial license or contractual agreement.
  15
  16 class MsgFile from Message
  17
  18     ---Purpose: A tool providing facility to load definitions of message strings from
  19     --          resource file(s).
  20     --
  21     --          The message file is an ASCII file which defines a set of messages.
  22     --          Each message is identified by its keyword (string).
  23     --
  24     --          All lines in the file starting with the exclamation sign
  25     --          (perhaps preceeding by spaces and/or tabs) are ignored as comments.
  26     --
  27     --          Each line in the file starting with the dot character "."
  28     --          (perhaps preceeding by spaces and/or tabs) defines the keyword.
  29     --          The keyword is a string starting from the next symbol after dot
  30     --          and ending at the symbol preceeding ending newline character "\n".
  31     --
  32     --          All the lines in the file after the keyword and before next
  33     --          keyword (and which are not comments) define the message for that
  34     --          keyword. If the message consists of several lines, the message
  35     --          string will contain newline symbols "\n" between parts (but not
  36     --          at the end).
  37     --
  38     --          The experimental support of Unicode message files is provided.
  39     --          These are distinguished by two bytes FF.FE or FE.FF at the beginning.
  40     --
  41     --          The loaded messages are stored in static data map; all methods of that
  42     --          class are also static.
  43
  44 uses
  45
  46     CString,
  47     AsciiString from TCollection,
  48     ExtendedString from TCollection
  49
  50 is
  51
  52     Load (myclass; theDirName, theFileName: CString) returns Boolean;
  53         ---Purpose: Load message file <theFileName> from directory <theDirName>
  54         --          or its sub-directory
  55
  56
  57     LoadFile (myclass; theFName: CString) returns Boolean;
  58         ---Purpose: Load the messages from the given file, additive to any previously
  59         --          loaded messages. Messages with same keywords, if already present,
  60         --          are replaced with the new ones.
  61
  62     LoadFromEnv (myclass; envname: CString; filename: CString; ext: CString = "");
  63         ---Purpose: Loads the messages from the file with name (without extension)
  64         --          given by environment variable.
  65         --          Extension of the file name is given separately. If its not
  66         --          defined, it is taken:
  67         --          - by default from environment CSF_LANGUAGE,
  68         --          - if not defined either, as "us".
  69
  70     AddMsg (myclass; key: AsciiString from TCollection;
  71                      text: ExtendedString from TCollection) returns Boolean;
  72         ---Purpose: Adds new message to the map. Parameter <key> gives
  73         --          the key of the message, <text> defines the message itself.
  74         --          If there already was defined the message identified by the
  75         --          same keyword, it is replaced with the new one.
  76
  77     Msg (myclass; key: CString) returns ExtendedString from TCollection;
  78         ---C++: return const &
  79     Msg (myclass; key: AsciiString from TCollection) returns ExtendedString from TCollection;
  80         ---C++: return const &
  81         ---Purpose: Gives the text for the message identified by the keyword <key>
  82         --          If there are no messages with such keyword defined,
  83         --          the error message is returned.
  84         --          In that case reference to static string is returned, it can
  85         --          be chenged with next call(s) to Msg().
  86         --          Note: The error message is constructed like 'Unknown message: <key>', and can
  87         --                itself be customized by defining message with key Message_Msg_BadKeyword.
  88
  89 end MsgFile;