UserDoc:Shell

What is a shell?

The Shell/Console is a text based window that provides a mechanism for the user to send commands to the operating system or run user programs. It is a low-level version of the Graphical User Interface (GUI) known as the Workbench. Some commands are unique to the Shell, just as some are unique to the Workbench. In practice, the two user interfaces complement each other with a large amount of overlap. The choice is left to personal taste.

The user-supplied commands and responses from the Shell and other programs can be displayed in a Console text window on the screen. Alternatively, the user interface may be used via a remote mechanism such as a terminal program running on another computer. Such a remote machine might be connected via a serial interface, a network connection or other means.

Starting a shell

Opening a Shell with default settings

You can open a shell doing like this:

• Double click the Shell icon, that you can find in the System folder of the system partition.

TODO: insert icon image

• Issue one of the following commands newshell, newcli or cli. As an example, you can use such command in the Execute... requester of the Workbench.

Using settings to customise the shell

If you issue the newshell command without an argument, the default value will be used and a shell will be opened positionned at the top left of the screen, with a height of 130 pixels and it will take the width of the screen. The newshell command can be used with a special argument that describes how the shell should look. This is the WINDOW template that looks like this:

CON:[X]/[Y]/[width]/[height]/[title]/[options] where:

X

is the number of pixels from the left edge of the screen to the left border of the console window. Use no value (i.e. //) to specify the minimum possible pixels. Use the value -1 to generate a window that is centred horizontally on the screen.

Y

is the number of pixels from the top of the screen to the top of the console window. Use no value (//) to specify the minimum possible pixels. Use the value -1 to generate a window that is centred vertically on the screen.

width

is the width of the console window, in pixels. Use no value (//) to specify the full width of the screen.

height

is the height of the console window, in pixels. Use no value (//) to specify minimum possible height.

title

is the text that appears in the console window title bar.

options

You can use here any of the following options:

AUTO

The window automatically appears when the program needs input or produces output. Selecting the Shell's close gadget closes the window, but it re-opens immediately since it is expecting input.

CLOSE

The window has all the standard gadgets, including a close gadget.

NOCLOSE

The window does not have a close gadget. If you open a console normally, there is no close gadget. If you open a console using the AUTO option, there is automatically a close gadget on the window.

NODEPTH

The window has no window depth gadget.

NODRAG

The window cannot be dragged. It has zoom, depth and sizing gadgets, but no close gadget.

NOSIZE

The window only has a depth gadget.

NOICONIFY

The window is opened without an iconify gadget. The window can still be iconified by use of the Right-Amiga/I keyboard shortcut.

WAIT

The window can only be closed by selecting the close gadget or entering Ctrl-\. If WAIT is the only option, there is no close gadget.

Example:

newshell "CON:0/0//300/This is a shell/CLOSE"

Note: double quotes (") are used because there are spaces in the title string.

Using a shell

A shell being a text only interface you will use it almost exclusively with the keyboard. There are a few graphic elements that will require the use of a mouse: menu items, window sliders, tabs...

TODO: insert shell image with tabs and menus

Menus

Project menu

Some items in the Project menu may not appear, depending on the mode in which the window has been opened. These dependencies are listed with each item below.

• New shell

This option opens a clone of the Shell that was running at the time the menu item was selected. It is equivalent to the keystroke RAmiga-N.

---

• Load history...

This item brings up an ASL requester, allowing you to select an ASCII file that will be read into the console as though it were command history. Any control characters or escape sequences embedded in the file will be actioned in the normal manner when loaded. Notes: display history files are saved without any formatting, therefore the text may not appear the same in the window as it did before being saved. The file is read simply as a string of text and any Shell commands in it are not recognised or actioned. Therefore, the con-handler's command history will not contain any of the saved commands in the display history file.

• Save history...

This item brings up an ASL requester, allowing you to nominate a drawer and file name under which to save the current display history. Notes: the display history is saved without any formatting codes. The history is not changed after the text is saved.

• Clear history

This item clears all display history except that which is in the current window. Any temporary disk files are also cleared.

---

• Iconify

this iconifies the shell into an icon on the Workbench screen. The icon will be named with the process ID of the shell. This is equivalent to the keystroke RAmiga-I.

• About...

This gives the version numbers of the console.device and the console.handler. It is equivalent to the keystroke RAmiga-?.

---

• Close shell

This item issues a CLOSEWINDOW command (equivalent to typing Ctrl-\ or RAmiga-K). It will close only the current Shell and will appear only when there are two or more Shells in the window. The window may not close if there are unfinished tasks running.

• Close all

This item closes every Shell operating in the current window. Some or all of the Shells may remain open if they have tasks still running. It is equivalent to the keystroke RAmiga-Q.

Edit menu

• Copy - copies the selected text into the clipboard.
• Paste - pastes the text from the clipboard to the shell prompt.

View menu

• Prev shell

This item will only appear if you have more than one Shell open in the window. It will appear with or without a ClickTab gadget in the window. When selected, it changes the current Shell to the previous Shell, where "previous" refers to the Tabs in a ClickTab Window. If there is no ClickTab in this window, the "previous" Shell is that opened before the currently active Shell. If the current Shell is the first Shell opened, this item will select the last Shell opened. It is equivalent to the keystroke RAmiga-<.

• Next shell

This item will only appear if you have more than one Shell open in the window. It will appear with or without a ClickTab gadget in the window. When selected, it changes the current Shell to the next Shell, where "next" refers to the Tabs in a ClickTab Window. If there is no ClickTab in this window, the "next" Shell is that opened before the currently active Shell. If the current Shell is the last Shell opened, this item will select the first Shell opened. It is equivalent to the keystroke RAmiga->.

• Select...

This item will only appear if you have more than one Shell open in the window. It will appear with or without a ClickTab gadget in the window. If you have two or more Shells open, the "Select" item will open a pop-up window showing you the names of each open Shell. The names are taken from the ClickTab Labels assigned in the Prefs editor. If you click on any named Shell in the list, that Shell will become the "front" Shell. You can close the pop-up window with the mouse or double-click on the name you want.

Settings menu

The Settings menu allows you to alter the Preferences of the current window. All Shells operating in that window will be affected by any changes you make.

• Edit...

This item calls the Preferences Editor. You may make any changes you wish, then Use, Save or Cancel them as you please. If you exit with "Save", they will be saved in ENVARC: and all consoles opened after that time will use the new settings. If you exit with "Use", additional prefs settings will decide whether the changes apply to this window only, this window and all future windows or future windows only. Additionally, if the current window has two or more Shells operating under different Tabs, you can specify whether the changes are to apply to the frontmost Shell only, or to all Shells within that window.

�* Load... This item opens an ASL requester that allows you to select a special settings file that you have saved somewhere. Its contents will affect only the current window.

• Save As...

This item opens an ASL requester that allows you to choose the drawer and file name under which the settings will be saved.

Command line editing

Typing commands in a shell.