src/IFSelect/IFSelect_SessionPilot.cdl

   1 -- Created on: 1993-07-27
   2 -- Created by: Christian CAILLET
   3 -- Copyright (c) 1993-1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  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.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 class SessionPilot  from IFSelect  inherits Activator
  18
  19     ---Purpose : A SessionPilot is intended to make easier the use of a
  20     --           WorkSession. It receives commands, under alphanumeric form,
  21     --           then calls a library of Activators to interprete and run them.
  22     --
  23     --           Then, WorkSession just records data required to work :
  24     --           Rules for Selection, Dispatch ... ; File Data (InterfaceModel
  25     --           and results of Evaluations and Transfer as required).
  26     --           SessionPilot records and works with alphanumeric commands and
  27     --           their results (under a very simple form). It calls a list of
  28     --           Activators to perform the actions.
  29     --
  30     --           A Command can have several forms :
  31     --           - classic execution, to list, evaluate, or enrich the session
  32     --           - command which creates a new item (a Selection for instance)
  33     --             such a command should not add it to the session, but make it
  34     --             recorded by the Pilot (method RecordItem). The Pilot will
  35     --             add the item in the session, with no name
  36     --           -> such a command may be called :
  37     --             - directly, it will add an item with no name
  38     --             - by command xset, in the following form :
  39     --             xset name command ...  calls the command and adds the item
  40     --               to the session under the specified name (if not yet known)
  41     --
  42     --           Thus, to a specific Norm or way of working, only Activators
  43     --           change. A specific Initialisation can be done by starting
  44     --           with a specific set of commands.
  45     --
  46     --           In addition, SessionPilot is a sub-type of Activator, to
  47     --           recognize some built-in commands : exit/x, help/?, control of
  48     --           command line, and commands xstep xset ... See method Do
  49     --
  50     --           At least, empty lines and comment lines (beginning by '#')
  51     --           are skipped (comment lines are display if read from file)
  52
  53 uses CString, OStream, Transient, AsciiString from TCollection,
  54      Array1OfAsciiString,  SequenceOfAsciiString, Array1OfInteger,
  55      SequenceOfInteger,    SequenceOfTransient,
  56      WorkSession, WorkLibrary,     ReturnStatus,   -- Activator
  57      Selection,   Dispatch,        Modifier, SignCounter, PrintCount
  58
  59 is
  60
  61     Create (prompt : CString = "") returns mutable SessionPilot;
  62     ---Purpose : Creates an empty SessionPilot, with a prompt which will be
  63     --           displayed on querying commands. If not precised (""), this
  64     --           prompt is set to "Test-XSTEP>"
  65
  66     Session (me) returns mutable WorkSession;
  67     ---Purpose : Returns the WorkSession which is worked on
  68
  69     Library (me) returns mutable WorkLibrary;
  70     ---Purpose : Returns the WorKlibrary (Null if not set). WorkLibrary is used
  71     --           to Read and Write Files, according to the Norm
  72
  73     RecordMode (me) returns Boolean;
  74     ---Purpose : Returns the Record Mode for Commands. Default is False.
  75
  76     SetSession (me : mutable; WS : mutable WorkSession);
  77     ---Purpose : Sets a WorkSession to be worked on
  78
  79     SetLibrary (me : mutable; WL : mutable WorkLibrary);
  80     ---Purpose : Sets a WorkLibrary
  81
  82     SetRecordMode (me : mutable; mode : Boolean);
  83     ---Purpose : Changes the RecordMode.
  84
  85     SetCommandLine (me : mutable; command : AsciiString from TCollection);
  86     ---Purpose : Sets the value of the Command Line to be interpreted
  87     --           Also prepares the interpretation (splitting by blanks)
  88
  89     CommandLine (me) returns AsciiString from TCollection;
  90     ---Purpose : Returns the Command Line to be interpreted
  91     ---C++ : return const &
  92
  93     CommandPart (me; numarg : Integer = 0) returns CString;
  94     ---Purpose : Returns the part of the command line which begins at argument
  95     --           <numarg> between 0 and NbWords-1 (by default, all the line)
  96     --           Empty string if out of range
  97
  98     NbWords (me) returns Integer;
  99     ---Purpose : Returns the count of words of the Command Line, separated by
 100     --           blanks : 0 if empty, one if a command without args, else it
 101     --           gives the count of args minus one.
 102     --  Warning : limited to 10 (command title + 9 args)
 103
 104     Word (me; num : Integer) returns AsciiString from TCollection;
 105     ---Purpose : Returns a word given its rank in the Command Line. Begins at 0
 106     --           which is the Command Title, 1 is the 1st arg., etc...
 107     ---C++ : return const &
 108
 109     Arg  (me; num : Integer) returns CString;
 110     ---Purpose : Returns a word given its rank, as a CString.
 111     --           As for Word, begins at 0 (the command name), etc...
 112
 113     RemoveWord (me : mutable; num : Integer) returns Boolean;
 114     ---Purpose : Removes a word given its rank. Returns True if Done, False if
 115     --           <num> is out of range
 116
 117     NbCommands (me) returns Integer;
 118     ---Purpose : Returns the count of recorded Commands
 119
 120     Command (me; num : Integer) returns AsciiString from TCollection;
 121     ---Purpose : Returns a recorded Command, given its rank (from 1)
 122     ---C++ : return const &
 123
 124     RecordItem (me : mutable; item : any Transient) returns ReturnStatus;
 125     ---Purpose : Allows to associate a Transient Value with the last execution
 126     --           as a partial result
 127     --           Returns RetDone if item is not Null, RetFail if item is Null
 128     --           Remark : it is nullified for each Perform
 129
 130     RecordedItem (me) returns any Transient;
 131     ---Purpose : Returns the Transient Object which was recorded with the
 132     --           current Line Command. If none was, returns a Null Handle
 133
 134     Clear (me : mutable);
 135     ---Purpose : Clears the recorded informations (commands, objects)
 136
 137         -- --    Execution    -- --
 138
 139     ReadScript (me : mutable; file : CString = "") returns ReturnStatus;
 140     ---Purpose : Reads commands from a Script File, named <file>. By default
 141     --           (file = ""), reads from standard input with a prompt
 142     --           Else (reading from a file), the read commands are displayed
 143     --           onto standard output. Allows nested reads. Reading is stopped
 144     --           either by command x or exit, or by reaching end of file
 145     --           Return Value follows the rules of Do : RetEnd for normal end,
 146     --           RetFail if script could not be opened
 147
 148     Perform (me : mutable) returns ReturnStatus;
 149     ---Purpose : Executes the Command, itself (for built-in commands, which
 150     --           have priority) or by using the list of Activators.
 151     --           The value returned is : RetVoid if nothing done (void command)
 152     --           RetDone if execution OK, RetEnd if END OF SESSION, RetError if
 153     --           command unknown or incorrect, RetFail if error on execution
 154     --           If execution is OK and RecordMode is set, this Command Line is
 155     --           recorded to the list (see below).
 156
 157     ExecuteAlias (me : mutable; aliasname : AsciiString from TCollection)
 158         returns ReturnStatus;
 159     ---Purpose : Executes the Commands, except that the command name (word 0)
 160     --           is aliased. The rest of the command line is unchanged
 161     --           If <alias> is empty, Executes with no change
 162     --
 163     --           Error status is returned if the alias is unknown as command
 164
 165     Execute (me : mutable; command : AsciiString from TCollection)
 166         returns ReturnStatus;
 167     ---Purpose : Sets the Command then tries to execute it. Return value :
 168     --           same as for Perform
 169
 170     ExecuteCounter (me : mutable; counter : mutable SignCounter;
 171                     numword : Integer; mode : PrintCount = IFSelect_CountByItem)
 172         returns ReturnStatus;
 173     ---Purpose : Executes a Counter in a general way
 174     --           If <numword> is greater than count of command words, it counts
 175     --           all the model. Else it considers the word <numword> as the
 176     --           identifier of a Selection
 177     --           <mode> gives the mode of printing results, default is
 178     --           CountByItem
 179
 180     Number(me; val : CString) returns Integer;
 181     ---Purpose : Interprets a string value as an entity number :
 182     --           if it gives an integer, returns its value
 183     --           else, considers it as ENtityLabel (preferably case sensitive)
 184     --           in case of failure, returns 0
 185
 186     Do   (me : mutable; number : Integer; session : mutable SessionPilot)
 187         returns ReturnStatus;
 188     ---Purpose : Processes specific commands, which are :
 189     --           x or exit for end of session
 190     --           ? or help for help messages
 191     --           xcommand to control command lines (Record Mode, List, Clear,
 192     --             File Output ...)
 193     --           xsource to execute a command file (no nesting allowed),
 194     --             in case of error, source is stopped and keyword recovers
 195     --           xstep is a simple prefix (useful in a wider environment, to
 196     --             avoid conflicts on command names)
 197     --           xset control commands which create items with names
 198
 199     Help (me; number : Integer) returns CString;
 200     ---Purpose : Help for specific commands (apart from general command help)
 201
 202 fields
 203
 204     thesession : WorkSession;
 205     theprompt  : AsciiString from TCollection;
 206     thecommand : AsciiString from TCollection;
 207     thenbwords : Integer;
 208     thewords   : Array1OfAsciiString;
 209     thewordeb  : Array1OfInteger;
 210     therecord  : Boolean;
 211
 212     thenumrec  : Integer;
 213     theobjrec  : Transient;
 214     thecomlist : SequenceOfAsciiString;
 215
 216 end SessionPilot;