src/Interface/Interface_MSG.cdl

   1 -- Created on: 1995-03-08
   2 -- Created by: Christian CAILLET
   3 -- Copyright (c) 1995-1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  10 -- by the Free Software Foundation, with special exception defined in the file
  11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 -- distribution for complete text of the license and disclaimer of any warranty.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 class MSG  from Interface
  18
  19     ---Purpose : This class gives a set of functions to manage and use a list
  20     --           of translated messages (messagery)
  21     --
  22     --           Keys are strings, their corresponding (i.e. translated) items
  23     --           are strings, managed by a dictionary (a global one).
  24     --
  25     --           If the dictionary is not set, or if a key is not recorded,
  26     --           the key is returned as item, and it is possible to :
  27     --           - trace or not this fail, record or not it for further trace
  28     --
  29     --           It is also possible to suspend the translation (keys are then
  30     --           always returned as items)
  31     --
  32     --           This class also provides a file format for loading :
  33     --           It is made of couples of lines, the first one begins by '@'
  34     --           the following is the key, the second one is the message
  35     --           Lines which are empty or which begin by '@@' are skipped
  36
  37
  38 uses Character, CString , OStream, IStream
  39
  40 raises DomainError
  41
  42 is
  43
  44     Create (key : CString) returns MSG;
  45     ---Purpose : A MSG is created to write a "functional code" in conjunction
  46     --           with operator () attached to Value
  47     --           Then, to have a translated message, write in C++ :
  48     --
  49     --           Interface_MSG("...mykey...")  which returns a CString
  50     --           See also some help which follow
  51
  52     Create (key : CString; i1 : Integer) returns MSG;
  53     ---Purpose : Translates a message which contains one integer variable
  54     --           It is just a help which avoid the following :
  55     --             char mess[100];  sprintf(mess,Interface_MSG("code"),ival);
  56     --             then  AddFail(mess);
  57     --           replaced by  AddFail (Interface_MSG("code",ival));
  58     --
  59     --           The basic message is intended to be in  C-sprintf  format,
  60     --           with one %d form in it
  61
  62     Create (key : CString; i1,i2 : Integer) returns MSG;
  63     ---Purpose : Translates a message which contains two integer variables
  64     --           As for one integer, it is just a writing help
  65     --
  66     --           The basic message is intended to be in  C-sprintf  format
  67     --           with two %d forms in it
  68
  69     Create (key : CString; r1 : Real; intervals : Integer = -1) returns MSG;
  70     ---Purpose : Translates a message which contains one real variable
  71     --           <intervals> if set, commands the variable to be rounded to an
  72     --           interval (see below, method Intervals)
  73     --           As for one integer, it is just a writing help
  74     --
  75     --           The basic message is intended to be in  C-sprintf  format
  76     --           with one %f form (or equivalent : %e etc) in it
  77
  78     Create (key : CString; str : CString) returns MSG;
  79     ---Purpose : Translates a message which contains one string variable
  80     --           As for one integer, it is just a writing help
  81     --
  82     --           The basic message is intended to be in  C-sprintf  format
  83     --           with one %s form in it
  84
  85     Create (key : CString; ival : Integer; str : CString) returns MSG;
  86     ---Purpose : Translates a message which contains one integer and one
  87     --           string variables
  88     --           As for one integer, it is just a writing help
  89     --           Used for instance to say "Param n0.<ival> i.e. <str> is not.."
  90     --
  91     --           The basic message is intended to be in  C-sprintf  format
  92     --           with one %d then one %s forms in it
  93
  94     Destroy (me : in out);
  95     ---Purpose : Optimised destructor (applies for additional forms of Create)
  96     ---C++ : alias ~
  97
  98     Value (me) returns CString  is static;
  99     ---Purpose : Returns the translated message, in a functional form with
 100     --           operator ()
 101     -- was C++ : return const
 102     ---C++ : alias "operator Standard_CString() const;"
 103
 104     Read (myclass; S : in out IStream) returns Integer;
 105     ---Purpose : Reads a list of messages from a stream, returns read count
 106     --           0 means empty file, -1 means error
 107
 108     Read (myclass; file : CString) returns Integer;
 109     ---Purpose : Reads a list of messages from a file defined by its name
 110
 111     Write (myclass; S : in out OStream; rootkey : CString = "") returns Integer;
 112     ---Purpose : Writes the list of messages recorded to be translated, to a
 113     --           stream. Writes all the list (Default) or only keys which begin
 114     --           by <rootkey>. Returns the count of written messages
 115
 116     IsKey (myclass; mess : CString) returns Boolean;
 117     ---Purpose : Returns True if a given message is surely a key
 118     --           (according to the form adopted for keys)
 119     --           (before activating messages, answer is false)
 120
 121     Translated (myclass; key : CString) returns CString
 122     ---Purpose : Returns the item recorded for a key.
 123     --           Returns the key itself if :
 124     --           - it is not recorded (then, the trace system is activated)
 125     --           - MSG has been required to be hung on
 126         raises DomainError;
 127     --           Raises an exception if not found and if <raising> mode is True
 128
 129     Record (myclass; key : CString; item : CString)
 130     ---Purpose : Fills the dictionary with a couple (key-item)
 131     --           If a key is already recorded, it is possible to :
 132     --           - keep the last definition, and activate the trace system
 133         raises DomainError;
 134     --           - or raise an exception
 135
 136     SetTrace (myclass; toprint, torecord : Boolean);
 137     ---Purpose : Sets the trace system to work when activated, as follow :
 138     --           - if <toprint>  is True, print immediately on standard output
 139     --           - if <torecord> is True, record it for further print
 140
 141     SetMode (myclass; running, raising : Boolean);
 142     ---Purpose : Sets the main modes for MSG :
 143     --           - if <running> is True, translation works normally
 144     --           - if <running> is False, translated item equate keys
 145     --           - if <raising> is True, errors (from Record or Translate)
 146     --             cause MSG to raise an exception
 147     --           - if <raising> is False, MSG runs without exception, then
 148     --             see also Trace Modes above
 149
 150     PrintTrace (myclass; S : in out OStream);
 151     ---Purpose : Prints the recorded errors (without title; can be empty, this
 152     --           is the normally expected case)
 153
 154         --  some helps : printing rounded floating values
 155
 156     Intervalled (myclass; val : Real; order : Integer = 3;
 157                  upper : Boolean = Standard_False)
 158         returns Real;
 159     ---Purpose : Returns an "intervalled" value from a starting real <val> :
 160     --           i.e. a value which is rounded on an interval limit
 161     --           Interval limits are defined to be in a coarsely "geometric"
 162     --           progression (two successive intervals are inside a limit ratio)
 163     --
 164     --           <order> gives the count of desired intervals in a range <1-10>
 165     --           <upper> False, returns the first lower interval (D)
 166     --           <upper> True,  returns the first upper interval
 167     --           Values of Intervals according <order> :
 168     --           0,1 : 1 10 100 ...
 169     --           2   : 1 3 10 30 100 ...
 170     --           3(D): 1 2 5 10 20 50 100 ...
 171     --           4   : 1 2 3 6 10 20 30 60 100 ...
 172     --           6   : 1 1.5 2 3 5 7 10 15 20 ...
 173     --           10  : 1 1.2 1.5 2 2.5 3 4 5 6 8 10 12 15 20 25 ...
 174
 175         -- coding/decoding dates with strings --
 176
 177     TDate (myclass; text : CString; yy,mm,dd,hh,mn,ss : Integer;
 178                     format : CString = "");
 179     ---Purpose : Codes a date as a text, from its numeric value (-> seconds) :
 180     --           YYYY-MM-DD:HH-MN-SS  fixed format, completed by leading zeros
 181     --           Another format can be provided, as follows :
 182     --           C:%d ...   C like format, preceeded by  C:
 183     --           S:...      format to call system (not yet implemented)
 184
 185     NDate (myclass; text : CString; yy,mm,dd,hh,mn,ss : out Integer) returns Boolean;
 186     ---Purpose : Decodes a date to numeric integer values
 187     --           Returns True if OK, False if text does not fit with required
 188     --           format. Incomplete forms are allowed (for instance, for only
 189     --           YYYY-MM-DD, hour is zero)
 190
 191     CDate (myclass; text1, text2 : CString) returns Integer;
 192     ---Purpose : Returns a value about comparison of two dates
 193     --           0 : equal. <0 text1 anterior. >0 text1 posterior
 194
 195     Blanks (myclass; val : Integer; max : Integer) returns CString;
 196     ---Purpose : Returns a blank string, of length between 0 and <max>, to fill
 197     --           the printing of a numeric value <val>, i.e. :
 198     --           If val < 10 , max-1 blanks
 199     --           If val between 10 and 99, max-2 blanks  ...   etc...
 200
 201     Blanks (myclass; val : CString; max : Integer) returns CString;
 202     ---Purpose : Returns a blank string, to complete a given string <val> up to
 203     --           <max> characters :
 204     --           If strlen(val) is 0, max blanks
 205     --           If strlen(val) is 5, max-5 blanks    etc...
 206
 207     Blanks (myclass; count : Integer) returns CString;
 208     ---Purpose : Returns a blank string of <count> blanks (mini 0, maxi 76)
 209
 210     Print  (myclass; S : in out OStream;
 211             val : CString; max : Integer; just : Integer = -1);
 212     ---Purpose : Prints a String on an Output Stream, as follows :
 213     --           Accompagned with blanks, to give up to <max> charis at all,
 214     --           justified according just :
 215     --           -1 (D) : left     0 : center    1 : right
 216     --           Maximum 76 characters
 217
 218 fields
 219
 220     thekey  : CString;
 221     theval  : PCharacter;  -- only if translation is done
 222 --    thecont : Character[30];  -- for a short local definition
 223
 224 end MSG;