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