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