0025266: Debug statements in the source are getting flushed on to the console
[occt.git] / src / IFSelect / IFSelect_SessionFile.cdl
CommitLineData
b311480e 1-- Created on: 1993-11-03
2-- Created by: Christian CAILLET
3-- Copyright (c) 1993-1999 Matra Datavision
973c2be1 4-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e 5--
973c2be1 6-- This file is part of Open CASCADE Technology software library.
b311480e 7--
d5f74e42 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
973c2be1 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.
b311480e 13--
973c2be1 14-- Alternatively, this file may be used under the terms of Open CASCADE
15-- commercial license or contractual agreement.
7fd59977 16
17class 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
50uses CString, Character, Transient,
51 AsciiString from TCollection, SequenceOfAsciiString from TColStd,
52 HArray1OfInteger from TColStd, DictionaryOfInteger,
53 WorkSession
54
55is
56
6e33d3ce 57 Create (WS : WorkSession) returns SessionFile;
7fd59977 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
6e33d3ce 167 ReadOwn (me : in out; item : out Transient) returns Boolean;
7fd59977 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
6e33d3ce 256 ItemValue (me; num : Integer) returns Transient;
7fd59977 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
264fields
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
279end SessionFile;