Shang interpreter is a software that interprets and executes Shang commands and programs. It translates a Shang program into internal code and can executes it with a virtual machine. Currently we have an interpreter for the Windows operating system, but are planning to come up with interpreters for other systems soon. The windows version of the interpreter is an interactive environment where user can enter commands and get response from the interpreter immediately. It has GUI interface, multiple line editing, and syntax-highlighting. It can be used to create, edit, and run Shang programs.
In the command window, after the prompt sign >>, type any arithmetic expression and press enter, the result will be displayed right underneath the input. Besides the common arithmetic operations, many built-in functions can be used -- including most math routines.
A program refers to any sequence of commands, which may contain control structures, definitions of variables, functions, classes, etc.
There are two ways. One can use any text editor to create a text file, and then run it using Shang interpreter. The file name doesn't have to have any special extension.
Or one can type the commands into the interpreter directly. The commands will be executed, and can be saved into a file as well. The Shang interpreter can edit multi-line programs.
There are three ways to run a program that is saved in a text file:
The command buffer is the area in the command window after the bottom prompt >>, where text can be entered and edited. It may contain a single line or several lines.
The command buffer is the only place in the window where text can be entered and edited. After the command buffer is submitted, the screen is scrolled down, and a new prompt is displayed and new empty buffer is created. The content of the old buffer is scrolled up, and cannot be changed anymore.
One may click on an arbitrary position in the window, and thus temporarily move the cursor position out of the command buffer. But the interpreter remembers the original cursor position in the command buffer, and, once new input is received, it will be inserted at the original position in the command buffer. However, by moving the cursor to arbitrary position in the window, one can copy any content of the window, not just the command buffer.
Back to Top
Usually when the ENTER key is hit, the current command buffer is submitted for execution. However, if the current command buffer does not form a complete block, i.e., unmatched brackets or unfinished loops or conditional blocks are present, pressing ENTER will not submit the command buffer, but instead open a new line. The interpreter will continue working in multi-line editing mode. When the buffer forms a complete executable unit (no closing brackets, or block closing statements expected), and the cursor position is at the end of the bottom line of the buffer, pressing ENTER will cause the command buffer to be executed. In the multi-line editing mode, the cursor can be moved throughout the whole buffer.
Back to Top
Usually the output of a command is displayed right below the completed command. If this is unwanted, append a semicolon at the end of the command. But this will not stop the error message from being shown.
A line break following three dots will break the current line, but the three dots and the line break are treated as an empty token. So the interpreter ignores the line break. This can be used to enter very long lines of input.
If the command buffer has a single line, pressing the up arrow will copy the previously entered command to the command buffer, and replace what ever that has already been typed. If the current command buffer has multiple lines, pressing the up arrow key will move the cursor up one line, until the cursor location is at the first line of the buffer. Then hitting the up arrow key causes the previously entered command to be brought up. Continuing pressing the up arrow key will go further back to the command history and bring up older commands. Pressing the down arrow key in the single line mode, or in the multi-line mode when the cursor is at the bottom of the buffer, will move the history pointer forward. Each time a command is executed, the history pointer is set to the command just being executed.
Note that each time you press the up arrow key, a whole command block that has just been executed will be brought up, which may contain many lines. For example, if you first type
s = 0 followed by ENTER, this command will be executed
Then type "for k = 1 : 1000000" followed by ENTER, the interpreter will not execute it because it expects a block closing statement. Instead, a new line is opened. You can continue typing until the block is completed
Now pressing the up arrow key, the whole block of text will be copied to the command buffer.
Alternatively, Ctrl-B and Ctrl-F instead of the arrow keys can be used for browsing the command history. The advantage is the cursor doesn't have to be at the top or bottom of the command buffer.
[This is the answer to the question.]
All the commands entered in a Shang session can be saved to a file -- select "File -- Save command history" from menu bar, and specify a file name in the dialog box. This will save all the previous input to the file, and the file will be closed then. So the commands entered after the save action will not be saved. The saved file can be run as a Shang program.
One can record diary -- save all the commands and execution results to a file -- select "File -- Record history" from menu bar, and specify a file name in the dialog box. Note that this will keep the file open and save all the input and output that are generated after the "starting recording" action, until you do "stop recording" from the menu bar, or when the interpreter is closed.
Comments are the commands that will be ignored by the interpreter. To enter a comment, start the line with two slashes "//".
One can also type in multi-line comments. Such a body of comments starts with "/*" and ends with "*/". The interpreter can recognize five levels of nested multi-line comments. In other words, it will not complain at the following
/* no in commenting mode
/* now in nested comment
still in commenting mode
If you need to write a large program, probably you should use a decent text editor. The Shang interpreter does have multiple-line editing capabilities, plus syntax highlighting (for Shang language only). However, it's not a particularly powerful editor. Besides, whenever the command buffer is considered complete (no closing brackets or block closing statement expected), when you hit enter, the interpreter will try execute it and display the result. There is a simple trick to go around this, that is, enclose your program in a trivial conditional block
The text content at any position in the window can be selected using mouse, and copied to the clipboard. But only when the selected area is totally inside the command buffer can it be cut off. The content of the clipboard can be pasted in the window, at the cursor position of the command buffer (even if the cursor position has been moved out of the command buffer, it will still be pasted at the original position of the buffer)
With the syntax-highlighting feature, tokens of different types, such as keywords, identifiers, numbers, operators, brackets, will be displayed with various colors and styles. Brackets that haven't been matched will displayed in red, signaling a potential error. However, this features does very little to highlight syntax errors besides unmatched brackets. Its major purpose is to make the text less boring and more pleasing to the eyes. This feature can be switched on and off from the Edit menu. I plan to enhance it in the future so that all common syntax errors can be highlighted.
The font style and size, text color, and background color can be customized by clicking the menu bar and selecting "Select font" and others. The syntax-highlighting scheme is working best with the default BW foreground/background color setting. There ought to be some adjustment in the syntax highlighting scheme when foreground/background colors are changed, but we haven't done this yet.