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