Please note that these Trac pages are no longer being updated. Wiki contents/documentation have moved to GitHub.

Version 5 (modified by leonwlaw, 6 years ago)

Added user toggling of modules

Seash (also known as Seattle Shell) is the command line interface for interacting with Seattle vessels. For a basic tutorial on how to use seash, see the Repy Tutorial.

Command Dictionary


The command dictionary contains command nodes that determine how seash responds to various input. Each command node represents a recognized command keyword, and may have child command nodes that represent keywords that should come after that command. Seash will use this dictionary to check if an input string matches a path through the command dictionary, and if it does, executes the command at the terminating node.

Each command node is defined in the following manner:

command_dict = { 
  'mycommandtoken': {
    'name': 'tokenname',
    'callback': command_callback,
    'summary': 'summary text for the command',
    'help_text': 'comprehensive help text for the command',
    'display_keyword': 'display this command in the list of commands when the help command contains this display keyword.',
    'children': {} # command dictionaries of subsequent child commands
  }
}
  • mycommandtoken: What the user should input to use this command. This should be a single word. If the user should type in 'browse', then this should be 'browse'. This can also be a user-entered argument. These arguments include [TARGET], [FILENAME], [KEYNAME], and [ARGUMENT].
  • name: A unique tag that can be used in the callback function to identify a specific token.
  • callback: The callback function to run if this command was entered. It should take two parameters: an input_dict that contains the parsed input as a command dictionary, as well as an environmentdict that describes seash's current state.
  • summary: A short summary of what the command does.
  • help_text: A detailed explanation of what the command should do and can do.
  • display_keyword: When showing help for a command, the summaries of any sub-commands are shown. This is the keyword that should be specified in order for this summary to show. Omit this if a command should be shown by default.
  • children: A dictionary containing command tokens that map to command nodes for subsequent commands.

The root dictionary is treated as a list of children. Therefore, the command dictionary should be as such:

command_dictionary = {
  'show': {
    ...
  },
  'add': {
    ...
  },
  ...
}


Extending seash: seash's Module system


Seash has support for adding additional commands via modules that are imported on startup. These modules should be placed in the /modules/ folder. The importer will automatically import modules ending in *_module.py.

Defining a module is relatively straightforward. The only requirement for a module is that it must have a command_dict defined in the module namespace for all the commands that should be added. These command_dicts should be specified in a similar manner as described in the command dictionary section above. However, there are several differences:

  • You specify the full command on the top level of the command dictionary. The entire command becomes the key entry. The importer will use this to figure out where to insert the node.
  • Commands should not have any child entries. These will be automatically generated by the importer as the dictionary is being populated.

Therefore, each command node needs to have the following elements:

  • name
  • callback
  • summary
  • help text
  • display keyword (optional)
    command_dict = {
      'show location':{
          'name':'location',
          'callback': show_location_callback,
          'summary': "Display location information (countries) for the nodes",
          'help_text':"""...""",},
    
      'show coordinates':{
          'name':'coordinates',
          'callback': show_coordinates_callback,
          'summary':'Display the latitude & longitude of the node',
          'help_text':"""...""",}
    }
    

Using modules

Modules are imported when you initially start seash. However, they are not enabled by default.

To enable a module, use the enable command:

user@ !> help enable
enable modulename

Enables use of the specified module.  You can only enable modules if they do not
contain commands that conflict with existing commands.


user@ !> enable modulename
user@ !> enable modulename
Module 'modulename' is already enabled.

user@ !> enable conflictingmodule
Module 'conflictingmodule' cannot be enabled due to these conflicting commands:
show info (default)
get (selexor)

user@ !>

Similarly, you can disable modules using the disable command:

user@ !> help disable
disable modulename

Disables the specified module.  You will no longer be able to access the commands 
that were found in the disabled module until the module is re-enabled.


user@ !> disable modulename
user@ !> disable modulename
Module 'modulename' is not enabled.

user@ !>