0024750: Replace instantiations of TCollection generic classes by NCollection templat...

[occt.git] / src / StepData / StepData_StepReaderData.cdl

-- Created on: 1992-02-11
-- 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.

class StepReaderData  from StepData  inherits FileReaderData

    ---Purpose : Specific FileReaderData for Step
    --           Contains litteral description of entities (for each one : type
    --           as a string, ident, parameter list)
    --           provides references evaluation, plus access to litteral data
    --           and specific access methods (Boolean, XY, XYZ)

uses Integer, Boolean, CString, Transient, Type, HAsciiString from TCollection,
     Array1OfInteger from TColStd, AsciiString from TCollection,
     Array1OfAsciiString, SequenceOfAsciiString from TColStd,
     Check from Interface,   ParamType from Interface,
     Logical from StepData, SelectType from StepData, EnumTool from StepData,
     SelectMember from StepData, Field from StepData, PDescr from StepData,
     FieldList from StepData, ESDescr from StepData,
     IndexedMapOfAsciiString from Interface,
     DataMapOfIntegerInteger from TColStd

is

    	-- --   File data storing and access (specific)   -- --

    Create (nbheader,nbtotal,nbpar : Integer) returns StepReaderData;
    ---Purpose : creates StepReaderData correctly dimensionned (necessary at
    --           creation time, because it contains arrays)
    --           nbheader is nb of records for Header, nbtotal for Header+Data
    --           and nbpar gives the total count of parameters

    SetRecord (me    : mutable;    num  : Integer;
               ident : CString;   type : CString; nbpar : Integer)
    	is static;
    ---Purpose : Fills the fields of a record

    AddStepParam (me   : mutable;   num   : Integer;
              aval : CString;  atype : ParamType; nument : Integer = 0)
    	is static;
    ---Purpose : Fills the fields of a parameter of a record. This is a variant
    --           of AddParam, Adapted to STEP (optimized for specific values)

    RecordType  (me; num : Integer) returns AsciiString from TCollection
    	is static;
    ---Purpose : Returns Record Type
    ---C++ : return const &

    CType (me; num : Integer) returns CString  is static;
    ---Purpose : Returns Record Type as a CString
    -- was C++ : return const

    RecordIdent (me; num : Integer) returns Integer  is static;
    ---Purpose : Returns record identifier (Positive number)
    --           If returned ident is not positive : Sub-List or Scope mark

    SubListNumber (me; num, nump : Integer; aslast : Boolean) returns Integer
    	is static;
    ---Purpose : Returns SubList numero designated by a parameter (nump) in a
    --           record (num), or zero if the parameter does not exist or is
    --           not a SubList address. Zero too If aslast is True and nump
    --           is not for the last parameter

    IsComplex (me; num : Integer) returns Boolean  is static;
    ---Purpose : Returns True if <num> corresponds to a Complex Type Entity
    --           (as can be defined by ANDOR Express clause)

    ComplexType (me; num : Integer;
    	    	  types : in out SequenceOfAsciiString from TColStd)
    	is static;
    ---Purpose : Returns the List of Types which correspond to a Complex Type
    --           Entity. If not Complex, there is just one Type in it
    --           For a SubList or a Scope mark, <types> remains empty

    NextForComplex (me; num : Integer) returns Integer  is static;
    ---Purpose : Returns the Next "Componant" for a Complex Type Entity, of
    --           which <num> is already a Componant (the first one or a next one)
    --           Returns 0 for a Simple Type or for the last Componant

    NamedForComplex (me; name : CString; num0 : Integer;
    	    	     num  : in out Integer; ach : in out Check)
	     returns Boolean;
    ---Purpose : Determines the first component which brings a given name, for
    --           a Complex Type Entity
    --           <num0> is the very first record of this entity
    --           <num> is given the last NextNamedForComplex, starts at zero
    --           it is returned as the newly found number
    --           Hence, in the normal case, NextNamedForComplex starts by num0
    --           if <num> is zero, else by NextForComplex(num)
    --           If the alphabetic order is not respected, it restarts from
    --           num0 and loops on NextForComplex until finding <name>
    --           In case of "non-alphabetic order", <ach> is filled with a
    --             Warning for this name
    --           In case of "not-found at all", <ach> is filled with a Fail,
    --             and <num> is returned as zero
    --           
    --           Returns True if alphabetic order, False else

    	-- --    Some Useful Accesses which are provided    -- --

    CheckNbParams (me; num : Integer; nbreq : Integer; ach : in out Check;
    	    	   mess : CString = "")  returns Boolean  is static;
    ---Purpose : Checks Count of Parameters of record <num> to equate <nbreq>
    --           If this Check is successful, returns True
    --           Else, fills <ach> with an Error Message then returns False
    --           <mess> is included in the Error message if given non empty

    ReadSubList (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 numsub : out Integer;
		 optional : Boolean = Standard_False;
		 lenmin : Integer = 0; lenmax : Integer = 0)
    	    	    returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a sub-list (may be
    --           typed, see ReadTypedParameter in this case)
    --           Returns True if OK. Else (not a LIST), returns false and
    --           feeds Check with appropriate check
    --           If <optional> is True and Param is not defined, returns True
    --             with <ach> not filled and <numsub> returned as 0
    --           Works with SubListNumber with <aslast> false (no specific case
    --           for last parameter)

    ReadSub     (me; numsub : Integer; mess : CString; ach : in out Check;
    	    	 descr : PDescr; val : out Transient)  returns Integer;
    ---Purpose : reads the content of a sub-list into a transient :
    --           SelectNamed, or HArray1 of Integer,Real,String,Transient ...
    --           recursive call if list of list ...
    --           If a sub-list has mixed types, an HArray1OfTransient is
    --             produced, it may contain SelectMember
    --           Intended to be called by ReadField
    --           The returned status is : negative if failed, 0 if empty.
    --           Else the kind to be recorded in the field

    ReadMember (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	val : in out SelectMember)  returns Boolean;
    ---Purpose : Reads parameter <nump> of record <num> into a SelectMember,
    --           self-sufficient (no Description needed)
    --           If <val> is already created, it will be filled, as possible
    --           And if reading does not match its own description, the result
    --           will be False
    --           If <val> is not it not yet created, it will be (SelectNamed)
    --           Usefull if a field is defined as a SelectMember, directly
    --           (SELECT with no Entity as member)
    --           But SelectType also manages SelectMember (for SELECT with
    --           some members as Entity, some other not)

    ReadField  (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 descr : PDescr; fild : in out Field) returns Boolean;
    ---Purpose : reads parameter <nump> of record <num> into a Field,
    --           controlled by a Parameter Descriptor (PDescr), which controls
    --           its allowed type(s) and value
    --           <ach> is filled if the read parameter does not match its
    --           description (but the field is read anyway)
    --           If the description is not defined, no control is done
    --           Returns True when done

    ReadList   (me; num : Integer; ach : in out Check;
    	    	descr : ESDescr; list : in out FieldList) returns Boolean;
    ---Purpose : reads a list of fields controlled by an ESDescr

    ReadAny    (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	descr : PDescr; val : in out Transient) returns Boolean;
    ---Purpose : Reads parameter <nump> of record <num> into a Transient Value
    --           according to the type of the parameter :
    --           Named for Integer,Boolean,Logical,Enum,Real : SelectNamed
    --           Immediate Integer,Boolean,Logical,Enum,Real : SelectInt/Real
    --           Text  : HAsciiString
    --           Ident : the referenced Entity
    --           Sub-List not processed, see ReadSub
    --           This value is controlled by a Parameter Descriptor (PDescr),
    --           which controls its allowed type and value
    --           <ach> is filled if the read parameter does not match its
    --           description (the select is nevertheless created if possible)
    --           
    --  Warning : val is in out, hence it is possible to predefine a specific
    --           SelectMember then to fill it. If <val> is Null or if the
    --           result is not a SelectMember, val itself is returned a new ref
    --           For a Select with a Name, <val> must then be a SelectNamed

    ReadXY     (me; num, nump : Integer; mess : CString; ach : in out Check;
    	        X,Y : out Real) returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a sub-list of
    --           two Reals X,Y. Returns True if OK. Else, returns false and
    --           feeds Check with appropriate Fails (parameter not a sub-list,
    --           not two Reals in the sub-list) composed with "mess" which
    --           gives the name of the parameter

    ReadXYZ    (me; num, nump : Integer; mess : CString; ach : in out Check;
    	        X,Y,Z : out Real) returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a sub-list of
    --           three Reals X,Y,Z. Return value and Check managed as by
    --           ReadXY (demands a sub-list of three Reals)

    ReadReal   (me; num, nump : Integer; mess : CString; ach : in out Check;
    	        val : out Real) returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a single Real value.
    --           Return value and Check managed as by ReadXY (demands a Real)

    ReadEntity  (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 atype : Type; ent : out Transient)
    	returns Boolean  is static;
    ---Purpose : Reads parameter <nump> of record <num> as a single Entity.
    --           Return value and Check managed as by ReadReal (demands a
    --           reference to an Entity). In Addition, demands read Entity
    --           to be Kind of a required Type <atype>.
    --           Remark that returned status is False and <ent> is Null if
    --           parameter is not an Entity, <ent> remains Not Null is parameter
    --           is an Entity but is not Kind of required type

    ReadEntity  (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 sel : in out SelectType) returns Boolean  is static;
    ---Purpose : Same as above, but a SelectType checks Type Matching, and
    --          records the read Entity (see method Value from SelectType)

    ReadInteger (me; num, nump : Integer; mess : CString; ach : in out Check;
    	         val : out Integer) returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a single Integer.
    --           Return value & Check managed as by ReadXY (demands an Integer)

    ReadBoolean (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 flag : out Boolean) returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a Boolean
    --           Return value and Check managed as by ReadReal (demands a
    --           Boolean enum, i.e. text ".T." for True or ".F." for False)

    ReadLogical (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 flag : out Logical from StepData) returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a Logical
    --           Return value and Check managed as by ReadBoolean (demands a
    --           Logical enum, i.e. text ".T.", ".F.", or ".U.")

    ReadString  (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 val : out HAsciiString from TCollection)
    	    	     returns Boolean  is static;
    ---Purpose : reads parameter <nump> of record <num> as a String (text
    --           between quotes, quotes are removed by the Read operation)
    --           Return value and Check managed as by ReadXY (demands a String)

    ReadEnumParam (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	   text : out CString)
    	    	     returns Boolean  is static;
    ---Puroise : Reads parameter <nump> of record <num>, checks if it is an
    --           Enumeration, if yes returns its text value
    --           Returns True if OK, False (+ empty string) if not an enum
    --           (also fills <ach>

    FailEnumValue (me; num, nump : Integer; mess : CString; ach : in out Check);
    ---Purpose : Fills a check with a fail message if enumeration value does
    --           match parameter definition
    --           Just a help to centralize message definitions

    ReadEnum    (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	 enumtool : EnumTool from StepData; val : out Integer)
    	    	     returns Boolean  is static;
    ---Purpose : Reads parameter <nump> of record <num> as an Enumeration (text
    --           between dots) and converts it to an integer value, by an
    --           EnumTool. Returns True if OK, false if : this parameter is not
    --           enumeration, or is not recognized by the EnumTool (with fail)

    ReadTypedParam (me; num,nump : Integer; mustbetyped : Boolean;
    	    	    mess : CString; ach : in out Check;
    	    	    numr,numrp : out Integer; typ : out AsciiString)
		    	returns Boolean  is static;
    ---Purpose : Resolves a parameter which can be enclosed in a type def., as
    --           TYPE(val). The parameter must then be read normally according
    --           its type.  Parameter to be resolved is <nump> of record <num>
    --           <mustbetyped> True  demands a typed parameter
    --           <mustbetyped> False accepts a non-typed parameter as option
    --           mess and ach as usual
    --           <numr>,<numrp> are the resolved record and parameter numbers
    --             = num,nump if no type,  else numrp=1
    --           <typ> returns the recorded type, or empty string
    --           Remark : a non-typed list is considered as "non-typed"

    CheckDerived (me; num, nump : Integer; mess : CString; ach : in out Check;
    	    	  errstat : Boolean = Standard_False)
    	    	     returns Boolean  is static;
    ---Purpose : Checks if parameter <nump> of record <num> is given as Derived
    --           If this Check is successful (i.e. Param = "*"), returns True
    --           Else, fills <ach> with a Message which contains <mess> and
    --           returns False. According to <errstat>, this message is Warning
    --           if errstat is False (Default), Fail if errstat is True

    	-- --   General exploitation methods   -- --

    NbEntities (me) returns Integer  is redefined;
    ---Purpose : Returns total count of Entities (including Header)

    FindNextRecord (me; num : Integer) returns Integer;
    ---Purpose : determines the first suitable record following a given one
    --           that is, skips SCOPE,ENDSCOPE and SUBLIST records
    --           Note : skips Header records, which are accessed separately

    FindEntityNumber (me; num, id : Integer) returns Integer is static private;
    ---Purpose : Searches for a Parameter of the record <num>, which refers to
    --           the Ident <id> (form #nnn). [Used by SetEntityNumbers]
    --           If found, returns its EntityNumber, else returns Zero.

    	-- --   Preparation before loading model   -- --

    SetEntityNumbers (me : mutable; withmap : Boolean = Standard_True);
    ---Purpose : determines reference numbers in EntityNumber fields
    --           called by Prepare from StepReaderTool to prepare later using
    --           by a StepModel. This method is attached to StepReaderData
    --           because it needs a massive amount of data accesses to work
    --           
    --           If <withmap> is given False, the basic exploration algorithm
    --           is activated, otherwise a map is used as far as it is possible
    --           this option can be used only to test this algorithm

    	-- --   Managing Header  -- --
    	--   Header is defined as a list of StepEntities (without ident)

    FindNextHeaderRecord (me; num : Integer) returns Integer;
    ---Purpose : determine first suitable record of Header
    --           works as FindNextRecord, but treats only Header records

    PrepareHeader (me : mutable);
    ---Purpose : Works as SetEntityNumbers but for Header : more simple because
    --           there are no Reference, only Sub-Lists

    GlobalCheck (me) returns Check;
    ---Purpose : Returns the Global Check. It can record Fail messages about
    --           Undefined References (detected by SetEntityNumbers)
    ---C++ : return const

fields

    theidents : Array1OfInteger from TColStd;
    -- ident (entity/sub) or indicates SCOPE/END.
--    thetypes  : Array1OfAsciiString;
    thetypes  : Array1OfInteger;
    thenametypes  : IndexedMapOfAsciiString from Interface;
    themults : DataMapOfIntegerInteger from TColStd;
    --themults  : Array1OfInteger from TColStd;  -- For Complex Type Entities
    thenbents : Integer;  -- internal data used for optimization
    thelastn  : Integer;
    thenbhead : Integer;  -- nb of records taken by Header
    thenbscop : Integer;
    thecheck  : Check;

end StepReaderData;