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

Version 6 (modified by leonwlaw, 6 years ago)

Added details for module management within seash

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 a subdirectory within the /modules/ folder. The importer will try to look for a *.seashplugin.py file in each module folder and import it. There should only be one such file in each module.

Defining a module is relatively straightforward. There must be a *.seashplugin.py file that contains the main command_dict for the module. It defines all the commands that are to be part of the module. 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
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':"""...""",}
}

In addition, you must have module-level documentation. You do this by specifying a module_help string on the module-level namespace.

module_help = """
GeoIP Module

This module includes commands that provide information regarding vessels' geographical 
locations.  To get started using this module, acquire several vessels through the Seattle
Clearinghouse, use the 'browse' command, and then in any group, run either 'show location' 
or 'show coordinates'.
"""


Current Module Information


To view information on all currently installed modules, you can use the show modules command.

user@ !> help show modules
show modules

Shows information on all installed modules.  Modules will be separated into 
two categories: enabled and disabled.  Each entry will be in the following 
format:
  [module name] - [URL where the module was installed from, if available]

The URL will be missing if the module was installed manually.


user@ !> show modules
Enabled Modules:
geoip - https://seattle.poly.edu/plugins/geoip/

Disabled Modules:
selexor - https://seattle.poly.edu/plugins/selexor/  


Module-Level Help


To view information about a particular module, use the help module modulename command. This helptext is defined by the module creator.

user@ !> help module geoip
GeoIP Module

This module includes commands that provide information regarding vessels' geographical 
locations.  To get started using this module, acquire several vessels through the Seattle
Clearinghouse, use the 'browse' command, and then in any group, run either 'show location' 
or 'show coordinates'.


Installing/Uninstalling Modules


To install a new module, you can use the install command.

user@ !> help install
install modulename url_to_module

Downloads the specified module as modulename and enables it if possible.  
The module will be automatically updated when you run seash.


user@ !> install selexor https://seattle.poly.edu/plugins/selexor
Module 'selexor' has been successfully installed and enabled.

user@ !> install selexor https://seattle.poly.edu/plugins/selexor
Module 'selexor' already exists.  You can either uninstall it using 'uninstall'
or install it under a different name.

To uninstall an existing module, you can use the uninstall command.

user@ !> help uninstall
uninstall modulename

Uninstalls the specified module.  Use with caution, as you cannot undo this action!
You can use 'show modules' to view a list of all installed modules.


user@ !> uninstall selexor
Module 'selexor' has been successfully uninstalled.

user@ !> uninstall selexor
Module 'selexor' is not installed.


Enabling/Disabling Modules


Modules are imported when you initially start seash, but they may not be enabled depending on conflicting modules, you disabled them on a previous run, etc. 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. This is useful if you have modules that have conflicting commands. You can disable a module you're not currently using and enable the new module to use the conflicting 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@ !>