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 Shell, its 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 Right-Amiga/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 Right-Amiga/?.

---

• 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.

Command line editing

Typing commands in a shell.