src/IFSelect/IFSelect_SessionFile.cdl

   1 -- Created on: 1993-11-03
   2 -- Created by: Christian CAILLET
   3 -- Copyright (c) 1993-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 SessionFile  from IFSelect
  18
  19     ---Purpose : A SessionFile is intended to manage access between a
  20     --           WorkSession and an Ascii Form, to be considered as a Dump.
  21     --           It allows to write the File from the WorkSession, and later
  22     --           read the File to the WorkSession, by keeping required
  23     --           descriptions (such as dependances).
  24     --
  25     --           The produced File is under an Ascii Form, then it may be
  26     --           easily consulted.
  27     --           It is possible to cumulate reading of several Files. But in
  28     --           case of Names conflict, the newer Names are forgottens.
  29     --
  30     --           The Dump supports the description of XSTEP functionnalities
  31     --           (Sharing an Interface File, with Selections, Dispatches,
  32     --           Modifiers ...) but does not refer to the Interface File
  33     --           which is currently loaded.
  34     --
  35     --           SessionFile works with a library of SessionDumper type objects
  36     --
  37     --           The File is Produced as follows :
  38     --           SessionFile produces all general Informations (such as Int and
  39     --           Text Parameters, Types and Inputs of Selections, Dispatches,
  40     --           Modifiers ...) and calls the SessionDumpers to produce all
  41     --           the particular Data : creation arguments, parameters to be set
  42     --           It is Read in the same terms :
  43     --           SessionFile reads and interprets all general Informations,
  44     --           and calls the SessionDumpers to recognize Types and for a
  45     --           recognized Type create the corresponding Object with its
  46     --           particular parameters as they were written.
  47     --           The best way to work is to have one SessionDumper for each
  48     --           consistent set of classes (e.g. a package).
  49
  50 uses CString, Character, Transient,
  51      AsciiString from TCollection,  SequenceOfAsciiString from TColStd,
  52      HArray1OfInteger from TColStd, DictionaryOfInteger,
  53      WorkSession
  54
  55 is
  56
  57     Create (WS : mutable WorkSession) returns SessionFile;
  58     ---Purpose : Creates a SessionFile, ready to read Files in order to load
  59     --           them into a given WorkSession.
  60     --           The following Read Operations must then be called.
  61     --           It is also possible to perform a Write, which produces a
  62     --           complete File of all the content of the WorkSession.
  63
  64     Create (WS : WorkSession; filename : CString) returns SessionFile;
  65     ---Purpose : Creates a SessionFile which Writes the content of a WorkSession
  66     --           to a File (directly calls Write)
  67     --           Then, IsDone aknowledges on the result of the Operation.
  68     --           But such a SessionFile may not Read a File to a WorkSession.
  69
  70     ClearLines (me : in out);
  71     ---Purpose : Clears the lines recorded whatever for writing or for reading
  72
  73     NbLines (me) returns Integer;
  74     ---Purpose : Returns the count of recorded lines
  75
  76     Line (me; num : Integer) returns AsciiString from TCollection;
  77     ---Purpose : Returns a line given its rank in the list of recorded lines
  78     ---C++ : return const &
  79
  80     AddLine (me : in out; line : CString);
  81     ---Purpose : Adds a line to the list of recorded lines
  82
  83     RemoveLastLine (me : in out);
  84     ---Purpose : Removes the last line. Can be called recursively.
  85     --           Does nothing if the list is empty
  86
  87     WriteFile (me : in out; name : CString) returns Boolean;
  88     ---Purpose : Writes the recorded lines to a file named <name> then clears
  89     --           the list of lines.
  90     --           Returns False (with no clearing) if the file could not be
  91     --           created
  92
  93     ReadFile  (me : in out; name : CString) returns Boolean;
  94     ---Purpose : Reads the recorded lines from a file named <name>, after
  95     --           having cleared the list (stops if RecognizeFile fails)
  96     --           Returns False (with no clearing) if the file could not be read
  97
  98     RecognizeFile (me : in out; headerline : CString) returns Boolean;
  99     ---Purpose : Recognizes the header line. returns True if OK, False else
 100
 101
 102     Write (me : in out; filename : CString) returns Integer;
 103     ---Purpose : Performs a Write Operation from a WorkSession to a File
 104     --           i.e. calls WriteSession then WriteEnd, and WriteFile
 105     --           Returned Value is : 0 for OK, -1 File could not be created,
 106     --            >0 Error during Write (see WriteSession)
 107     --           IsDone can be called too (will return True for OK)
 108
 109     Read  (me : in out; filename : CString) returns Integer;
 110     ---Purpose : Performs a Read Operation from a file to a WorkSession
 111     --           i.e. calls ReadFile, then ReadSession and ReadEnd
 112     --           Returned Value is : 0 for OK, -1 File could not be opened,
 113     --            >0 Error during Read  (see WriteSession)
 114     --           IsDone can be called too (will return True for OK)
 115
 116
 117         --  Specific actions : Write and Read the content of a WorkSession  --
 118
 119     WriteSession (me : in out) returns Integer;
 120     ---Purpose : Prepares the Write operation from a WorkSession (IFSelect) to
 121     --           a File, i.e. fills the list of lines (the file itself remains
 122     --           to be written; or NbLines/Line may be called)
 123     --           Important Remark : this excludes the reading of the last line,
 124     --           which is performed by WriteEnd
 125     --           Returns 0 if OK, status > 0 in case of error
 126
 127     WriteEnd (me : in out) returns Integer;
 128     ---Purpose : Writes the trailing line. It is separate from WriteSession,
 129     --           in order to allow to redefine WriteSession without touching
 130     --           WriteEnd (WriteSession defines the body of the file)
 131     --           WriteEnd fills the list of lines. Returns a status of error,
 132     --           0 if OK, >0 else
 133
 134     WriteLine (me : in out; line : CString; follow : Character = 0);
 135     ---Purpose : Writes a line to the File. If <follow> is given, it is added
 136     --           at the following of the line. '\n' must be added for the end.
 137
 138     WriteOwn (me : in out; item : Transient) returns Boolean;
 139     ---Purpose : Writes the Parameters own to each type of Item. Uses the
 140     --           Library of SessionDumpers
 141     --           Returns True if Done, False if <item> could not be treated
 142     --           (hence it remains written with no Own Parameter)
 143
 144     ReadSession (me : in out) returns Integer;
 145     ---Purpose : Performs a Read Operation from a File to a WorkSession, i.e.
 146     --           reads the list of line (which must have already been loaded,
 147     --           by ReadFile or by calls to AddLine)
 148     --           Important Remark : this excludes the reading of the last line,
 149     --           which is performed by ReadEnd
 150     --           Returns 0 for OK, >0 status for Read Error (not a suitable
 151     --           File, or WorkSession given as Immutable at Creation Time)
 152     --           IsDone can be called too (will return True for OK)
 153
 154     ReadEnd (me : in out) returns Integer;
 155     ---Purpose : Reads the end of a file (its last line). Returns 0 if OK,
 156     --           status >0 in case of error (not a suitable end line).
 157
 158
 159     ReadLine (me : in out) returns Boolean;
 160     ---Purpose : Reads a Line and splits it into a set of alphanumeric items,
 161     --           which can then be queried by NbParams/ParamValue ...
 162
 163     SplitLine (me : in out; line : CString);
 164     ---Purpose : Internal routine which processes a line into words
 165     --           and prepares its exploration
 166
 167     ReadOwn (me : in out; item : out mutable Transient) returns Boolean;
 168     ---Purpose : Tries to Read an Item, by calling the Library of Dumpers
 169     --           Sets the list of parameters of the line to be read from the
 170     --           first own one
 171
 172     AddItem (me : in out; item : Transient; active : Boolean = Standard_True);
 173     ---Purpose : Adds an Item to the WorkSession, taken as Name the first
 174     --           item of the read Line. If this Name is not a Name but a Number
 175     --           or if this Name is already recorded in the WorkSession, it
 176     --           adds the Item but with no Name. Then the Name is recorded
 177     --           in order to be used by the method ItemValue
 178     --           <active> commands to make <item> active or not in the session
 179
 180     IsDone (me) returns Boolean;
 181     ---Purpose : Returns True if the last Read or Write operation has been
 182     --           corectly performed. ELse returns False.
 183
 184     WorkSession (me) returns WorkSession;
 185     ---Purpose : Returns the WorkSession on which a SessionFile works.
 186     --           Remark that it is returned as Immutable.
 187
 188         --  The following methods are used by SessionDumper to perform
 189         --  their ReadOwn and WriteOwn
 190
 191     NewItem (me : in out; ident : Integer; par : Transient);
 192     ---Purpose : At beginning of writing an Item, writes its basics :
 193     --           - either its name in the session if it has one
 194     --           - or its relative number of item in the file, else
 195     --             (preceeded by a '_')
 196     --           - then, its Dynamic Type (in the sense of cdl : pk_class)
 197     --           This basic description can be followed by the parameters
 198     --           which are used in the definition of the item.
 199
 200     SetOwn (me : in out; mode : Boolean);
 201     ---Purpose : Sets Parameters to be sent as Own if <mode> is True (their
 202     --           Name or Number or Void Mark or Text Value is preceeded by a
 203     --           Column sign ':') else they are sent normally
 204     --           Hence, the Own Parameter are clearly identified in the File
 205
 206     SendVoid (me : in out);
 207     ---Purpose : During a Write action, commands to send a Void Parameter
 208     --           i.e. a Parameter which is present but undefined
 209     --           Its form will be the dollar sign : $
 210
 211     SendItem (me : in out; par : Transient);
 212     ---Purpose : During a Write action, commands to send the identification of
 213     --           a Parameter : if it is Null (undefined) it is send as Void ($)
 214     --           if it is Named in the WorkSession, its Name is sent preceeded
 215     --           by ':', else a relative Ident Number is sent preceeded by '#'
 216     --           (relative to the present Write, i.e. starting at one, without
 217     --           skip, and counted part from Named Items)
 218
 219     SendText (me : in out; text : CString);
 220     ---Purpose : During a Write action, commands to send a Text without
 221     --           interpretation. It will be sent as well
 222
 223
 224     SetLastGeneral (me : in out; lastgen : Integer);
 225     ---Purpose : Sets the rank of Last General Parameter to a new value. It is
 226     --           followed by the Fist Own Parameter of the item.
 227     --           Used by SessionFile after reading general parameters.
 228
 229     NbParams (me) returns Integer;
 230     ---Purpose : During a Read operation, SessionFile processes sequencially
 231     --           the Items to read. For each one, it gives access to the list
 232     --           of its Parameters : they were defined by calls to
 233     --           SendVoid/SendParam/SendText during Writing the File.
 234     --           NbParams returns the count of Parameters for the line
 235     --           currently read.
 236
 237     IsVoid (me; num : Integer) returns Boolean;
 238     ---Purpose : Returns True if a Parameter, given its rank in the Own List
 239     --           (see NbOwnParams), is Void. Returns also True if <num> is
 240     --           out of range (undefined parameters)
 241
 242     IsText (me; num : Integer) returns Boolean;
 243     ---Purpose : Returns True if a Parameter, in the Own List (see NbOwnParams)
 244     --           is a Text (between "..."). Else it is an Item (Parameter,
 245     --           Selection, Dispatch ...), which can be Void.
 246
 247     ParamValue (me; num : Integer) returns AsciiString from TCollection;
 248     ---Purpose : Returns a Parameter (alphanumeric item of a line) as it
 249     --           has been read
 250     ---C++ : return const &
 251
 252     TextValue (me; num : Integer) returns AsciiString from TCollection;
 253     ---Purpose : Returns the content of a Text Parameter (without the quotes).
 254     --           Returns an empty string if the Parameter is not a Text.
 255
 256     ItemValue (me; num : Integer) returns mutable Transient;
 257     ---Purpose : Returns a Parameter as an Item. Returns a Null Handle if the
 258     --           Parameter is a Text, or if it is defined as Void
 259
 260     Destroy (me : in out);
 261     ---Purpose : Specific Destructor (closes the File if not yet done)
 262     ---C++ : alias ~
 263
 264 fields
 265
 266     themode  : Boolean;   -- Read(False) or Write(True)
 267     thesess  : WorkSession  is protected;
 268     thenums  : HArray1OfInteger from TColStd  is protected;       -- for Write
 269     thenames : DictionaryOfInteger  is protected;                 -- for Read
 270     thelist  : SequenceOfAsciiString from TColStd;       -- for the whole File
 271     thenl    : Integer  is protected;                    -- line number in File
 272     thebuff  : AsciiString from TCollection;
 273     theline  : SequenceOfAsciiString from TColStd  is protected;  -- for a Line
 274     thelastgen : Integer;
 275     thedone    : Boolean;
 276     theownflag : Boolean;
 277     thenewnum  : Integer;  -- to identify non-named items
 278
 279 end SessionFile;