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

-- Created on: 1992-02-10
-- Created by: Christian CAILLET
-- Copyright (c) 1992-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

deferred class FileReaderData  from Interface  inherits TShared

    ---Purpose : This class defines services which permit to access Data issued
    --           from a File, in a form which does not depend of physical
    --           format : thus, each Record has an attached ParamList (to be
    --           managed) and resulting Entity.
    --           
    --           Each Interface defines its own FileReaderData : on one hand by
    --           defining deferred methods given here, on the other hand by
    --           describing literal data and their accesses, with the help of
    --           basic classes such as String, Array1OfString, etc...
    --           
    --           FileReaderData is used by a FileReaderTool, which is also
    --           specific of each Norm, to read an InterfaceModel of the Norm
    --           FileReaderData inherits TShared to be accessed by Handle :
    --           this allows FileReaderTool to define more easily the specific
    --           methods, and improves memory management.

uses Integer, Boolean,  CString, Transient,  AsciiString from TCollection,
     Array1OfInteger  from TColStd,     Array1OfTransient from TColStd,
     InterfaceModel,  Check,  FileParameter,  ParamSet,  ParamList,  ParamType

raises NoSuchObject

is

    Initialize (nbr : Integer; npar : Integer);
    ---Purpose : Initializes arrays of Entities and of ParamLists attached
    --           to registered records
    --           <nbr> must be the maximum number of records to get (no way to
    --           extend it at run-time) : count entities and sub-entities ...
    --           <npar> is the total count of parameters (if it is not exact,
    --           it will be extented as necessary)
    --           
    --           Hence, to each record can be bound an Entity and a list of
    --           Parameters. Each kind of FileReaderData can add other data, by
    --           having them in parallel (other arrays with same sizes)
    --           Else, it must manage binding between items and their data


    NbRecords (me) returns Integer   is virtual;
    ---Purpose : Returns the count of registered records
    --           That is, value given for Initialization (can be redefined)

    NbEntities (me) returns Integer  is virtual;
    ---Purpose : Returns the count of entities. Depending of each norm, records
    --           can be Entities or SubParts (SubList in STEP, SubGroup in SET
    --           ...). NbEntities counts only Entities, not Subs
    --           Used for memory reservation in InterfaceModel
    --           Default implementation uses FindNextRecord
    --           Can be redefined into a more performant way

    FindNextRecord (me; num : Integer) returns Integer is deferred;
    ---Purpose : Determines the record number defining an Entity following a
    --           given record number. Specific to each sub-class of
    --           FileReaderData. Returning zero means no record found

    	-- --   access to Paramaters   -- --

    InitParams (me : mutable; num : Integer);
    ---Purpose : attaches an empty ParamList to a Record

    AddParam   (me : mutable; num : Integer; aval : CString;
    	        atype : ParamType; nument : Integer = 0);
    ---Purpose : Adds a parameter to record no "num" and fills its fields
    --           (EntityNumber is optional)
    --  Warning : <aval> is assumed to be memory-managed elsewhere : it is NOT
    --           copied. This gives a best speed : strings remain stored in
    --           pages of characters

    AddParam   (me : mutable; num : Integer; aval : AsciiString from TCollection;
    	        atype : ParamType; nument : Integer = 0);
    ---Purpose : Same as above, but gets a AsciiString from TCollection
    --           Remark that the content of the AsciiString is locally copied
    --           (because its content is most often lost after using)

    AddParam   (me : mutable; num : Integer; FP : FileParameter);
    ---Purpose : Same as above, but gets a complete FileParameter
    --  Warning : Content of <FP> is NOT copied : its original address and space
    --           in memory are assumed to be managed elsewhere (see ParamSet)

    SetParam   (me : mutable; num, nump : Integer; FP : FileParameter);
    ---Purpose : Sets a new value for a parameter of a record, given by :
    --           num : record number; nump : parameter number in the record

    NbParams (me; num : Integer) returns Integer  is static;
    ---Purpose : Returns count of parameters attached to record "num"
    --           If <num> = 0, returns the total recorded count of parameters

    Params   (me; num : Integer) returns ParamList  is static;
    ---Purpose : Returns the complete ParamList of a record (read only)
    --           num = 0 to return the whole param list for the file

    Param       (me; num, nump : Integer) returns FileParameter  is static;
    ---Purpose : Returns parameter "nump" of record "num", as a complete
    --           FileParameter
    ---C++ : return const &

    ChangeParam (me : mutable; num, nump : Integer) returns FileParameter
    	is static;
    ---Purpose : Same as above, but in order to be modified on place
    ---C++ : return &

    ParamType   (me; num, nump : Integer) returns ParamType  is static;
    ---Purpose : Returns type of parameter "nump" of record "num"

--    ParamValue  (me; num, nump : Integer) returns AsciiString from TCollection;
    ---Purpose : Returns literal value of parameter "nump" of record "num"
    --  was C++ : return const &

    ParamCValue (me; num, nump : Integer) returns CString  is static;
    ---Purpose : Same as above, but as a CString
    --  was C++ : return const

    IsParamDefined (me; num, nump : Integer) returns Boolean  is static;
    ---Purpose : Returns True if parameter "nump" of record "num" is defined
    --           (it is not if its type is ParamVoid)

    ParamNumber (me; num, nump : Integer) returns Integer  is static;
    ---Purpose : Returns record number of an entity referenced by a parameter
    --           of type Ident; 0 if no EntityNumber has been determined
    --           Note that it is used to reference Entities but also Sublists
    --           (sublists are not objects, but internal descriptions)

    ParamEntity (me; num, nump : Integer)
    	returns Transient  raises NoSuchObject  is static;
    ---Purpose : Returns the StepEntity referenced by a parameter
    --           Error if none
    ---C++ : return const &

    ChangeParameter (me : mutable; numpar : Integer) returns FileParameter
    	is static protected;
    ---Purpose : Returns a parameter given its absolute rank in the file
    --           in order to be consulted or modified in specilaized actions
    ---C++ : return &

    ParamPosition (me; numpar : Integer; num,nump : out Integer)
    	is static protected;
    ---Purpose : For a given absolute rank of parameter, determines the
    --           record to which its belongs, and the parameter number for it

    ParamFirstRank (me; num : Integer) returns Integer  is static;
    ---Purpose : Returns the absolute rank of the beginning of a record
    --           (its lsit is from ParamFirstRank+1 to ParamFirstRank+NbParams)

    	-- --   binding empty entities before loading model   -- --

    BoundEntity (me; num : Integer) returns Transient;
    ---Purpose : Returns the entity bound to a record, set by SetEntities
    ---C++ : return const &

    BindEntity (me : mutable; num : Integer; ent : Transient);
    ---Purpose : Binds an entity to a record

    SetErrorLoad (me : mutable; val : Boolean);
    ---Purpose : Sets the status "Error Load" on, to overside check fails
    --           <val> True  : declares unloaded
    --           <val> False : declares loaded
    --           If not called before loading (see FileReaderTool), check fails
    --             give the status
    --           IsErrorLoad says if SetErrorLoad has been called by user
    --           ResetErrorLoad resets it (called by FileReaderTool)
    --           This allows to specify that the currently loaded entity
    --           remains unloaded (because of syntactic fail)

    IsErrorLoad (me) returns Boolean;
    ---Purpose : Returns True if the status "Error Load" has been set (to True
    --           or False)

    ResetErrorLoad (me : mutable) returns Boolean;
    ---Purpose : Returns the former value of status "Error Load" then resets it
    --           Used to read the status then ensure it is reset

    	-- --   specials    -- --

    Destroy (me : mutable);
    ---Purpose : Destructor (waiting for memory management)
    ---C++ : alias ~

    Fastof (myclass; str : CString) returns Real;
    ---Purpose : Same spec.s as standard <atof> but 5 times faster

fields

    thenum0   : Integer;        -- current data for access to parameters
    therrload : Integer;
    theparams : ParamSet;               -- the general set of parameters
    thenumpar : Array1OfInteger   from TColStd;   -- beginning of each one
--    thenbpar  : Array1OfInteger   from TColStd;   -- its size
    theents   : Array1OfTransient from TColStd;   -- entities bound to records

end FileReaderData;
Commit	Line	Data
b311480e	1	-- Created on: 1992-02-10
	2	-- Created by: Christian CAILLET
	3	-- Copyright (c) 1992-1999 Matra Datavision
973c2be1	4	-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e	5	--
973c2be1	6	-- This file is part of Open CASCADE Technology software library.
b311480e	7	--
d5f74e42	8	-- This library is free software; you can redistribute it and/or modify it under
d5f74e42	9	-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1	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.
b311480e	13	--
973c2be1	14	-- Alternatively, this file may be used under the terms of Open CASCADE
973c2be1	15	-- commercial license or contractual agreement.
7fd59977	16
	17	deferred class FileReaderData from Interface inherits TShared
	18
	19	---Purpose : This class defines services which permit to access Data issued
	20	-- from a File, in a form which does not depend of physical
	21	-- format : thus, each Record has an attached ParamList (to be
	22	-- managed) and resulting Entity.
	23	--
	24	-- Each Interface defines its own FileReaderData : on one hand by
	25	-- defining deferred methods given here, on the other hand by
	26	-- describing literal data and their accesses, with the help of
	27	-- basic classes such as String, Array1OfString, etc...
	28	--
	29	-- FileReaderData is used by a FileReaderTool, which is also
	30	-- specific of each Norm, to read an InterfaceModel of the Norm
	31	-- FileReaderData inherits TShared to be accessed by Handle :
	32	-- this allows FileReaderTool to define more easily the specific
	33	-- methods, and improves memory management.
	34
	35	uses Integer, Boolean, CString, Transient, AsciiString from TCollection,
	36	Array1OfInteger from TColStd, Array1OfTransient from TColStd,
	37	InterfaceModel, Check, FileParameter, ParamSet, ParamList, ParamType
	38
	39	raises NoSuchObject
	40
	41	is
	42
	43	Initialize (nbr : Integer; npar : Integer);
	44	---Purpose : Initializes arrays of Entities and of ParamLists attached
	45	-- to registered records
	46	-- <nbr> must be the maximum number of records to get (no way to
	47	-- extend it at run-time) : count entities and sub-entities ...
	48	-- <npar> is the total count of parameters (if it is not exact,
	49	-- it will be extented as necessary)
	50	--
	51	-- Hence, to each record can be bound an Entity and a list of
	52	-- Parameters. Each kind of FileReaderData can add other data, by
	53	-- having them in parallel (other arrays with same sizes)
	54	-- Else, it must manage binding between items and their data
	55
	56
	57	NbRecords (me) returns Integer is virtual;
	58	---Purpose : Returns the count of registered records
	59	-- That is, value given for Initialization (can be redefined)
	60
	61	NbEntities (me) returns Integer is virtual;
	62	---Purpose : Returns the count of entities. Depending of each norm, records
	63	-- can be Entities or SubParts (SubList in STEP, SubGroup in SET
	64	-- ...). NbEntities counts only Entities, not Subs
	65	-- Used for memory reservation in InterfaceModel
	66	-- Default implementation uses FindNextRecord
	67	-- Can be redefined into a more performant way
	68
	69	FindNextRecord (me; num : Integer) returns Integer is deferred;
	70	---Purpose : Determines the record number defining an Entity following a
	71	-- given record number. Specific to each sub-class of
	72	-- FileReaderData. Returning zero means no record found
	73
	74	-- -- access to Paramaters -- --
	75
	76	InitParams (me : mutable; num : Integer);
	77	---Purpose : attaches an empty ParamList to a Record
	78
	79	AddParam (me : mutable; num : Integer; aval : CString;
80	atype : ParamType; nument : Integer = 0);
81	---Purpose : Adds a parameter to record no "num" and fills its fields
82	-- (EntityNumber is optional)
83	-- Warning : <aval> is assumed to be memory-managed elsewhere : it is NOT
84	-- copied. This gives a best speed : strings remain stored in
85	-- pages of characters
86
87	AddParam (me : mutable; num : Integer; aval : AsciiString from TCollection;
88	atype : ParamType; nument : Integer = 0);
89	---Purpose : Same as above, but gets a AsciiString from TCollection
90	-- Remark that the content of the AsciiString is locally copied
91	-- (because its content is most often lost after using)
92
93	AddParam (me : mutable; num : Integer; FP : FileParameter);
94	---Purpose : Same as above, but gets a complete FileParameter
95	-- Warning : Content of <FP> is NOT copied : its original address and space
96	-- in memory are assumed to be managed elsewhere (see ParamSet)
97
98	SetParam (me : mutable; num, nump : Integer; FP : FileParameter);
99	---Purpose : Sets a new value for a parameter of a record, given by :
100	-- num : record number; nump : parameter number in the record
101
102	NbParams (me; num : Integer) returns Integer is static;
103	---Purpose : Returns count of parameters attached to record "num"
104	-- If <num> = 0, returns the total recorded count of parameters
105
106	Params (me; num : Integer) returns ParamList is static;
107	---Purpose : Returns the complete ParamList of a record (read only)
108	-- num = 0 to return the whole param list for the file
109
110	Param (me; num, nump : Integer) returns FileParameter is static;
111	---Purpose : Returns parameter "nump" of record "num", as a complete
112	-- FileParameter
113	---C++ : return const &
114
115	ChangeParam (me : mutable; num, nump : Integer) returns FileParameter
116	is static;
117	---Purpose : Same as above, but in order to be modified on place
118	---C++ : return &
119
120	ParamType (me; num, nump : Integer) returns ParamType is static;
121	---Purpose : Returns type of parameter "nump" of record "num"
122
123	-- ParamValue (me; num, nump : Integer) returns AsciiString from TCollection;
124	---Purpose : Returns literal value of parameter "nump" of record "num"
125	-- was C++ : return const &
126
127	ParamCValue (me; num, nump : Integer) returns CString is static;
128	---Purpose : Same as above, but as a CString
129	-- was C++ : return const
130
131	IsParamDefined (me; num, nump : Integer) returns Boolean is static;
132	---Purpose : Returns True if parameter "nump" of record "num" is defined
133	-- (it is not if its type is ParamVoid)
134
135	ParamNumber (me; num, nump : Integer) returns Integer is static;
136	---Purpose : Returns record number of an entity referenced by a parameter
137	-- of type Ident; 0 if no EntityNumber has been determined
138	-- Note that it is used to reference Entities but also Sublists
139	-- (sublists are not objects, but internal descriptions)
140
141	ParamEntity (me; num, nump : Integer)
6e33d3ce	142	returns Transient raises NoSuchObject is static;
7fd59977	143	---Purpose : Returns the StepEntity referenced by a parameter
	144	-- Error if none
	145	---C++ : return const &
	146
	147	ChangeParameter (me : mutable; numpar : Integer) returns FileParameter
	148	is static protected;
	149	---Purpose : Returns a parameter given its absolute rank in the file
	150	-- in order to be consulted or modified in specilaized actions
	151	---C++ : return &
	152
	153	ParamPosition (me; numpar : Integer; num,nump : out Integer)
	154	is static protected;
	155	---Purpose : For a given absolute rank of parameter, determines the
	156	-- record to which its belongs, and the parameter number for it
	157
	158	ParamFirstRank (me; num : Integer) returns Integer is static;
	159	---Purpose : Returns the absolute rank of the beginning of a record
	160	-- (its lsit is from ParamFirstRank+1 to ParamFirstRank+NbParams)
	161
	162	-- -- binding empty entities before loading model -- --
	163
6e33d3ce	164	BoundEntity (me; num : Integer) returns Transient;
7fd59977	165	---Purpose : Returns the entity bound to a record, set by SetEntities
	166	---C++ : return const &
	167
6e33d3ce	168	BindEntity (me : mutable; num : Integer; ent : Transient);
7fd59977	169	---Purpose : Binds an entity to a record
	170
	171	SetErrorLoad (me : mutable; val : Boolean);
	172	---Purpose : Sets the status "Error Load" on, to overside check fails
	173	-- <val> True : declares unloaded
	174	-- <val> False : declares loaded
	175	-- If not called before loading (see FileReaderTool), check fails
	176	-- give the status
	177	-- IsErrorLoad says if SetErrorLoad has been called by user
	178	-- ResetErrorLoad resets it (called by FileReaderTool)
	179	-- This allows to specify that the currently loaded entity
	180	-- remains unloaded (because of syntactic fail)
	181
	182	IsErrorLoad (me) returns Boolean;
	183	---Purpose : Returns True if the status "Error Load" has been set (to True
	184	-- or False)
	185
	186	ResetErrorLoad (me : mutable) returns Boolean;
	187	---Purpose : Returns the former value of status "Error Load" then resets it
	188	-- Used to read the status then ensure it is reset
	189
	190	-- -- specials -- --
	191
	192	Destroy (me : mutable);
	193	---Purpose : Destructor (waiting for memory management)
	194	---C++ : alias ~
	195
	196	Fastof (myclass; str : CString) returns Real;
	197	---Purpose : Same spec.s as standard <atof> but 5 times faster
	198
	199	fields
	200
	201	thenum0 : Integer; -- current data for access to parameters
7fd59977	202	therrload : Integer;
	203	theparams : ParamSet; -- the general set of parameters
	204	thenumpar : Array1OfInteger from TColStd; -- beginning of each one
	205	-- thenbpar : Array1OfInteger from TColStd; -- its size
	206	theents : Array1OfTransient from TColStd; -- entities bound to records
	207
	208	end FileReaderData;