[occt.git] / src / IFSelect / IFSelect_SessionFile.cdl

-- File:	IFSelect_SessionFile.cdl
-- Created:	Wed Nov  3 19:31:56 1993
-- Author:	Christian CAILLET
--		<cky@sdsun2>
---Copyright:	 Matra Datavision 1993


class SessionFile  from IFSelect

    ---Purpose : A SessionFile is intended to manage access between a
    --           WorkSession and an Ascii Form, to be considered as a Dump.
    --           It allows to write the File from the WorkSession, and later
    --           read the File to the WorkSession, by keeping required
    --           descriptions (such as dependances).
    --           
    --           The produced File is under an Ascii Form, then it may be
    --           easily consulted.
    --           It is possible to cumulate reading of several Files. But in
    --           case of Names conflict, the newer Names are forgottens.
    --           
    --           The Dump supports the description of XSTEP functionnalities
    --           (Sharing an Interface File, with Selections, Dispatches,
    --           Modifiers ...) but does not refer to the Interface File
    --           which is currently loaded.
    --           
    --           SessionFile works with a library of SessionDumper type objects
    --           
    --           The File is Produced as follows :
    --           SessionFile produces all general Informations (such as Int and
    --           Text Parameters, Types and Inputs of Selections, Dispatches,
    --           Modifiers ...) and calls the SessionDumpers to produce all
    --           the particular Data : creation arguments, parameters to be set
    --           It is Read in the same terms :
    --           SessionFile reads and interprets all general Informations,
    --           and calls the SessionDumpers to recognize Types and for a
    --           recognized Type create the corresponding Object with its
    --           particular parameters as they were written.
    --           The best way to work is to have one SessionDumper for each
    --           consistent set of classes (e.g. a package).

uses CString, Character, Transient,
     AsciiString from TCollection,  SequenceOfAsciiString from TColStd,
     HArray1OfInteger from TColStd, DictionaryOfInteger,
     WorkSession

is

    Create (WS : mutable WorkSession) returns SessionFile;
    ---Purpose : Creates a SessionFile, ready to read Files in order to load
    --           them into a given WorkSession.
    --           The following Read Operations must then be called.
    --           It is also possible to perform a Write, which produces a
    --           complete File of all the content of the WorkSession.

    Create (WS : WorkSession; filename : CString) returns SessionFile;
    ---Purpose : Creates a SessionFile which Writes the content of a WorkSession
    --           to a File (directly calls Write)
    --           Then, IsDone aknowledges on the result of the Operation.
    --           But such a SessionFile may not Read a File to a WorkSession.

    ClearLines (me : in out);
    ---Purpose : Clears the lines recorded whatever for writing or for reading

    NbLines (me) returns Integer;
    ---Purpose : Returns the count of recorded lines

    Line (me; num : Integer) returns AsciiString from TCollection;
    ---Purpose : Returns a line given its rank in the list of recorded lines
    ---C++ : return const &

    AddLine (me : in out; line : CString);
    ---Purpose : Adds a line to the list of recorded lines

    RemoveLastLine (me : in out);
    ---Purpose : Removes the last line. Can be called recursively.
    --           Does nothing if the list is empty

    WriteFile (me : in out; name : CString) returns Boolean;
    ---Purpose : Writes the recorded lines to a file named <name> then clears
    --           the list of lines.
    --           Returns False (with no clearing) if the file could not be
    --           created

    ReadFile  (me : in out; name : CString) returns Boolean;
    ---Purpose : Reads the recorded lines from a file named <name>, after
    --           having cleared the list (stops if RecognizeFile fails)
    --           Returns False (with no clearing) if the file could not be read

    RecognizeFile (me : in out; headerline : CString) returns Boolean;
    ---Purpose : Recognizes the header line. returns True if OK, False else


    Write (me : in out; filename : CString) returns Integer;
    ---Purpose : Performs a Write Operation from a WorkSession to a File
    --           i.e. calls WriteSession then WriteEnd, and WriteFile
    --           Returned Value is : 0 for OK, -1 File could not be created,
    --            >0 Error during Write (see WriteSession)
    --           IsDone can be called too (will return True for OK)

    Read  (me : in out; filename : CString) returns Integer;
    ---Purpose : Performs a Read Operation from a file to a WorkSession
    --           i.e. calls ReadFile, then ReadSession and ReadEnd
    --           Returned Value is : 0 for OK, -1 File could not be opened,
    --            >0 Error during Read  (see WriteSession)
    --           IsDone can be called too (will return True for OK)


    	--  Specific actions : Write and Read the content of a WorkSession  --

    WriteSession (me : in out) returns Integer;
    ---Purpose : Prepares the Write operation from a WorkSession (IFSelect) to
    --           a File, i.e. fills the list of lines (the file itself remains
    --           to be written; or NbLines/Line may be called)
    --           Important Remark : this excludes the reading of the last line,
    --           which is performed by WriteEnd
    --           Returns 0 if OK, status > 0 in case of error

    WriteEnd (me : in out) returns Integer;
    ---Purpose : Writes the trailing line. It is separate from WriteSession,
    --           in order to allow to redefine WriteSession without touching
    --           WriteEnd (WriteSession defines the body of the file)
    --           WriteEnd fills the list of lines. Returns a status of error,
    --           0 if OK, >0 else

    WriteLine (me : in out; line : CString; follow : Character = 0);
    ---Purpose : Writes a line to the File. If <follow> is given, it is added
    --           at the following of the line. '\n' must be added for the end.

    WriteOwn (me : in out; item : Transient) returns Boolean;
    ---Purpose : Writes the Parameters own to each type of Item. Uses the
    --           Library of SessionDumpers
    --           Returns True if Done, False if <item> could not be treated
    --           (hence it remains written with no Own Parameter)

    ReadSession (me : in out) returns Integer;
    ---Purpose : Performs a Read Operation from a File to a WorkSession, i.e.
    --           reads the list of line (which must have already been loaded,
    --           by ReadFile or by calls to AddLine)
    --           Important Remark : this excludes the reading of the last line,
    --           which is performed by ReadEnd
    --           Returns 0 for OK, >0 status for Read Error (not a suitable
    --           File, or WorkSession given as Immutable at Creation Time)
    --           IsDone can be called too (will return True for OK)

    ReadEnd (me : in out) returns Integer;
    ---Purpose : Reads the end of a file (its last line). Returns 0 if OK,
    --           status >0 in case of error (not a suitable end line).


    ReadLine (me : in out) returns Boolean;
    ---Purpose : Reads a Line and splits it into a set of alphanumeric items,
    --           which can then be queried by NbParams/ParamValue ...

    SplitLine (me : in out; line : CString);
    ---Purpose : Internal routine which processes a line into words
    --           and prepares its exploration

    ReadOwn (me : in out; item : out mutable Transient) returns Boolean;
    ---Purpose : Tries to Read an Item, by calling the Library of Dumpers
    --           Sets the list of parameters of the line to be read from the
    --           first own one

    AddItem (me : in out; item : Transient; active : Boolean = Standard_True);
    ---Purpose : Adds an Item to the WorkSession, taken as Name the first
    --           item of the read Line. If this Name is not a Name but a Number
    --           or if this Name is already recorded in the WorkSession, it
    --           adds the Item but with no Name. Then the Name is recorded
    --           in order to be used by the method ItemValue
    --           <active> commands to make <item> active or not in the session

    IsDone (me) returns Boolean;
    ---Purpose : Returns True if the last Read or Write operation has been
    --           corectly performed. ELse returns False.

    WorkSession (me) returns WorkSession;
    ---Purpose : Returns the WorkSession on which a SessionFile works.
    --           Remark that it is returned as Immutable.

    	--  The following methods are used by SessionDumper to perform
    	--  their ReadOwn and WriteOwn

    NewItem (me : in out; ident : Integer; par : Transient);
    ---Purpose : At beginning of writing an Item, writes its basics :
    --           - either its name in the session if it has one
    --           - or its relative number of item in the file, else
    --             (preceeded by a '_')
    --           - then, its Dynamic Type (in the sense of cdl : pk_class)
    --           This basic description can be followed by the parameters
    --           which are used in the definition of the item.

    SetOwn (me : in out; mode : Boolean);
    ---Purpose : Sets Parameters to be sent as Own if <mode> is True (their
    --           Name or Number or Void Mark or Text Value is preceeded by a
    --           Column sign ':') else they are sent normally
    --           Hence, the Own Parameter are clearly identified in the File

    SendVoid (me : in out);
    ---Purpose : During a Write action, commands to send a Void Parameter
    --           i.e. a Parameter which is present but undefined
    --           Its form will be the dollar sign : $

    SendItem (me : in out; par : Transient);
    ---Purpose : During a Write action, commands to send the identification of
    --           a Parameter : if it is Null (undefined) it is send as Void ($)
    --           if it is Named in the WorkSession, its Name is sent preceeded
    --           by ':', else a relative Ident Number is sent preceeded by '#'
    --           (relative to the present Write, i.e. starting at one, without
    --           skip, and counted part from Named Items)

    SendText (me : in out; text : CString);
    ---Purpose : During a Write action, commands to send a Text without
    --           interpretation. It will be sent as well


    SetLastGeneral (me : in out; lastgen : Integer);
    ---Purpose : Sets the rank of Last General Parameter to a new value. It is
    --           followed by the Fist Own Parameter of the item.
    --           Used by SessionFile after reading general parameters.

    NbParams (me) returns Integer;
    ---Purpose : During a Read operation, SessionFile processes sequencially
    --           the Items to read. For each one, it gives access to the list
    --           of its Parameters : they were defined by calls to
    --           SendVoid/SendParam/SendText during Writing the File.
    --           NbParams returns the count of Parameters for the line
    --           currently read.

    IsVoid (me; num : Integer) returns Boolean;
    ---Purpose : Returns True if a Parameter, given its rank in the Own List
    --           (see NbOwnParams), is Void. Returns also True if <num> is
    --           out of range (undefined parameters)

    IsText (me; num : Integer) returns Boolean;
    ---Purpose : Returns True if a Parameter, in the Own List (see NbOwnParams)
    --           is a Text (between "..."). Else it is an Item (Parameter,
    --           Selection, Dispatch ...), which can be Void.

    ParamValue (me; num : Integer) returns AsciiString from TCollection;
    ---Purpose : Returns a Parameter (alphanumeric item of a line) as it
    --           has been read
    ---C++ : return const &

    TextValue (me; num : Integer) returns AsciiString from TCollection;
    ---Purpose : Returns the content of a Text Parameter (without the quotes).
    --           Returns an empty string if the Parameter is not a Text.

    ItemValue (me; num : Integer) returns mutable Transient;
    ---Purpose : Returns a Parameter as an Item. Returns a Null Handle if the
    --           Parameter is a Text, or if it is defined as Void

    Destroy (me : in out);
    ---Purpose : Specific Destructor (closes the File if not yet done)
    ---C++ : alias ~

fields

    themode  : Boolean;   -- Read(False) or Write(True)
    thesess  : WorkSession  is protected;
    thenums  : HArray1OfInteger from TColStd  is protected;       -- for Write
    thenames : DictionaryOfInteger  is protected;                 -- for Read
    thelist  : SequenceOfAsciiString from TColStd;       -- for the whole File
    thenl    : Integer  is protected;                    -- line number in File
    thebuff  : AsciiString from TCollection;
    theline  : SequenceOfAsciiString from TColStd  is protected;  -- for a Line
    thelastgen : Integer;
    thedone    : Boolean;
    theownflag : Boolean;
    thenewnum  : Integer;  -- to identify non-named items

end SessionFile;
Commit	Line	Data
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;