CommandInterpreter.h Source File

Back to the index.

CommandInterpreter.h
Go to the documentation of this file.
1 #ifndef COMMANDINTERPRETER_H
2 #define COMMANDINTERPRETER_H
3 
4 /*
5  * Copyright (C) 2007-2010 Anders Gavare. All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  * 3. The name of the author may not be used to endorse or promote products
16  * derived from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28  * SUCH DAMAGE.
29  */
30 
31 #include "misc.h"
32 
33 #include "Command.h"
34 #include "UnitTest.h"
35 
36 
37 class GXemul;
38 
39 
40 /**
41  * \brief An interactive command interpreter, which run Commands.
42  *
43  * A command interpreter can execute commands in the form of complete strings,
44  * or it can be given one character (keypress) at a time to build up a command.
45  * When given individual keypresses, the command interpreter echoes back
46  * what is to be printed. It also supports TAB completion.
47  */
49  : public UnitTestable
50 {
51 public:
52  /**
53  * \brief Constructs a %CommandInterpreter.
54  *
55  * @param owner the GXemul instance that owns the %CommandInterpreter
56  */
57  CommandInterpreter(GXemul* owner);
58 
59  /**
60  * \brief Adds a character (keypress) to the current command buffer.
61  *
62  * Most normal keys are added at the end of the buffer. Some exceptions
63  * are:
64  * <ul>
65  * <li>nul char: does not change the input line buffer,
66  * but forces it to be visually redrawn/updated
67  * <li>backspace: removes the last character (if any)
68  * <li>tab: attempts TAB completion of the last word
69  * <li>newline or cr: calls RunCommand, and then clears
70  * the current buffer
71  * <li>escape: special handling
72  * </ul>
73  *
74  * @param key the character/key to add
75  * @return true if this was a complete command line (i.e. the key
76  * was a newline), false otherwise
77  */
78  bool AddKey(stringchar key);
79 
80  /**
81  * \brief Clears the current command buffer.
82  */
84 
85  /**
86  * \brief Re-displays the current command buffer.
87  *
88  * Useful e.g. when running in text console mode, and the user has
89  * pressed CTRL-Z. When returning to %GXemul, the current command
90  * buffer can be showed again by calling this function.
91  */
93 
94  /**
95  * \brief Runs a command, given as a string.
96  *
97  * The return value from the function is true if the command was run.
98  * However, the command may run and fail, and that's what pSuccess is
99  * for.
100  *
101  * @param command the command to run
102  * @param pSuccess a pointer to a bool, which (if pSuccess is non-NULL)
103  * will be set to whether the command succeeded or not.
104  * @return true if the command was run, false if the command was
105  * not known
106  */
107  bool RunCommand(const string& command, bool* pSuccess = NULL);
108 
109  /**
110  * \brief Retrieves the current command buffer.
111  *
112  * @return a string representing the current command buffer
113  */
114  const string& GetCurrentCommandBuffer() const;
115 
116  /**
117  * \brief Adds a new Command to the command interpreter.
118  *
119  * @param command A reference counter pointer to the Command.
120  */
121  void AddCommand(refcount_ptr<Command> command);
122 
123  /**
124  * \brief Gets a collection of all commands.
125  *
126  * @return A const reference to the collection of commands.
127  */
128  const Commands& GetCommands() const;
129 
130  /**
131  * \brief Adds a command line to the command history.
132  *
133  * If the command is empty, or the same as the last command in the
134  * command history, it is ignored.
135  *
136  * The command history buffer only holds a small fixed number of
137  * entries.
138  *
139  * @param command The command line to add to the command history.
140  * @return The next insert position in the command history. Useful
141  * for unit testing purposes; should otherwise be ignored.
142  */
143  int AddLineToCommandHistory(const string& command);
144 
145  /**
146  * \brief Retrieves a line from the command history.
147  *
148  * @param nStepsBack The number of steps back into the history. 0
149  * means return an empty line, 1 means the last history line,
150  * 2 means the second last, and so on.
151  * @return The line from the history, or an empty string if
152  * nStepsBack was zero.
153  */
154  string GetHistoryLine(int nStepsBack) const;
155 
156 private:
157  /**
158  * \brief Internal helper which clears a line by outputting spaces.
159  */
160  void ClearCurrentInputLineVisually();
161 
162  /**
163  * \brief Completes the word at the current position in the input line.
164  *
165  * @param commandString A reference to the string to
166  * tab-complete.
167  * @param cursorPosition A refernce to a size_t, which
168  * indicates the current cursor position within the string.
169  * @param visibleShowAvailable True if available words should be
170  * echoed back via the UI.
171  * @return True if there was a single match, false otherwise.
172  */
173  bool TabComplete(string& commandString, size_t& cursorPosition,
174  bool visibleShowAvailable = false);
175 
176  /**
177  * \brief Tab-completes; takes optional method or state variable
178  * name into account.
179  *
180  * Strings such as "cpu." and "cpu.u" should e.g. be expanded to
181  * "root.machine0.mainbus0.cpu." and
182  * "root.machine0.mainbus0.cpu.unassemble", respectively.
183  *
184  * @param commandString A reference to the string to
185  * tab-complete.
186  * @param cursorPosition A refernce to a size_t, which
187  * indicates the current cursor position within the string.
188  * @param visibleShowAvailable True if available words should be
189  * echoed back via the UI.
190  * @return True if there was a single match, false otherwise.
191  */
192  bool TabCompleteWithSubname(string& commandString,
193  size_t& cursorPosition, bool visibleShowAvailable = false);
194 
195  /**
196  * \brief Runs a method on a Component.
197  *
198  * Note: The componentPathAndMethod argument may contain an optional
199  * ".method" suffix. The part before the method may need to be
200  * tab-completed.
201  *
202  * Some examples of componentPathAndMethod:
203  * <ul>
204  * <li>cpu
205  * <li>cpu.u
206  * <li>cpu.unassemble
207  * <li>root.machine0.mainbus0.cpu
208  * <li>root.machine0.mainbus0.cpu0
209  * <li>root.machine0.mainbus0.cpu.u
210  * <li>root.machine0.mainbus0.cpu0.unassemble
211  * </ul>
212  *
213  * If the method name is missing, a default method will be executed.
214  *
215  * @param componentPathAndMethod The path to the component, plus a
216  * possible ".method" suffix.
217  * @param arguments A vector of string arguments.
218  * @return True if a component method was executed, false otherwise.
219  */
220  bool RunComponentMethod(const string& componentPathAndMethod,
221  const vector<string>& arguments);
222 
223  /**
224  * \brief Prints a list of available words (for tab completion).
225  *
226  * @param words A vector of all available words.
227  */
228  void ShowAvailableWords(const vector<string>& words);
229 
230  void VariableAssignment(const string& componentPath,
231  const string& variableName, const string& expression);
232 
233 
234  /********************************************************************/
235 public:
236  static void RunUnitTests(int& nSucceeded, int& nFailures);
237 
238 
239 private:
240  // Pointer to the owning GXemul instance:
241  GXemul* m_GXemul;
242 
243  // A collection of all available commands that can be executed:
244  Commands m_commands;
245 
246  // The current input line:
247  string m_currentCommandString;
248  size_t m_currentCommandCursorPosition;
249  bool m_inEscapeSequence;
250  string m_escapeSequence;
251  int m_historyEntryToCopyFrom;
252 
253  // Command history (usually accessed by cursor up/down keys):
254  vector<string> m_commandHistory;
255  size_t m_commandHistoryInsertPosition;
256  size_t m_commandHistoryMaxSize;
257 
258  // If non-empty, a command which may be reexecuted if an empty
259  // command line is given:
260  string m_mayBeReexecuted;
261 };
262 
263 
264 #endif // COMMANDINTERPRETER_H
Commands
map< string, refcount_ptr< Command > > Commands
Definition: Command.h:135
stringchar
char stringchar
Definition: misc.h:59
CommandInterpreter::RunUnitTests
static void RunUnitTests(int &nSucceeded, int &nFailures)
GXemul
The main emulator class.
Definition: GXemul.h:55
CommandInterpreter::AddKey
bool AddKey(stringchar key)
Adds a character (keypress) to the current command buffer.
Definition: CommandInterpreter.cc:381
Command.h
CommandInterpreter::CommandInterpreter
CommandInterpreter(GXemul *owner)
Constructs a CommandInterpreter.
Definition: CommandInterpreter.cc:38
refcount_ptr< Command >
CommandInterpreter::AddCommand
void AddCommand(refcount_ptr< Command > command)
Adds a new Command to the command interpreter.
Definition: CommandInterpreter.cc:57
misc.h
UnitTest.h
CommandInterpreter::RunCommand
bool RunCommand(const string &command, bool *pSuccess=NULL)
Runs a command, given as a string.
Definition: CommandInterpreter.cc:958
CommandInterpreter::GetCurrentCommandBuffer
const string & GetCurrentCommandBuffer() const
Retrieves the current command buffer.
Definition: CommandInterpreter.cc:1019
CommandInterpreter::GetCommands
const Commands & GetCommands() const
Gets a collection of all commands.
Definition: CommandInterpreter.cc:63
CommandInterpreter
An interactive command interpreter, which run Commands.
Definition: CommandInterpreter.h:50
UnitTestable
Base class for unit testable classes.
Definition: UnitTest.h:75
CommandInterpreter::AddLineToCommandHistory
int AddLineToCommandHistory(const string &command)
Adds a command line to the command history.
Definition: CommandInterpreter.cc:69
CommandInterpreter::GetHistoryLine
string GetHistoryLine(int nStepsBack) const
Retrieves a line from the command history.
Definition: CommandInterpreter.cc:88
CommandInterpreter::ReshowCurrentCommandBuffer
void ReshowCurrentCommandBuffer()
Re-displays the current command buffer.
Definition: CommandInterpreter.cc:638
CommandInterpreter::ClearCurrentCommandBuffer
void ClearCurrentCommandBuffer()
Clears the current command buffer.
Definition: CommandInterpreter.cc:655

Generated on Tue Aug 25 2020 19:25:06 for GXemul by doxygen 1.8.18