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 | |
8 | class 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 | |
41 | uses CString, Character, Transient, |
42 | AsciiString from TCollection, SequenceOfAsciiString from TColStd, |
43 | HArray1OfInteger from TColStd, DictionaryOfInteger, |
44 | WorkSession |
45 | |
46 | is |
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 | |
255 | fields |
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 | |
270 | end SessionFile; |