[occt.git] / src / Interface / Interface_FileReaderTool.cdl

-- Created on: 1993-02-04
-- Created by: Christian CAILLET
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.


deferred class FileReaderTool  from Interface

    ---Purpose : Defines services which are required to load an InterfaceModel
    --           from a File. Typically, it may firstly transform a system
    --           file into a FileReaderData object, then work on it, not longer
    --           considering file contents, to load an Interface Model.
    --           It may also work on a FileReaderData already loaded.
    --           
    --           FileReaderTool provides, on one hand, some general services
    --           which are common to all read operations but can be redefined,
    --           plus general actions to be performed specifically for each
    --           Norm, as deferred methods to define.
    --           
    --           In particular, FileReaderTool defines the Interface's Unknown
    --           and Error entities

uses Integer, Boolean,  Transient, HArray1OfTransient,
     FileReaderData,    InterfaceModel,  Check, Protocol from Interface,
     Messenger from Message,
     GeneralLib, ReaderLib

raises DomainError, NoSuchObject

is

    	-- --   generals   -- --
    Initialize returns FileReaderTool  from Interface;
    ---Purpose: Constructor; sets default fields

    SetData (me : in out; reader : mutable FileReaderData;
    	     protocol : Protocol from Interface);
    ---Purpose : Sets Data to a FileReaderData. Works with a Protocol

    Protocol (me) returns Protocol from Interface;
    ---Purpose : Returns the Protocol given at creation time

    Data (me) returns mutable FileReaderData;
    ---Purpose : Returns the FileReaderData which is used to work

    SetModel (me : in out; amodel : mutable InterfaceModel);
    ---Purpose : Stores a Model. Used when the Model has been loaded

    Model (me) returns mutable InterfaceModel;
    ---Purpose : Returns the stored Model

    	-- --   setting empty entities before loading model   -- --

    SetMessenger (me: out; messenger: Messenger from Message);
    ---Purpose : Sets Messenger used for outputting messages

    Messenger (me) returns Messenger from Message;
    ---Purpose : Returns Messenger used for outputting messages.
    --           The returned object is guaranteed to be non-null;
    --           default is Message::Messenger().

    SetTraceLevel (me: out; tracelev: Integer);
    ---Purpose : Sets trace level used for outputting messages
    --           - 0: no trace at all
    --           - 1: errors
    --           - 2: errors and warnings
    --           - 3: all messages
    --           Default is 1 : Errors traced

    TraceLevel (me) returns Integer;
    ---Purpose : Returns trace level used for outputting messages.

    SetErrorHandle (me : in out; err : Boolean);
    ---Purpose : Allows controlling whether exception raisings are handled
    --           If err is False, they are not (hence, dbx can take control)
    --           If err is True, they are, and they are traced 
    --           (by putting on messenger Entity's Number and file record num)
    --           Default given at Model's creation time is True

    ErrorHandle (me) returns Boolean;
    ---Purpose : Returns ErrorHandle flag

    	-- --   setting empty entities before loading model   -- --

    SetEntities (me : in out);
    ---Purpose : Fills records with empty entities; once done, each entity can
    --           ask the FileReaderTool for any entity referenced through an
    --           identifier. Calls Recognize which is specific to each specific
    --           type of FileReaderTool

    Recognize (me : in out; num : Integer;
    	       ach : in out Check; ent : out mutable Transient)
    	returns Boolean  is deferred;
    ---Purpose : Recognizes a record, given its number. Specific to each
    --           Interface; called by SetEntities. It can call the basic method
    --           RecognizeByLib.
    --           Returns False if recognition has failed, True else.
    --           <ach> has not to be filled if simply Recognition has failed :
    --           it must record true error messages : RecognizeByLib can
    --           generate error messages if NewRead is called
    --           
    --           Note that it works thru a Recognizer (method Evaluate) which
    --           has to be memorized before starting

    RecognizeByLib (me; num : Integer;
    	    	    glib : in out GeneralLib; rlib : in out ReaderLib;
		    ach : in out Check; ent : out mutable Transient)
    	 returns Boolean;
    ---Purpose : Recognizes a record with the help of Libraries. Can be used
    --           to implement the method Recognize.
    --           <rlib> is used to find Protocol and CaseNumber to apply
    --           <glib> performs the creation (by service NewVoid, or NewRead
    --             if NewVoid gave no result)
    --           <ach> is a check, which is transmitted to NewRead if it is
    --             called, gives a result but which is false
    --           <ent> is the result
    --           Returns False if recognition has failed, True else

    UnknownEntity (me) returns mutable Transient;
    ---Purpose : Provides an unknown entity, specific to the Interface
    --           called by SetEntities when Recognize has failed (Unknown alone)
    --           or by LoadModel when an Entity has caused a Fail on reading
    --           (to keep at least its literal description)
    --           Uses Protocol to do it

    	-- --   loading entities into the model   -- --

    NewModel (me) returns mutable InterfaceModel;
    ---Purpose : Creates an empty Model of the norm. Uses Protocol to do it

    LoadModel (me : in out; amodel : mutable InterfaceModel)
    	raises DomainError;
    ---Purpose : Reads and fills Entities from the FileReaderData set by
    --           SetData to an InterfaceModel.
    --           It enchains required operations, the specific ones correspond
    --           to deferred methods (below) to be defined for each Norm.
    --           It manages also error recovery and trace.
    --           Remark : it calls SetModel.
    --           It Can raise any error which can occur during a load
    --           operation, unless Error Handling is set.
    --           This method can also be redefined if judged necessary.

    LoadedEntity (me : in out; num : Integer) returns mutable Transient;
    ---Purpose : Reads, Fills and Returns one Entity read from a Record of the
    --           FileReaderData. This Method manages also case of Fail or
    --           Warning, by producing a ReportEntyty plus , for a Fail, a
    --           literal Content (as an UnknownEntity). Performs also Trace

    BeginRead (me : in out; amodel : mutable InterfaceModel) is deferred;
    ---Purpose : Fills model's header; each Interface defines for its Model its
    --           own file header; this method fills it from FileReaderTool.+
    --           It is called by AnalyseFile from InterfaceModel

    AnalyseRecord (me : in out;
        num : Integer; anent : mutable Transient; acheck : in out Check)
    	returns Boolean  is deferred;
    ---Purpose : Fills an Entity, given record no; specific to each Interface,
    --           called by AnalyseFile from InterfaceModel (which manages its
    --           calling arguments)
    --           To work, each Interface can define a method in its proper
    --           Transient class, like this (given as an example) :
    --           AnalyseRecord (me  : mutable; FR     : in out FileReaderTool;
    --                          num : Integer; acheck : in out Check)
    --                              returns Boolean;
    --           and call it from AnalyseRecord
    --           
    --           Returned Value : True if the entity could be loaded, False
    --             else (in case of syntactic fail)

    Destroy (me: in out) is virtual;
    ---C++ : alias "Standard_EXPORT virtual ~Interface_FileReaderTool() { Destroy(); }"

    EndRead (me : in out; amodel : mutable InterfaceModel)  is virtual;
    ---Purpose : Ends file reading after reading all the entities
    --           default is doing nothing; redefinable as necessary
    
    
    Clear(me : in out);
	---Purpose : Clear filelds

fields

    theproto   : Protocol from Interface;
    thereader  : FileReaderData;
    themodel   : InterfaceModel;
    themessenger:Messenger from Message;
    thetrace   : Integer;             -- trace level (exceptions,errors, etc...)
    theerrhand : Boolean;             -- to handle or not exceptions
    thenbrep0  : Integer;             -- (reports at creation time)
    thenbreps  : Integer;             -- (all reports)
    thereports : HArray1OfTransient;

end FileReaderTool;
Commit	Line	Data
b311480e	1	-- Created on: 1993-02-04
	2	-- Created by: Christian CAILLET
	3	-- Copyright (c) 1993-1999 Matra Datavision
	4	-- Copyright (c) 1999-2012 OPEN CASCADE SAS
	5	--
	6	-- The content of this file is subject to the Open CASCADE Technology Public
	7	-- License Version 6.5 (the "License"). You may not use the content of this file
	8	-- except in compliance with the License. Please obtain a copy of the License
	9	-- at http://www.opencascade.org and read it completely before using this file.
	10	--
	11	-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
	12	-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
	13	--
	14	-- The Original Code and all software distributed under the License is
	15	-- distributed on an "AS IS" basis, without warranty of any kind, and the
	16	-- Initial Developer hereby disclaims all such warranties, including without
	17	-- limitation, any warranties of merchantability, fitness for a particular
	18	-- purpose or non-infringement. Please see the License for the specific terms
	19	-- and conditions governing the rights and limitations under the License.
	20
7fd59977	21
	22
	23	deferred class FileReaderTool from Interface
	24
	25	---Purpose : Defines services which are required to load an InterfaceModel
	26	-- from a File. Typically, it may firstly transform a system
	27	-- file into a FileReaderData object, then work on it, not longer
	28	-- considering file contents, to load an Interface Model.
	29	-- It may also work on a FileReaderData already loaded.
	30	--
	31	-- FileReaderTool provides, on one hand, some general services
	32	-- which are common to all read operations but can be redefined,
	33	-- plus general actions to be performed specifically for each
	34	-- Norm, as deferred methods to define.
	35	--
	36	-- In particular, FileReaderTool defines the Interface's Unknown
	37	-- and Error entities
	38
	39	uses Integer, Boolean, Transient, HArray1OfTransient,
	40	FileReaderData, InterfaceModel, Check, Protocol from Interface,
	41	Messenger from Message,
	42	GeneralLib, ReaderLib
	43
	44	raises DomainError, NoSuchObject
	45
	46	is
	47
	48	-- -- generals -- --
	49	Initialize returns FileReaderTool from Interface;
	50	---Purpose: Constructor; sets default fields
	51
	52	SetData (me : in out; reader : mutable FileReaderData;
	53	protocol : Protocol from Interface);
	54	---Purpose : Sets Data to a FileReaderData. Works with a Protocol
	55
	56	Protocol (me) returns Protocol from Interface;
	57	---Purpose : Returns the Protocol given at creation time
	58
	59	Data (me) returns mutable FileReaderData;
	60	---Purpose : Returns the FileReaderData which is used to work
	61
	62	SetModel (me : in out; amodel : mutable InterfaceModel);
	63	---Purpose : Stores a Model. Used when the Model has been loaded
	64
	65	Model (me) returns mutable InterfaceModel;
	66	---Purpose : Returns the stored Model
	67
	68	-- -- setting empty entities before loading model -- --
	69
	70	SetMessenger (me: out; messenger: Messenger from Message);
	71	---Purpose : Sets Messenger used for outputting messages
	72
	73	Messenger (me) returns Messenger from Message;
	74	---Purpose : Returns Messenger used for outputting messages.
	75	-- The returned object is guaranteed to be non-null;
	76	-- default is Message::Messenger().
	77
	78	SetTraceLevel (me: out; tracelev: Integer);
	79	---Purpose : Sets trace level used for outputting messages
	80	-- - 0: no trace at all
	81	-- - 1: errors
	82	-- - 2: errors and warnings
	83	-- - 3: all messages
	84	-- Default is 1 : Errors traced
85
86	TraceLevel (me) returns Integer;
87	---Purpose : Returns trace level used for outputting messages.
88
89	SetErrorHandle (me : in out; err : Boolean);
90	---Purpose : Allows controlling whether exception raisings are handled
91	-- If err is False, they are not (hence, dbx can take control)
92	-- If err is True, they are, and they are traced
93	-- (by putting on messenger Entity's Number and file record num)
94	-- Default given at Model's creation time is True
95
96	ErrorHandle (me) returns Boolean;
97	---Purpose : Returns ErrorHandle flag
98
99	-- -- setting empty entities before loading model -- --
100
101	SetEntities (me : in out);
102	---Purpose : Fills records with empty entities; once done, each entity can
103	-- ask the FileReaderTool for any entity referenced through an
104	-- identifier. Calls Recognize which is specific to each specific
105	-- type of FileReaderTool
106
107	Recognize (me : in out; num : Integer;
108	ach : in out Check; ent : out mutable Transient)
109	returns Boolean is deferred;
110	---Purpose : Recognizes a record, given its number. Specific to each
111	-- Interface; called by SetEntities. It can call the basic method
112	-- RecognizeByLib.
113	-- Returns False if recognition has failed, True else.
114	-- <ach> has not to be filled if simply Recognition has failed :
115	-- it must record true error messages : RecognizeByLib can
116	-- generate error messages if NewRead is called
117	--
118	-- Note that it works thru a Recognizer (method Evaluate) which
119	-- has to be memorized before starting
120
121	RecognizeByLib (me; num : Integer;
122	glib : in out GeneralLib; rlib : in out ReaderLib;
123	ach : in out Check; ent : out mutable Transient)
124	returns Boolean;
125	---Purpose : Recognizes a record with the help of Libraries. Can be used
126	-- to implement the method Recognize.
127	-- <rlib> is used to find Protocol and CaseNumber to apply
128	-- <glib> performs the creation (by service NewVoid, or NewRead
129	-- if NewVoid gave no result)
130	-- <ach> is a check, which is transmitted to NewRead if it is
131	-- called, gives a result but which is false
132	-- <ent> is the result
133	-- Returns False if recognition has failed, True else
134
135	UnknownEntity (me) returns mutable Transient;
136	---Purpose : Provides an unknown entity, specific to the Interface
137	-- called by SetEntities when Recognize has failed (Unknown alone)
138	-- or by LoadModel when an Entity has caused a Fail on reading
139	-- (to keep at least its literal description)
140	-- Uses Protocol to do it
141
142	-- -- loading entities into the model -- --
143
144	NewModel (me) returns mutable InterfaceModel;
145	---Purpose : Creates an empty Model of the norm. Uses Protocol to do it
146
147	LoadModel (me : in out; amodel : mutable InterfaceModel)
148	raises DomainError;
149	---Purpose : Reads and fills Entities from the FileReaderData set by
150	-- SetData to an InterfaceModel.
151	-- It enchains required operations, the specific ones correspond
152	-- to deferred methods (below) to be defined for each Norm.
153	-- It manages also error recovery and trace.
154	-- Remark : it calls SetModel.
155	-- It Can raise any error which can occur during a load
156	-- operation, unless Error Handling is set.
157	-- This method can also be redefined if judged necessary.
158
159	LoadedEntity (me : in out; num : Integer) returns mutable Transient;
160	---Purpose : Reads, Fills and Returns one Entity read from a Record of the
161	-- FileReaderData. This Method manages also case of Fail or
162	-- Warning, by producing a ReportEntyty plus , for a Fail, a
163	-- literal Content (as an UnknownEntity). Performs also Trace
164
165	BeginRead (me : in out; amodel : mutable InterfaceModel) is deferred;
166	---Purpose : Fills model's header; each Interface defines for its Model its
167	-- own file header; this method fills it from FileReaderTool.+
168	-- It is called by AnalyseFile from InterfaceModel
169
170	AnalyseRecord (me : in out;
171	num : Integer; anent : mutable Transient; acheck : in out Check)
172	returns Boolean is deferred;
173	---Purpose : Fills an Entity, given record no; specific to each Interface,
174	-- called by AnalyseFile from InterfaceModel (which manages its
175	-- calling arguments)
176	-- To work, each Interface can define a method in its proper
177	-- Transient class, like this (given as an example) :
178	-- AnalyseRecord (me : mutable; FR : in out FileReaderTool;
179	-- num : Integer; acheck : in out Check)
180	-- returns Boolean;
181	-- and call it from AnalyseRecord
182	--
183	-- Returned Value : True if the entity could be loaded, False
184	-- else (in case of syntactic fail)
185
186	Destroy (me: in out) is virtual;
187	---C++ : alias "Standard_EXPORT virtual ~Interface_FileReaderTool() { Destroy(); }"
188
189	EndRead (me : in out; amodel : mutable InterfaceModel) is virtual;
190	---Purpose : Ends file reading after reading all the entities
191	-- default is doing nothing; redefinable as necessary
bc650d41 G	192
	193
	194	Clear(me : in out);
	195	---Purpose : Clear filelds
7fd59977	196
	197	fields
	198
	199	theproto : Protocol from Interface;
	200	thereader : FileReaderData;
	201	themodel : InterfaceModel;
	202	themessenger:Messenger from Message;
	203	thetrace : Integer; -- trace level (exceptions,errors, etc...)
	204	theerrhand : Boolean; -- to handle or not exceptions
	205	thenbrep0 : Integer; -- (reports at creation time)
	206	thenbreps : Integer; -- (all reports)
	207	thereports : HArray1OfTransient;
	208
	209	end FileReaderTool;