A New Shell for Equinox - How to Use It

Using Commands

The command usage in the new shell is not much different from whay you have seen in the built-in Equinox console. However, there are minor differences, mainly due to the fact that the new shell is based on the Apache Gogo shell and its commands are a little bit different.

Although the differences are much more evident when developing commands, they still could be found when using them. First of all, with Gogo comes the notion of scope. Each command has its scope, within which there should be no other command with the same name. In practice, if there are registered several commands with identical name and scope, the last one registered wins.

However, scoping solves to some extent the problem with identical commands names. In the old console all commands should be with different names - otherwise Equinox does not guarantee which one it will execute. With the nothion of scopes each bundle could provide a unique scope and then has commands with the same names as commands in other bundles.

When calling commands the scope is represented by a prefix of the command name, separated from it with a column. You may call a command without prefixing with its scope, but do this only when you are sure that there is no command with the same name in another scope. Or else the other may get executed. The Gogo scope takes priority over all other scopes, so if a command is called without a scope, it is first searched within the Gogo scope, and then in the others.

Equinox comes with a number of commands and there are also other Eclipse bundles, providing console commands. There are also many custom bundles, which provide commands. All these are not Gogo commands and Gogo does not recognize them. That is why the new shell provides an adapter for these commands, so that all commands that used to work in the built-in Equinox shell will continue to work in the new one. In the new shell the adapter registers them with scope equinox.

If you want to disconnect from a telnet or ssh session, use the disconnect command. The exit command will directly stop the Equinox framework, which could be an unpleasant surprise.

The Help Commands

Gogo comes with its own help command. When called with no arguments, it lists all available commands, together with there scopes. If a command name is passed as an argument to the help command, it displays help for the given command, if such is available. However, Gogo help command does not recognize the "adapted" legacy Equinox commands. That is why there is also another help command, with scope equinox, which does recognize them. It has also accepts two options:

• -legacy - lists only the "adapted" commands
• -all - lists all commands, both new and "adapted"

If used without arguments it behaves lake the Gogo help command and lists the new commands.
If you want to get help for a particular "adapted" command, you should use equinox:help -legacy and the name of the command, without scope. This will work only for legacy commands, which provide help.
Instead of using equinox:help, you could use man. It has exactly the same behavior, and you could omit its scope (which is equinox), because there is no other command with this name currently.

Tab completion

A nice feature of the new shell is command completion. This feature is available only when connecting through telnet and ssh. Command completion is available for command names, session variables names and file names. The variables should be previously defined in the session. The completion functionality is activated by pressing the tab key. If there is only one possible candidate, the current string is completed with it. If there are more candidates, they are listed in a column and may be iterated by pressing tab multiple times until the desired candidate is reached.