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