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