🐚Shell Structure
Explaining the inner workings of all the kernel shells
Kernel shells can be built by implementing two different interfaces and base classes. Why two? Because the shell handler relies on:
BaseShell
andIShell
: To hold shell type and initialization codeBaseShellInfo
andIShellInfo
: To hold shell commands and the base shell
Shell Handler
The shell handler, ShellManager
, uses the available shell list, which holds the BaseShellInfo
abstract class, to manipulate with that shell. That class can be get, depending on the needed type, with the ShellManager.GetShellInfo()
function in the ︎KS.Shell
namespace.
The shell handler also contains two properties: CurrentShellType
and LastShellType
. The former property holds the current shell type, which can be used with the shell management functions. The latter property holds the last shell type, which is usually the shell that you exited. However, there are three cases:
If there are no shells in the shell stack, it returns the primary
Shell
If there is only one shell in the stack, it returns the current shell as the last one
If there are two or more shells in the stack, it returns the last shell type
Additionally, when GetLine()
is called, it sets Terminaux's reader history to point to the shell's history list. After it's done getting the input, it reverts back to the General
history buffer. They are loaded on boot and saved on shutdown or reboot.
You can force a reload on the history by using the loadhistories
command across all the shells.
You can manually save the history list for all the shells using the savehistories
command.
Base Shell
The BaseShell
abstract class, which your shell must override, contains the shell type name (ShellType
), the flag to bail from the shell (Bail
), and the shell initialization code with the shell arguments (InitializeShell()
).
The shell initialization code usually waits for the Bail
value to become true
(the shell requested bailing, usually done by exiting the shell using the exit
universal command), as in the below example code.
While it's waiting for this to happen, the shell does what it's programmed to do, but in two conditions:
All shells must call the
ShellManager.GetLine()
function, which usually is adaptive to your shell type. This is the below example code inside the shell initialization code to illustrate this:
All shells must also handle both the
ThreadInterruptedException
, which must setBail
totrue
, and the general exceptions, which must callcontinue
after dumping the exception to the debugger or to the console. For example, the below example code, inside theInitializeShell()
function:
The shell registration is required once you're done implementing the shell and all its required values, which will show you how to implement them in the next three pages. The function responsible for this action is ShellTypeManager.RegisterShell()
in the KS.Shell.ShellBase.Shells
namespace.
Be sure to unregister your shell using the UnregisterShell()
function, or the shell registry function will not update your BaseShellInfo
class in the available shell lists!
Shell Information
Every BaseShell
class you create must accompany it with a separate class that implements the BaseShellInfo
and IShellInfo
classes, as in below:
This is where your commands get together by overriding the Commands
variable with the new dictionary containing all your commands, like below (in the UESH shell):
In addition, you can override the ShellPresets
class with a new dictionary containing all the presets for your shell, like below:
ShellBase
, however, must be overridden with an instance of your shell in this form:
Additionally, CurrentPreset
must be overridden with a variable that queries your shell type with the CurrentPresets
variable as in below:
The ShellType
variable found within the BaseShellInfo
class is a wrapper for the ShellBase.ShellType
variable for easier access. It's not overridable and is defined like this:
By default, your shells don't accept network connections. To make them accept network connections, you must override the AcceptsNetworkConnection
so that it holds the value of true
instead of false
. This causes the network connection selector, especially OpenConnectionForShell()
which can be invoked in your networked shell launch code in your command class, to be able to acknowledge your shell.
By default, all the shells provide you a multi-line prompt, but if you want your input to be in one line wrapped mode, you can override the below property:
If your shell meets the following conditions:
You need to handle written text in a way, and
You need to use your commands with a slash character, just like the remote debugger,
Then, you need to override the two properties in order for your special non-slash handler to execute:
If you need to know how to define a command information class, consult the below link:
You'll have to adapt your shell to take the first argument, ShellArgs[0]
, as the network connection instance in your Shell
instance. For example, we've done this to the FTP shell and shell info instances:
Base Command
The base command is required to be implemented, since it contains overridable command execution code. Your command must implement the command base class below:
The only function that you need to override is Execute()
, which you can override like below:
To support dumb consoles that don't support positioning or complex console functions, you can override ExecuteDumb()
:
Additionally, you can override the extra help function, HelpHelper()
, like this:
If you want to support redirection or wrapping, you must either take dumb console support into account on the Execute()
function by not calling any of the below console wrappers, or you must override the ExecuteDumb()
function shown above to be compatible with the dumb consoles.
The following wrappers should not be called (explicitly and implicitly) on that function:
CursorLeft
(set)CursorTop
(set)ForegroundColor
BackgroundColor
CursorVisible
OutputEncoding
InputEncoding
KeyAvailable
Beep()
Clear()
OpenStandardError()
OpenStandardInput()
OpenStandardOutput()
ReadKey()
ResetColor()
SetCursorPosition()
SetOut()
Registering your command
In order for your command to be usable, your mods are now required to register the commands manually using a function that helps doing this. That function is defined in the CommandManager
class.
Similarly, if your mod is going to stop, you must unregister all your mod commands, including those that it created in the middle of the kernel uptime. You can use the following functions:
If you've registered your commands correctly, the help
command list should list your mod command that you've registered using one of the RegisterCustomCommand
functions.
If you're migrating your mods, your mod code can still contain the old Commands
list, but you must use the following properties:
Commands.Keys
(command names for unregistration)Commands.Values
(command info instances for registration)
Since Nitrocid no longer uses this list, we recommend that you use it as a mutable list of commands just for your mods, since you could be generating commands and registering them.
Setting command values
There is a special switch called set
that allows your command to set the final variable value to any value. For example, if you run calc
with the -set
switch to a variable called result
, that variable will be set to an output value (in this case an arithmetic result) using the variableValue
argument.
To take advantage of the feature, just write the following code at the end of Execute()
:
...where myValue
is a string representation of the resulting value that the command produces. A real-world example of this is provided (from the echo
command code):
Command flags
Finally, the command flags (CommandFlags
) can be defined. One or more of the command flags can be defined using the OR (|
) operator when defining the command flags. These flags are available:
Strict
: The command is strict, meaning that it's only available for administrators.The flag value is 1
NoMaintenance
: This command can't run in maintenance mode.The flag value is 2
Obsolete
: The command is obsolete.The flag value is 4
SettingVariable
: The command is setting a UESH variable.The flag value is 8
RedirectionSupported
: Redirection is supported, meaning that all the output to the commands can be redirected to a file.The flag value is 16
Wrappable
: This command is wrappable to pages.The flag value is 32
SettingVariable
is obsolete. Please use the AcceptsSet parameter when making a new CommandArgumentInfo.
More?
For guidance on how to define your command, click the below button:
🔋Command InformationFor guidance on how to define your command's switches, click the below button:
🎚️Command Switch InformationFor guidance on how to manage your command's switches, click the below button:
⏲️Command Switch ManagementFor information about the help system and how it works, consult the below page:
❔Help SystemFor command parsing, click the below button:
🗜️Command ParsingFor shell scripting, click the below button:
📜Shell ScriptingFor shell presets, click the below button:
📟Shell PresetsFor shell history, click the below button:
⏳Shell HistoryFor extra shell features, click the below button:
💠Extra Shell FeaturesLast updated