Package configshell :: Module shell :: Class ConfigShell

[hide private]
[frames] | no frames]

# Class ConfigShell

    object --+
             |
            ConfigShell

This is a simple CLI command interpreter that can be used both in interactive or non-interactive modes. It is based on a tree of ConfigNode objects, which can be navigated.

The ConfigShell object itself provides global navigation commands. It also handles the parsing of local commands (specific to a certain ConfigNode) according to the ConfigNode commands definitions. If the ConfigNode provides hooks for possible parameter values in a given context, then the ConfigShell will also provide command-line completion using the TAB key. If no completion hooks are available from the ConfigNode, the completion function will still be able to display some help and general syntax advice (as much as the ConfigNode will provide).

Interactive sessions can be saved/loaded automatically by ConfigShell is a writable session directory is supplied. This includes command-line history, current node and global parameters.

Instance Methods | [hide private]

__init__(self, preferences_dir=None) Creates a new ConfigShell. |

_display_completions(self, substitution, matches, max_length) Display the completions. |

list of str

_complete_token_command(self, text, path, command) Completes a partial command token, which could also be the beginning of a path. |

list of str

_complete_token_path(self, text) Completes a partial path token. |

list of str

_complete_token_pparam(self, text, path, command, pparams, kparams) Completes a positional parameter token, which can also be the keywork part of a kparam token, as before the '=' sign is on the line, the parser cannot know better. |

list of str

_complete_token_kparam(self, text, path, command, pparams, kparams) Completes a keyword=value parameter token. |

str

_complete(self, text, state) Text completion method, directly called by readline. |

list of str

_dispatch_completion(self, path, command, pparams, kparams, text, current_token) This method takes care of dispatching the current completion request from readline (via the _complete() method) to the relevant token completion methods. |

_get_prompt(self) Returns the command prompt string. |

_cli_loop(self) Starts the configuration shell interactive loop, that: |

(pyparsing.ParseResults, str, str, list, dict)

_parse_cmdline(self, line) Parses the command line entered by the user. |

_execute_command(self, path, command, pparams, kparams) Calls the target node to execute a command. |

run_cmdline(self, cmdline) Runs the specified command. |

run_script(self, script_path, exit_on_error=True) Runs the script located at script_path. |

run_stdin(self, file_descriptor=sys.stdin, exit_on_error=True) Reads commands to be run from a file descriptor, stdin by default. |

run_interactive(self) Starts interactive CLI mode. |

attach_root_node(self, root_node) |

Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Class Variables | [hide private]

| default_prefs = `{'color_path': 'magenta', 'color_command': 'cy`...``
| _completion_help_topic = `''`
| _current_parameter = `''`
| _current_token = `''`
| _current_completions = `[]`

Properties | [hide private]

Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, preferences_dir=None)
(Constructor)

Creates a new ConfigShell.

Parameters:
  - `preferences_dir` (str) - Directory to load/save preferences from/to
Overrides: object.__init__

### _display_completions(self, substitution, matches, max_length)

Display the completions. Invoked by readline.

Parameters:
  - `substitution` - string to complete
  - `matches` - list of possible matches
  - `max_length` - length of the longest matching item

### _complete_token_command(self, text, path, command)

Completes a partial command token, which could also be the beginning of a path.

Parameters:
  - `path` (str) - Path of the target ConfigNode.
  - `command` (str) - The command (if any) found by the parser.
  - `text` (str) - Current text being typed by the user.
Returns: list of str
  Possible completions for the token.

### _complete_token_path(self, text)

Completes a partial path token.

Parameters:
  - `text` (str) - Current text being typed by the user.
Returns: list of str
  Possible completions for the token.

### _complete_token_pparam(self, text, path, command, pparams, kparams)

Completes a positional parameter token, which can also be the keywork part of a kparam token, as before the '=' sign is on the line, the parser cannot know better.

Parameters:
  - `path` (str) - Path of the target ConfigNode.
  - `command` (str) - The command (if any) found by the parser.
  - `pparams` (list of str) - Positional parameters from commandline.
  - `kparams` (dict of str:str) - Keyword parameters from commandline.
  - `text` (str) - Current text being typed by the user.
Returns: list of str
  Possible completions for the token.

### _complete_token_kparam(self, text, path, command, pparams, kparams)

Completes a keyword=value parameter token.

Parameters:
  - `path` (str) - Path of the target ConfigNode.
  - `command` (str) - The command (if any) found by the parser.
  - `pparams` (list of str) - Positional parameters from commandline.
  - `kparams` (dict of str:str) - Keyword parameters from commandline.
  - `text` (str) - Current text being typed by the user.
Returns: list of str
  Possible completions for the token.

### _complete(self, text, state)

Text completion method, directly called by readline. Finds out what token the user wants completion for, and calls the _dispatch_completion() to get the possible completions. Then implements the state system needed by readline to return those possible completions to readline.

Parameters:
  - `text` (str) - The text to complete.
Returns: str
  The next possible completion for text.

### _dispatch_completion(self, path, command, pparams, kparams, text, current_token)

This method takes care of dispatching the current completion request from readline (via the _complete() method) to the relevant token completion methods. It has to cope with the fact that the commandline being incomplete yet, Of course, as the command line is still unfinished, the parser can only do so much of a job. For instance, until the '=' sign is on the command line, there is no way to distinguish a positional parameter from the begining of a keyword=value parameter.

Parameters:
  - `path` (str) - Path of the target ConfigNode.
  - `command` (str) - The command (if any) found by the parser.
  - `pparams` (list of str) - Positional parameters from commandline.
  - `kparams` (dict of str:str) - Keyword parameters from commandline.
  - `text` (str) - Current text being typed by the user.
  - `current_token` (str) - Name of token to complete.
Returns: list of str
  Possible completions for the token.

### _cli_loop(self)

Starts the configuration shell interactive loop, that:

- Goes to the last current path
- Displays the prompt
- Waits for user input
- Runs user command

### _parse_cmdline(self, line)

Parses the command line entered by the user. This is a wrapper around the actual pyparsing parser that pre-chews the result trees to cleanly extract the tokens we care for (parameters, path, command).

Parameters:
  - `line` (str) - The command line to parse.
Returns: (pyparsing.ParseResults, str, str, list, dict)
  (result_trees, path, command, pparams, kparams), pparams being positional parameters and kparams the keyword=value.

### _execute_command(self, path, command, pparams, kparams)

Calls the target node to execute a command. Behavior depends on the target node command's result:

- An 'EXIT' string will trigger shell exit.
- None will do nothing.
- A ConfigNode object will trigger a current_node change.

Parameters:
  - `path` (str) - Path of the target node.
  - `command` (str) - The command to call.
  - `pparams` (list) - The positional parameters to use.
  - `kparams` (dict) - The keyword=value parameters to use.

### run_cmdline(self, cmdline)

Runs the specified command. Global commands are checked first, then local commands from the current node.

Command syntax is: [PATH] COMMAND [POSITIONAL_PARAMETER]+ [PARAMETER=VALUE]+

Parameters:
  - `cmdline` (str) - The command line to run

### run_script(self, script_path, exit_on_error=True)

Runs the script located at script_path. Script runs always start from the root context.

Parameters:
  - `script_path` (str) - File path of the script to run
  - `exit_on_error` (bool) - If True, stops the run if an error occurs

### run_stdin(self, file_descriptor=sys.stdin, exit_on_error=True)

Reads commands to be run from a file descriptor, stdin by default. The run always starts from the root context.

Parameters:
  - `file_descriptor` (file object) - The file descriptor to read commands from
  - `exit_on_error` (bool) - If True, stops the run if an error occurs

### attach_root_node(self, root_node)

Parameters:
  - `root_node` (ConfigNode) - The root ConfigNode object

Class Variable Details | [hide private]

### default_prefs

Value:

      {'color_path': 'magenta', 'color_command': 'cyan', 'color_parameter':
      'magenta', 'color_keyword': 'cyan', 'logfile': None, 'loglevel_console
      ': 'info', 'loglevel_file': 'debug9', 'color_mode': True, 'prompt_leng
      th': 30, 'tree_max_depth': 0, 'tree_status_mode': True, 'tree_round_no
      des': True, 'tree_show_root': True}