-- File: Interface_FileReaderTool.cdl -- Created: Thu Feb 4 17:00:08 1993 -- Author: Christian CAILLET -- ---Copyright: Matra Datavision 1993 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. -- 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. -- is used to find Protocol and CaseNumber to apply -- performs the creation (by service NewVoid, or NewRead -- if NewVoid gave no result) -- is a check, which is transmitted to NewRead if it is -- called, gives a result but which is false -- 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 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;